Face Recognizer¶

Description¶

A face recognizer captures images from a camera and uses a Core ML model to classify them. Its intended use is to recognize the faces of specific experimental subjects, but the type of classification it performs depends entirely on the provided model. For information on obtaining or creating a suitable model, see Getting a Core ML Model.

On macOS, a face recognizer can use any camera (internal or external) that is supported by the operating system. On iOS, it always uses the built-in, front-facing, wide-angle camera.

Signature¶

iodevice/face_recognizer

Required Parameters¶

model_path¶

Filesystem path to a Core ML image classification model (i.e. a .mlmodel file).

Note: The experiment must also declare the model file as a File Resource, e.g.:

resource ('my_model.mlmodel')

iodevice/face_recognizer my_recognizer (
    model_path = 'my_model.mlmodel'
    ...
    )

identifier¶

Variable in which to store the most recent classification result (as a string), subject to minimum_confidence and required_matches. If classification fails to produce a valid result, the variable is set to an empty string.

image_capture_interval¶

Example: 250ms

Time interval between image captures. Must be greater than zero.

Optional Parameters¶

region_of_interest¶

Default: [0.0, 0.0, 1.0, 1.0]

Region of the image on which to perform classification.

The value of this parameter should be a four-element list of the form [x_min, y_min, x_max, y_max], where (x_min, y_min) and (x_max, y_max) are the coordinates of the lower-left and upper-right corners, respectively, of the region of interest. Each coordinate must be normalized to the dimensions of the image and lie between 0.0 and 1.0 (inclusive).

If this parameter is set to the name of a variable, the variable’s value can be changed at any time, even while the recognizer is running. This enables run-time refinement of recognizer performance via changes to the region of interest.

If this parameter is omitted, its value is not a list, or its value is an empty list, the entire image is used as input to the classifier.

minimum_confidence¶

Default: 0.0

Minimum confidence for a classification result to be considered valid. Must be between 0.0 and 1.0 (inclusive), where 1 is most confident.

result_history¶

Default: 1

Number of most recent classifications to consider when applying required_matches. Must be greater than or equal to 1.

required_matches¶

Default: 1

Number of most recent classifications that must give the same result in order for that result to be considered valid. Must be between 1 and the value of result_history (inclusive).

For example, if required_matches is 9, and result_history is 10, then 9 of the 10 most recent classification results must yield the same identifier in order for its value to be reported via the identifier parameter.

confidence¶

Variable in which to store the reported confidence for the most recent classification result. The value will be between 0.0 and 1.0 (inclusive), where 1 is most confident.

Note: The exact meaning of the confidence value depends on the model. If the model does not support confidence estimation, the value will always be 1.

camera_unique_id¶

If this parameter is omitted, and multiple cameras are detected, the face recognizer will fail to initialize. The error message reporting the failure will include the names and unique ID’s of all available cameras. To allow initialization to succeed, set the value of this parameter to the unique ID of the desired camera.

Note: This parameter is ignored on iOS, where the built-in, front-facing, wide-angle camera is always used.

image_logging_interval¶

Default: 0
Example: 60s

If greater than zero, determines the rate at which captured images are stored in the variable specified by image_data.

By enabling image logging, you can capture additional images of experimental subjects that can later be used to improve your model. In addition, MWClient’s Image Viewer window can display the logged images and provides a convenient interface for viewing and altering the current value of region_of_interest.

image_data¶

Variable in which to store logged images, as controlled by image_logging_interval. Each image is stored as a string containing JPEG-encoded data.

autostart¶

Default: NO

If YES, the device will start I/O automatically (as if by an implicit Start IO Device action) when the experiment starts running.

Note: Device I/O will always stop automatically when the experiment stops running, irrespective of this setting.

alt¶

Alternative device to use if this one fails to initialize (e.g. because the required hardware is not available). If #allowAltFailover is set to 0 or false, this parameter is ignored.

Placement¶

Allowed at top level:	Yes
Allowed parent:	Folder