Welcome to Trueface’s documentation!

trueface.age Age module
trueface.db DB Module
trueface.face_attributes module to handle face attributes like emotion
trueface.heartbeat Heartbeat detector
trueface.helper helper methods
trueface.motion Motion Detector module
trueface.object_detection Object Detection Module
trueface.recognition Recognition Module
trueface.reid_tracker Re-Id module
trueface.searching Search Module
trueface.spoof Spoof detection module
trueface.tracking Tracking module
trueface.utils utility methods
trueface.video Video module

Age module

class trueface.age.AgeDetector(model_path=None, params_path=None, license=None, ctx='cpu', set_weights=True)

AgeDetector class

Parameters:
  • model_path – path to the age model
  • params_path – path to params file
  • license – your license key
  • ctx – “gpu” or “cpu”
  • set_weights – True or false
predict(chip)

predict the age of the chip

Parameters:chip – image chip
Returns:predicted age
set_weights()

Set weights

DB Module

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(user='root', password='aez5Buem', host='127.0.0.1', port=3306, db_name='trueface_tests')

DBService class

Constructor for DBService class :param user: default: root :type user: str :param password: default: aez5Buem :type password: str :param host: mysql connect string, default:”127.0.0.1” :type host: str :param port: default: 3306 :type port: int :param db_name: default: “trueface_tests” :type db_name: str

create_collection(name, features=None, labels=None, imgpaths=None)

Create a new collection in the database :param name: table name of the new collection :type name: str :param features: list of features :type features: list :param labels: corresponding list of labels :type labels: list

Returns:labels labels: labels
Return type:features
delete_from_collection(collection_name, label)

Remove a label and the corresponding feature from a collection :param collection_name: table name of an existing collection :type collection_name: str :param labels: list of labels to remove :type labels: list

Returns:nothing
insert_into_collection(name, labels, features)

Insert features and labels into an existing collection :param name: name of the collection, this will become the table name :type name: str :param labels: list of labels :type labels: list :param features: list of corresponding features :type features: list

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, frames=100)

MotionDetector class

Object Detection Module

class trueface.object_detection.ObjectRecognizer(ctx='cpu', model_path=None, params_path=None, classes=None, license=None, 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
batch_predict(images)

Detect object

Parameters:images
Returns:list of results
compute_resize_scale(image_shape, min_side=512, max_side=700)

Compute an image scale such that the image size is constrained to min_side and max_side. :param min_side: The image’s min side will be equal to min_side after resizing. :param max_side: If after resizing the image’s max side is above max_side, resize until the max side is equal to max_side.

Returns:A resizing scale.
predict(image)

Detect object

Parameters:image
Returns:list of results
resize_image(img, min_side=512, max_side=700)

Resize an image such that the size is constrained to min_side and max_side. :param min_side: The image’s min side will be equal to min_side after resizing. :param max_side: If after resizing the image’s max side is above max_side, resize until the max side is equal to max_side.

Returns:A resized image.

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

Parameters:
  • images
  • 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

Parameters: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

Parameters:
  • ctx (str) – ‘cpu’ or ‘gpu’, memory and computation context
  • min_face (float) – minimum size of a face in pixels
  • accurate_landmark (bool) – use accurate landmark localization or not
  • fd_model_path (str) – path to the face detect model. For example fd_model
  • fr_model_path (str) – path to the face recognition model. For example model-lite/model.trueface
  • params_path (str) – path to the params file. For example model-lite/model.params
  • license (str) – your licsense token from creds.json
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, db=None, return_features=False, length=512, batch_size=24)

identify a batch of face chips by comparing it to a collection npz file, a list of features or a memsql table

Parameters:
  • chips (list) – a list of face chips. (opencv images or numpy arrays)
  • collection (str) – path to a collection npz file or the name of the collection the database
  • db (DBService) – DBService object or None if no database should be used
  • features (list) – list of corresponding features as numpy arrays
  • labels (list) – list of labels
  • return_features (bool) – whether to return the extracted features
  • threshold (float) – similarity threshold over which to call it a match
Returns:

List of dictionaries with predicted_label and confidence as well as features if the return_features param was set to True

create_collection(name, folder=None, images=None, labels=None, return_features=False, batch_size=8, db=False, mp=False)

creates a collection from a folder or from a list of features with corresponding labels. Creates an npz file by default or will write the collection to DB if a DBService object is passed

Parameters:
  • name (str) – location for the generated npz collection file or the table name if a DBService object is being passed
  • folder (str) – path to folder holding images
  • images (list) – alternatively, you can pass a list of images with corresponding labels
  • labels (list) – labels corresponding to the images list. You will have to pass both images and labels or neither
  • 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_arrays(images, labels, batch_size)

creates a collection from two arrays of images and labels

create_collection_directory(folder, batch_size=8, mp=None)

Create a list of labels and corresponding features out of a directory

delete_feature_from_collection(collection_filename, index_in_collection)

Remove an individual face feature from a collection

Parameters:
  • collection_filename (str) – Path to an existing collection npz file
  • feature (numpy array) – the feature as returend by identify for example
Returns:

updated collection

delete_from_collection(collection_filename, labels)

Remove a label and the corresponding features from a collection

Parameters:
  • collection_filename (str) – Path to an existing collection npz file
  • labels (list) – list of labels to delete
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 or database table

Parameters:
  • chip (opencv image or numpy array) – face chip (padded image array)
  • collection (str) – path to a collection npz file
  • features (list) – list of features, this gets overloaded if you pass a collection
  • threshold (float) – similarity threshold over which to call it a match
  • return_features (bool) – whether to return the features
  • labels (bool) – whether to return the label
  • db (DBService) – pass a DBService object if you want to use the DB backend to manage your collection
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) –
Returns:

JSON object with score, match and probability

read_collection_dir_parallel(folder)

Load an image collection from disk using all available CPUs

Parameters:folder (str) – path to collection folder
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=None, collection_filename=None, return_features=False, features=None, labels=None, db=None)

Update a collection by adding features and labels

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
  • features (list) – list of features
  • labels (list) – corresponding list of labels
  • db (DBService) – db object to write the collection to
Returns:

json response with the path to the updated collection filename

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

Re-Id module

class trueface.reid_tracker.VideoTracker(detector_weight_path=None, reid_weight_path=None, license=None, detector_threshold=0.5, detector_nms_threshold=0.4, max_dist=0.2, min_confidence=0.3, nms_overlap=0.5, iou_dist=0.7, max_age=9999, num_init=3, nn_budget=100, use_cuda=False)

Person re-identification tracker

Parameters:
  • detector_weight_path (str) – Path to detector (yolo) weights file. For example “~/yolo_v3.weights”.
  • re-id_weight_path (str) – Path to reid model. For example “~/reid.t7”.
  • license (str) – sdk license token given by Trueface team
  • detector_threshold (float) – Score threshold for detector.
  • detector_nms_threshold (float) – Non maximum suppression threshold for detections.
  • max_dist (float) – The matching threshold. Detections with larger distance are considered an invalid match.
  • min_confidence (float) – Min confidence for detections to be considered correct.
  • nms_overlap (float) – ROIs that overlap more than this values are suppressed.
  • iou_dist (float) – Gating threshold. Associations with cost larger than this value are disregarded.
  • max_age (int) – Maximum number frames with missed detections before a track is deleted.
  • num_init (int) – Number of consecutive detections before the track is confirmed. The track state is set to Deleted if a miss occurs within the first num_init frames.
  • nn_budget (int) – Fix samples per class to at most this number. Removes the oldest samples when the budget is reached.
  • use_cuda (bool) – Use cuda if set True and compatible gpu is available, otherwise use cpu.
Returns:

Array of bounding boxes and associated identities, class confidences.

draw_box(image, bbox, identities)

Draw bounding box around detected people

Parameters:
  • image (float array) – source image
  • bbox (list) – list of bounding boxes with format x1,y1,x2,y2
  • identities (list) – list of identities associated with bounding boxes
Returns:

Image with bounding box drawn around detected people

run(image)

Run person reid tracker

Parameters:image (float array) – Image to run tracker on
Returns:Identities, associated bounding boxes and class confidences for detected people

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

Parameters:
  • threshold (float) – default 10, value between 0 and 30
  • min_feats (integer) – minimum number of features to keep, used for multi frame inference
  • track_movements (integer) – value between 0 and 1, records movement of objects
  • max_steps (integer) – number of movements to keep in tracked object
clean()

clean tracked objects, removes idenities that fell below the threshold

draw_motion_tracks(frame)

draw motion tracks on frame :param frame: numpy/opencv frame to draw movements on

find_tracked_object(bbox, image)

Abstract method

remove_unknown_identities()

removes unknown identities that haven’t been identitied and that reached the max feature count

track(object_to_track, image, identity, chip=None, related_object=None)

Abstract method

update(bboxes, frame, chips=None, features=None)

Abstract method

class trueface.tracking.COObjectTracker(threshold, min_feats=1, track_movements=0, max_steps=20)

A tracker class utilizing a correlation based tracker :param threshold: default 10, value between 0 and 30 :type threshold: float :param min_feats: minimum number of features to keep, used for multi frame inference :type min_feats: integer :param track_movements: value between 0 and 1, records movement of objects :type track_movements: integer :param max_steps: number of movements to keep in tracked object :type max_steps: integer

find_tracked_object(obj, frame, track_movements=False, method=2, iou_threshold=0.6)

Matches passed obj to a tracked obj :param obj: rectangle containing tracked object to find from face detect call :param frame: opencv/numpy frame

Returns:quality measure that can be compared against the threshold matched_oid: id of matched object in the tracked object array bbox: bounding box of matched tracked object
Return type:quality
track(object_to_track, image, identity=None, chip=None, features=None, related_object=None)

Initiates the tracking of a obj :param object_to_track: rectangle containing object to track :type object_to_track: list :param image: numpy or opencv image :param identity: identity label if available :param chip: extracted face chip, used in face averaging and multi frame inference :param features: face recognition features, used in multi frame inference :param related_object: related tracked object

update(bboxes, frame, chips=None, features=None)

updates tracked object returning known and unkown objects in the frame :param bounding boxes: :param frame: numpy/opencv frame :param chips: optional, chips to store in tracked :type chips: numpy/opencv image :param objects: :param features: optional, features to store in tracked object :type features: array

Returns:an array of known_objects and unknown_objects
update_trackers(frame)

update bounding box positions of trackers Args: frame: numpy/opencv frame

class trueface.tracking.CVObjectTracker(threshold, min_feats=1, track_movements=0, max_steps=20, tracker_type='KCF')

A Tracking class that exposes 8 Opencv Trackers

Parameters:
  • threshold (float) – default 10, value between 0 and 30
  • min_feats (integer) – minimum number of features to keep, used for multi frame inference
  • track_movements (integer) – value between 0 and 1, records movement of objects
  • max_steps (integer) – number of movements to keep in tracked object
  • tracker_type (str) – one of the following choices (BOOSTING, MIL, TLD, MEDIANFLOW, GOTURN, MOSSE, CSRT)
find_tracked_object(obj, frame)

Matches passed obj to a tracked obj :param object: bounding box of object to find :param frame: numpy of opencv frame

Returns:boolean matched_oid: id of matched object in the tracked object array bbox: bounding box of matched object
Return type:found
track(object_to_track, image, identity, chip=None, features=None, related_object=None)

track object :param object_to_track: rectangle containing object to track :type object_to_track: list :param image: numpy or opencv image :param identity: identity label if avaliable :param chip: extracted face chip, used in face averaging and multi frame inference :param features: face recognition features, used in multi frame inference :param related_object: related tracked object

update(bboxes, frame, chips=[], features=[])

updates tracked object positions :param bounding boxes: :param frame: numpy/opencv frame :param chips: optional, chips to store in tracked objects :type chips: numpy/opencv image :param features: optional, features to store in tracked object :type features: array

Returns:an array of known_objects and unknown_objects

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.

trueface.utils.bbox_to_rect(bbox)

Convert a bounding box to a rectangle

Parameters:bbox – array with coordinates [top_left_x, top_left_y, width, height]
Returns:array with coordinates [top_left_x, top_left_y, bottom_right_x, bottom_right_y]
Return type:rectangle
trueface.utils.compute_color_for_labels(label)

Simple function that adds fixed color depending on the class

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

Indices and tables