Welcome to Trueface’s documentation!

trueface.access_control access control integrations and related utilities
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

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(token, ctx='cpu')

The BaseRecognizer class

batch_make_mx_input(images, dims=(512, 512))

use a list of images to make mx input

batch_preprocess_image(images, dims=(512, 512))

resize, color convert and transpose a list of images

Parameters:
  • images – list of images
  • dims (tuple) – tuple with dimensions to resize to
Returns:

list of processed images
blur_region(region, frame)

blurs a region in the image

cosine_sim(feature, collection_features, length=512)

Cosine Similarity with mxnet

draw_box(img, box)

draws a box on the frame

draw_label(image, point, label, font=0, font_scale=0.5, thickness=1)

Draw label on the video

get_image(_bin, rgb=True)

gets an image from a path or from base64 and returns binary (BGR2RGB)

Parameters:
  • _bin (str) – filepath or base64 representation of an image
  • rgb (bool) – whether to convert image to RGB
Returns:

the image
get_string_from_cv2(image, encode=False)

Gets a string from a cv2 image

make_cv_input(image)

make cv input

make_mx_input(image, dims=(512, 512))

make mx input

preprocess_image(image, dims=(512, 512))

resize, color convert and transpose the image

Parameters:
  • image – input image
  • dims (tuple) – tuple with dimensions to resize to
Returns:

processed image
class trueface.recognition.Batch(data)

Create new instance of Batch(data,)

data

Alias for field number 0

class trueface.recognition.ColorRecognizer(n_clusters=10)

ColorRecognizer class

centroid_histogram()

grab the number of different clusters and create a histogram based on the number of pixels assigned to each cluster

detect(img)

detect color

class trueface.recognition.FaceRecognizer(ctx='cpu', min_face=40, accurate_landmark=False, fd_model_path=None, fr_model_path=None, params_path=None, token=None)

TF Local Face Detector

static average_features(features_lists)

average features

batch_get_features(img, return_list=False)

returns face features for an image

batch_identify(chips, collection='collection.npz', threshold=0.25, return_features=False)

identify a list of face chips against a collection

create_collection(folder, output_path, return_features=False)

creates a collection from a folder

find_biggest_face(img, return_chips=False, chip_size=112, padding=0.2, return_binary=False)

finds the biggest face

find_faces(img, return_chips=False, chip_size=112, padding=0.2, return_binary=False)

finds all faces and returns chips

get_features(img, b64=False)

returns features for a face

get_match(score, threshold, use_sim)

get match

identify(chip, collection='collection.npz', threshold=0.25, return_features=False)

identify a face chip against a collection

impl_batch_identify(features, collection='collection.npz', threshold=0.25)

identify a list of features against a collection

impl_get_features(img, return_list=False)

returns face features for an image

match_two_features(source, target, use_sim=False, threshold=1.5)

Match two features

match_two_images(source, target, use_sim=False, threshold=1.5)

matches two images

read_collection_dir_parallel(folder)

read a directory of images using all cpu’s and return features and labels

read_collection_dir_sequential(folder)

read a directory of images using one cpu and return features and labels

update_collection(input_folder, collection_filename, return_features=False)

update an existing collection based on a folder of images

class trueface.recognition.ObjectRecognizer(ctx='cpu', model_path=None, params_path=None, token=None, method='ssd', conf_threshold=0.5, nms_threshold=0.4, dims=(640, 480))

TF Local Object Detector

detect(input)

detect objects

non_max_suppression(boxes, confidences)

Remove the bounding boxes with low confidence using non-max suppression

postprocess_mx_output(outs, conf_threshold, nms_threshold)

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.

trueface.recognition.response(message, data)

Returns message and data as a json object

Parameters:
  • message (str) – text you want to respond with
  • data (str) – content of the data field
Returns:

json object of format ‘{“message”: message, “data”: data}’
Return type:

str

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 (str) – filesystem path to model
  • params_path (str) – filesystem path to params
  • token (str) – your token from creds.json
  • ctx (str) – 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)
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, chips, frame, features=[])
update_trackers(frame)

update trackers

class trueface.tracking.CVObjectTracker(threshold, min_feats=1, track_movements=0, 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

Video module

Indices and tables