 |
ROC SDK
2.4.0
Scalable Face Recognition Software
|
|
ROC SDK
2.4.0
Scalable Face Recognition Software
|
Process faces in an image. More...
Data Structures | |
| struct | roc_thumbnail_parameters |
| Set the characteristics of generated roc_template thumbnails. See ROC_THUMBNAIL for details. More... | |
Typedefs | |
| typedef struct roc_thumbnail_parameters | roc_thumbnail_parameters |
| Set the characteristics of generated roc_template thumbnails. See ROC_THUMBNAIL for details. More... | |
Functions | |
| roc_error | roc_get_thumbnail_parameters (roc_thumbnail_parameters *thumbnail_parameters) |
| Get the parameters used by ROC_THUMBNAIL in roc_represent. More... | |
| roc_error | roc_set_thumbnail_parameters (roc_thumbnail_parameters thumbnail_parameters) |
| Set the parameters used by ROC_THUMBNAIL in roc_represent. More... | |
| roc_error | roc_preload (roc_algorithm_id algorithm_id) |
| Pre-load the model files to be used by roc_represent. More... | |
| roc_error | roc_set_model_path (const char *path) |
| Set path to the object and/or text detection configuration files. More... | |
| roc_error | roc_represent (roc_image image, roc_algorithm_id algorithm_id, size_t min_size, int k, float false_detection_rate, float min_quality, roc_template *templates) |
| Detect faces and objects in an image. Process faces into templates for comparison. More... | |
| roc_error | roc_represent_roi (roc_image image, roc_algorithm_id algorithm_id, float relative_min_size, size_t absolute_min_size, size_t min_representation_size, int k, float false_detection_rate, float min_quality, const roc_roi *include, size_t num_include, const roc_roi *exclude, size_t num_exclude, float min_roi_overlap, const roc_string text_filter, const roc_thumbnail_parameters thumbnail_parameters, bool rotate_on_failure, roc_template *templates) |
| A generalization of roc_represent that supports additional fields specifying where in an image to process. This function also supports filtering text detections. This function computes Minimum Size internally. More... | |
| roc_error | roc_represent_fingerprint (roc_image image, roc_finger_id finger_id, const int resolution, const int k, float false_detection_rate, float min_quality, roc_template *templates) |
| Encode a fingerprint image into a ROC fingerprint template suitable for comparison and matching. More... | |
| roc_error | roc_merge_fingerprints (const roc_template *templates, int n, roc_template *merged) |
| Merge multiple individual fingerprint templates into a single comined template. More... | |
| roc_error | roc_representation_limit (size_t *representation_limit) |
| Query the remaining representation limit. More... | |
Process faces in an image.
Process faces in an image with roc_represent. Free a face roc_template after use with roc_free_template.
| struct roc_thumbnail_parameters |
Set the characteristics of generated roc_template thumbnails. See ROC_THUMBNAIL for details.
A width and height of -1 may be specified to use the roc_detection width and height.
As a special case, if scale is 0.0 then the full image will used as the thumbnail instead of the detection.
| typedef struct roc_thumbnail_parameters roc_thumbnail_parameters |
Set the characteristics of generated roc_template thumbnails. See ROC_THUMBNAIL for details.
A width and height of -1 may be specified to use the roc_detection width and height.
As a special case, if scale is 0.0 then the full image will used as the thumbnail instead of the detection.
| roc_error roc_get_thumbnail_parameters | ( | roc_thumbnail_parameters * | thumbnail_parameters | ) |
Get the parameters used by ROC_THUMBNAIL in roc_represent.
| [out] | thumbnail_parameters | roc_thumbnail_parameters object. |
| roc_error roc_set_thumbnail_parameters | ( | roc_thumbnail_parameters | thumbnail_parameters | ) |
Set the parameters used by ROC_THUMBNAIL in roc_represent.
| [in] | thumbnail_parameters | New roc_thumbnail_parameters settings. |
| roc_error roc_preload | ( | roc_algorithm_id | algorithm_id | ) |
Pre-load the model files to be used by roc_represent.
Call this function once after roc_initialize with the algorithm_id that will be used in roc_represent. See Lazy Initialization for details.
| [in] | algorithm_id | Pre-load the model files to be used by roc_represent for this roc_algorithm_id. |
| roc_error roc_set_model_path | ( | const char * | path | ) |
Set path to the object and/or text detection configuration files.
path is expected to point to the models folder of the SDK. This function must be called before a call to roc_preload or roc_represent in which ROC_ALL_OBJECT_DETECTION, ROC_TEXT_DETECTION or ROC_TEXT_REPRESENTATION is used.
| roc_error roc_represent | ( | roc_image | image, |
| roc_algorithm_id | algorithm_id, | ||
| size_t | min_size, | ||
| int | k, | ||
| float | false_detection_rate, | ||
| float | min_quality, | ||
| roc_template * | templates | ||
| ) |
Detect faces and objects in an image. Process faces into templates for comparison.
Each face and object is represented by a roc_template. In the case that the number of representable faces or objects is less than k, the trailing elements of templates will have roc_template::algorithm_id set to ROC_NO_ALGORITHM_OPTIONS. In the case that the number of representable faces is greater than k, the implementation will choose which faces to represent, see Maximum Faces for details. The populated templates will be returned sorted by decreasing roc_detection::confidence where faces are always prioritized over objects in the case that both are detected. Each constructed template will have roc_template::template_id initialized by roc_uuid_get_random.
Each roc_template in templates should be freed after use with roc_free_template. Templates with roc_algorithm_id equal to ROC_NO_ALGORITHM_OPTIONS do not have any allocated memory associated with them, freeing them is a no-op and therefore optional.
This function is exposed in the Command Line Interface as roc-represent.
The algorithm_id is a combination of roc_algorithm_options indicating how to process faces in an image. There are three components to an algorithm id: detection, representation and metadata. Components are combined together using a bitwise-or operation, as in Algorithm ID Examples. You do not need to specify ROC_TEMPLATE_VERSION, this will be added automatically.
The below options are available as face detection algorithms.
| Detection Options | Description |
|---|---|
| ROC_FRONTAL_DETECTION | Detect faces from -30 to +30 degrees yaw. |
| ROC_STANDARD_DETECTION | Detect faces from -100 to +100 degrees yaw with high accuracy. |
| ROC_MANUAL_DETECTION | Bypass automatic face detection by using caller-provided bounding boxes. |
| ROC_ALL_OBJECT_DETECTION | Detect all objects in an image. |
| None | Use ROC_FRONTAL_DETECTION. |
When ROC_STANDARD_DETECTION is specified, ROC_FRONTAL_DETECTION is ignored.
In the typical case, one option should be specified to indicate the desired face comparison mechanism. Detected objects will not be templatized. If no option is specified, roc_template::fv_size will be zero and the resulting roc_template can not be used in roc_compare_templates or roc_search.
| Representation Options | Description |
|---|---|
| ROC_STANDARD_REPRESENTATION | Represent faces for comparison. |
| ROC_DEEP_REPRESENTATION | Slower but more accurate alternative to ROC_STANDARD_REPRESENTATION. |
| ROC_FAST_REPRESENTATION | Faster but less accurate alternative to ROC_STANDARD_REPRESENTATION. |
| ROC_TATTOO_REPRESENTATION | Represent a law enforcement booking-style scar/mark/tattoo (SMT) image. |
| None | No template comparison needed. |
Each metadata option may be optionally included to add additional fields to the Metadata.
| Metadata Options | Description |
|---|---|
| ROC_PITCHYAW | Add Yaw and Pitch (degrees) estimation to the template metadata. |
| ROC_ANALYTICS | Estimate age, emotion, gaussian blur, geographic origin, gender, glasses, facial hair, artwork and mask detection. |
| ROC_LANDMARKS | Add the full set of landmark locations to the template metadata. |
| ROC_THUMBNAIL | An aligned and cropped face image suitable for displaying. |
| ROC_SPOOF | Add Spoof metric for static Face Liveness detection. |
| ROC_ICAO_METRICS | Compute ICAO face portrait quality measures. |
| ROC_ICAO_BACKGROUND | Compute ICAO uniform background face portrait quality metric. |
| None | No additional metadata needed. |
The min_size parameter indicates the smallest face to detect in an image. This parameter does not apply to object detection. Face detection size is measured by the width of the face in pixels. A larger value for min_size will result in faster execution speed and fewer false positives, as the image won't be scanned for smaller faces. While faces smaller than 20 pixels can be detected, they will be unreliable for recognition. Faces between 20 and 36 pixels can be used for recognition, albeit at a lower accuracy. A min_size less than 12 will be set to 12. Most applications should use roc_adaptive_minimum_size to compute a sensible minimum size relative to the image dimensions.
The parameter k indicates the maximum number of faces and objects to detect in an image. When k is less than the number of faces in the image, the faces with the highest roc_detection::width will be returned.
When k == -1 the following special-case behavior applies:
This is useful for enrolling controlled capture datasets where exactly one face is expected. In the general case where k == -N, at least 1 and up to N faces will be returned.
This setting has an analagous effect for object detection.
The false_detection_rate parameter specifies the allowable false positive rate for face detection. The suggested default value for false_detection_rate is ROC_SUGGESTED_FALSE_DETECTION_RATE which corresponds to one false detection in 50 images on an internal dataset similar to FDDB. A higher false detection rate will correctly detect more faces at the cost of also incorrectly detecting more non-faces. The accepted range of values for false_detection_rate is between 0 and 1 inclusive. Values outside this range will be truncated to the aforementioned bounds automatically.
The confidence values for detected objects do not have the same meaning as face detections. Thus, this parameter has no effect on objects detection and users can filter objects after calling roc_represent as desired.
See Face Quality.
The first call to roc_represent incurs additional overhead as the model files needed to execute the specified algorithm_id are loaded from disk. Call roc_preload beforehand to avoid incuring this overhead on the first call.
Identical templates are produced across all operating systems when provided the same input parameters. Templates are completely compatible when transferred to a different operating system.
For use cases that involve matching both masked and unmasked faces we recommend using all of the following flags:
To increase speed, the following changes will have the most impact:
min_size arm64-v8a SDK build instead of arm32-v7a, on Intel/AMD use the fma3 SDK build instead of sse4 | [in] | image | Input image to process for faces. |
| [in] | algorithm_id | Algorithm identifier, see Specifying an Algorithm ID. |
| [in] | min_size | Minimum size face to detect, see Minimum Size. |
| [in] | k | The desired number of face templates, see Maximum Faces. |
| [in] | false_detection_rate | The lower bound for face detection confidence, see False Detection Rate. |
| [in] | min_quality | Minimum Face Quality to templatize. |
| [out] | templates | Pre-allocated array to hold the generated templates. |
| roc_error roc_represent_roi | ( | roc_image | image, |
| roc_algorithm_id | algorithm_id, | ||
| float | relative_min_size, | ||
| size_t | absolute_min_size, | ||
| size_t | min_representation_size, | ||
| int | k, | ||
| float | false_detection_rate, | ||
| float | min_quality, | ||
| const roc_roi * | include, | ||
| size_t | num_include, | ||
| const roc_roi * | exclude, | ||
| size_t | num_exclude, | ||
| float | min_roi_overlap, | ||
| const roc_string | text_filter, | ||
| const roc_thumbnail_parameters | thumbnail_parameters, | ||
| bool | rotate_on_failure, | ||
| roc_template * | templates | ||
| ) |
A generalization of roc_represent that supports additional fields specifying where in an image to process. This function also supports filtering text detections. This function computes Minimum Size internally.
| [in] | image | Input image to process for faces. |
| [in] | algorithm_id | Algorithm identifier, see Specifying an Algorithm ID. |
| [in] | relative_min_size | Faces will be no smaller than this fraction of the image width and height. |
| [in] | absolute_min_size | Faces will be no smaller than this in pixels. |
| [in] | min_representation_size | Minimum size face in pixels to construct a feature vector, or 0 to represent all detected faces. |
| [in] | k | The desired number of face templates, see Maximum Faces. |
| [in] | false_detection_rate | The lower bound for face detection confidence, see False Detection Rate. |
| [in] | min_quality | Minimum Face Quality to templatize. |
| [in] | include | Regions of interest that detections must lie within, or NULL. |
| [in] | num_include | Length of include. |
| [in] | exclude | Regions of interest that detections must not lie within, or NULL. |
| [in] | num_exclude | Length of exclude. |
| [in] | min_roi_overlap | Minimum fraction of detection area that must be contained within include or exclude. Also used as the threshold for ROC_IGNORE_PARTIAL. |
| [in] | text_filter | Regular expressions describing text to check for in detection areas. |
| [in] | thumbnail_parameters | Settings used for generating template thumbnails. See ROC_THUMBNAIL. |
| [in] | rotate_on_failure | Rotate and reattempt failed templatizations for the input image. Function will attempt up to three 90 degree rotations. This argument generates an 'ImageRotation' field in the template Metadata. |
| [out] | templates | Pre-allocated array to hold the generated templates. |
| roc_error roc_represent_fingerprint | ( | roc_image | image, |
| roc_finger_id | finger_id, | ||
| const int | resolution, | ||
| const int | k, | ||
| float | false_detection_rate, | ||
| float | min_quality, | ||
| roc_template * | templates | ||
| ) |
Encode a fingerprint image into a ROC fingerprint template suitable for comparison and matching.
The returned templates should be freed after use with roc_free_template.
This function is exposed in the Command Line Interface as roc-represent.
The user is required to specify which finger created the provided print from the roc_finger_options list. If the user doesn't know the finger, they may specify ROC_UNKNOWN_FINGER to indicate the finger is unknown.
roc_finger_id can be combined as bit flags to express uncertainty, for example ROC_RIGHT_HAND | ROC_INDEX_FINGER | ROC_MIDDLE_FINGER indicates the finger is either the index or middle finger of the subject's right hand. This finger will be compared against both right hand index and middle fingers in a search.
If an image contains multiple fingers change the k value to the expected number of fingers in the image. If k >= 1, then finger_id should contain each finger expected to appear in the image. For example, a left hand four finger slap should have finger_id ROC_LEFT_HAND | ROC_FOUR_FINGERS and k equal to 4. The SDK will attempt to detect and assign the correct finger_id to k fingerprints. It is possible that detection will fail and fewer than k fingerprints will be returned. In this case, each returned fingerprint is assigned finger_id as its FingerID.
The output templates shall be pre-allocated but initialized array of length k.
The roc_template::algorithm_id will be automatically set to include ROC_FINGERPRINT_REPRESENTATION. If detection was run it will also include ROC_FINGERPRINT_DETECTION.
Fingerprint sensors have a fixed capture resolution given in pixels per inch or PPI. 500 and 1000 are common PPI values, but any resolution is supported.
A metric indicating how accurately a template will perform in recognition.
A higher fingerprint quality (or "finger matchability") value indicates a lower false non-match rate. The metric provides the number of standard deviations a template is from an average template. Lower quality templates will have a negative quality score.
See roc_merge_fingerprints for a method to merge individual finger templates into a ten print set.
| [in] | image | The grayscale input image containing one fingerprint. |
| [in] | finger_id | The index of the finger that created the print. See Specifying a Finger ID. |
| [in] | resolution | The resolution of the image. See Fingerprint Resolution. |
| [in] | k | The expected number of fingerprints in the image. At most k fingerprints will be detected and templatized. |
| [in] | false_detection_rate | The lower bound for fingerprint detection |
| [in] | min_quality | Minimum Fingerprint Quality to templatize. |
| [out] | templates | A preallocated output array of templates holding the representation of each fingerprint. The length of this array is determined by finger_id. |
| roc_error roc_merge_fingerprints | ( | const roc_template * | templates, |
| int | n, | ||
| roc_template * | merged | ||
| ) |
Merge multiple individual fingerprint templates into a single comined template.
The combined representation is useful to group multiple fingers from one encounter with the same individual when multiple fingers are collected. A merged template should contain at most one instance of each finger.
| [in] | templates | An array of templates of length n to merge. The templates should contain a unique set of fingers. |
| [in] | n | The length of templates. |
| [out] | merged | A single merged template containing all individual finger templates. |
| roc_error roc_representation_limit | ( | size_t * | representation_limit | ) |
Query the remaining representation limit.
Some licenses of the ROC SDK include a limit to the number of representations that can be made over the lifetime of the license. The number of representations is the number of times roc_represent has been called. This function returns the number of representations specified in the license file less the number of representations used to date.
| [out] | representation_limit | The remaining number of representations available. |
1.8.15