Welcome to Trueface’s documentation!¶
trueface.access_control |
access control integrations and related utilities |
trueface.db |
|
trueface.face_attributes |
module to handle face attributes like emotion |
trueface.heartbeat |
Heartbeat detector |
trueface.helper |
helper methods |
trueface.motion |
Motion Detector module |
trueface.recognition |
Recognition Module |
trueface.searching |
Search Module |
trueface.spoof |
Spoof detection module |
trueface.tracking |
Tracking module |
trueface.utils |
utility methods |
trueface.video |
Video module |
access control integrations and related utilities
-
class
trueface.access_control.
Kisi
(email=None, password=None)¶ Kisi Door Control
-
get_locks
(place_id)¶ retrieves a list of your locks or info about a single lock
-
get_places
()¶ obtains an authorization token
-
signin
(email, password)¶ obtains an authorization token
-
unlock
(lock_id)¶ unlocks a Kisi door
-
-
class
trueface.access_control.
Lockitron
¶ Lockitron Lock Control
-
class
trueface.db.
Collection
(**kwargs)¶ A simple constructor that allows initialization from kwargs.
Sets attributes on the constructed instance using the names and values in
kwargs
.Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.
-
class
trueface.db.
DBService
(host='mysql://root@127.0.0.1', port=3306, db_name='trueface_tests')¶ DBService class
DBService class
Parameters: - host (str) – hostname where DB (mysql) runs
- port (int) – port of the DB, default: 3306
- db_name (str) – db name to use
Returns: String that represents the features, hex-encoded or not
-
delete_from_collection
(collection_name, label)¶ Remove a label and the corresponding feature from a collection
Parameters: - collection_name (str) – table name of an existing collection
- labels (list) – list of labels to remove
Returns: nothing
-
class
trueface.db.
Detection
(**kwargs)¶ A simple constructor that allows initialization from kwargs.
Sets attributes on the constructed instance using the names and values in
kwargs
.Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.
-
class
trueface.db.
Frame
(**kwargs)¶ A simple constructor that allows initialization from kwargs.
Sets attributes on the constructed instance using the names and values in
kwargs
.Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.
-
class
trueface.db.
Video
(**kwargs)¶ A simple constructor that allows initialization from kwargs.
Sets attributes on the constructed instance using the names and values in
kwargs
.Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.
-
class
trueface.db.
VideoPart
(**kwargs)¶ A simple constructor that allows initialization from kwargs.
Sets attributes on the constructed instance using the names and values in
kwargs
.Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.
module to handle face attributes like emotion
-
class
trueface.face_attributes.
FaceAttributes
(model, params, labels)¶ Face attributes class
init emotion class
-
get_attributes
(chip)¶ gets emotion for a face
-
Heartbeat detector
-
class
trueface.heartbeat.
HeartbeatDetector
(buffer_size=250)¶ Heartbeat detector class
helper methods
-
trueface.helper.
adjust_input
(in_data)¶ - adjust the input from (h, w, c) to ( 1, c, h, w) for network input
- in_data: numpy array of shape (h, w, c)
- input data
- out_data: numpy array of shape (1, c, h, w)
- reshaped array
-
trueface.helper.
detect_first_stage
(img, net, scale, threshold)¶ - run PNet for first stage
- img: numpy array, bgr order
- input image
- scale: float number
- how much should the input image scale
- net: PNet
- worker
total_boxes : bboxes
-
trueface.helper.
generate_bbox
(map, reg, scale, threshold)¶ generate bbox from feature map
- map: numpy array , n x m x 1
- detect score for each position
- reg: numpy array , n x m x 4
- bbox
- scale: float number
- scale of this detection
- threshold: float number
- detect threshold
bbox array
-
trueface.helper.
nms
(boxes, overlap_threshold, mode='Union')¶ non max suppression
- box: numpy array n x 5
- input bbox array
- overlap_threshold: float number
- threshold of overlap
- mode: float number
- how to compute overlap ratio, ‘Union’ or ‘Min’
index array of the selected bbox
Motion Detector module
-
class
trueface.motion.
MotionDetector
(frame, threshold=2, max_value=2)¶ MotionDetector class
Recognition Module
-
class
trueface.recognition.
BaseRecognizer
(license, ctx='cpu', gpu=0)¶ BaseRecognizer class
-
batch_make_mx_input
(images, dims=(512, 512))¶ Prepare list of images for MXNet input :param images: :param dims:
Returns: list with mx.nd.array elements
-
batch_preprocess_image
(images, dims=(512, 512))¶ Takes a list of images, preprocesses them (resize and BGR2RGB
Parameters: - images –
- dims –
Returns: list of preprocessed images
-
blur_region
(region, frame)¶ blurs a region in the image
Parameters: - region – (leftx, topy, rightx, bottomy)
- frame –
-
cosine_sim
(feature, collection_features, length=512)¶ Cosine Similarity with mxnet
Parameters: - feature – the source feature
- collection_features – a list of features
- length –
-
draw_box
(img, box)¶ draws a box on the image
Parameters: - img (str or binary) – image path, base64 encoded image, numpy array or OpenCV image
- box – (pt1, pt2, pt3, pt4)
- pt1 – (x coordinate of vertex, y coordinate of vertex)
- pt2 – (x coordinate of point opposite vertex, y coordinate of vertex)
-
draw_label
(image, point, label, font=0, font_scale=0.5, thickness=1)¶ Draw label on the image
Parameters: - img (str or binary) – image path, base64 encoded image, numpy array or OpenCV image
- point (tuple) – (x_label, y_label)
- label (str) – The label you want to write
- font (int) – your preferred font
- font_scale (float) – scaling factor for the font
- thickness (int) – thickness of text
-
get_image
(_bin, rgb=True)¶ gets an image from a path or from base64 string
Parameters: - _bin (str) – filesystem path or base64 string
- rgb (bool) – whether to perform BGR2RGB conversion
Returns: a pre-handled image ready for further processing
-
get_string_from_cv2
(image, encode=False)¶ Gets a string from a cv2 image
Parameters: - image –
- encode –
Returns: string representation of image
-
make_cv_input
(image)¶ Create OpenCV blob from an image
Parameters: image – Returns: cv2.dnn.blob
-
make_mx_input
(image, dims=(512, 512))¶ prepare image for MXNet input
Parameters: - image –
- dims –
Returns: mx.nd.array
-
preprocess_image
(image, dims=(512, 512))¶ resize image to dims and perform a BGR2RGB conversion
Parameters: - image (opencv image) – Image
- dims – Dimensions
Returns:
-
-
class
trueface.recognition.
ColorRecognizer
(n_clusters=10)¶ Color Recognizer class
Parameters: n_clusters – -
centroid_histogram
()¶ grab the number of different clusters and create a histogram based on the number of pixels assigned to each cluster
Returns: Return type: histogram
-
detect
(img)¶ detect colors present in image :param img: the input image
Returns: list of colors along with percentages
-
-
class
trueface.recognition.
FaceRecognizer
(ctx='cpu', min_face=40, accurate_landmark=False, fd_model_path=None, fr_model_path=None, params_path=None, license=None, gpu=0)¶ TF Local Face Detector
-
static
average_features
(features_lists)¶ - return the mean of all features in the list
- This allows us to directly input a list of tracked objects where some of them will have a list of features and some will not
Parameters: features_lists – list of features lists or None Returns:
-
batch_get_features
(image_array, batch_size=24, progress_bar=True)¶ - returns face features for a list of images
- this function does not perform any face detection but feeds the provided image directly to the model for batch feature extraction
Parameters: - image_array (list) –
- batch_size (int) –
- progress_bar (bool) –
-
batch_identify
(chips, collection='collection.npz', features=None, labels=None, threshold=0.25, return_features=False, length=512)¶ identify a batch of face chips by comparing it to a collection npz file
Parameters: - chips (list) – a list of face chips. (opencv images or numpy arrays)
- collection (str) – path to a collection npz file
- threshold (float) – similarity threshold over which to call it a match
- return_features (bool) – whether to return the features
- labels (list) – list of labels
- features (list) – list of corresponding features, this gets overloaded if you pass a collection
Returns: List of dictionaries with predicted_label and confidence as well as features if the return_features param was set to True
-
create_collection
(folder=None, output=None, images=None, labels=None, return_features=False, batch_size=8, db=False, mp=False)¶ creates a collection from a folder :param folder: path to folder holding images :type folder: str :param images: alternatively, you can pass a list of images :type images: list :param labels: labels corresponding to the images list.
You will have to pass both images and labels or neitherParameters: - output (str) – location for the generated npz collection file or the db name if a DBService object is being passed as the db parameter If this is None, the folder parameter will be used
- db (DBService) – DBService object that connects to a database
- return_features (bool) – whether to return the extracted features
- batch_size (int) – size of the batch to break the passed list into for processing
-
create_collection_directory
(folder, batch_size, mp)¶
-
delete_from_collection
(collection_filename, labels)¶ delete a label and the corresponding feature from a collection
Parameters: - collection_filename (str) – Path to an existing collection npz file
- labels (list) – list of labels to remove
Returns: updated collection
-
find_biggest_face
(img, return_chips=False, chip_size=112, padding=0.2, return_binary=False)¶ finds the biggest face in the image
Parameters: - img (image path, base64 encoded image, numpy array or OpenCV image) – image
- return_chips (bool) –
- chip_size (int) – size of face chip
- padding (float) –
- return_binary (bool) –
Returns: the detected box, points and chips if the return_binary param was set to True, or a json dict with the above data otherwise. The chip is only returned if the return_chips param was set to True
-
find_faces
(img, return_chips=False, chip_size=112, padding=0.2, return_binary=False)¶ finds all faces and returns chips
Parameters: - img (image path, base64 encoded image, numpy array or OpenCV image) – image
- return_chips (bool) –
- chip_size (int) – size of face chip
- padding (float) –
- return_binary (bool) –
Returns: the detected box, points and chips if the return_binary param was set to True, or a json dict with the above data otherwise. The chip is only returned if the return_chips param was set to True
-
get_features
(img, b64=False)¶ features of the biggest face found in the provided image
Parameters: - img (image path, base64 encoded image, numpy array or OpenCV image) – image
- b64 (bool) – whether to return embedding b64 encoded
-
get_match
(score, threshold, use_sim)¶ Return true or false related to score and threshold
Parameters: - score –
- threshold –
- use_sim – return true if score >= threshold, if use_sim is false, return true if score <= threshold
Returns: boolean
Return type: match
-
identify
(chip, collection=None, threshold=0.25, return_features=False, labels=None, features=None, length=512, db=False)¶ identify a face chip by comparing it to a collection npz file :param chip: face chip (padded image array) :type chip: opencv image or numpy array :param collection: path to a collection npz file :type collection: str :param features: list of features, this gets overloaded if you pass a collection :type features: list :param threshold: similarity threshold over which to call it a match :type threshold: float :param return_features: whether to return the features :type return_features: bool :param labels: whether to return the label :type labels: bool :param db: pass a DBService object if you want to use the DB backend to manage your collection :type db: DBService
Returns: A dictionary with predicted_label and confidence as well as features if the return_features param was set to True
-
impl_get_features
(img)¶ - returns face features for an image
- this function does not perform any face detection but feeds the provided image directly to the model for feature extraction
Parameters: img (opencv image or numpy array) – Returns: feature found in image
-
match_two_features
(source, target, use_sim=False, threshold=1.5)¶ Match two features
Parameters: - source – base64 encoded source feature
- target – base64 encoded source feature
- use_sim – if use_sim = True, we recommend a threshold of 0.25
- threshold –
-
match_two_images
(source, target, use_sim=False, threshold=1.5)¶ matches two images
Parameters: - source (path, base64, binary, OpenCV or nympy image) – source image to match
- target (path, base64, binary, OpenCV or nympy image) – target image to match
- use_sim (bool) – if use_sim = True, we recommend a threshold of 0.25
- threshold (float) –
-
read_collection_dir_parallel
(folder)¶ Load an image collection from disk using all available CPUs :param folder: path to collection folder :type folder: str
Returns: list of extracted features labels (list): list of corresponding labels Return type: features (list)
-
read_collection_dir_sequential
(folder)¶ Load an image collection from disk in sequence on one CPU
Parameters: folder (str) – path to collection folder Returns: list of extracted features labels (list): list of corresponding labels Return type: features (list)
-
update_collection
(input_folder, collection_filename=None, return_features=False)¶ Parameters: - input_folder (str) – Path to a folder with updated images
- collection_filename (str) – Path to an existing collection npz file
- return_features (bool) – Whether to return features from input_folder
Returns: json response with the path to the updated collection filename
-
static
-
class
trueface.recognition.
ObjectRecognizer
(ctx='cpu', model_path=None, params_path=None, license=None, method='ssd', conf_threshold=0.5, nms_threshold=0.4, dims=(None, None))¶ TF Local Object Detector
Parameters: - ctx – ‘cpu’ or ‘gpu’
- model_path – path to model
- params_path – path to params file
- license – your license token
- method – ‘ssd’ or ‘yolo’
- conf_threshold – set the conf_threshold
- nms_threshold – set the nms_threshold
- dims –
-
detect
(input, dims=None)¶ Detect object
Parameters: - input –
- dims –
Returns: list of results
-
non_max_suppression
(boxes, confidences)¶ Remove the bounding boxes with low confidence using non-max suppression
Parameters: - boxes – list of boxes
- confidences – list of corresponding confidence scores
Returns:
-
postprocess_mx_output
(outs, conf_threshold, nms_threshold=None, dims=None)¶ Scan through all the bounding boxes output from the network and keep only the ones with high confidence scores. Assign the box’s class label as the class with the highest score.
Parameters: - outs – list of outs
- conf_threshold – confidence threshold
- nms_threshold – NMS threshold
- dims – dimensions
Returns: filtered results
-
trueface.recognition.
response
(message, data)¶ return a json object
Parameters: - message –
- data –
Returns: a json object containing a message and a data field
Search Module
-
class
trueface.searching.
VideoSearch
(index='index.npy', video='video.avi', output=None, out_filename='results.avi', save_photos=False, random_name_len=5, recognizer=None, similarity_threshold=0.25)¶ VideoSearch class
Spoof detection module
-
class
trueface.spoof.
SpoofDetector
(model_path, params_path, token, ctx='cpu')¶ The spoof detector class
Parameters: - model_path – filesystem path to model
- params_path – filesystem path to params
- token – your token from creds.json
- ctx – the mxnet context, “cpu” or “gpu”
-
is_spoof
(image, threshold)¶ Returns true or false wheter image is a spoof based on threshold
Parameters: - image (numpy array or str) – if image is a string it will be read as a filepath
- threshold (float) – threshold between 0 and 1 below which we call it a spoof
Returns: true or false whether this is a spoof image
Return type: bool
-
spoof_probability
(image)¶ Returns probability that image passed is a spoof
Parameters: image (numpy array or str) – if image is a string it will be read as a filepath Returns: Probability this is a spoof from 0 to 1 Return type: float
Tracking module
-
class
trueface.tracking.
BaseTracker
(threshold=10.0, min_feats=1, track_movements=0, max_steps=20)¶ BaseTracker class
-
clean
()¶ clean tracked objects
-
draw_motion_tracks
(frame)¶ draw motion tracks on frame
-
find_tracked_object
(bbox, image)¶ Abstract method
-
remove_unknown_identities
()¶ remove unknown identities
-
track
(object_to_track, image, identity, chip=None, related_object=None)¶ Abstract method
-
update
(bboxes, chips, frame, features=None)¶ Abstract method
-
-
class
trueface.tracking.
COObjectTracker
(threshold, min_feats=1, track_movements=0, max_steps=20)¶ -
find_tracked_object
(obj, frame)¶ Matches passed obj to a tracked obj
-
track
(object_to_track, image, identity, chip=None, features=None, related_object=None)¶ Initiates the tracking of a obj
-
update
(bboxes, frame, chips=None, features=[])¶
-
update_trackers
(frame)¶ update trackers
-
-
class
trueface.tracking.
CVObjectTracker
(threshold, min_feats=1, track_movements=0, max_steps=20, tracker_type='KCF')¶ -
find_tracked_object
(obj, frame)¶ Matches passed obj to a tracked obj
-
track
(object_to_track, image, identity, chip=None, features=None, related_object=None)¶ track object
-
update
(bboxes, chips, frame, features=[])¶ Abstract method
-
utility methods
-
class
trueface.utils.
RedisQueue
(name, namespace='queue', **redis_kwargs)¶ Simple Queue with Redis Backend
The default connection parameters are: host=’localhost’, port=6379, db=0
-
empty
()¶ Return True if the queue is empty, False otherwise.
-
get
(block=True, timeout=None)¶ Remove and return an item from the queue.
If optional args block is true and timeout is None (the default), block if necessary until an item is available.
-
get_nowait
()¶ Equivalent to get(False).
-
put
(item)¶ Put item into the queue.
-
qsize
()¶ Return the approximate size of the queue.
-
Video module
-
class
trueface.video.
QVideoStream
(src=0, queue_size=128)¶ QVideoStream class
initialize the file video stream along with the boolean used to indicate if the thread should be stopped or not
Parameters: - src –
- queue_size –
-
start
()¶ start a thread to read frames from the file video stream :return: QVideoStream object
-
update
()¶ read and update the video stream
Returns: loops infinitely