The ROC_FAST_REPRESENTATION and comparison algorithm in a bare-bones dependency-free shared library for ARM CPUs. More...

Data Structures
struct	roc_embedded_gender
	Data structure for gender estimation. More...

struct	roc_embedded_geographic_origin
	Data structure for geographic origin estimation. More...

struct	roc_embedded_emotion
	Data structure for emotion estimation. More...

struct	roc_embedded_artwork
	Data structure for artwork estimation. More...

struct	roc_embedded_glasses
	Data structure for glasses estimation. More...

struct	roc_embedded_mask
	Data structure for mask estimation. More...

struct	roc_embedded_array
	A very simple variable-length array implementation. More...

Typedefs
typedef enum roc_embedded_error	roc_embedded_error
	Embedded function return value error codes.

typedef struct roc_embedded_gender	roc_embedded_gender
	Data structure for gender estimation.

typedef struct roc_embedded_geographic_origin	roc_embedded_geographic_origin
	Data structure for geographic origin estimation.

typedef struct roc_embedded_emotion	roc_embedded_emotion
	Data structure for emotion estimation.

typedef struct roc_embedded_artwork	roc_embedded_artwork
	Data structure for artwork estimation.

typedef struct roc_embedded_glasses	roc_embedded_glasses
	Data structure for glasses estimation.

typedef struct roc_embedded_mask	roc_embedded_mask
	Data structure for mask estimation.

typedef struct roc_embedded_array	roc_embedded_array
	A very simple variable-length array implementation. More...

Enumerations
enum	roc_embedded_error { ROC_NOT_SUPPORTED = -1, ROC_SUCCESS = 0, ROC_ERROR_LICENSE = 1, ROC_ERROR_MALLOC = 2, ROC_ERROR_COLORSPACE = 3, ROC_ERROR_LICENSE_FILE = 4, ROC_ERROR_LICENSE_UNSUPPORTED = 5, ROC_ERROR_LICENSE_LOCKED = 6, ROC_ERROR_SNPE_RUNTIME_NOT_INITALIZED = 7, ROC_ERROR_SNPE_EXECUTE_FAILED = 8 }
	Embedded function return value error codes. More...

Functions
roc_embedded_error	roc_embedded_initialize (const char *license_file)
	Call once at the start of the application before making any other calls to the API. More...

roc_embedded_error	roc_embedded_finalize ()
	Call once at the end of the application after making all other calls to the API. More...

const char *	roc_embedded_error_to_string (roc_embedded_error error)
	Convert an error to a string for messaging. More...

roc_embedded_error	roc_embedded_detect_faces (roc_image image, size_t min_size, int k, float false_detection_rate, size_t n, roc_detection detections)
	Detect faces in an image. More...

roc_embedded_error	roc_embedded_detect_faces_accurate (roc_image image, size_t min_size, int k, float false_detection_rate, size_t n, roc_detection detections)
	Detect faces in an image. This uses a more accurate but slightly slower algorithm compared with roc_embedded_detect_faces. More...

roc_error	roc_landmarks_to_detection (const roc_landmark right_eye, const roc_landmark left_eye, const roc_landmark chin, roc_detection detection)
	Estimate the face detection bounding box and pose from landmarks. More...

int	roc_num_landmarks_for_pose (roc_pose pose)
	Returns the number of landmarks computed for the specified pose. More...

roc_embedded_error	roc_embedded_landmark_face (roc_image image, roc_detection detection, roc_landmark landmarks, roc_landmark right_eye, roc_landmark left_eye, roc_landmark chin, float pitch, float *yaw)
	Landmark a face detection. More...

roc_embedded_error	roc_embedded_liveness (roc_image image, roc_landmark right_eye, roc_landmark left_eye, roc_landmark chin, float *spoof)
	Compute ROC_SPOOF face liveness metric. More...

roc_embedded_error	roc_embedded_represent_face (roc_image image, roc_detection detection, roc_landmark right_eye, roc_landmark left_eye, roc_landmark chin, uint8_t feature_vector, float quality, float age, float facial_hair, roc_embedded_gender gender, roc_embedded_geographic_origin geographic_origin, roc_embedded_emotion emotion, roc_embedded_artwork artwork, roc_embedded_glasses glasses, roc_embedded_mask mask, float spoof, float gaussianblur)
	Extract a ROC_FAST_REPRESENTATION feature vector from a face detection. More...

roc_embedded_error	roc_embedded_represent_face_unlocked (roc_image image, roc_detection detection, roc_landmark right_eye, roc_landmark left_eye, roc_landmark chin, float unlocked_feature_vector, float quality, float age, float facial_hair, roc_embedded_gender gender, roc_embedded_geographic_origin geographic_origin, roc_embedded_emotion emotion, roc_embedded_artwork artwork, roc_embedded_glasses glasses, roc_embedded_mask mask, float spoof, float gaussianblur)
	Extract an "unlocked" ROC_FAST_REPRESENTATION feature vector from a face detection. More...

roc_similarity	roc_embedded_compare_templates (const uint8_t a, size_t a_size, const uint8_t b, size_t b_size)
	Static alternative to roc_compare_templates. More...

void	roc_embedded_array_initialize (roc_embedded_array *array, int element_size)
	Initialize a roc_array for use by informing it of the element size it will contain. More...

roc_embedded_error	roc_embedded_array_append (roc_embedded_array array, const void element)
	Append an element to the end of the array. More...

void	roc_embedded_array_get (roc_embedded_array array, int index, void *element)
	Retrieve an element from the array. More...

void	roc_embedded_array_free (roc_embedded_array *array)
	Free memory associated with the array. More...

uint32_t	roc_embedded_checksum (const uint8_t *data, const int size)
	32-bit CRC checksum. More...

Detailed Description

The ROC_FAST_REPRESENTATION and comparison algorithm in a bare-bones dependency-free shared library for ARM CPUs.

Usage

Include roc-embedded.h instead of roc.h. Link against roc_embedded instead of roc. For the Java wrapper use the java/embedded folder, for C# use the csharp/embedded folder.

The embedded library offers the following primary functions:

For convenience to the evaluation harness, the embedded library also exposes a very simple variable-length array and checksum implementation:

Finally, the following standard SDK components are also available:

Data Structure Documentation

◆ roc_embedded_gender

struct roc_embedded_gender

Data structure for gender estimation.

Data Fields
float	female	See ROC_ANALYTICS.
float	male	See ROC_ANALYTICS.

◆ roc_embedded_geographic_origin

struct roc_embedded_geographic_origin

Data structure for geographic origin estimation.

Data Fields
float	african	See ROC_ANALYTICS.
float	east_asian	See ROC_ANALYTICS.
float	european	See ROC_ANALYTICS.
float	latin_american	See ROC_ANALYTICS.
float	middle_eastern	See ROC_ANALYTICS.
float	south_asian	See ROC_ANALYTICS.
float	southeast_asian	See ROC_ANALYTICS.

◆ roc_embedded_emotion

struct roc_embedded_emotion

Data structure for emotion estimation.

Data Fields
float	anger	See ROC_ANALYTICS.
float	disgust	See ROC_ANALYTICS.
float	fear	See ROC_ANALYTICS.
float	joy	See ROC_ANALYTICS.
float	neutral	See ROC_ANALYTICS.
float	sadness	See ROC_ANALYTICS.
float	surprise	See ROC_ANALYTICS.

◆ roc_embedded_artwork

struct roc_embedded_artwork

Data structure for artwork estimation.

Data Fields
float	cartoon	See ROC_ANALYTICS.
float	human	See ROC_ANALYTICS.
float	painting	See ROC_ANALYTICS.

◆ roc_embedded_glasses

struct roc_embedded_glasses

Data structure for glasses estimation.

Data Fields
float	none	See ROC_ANALYTICS.
float	sun	See ROC_ANALYTICS.
float	eye	See ROC_ANALYTICS.

◆ roc_embedded_mask

struct roc_embedded_mask

Data structure for mask estimation.

Data Fields
float	mask	See ROC_ANALYTICS.
float	no_mask	See ROC_ANALYTICS.

◆ roc_embedded_array

struct roc_embedded_array

A very simple variable-length array implementation.

Example: The following example prints 0 1 4 9 .

roc_embedded_array numbers;
roc_embedded_array_initialize(&numbers, sizeof(size_t));
for (int i=0; i<4; i++) {
    const size_t val = i*i;
    roc_embedded_array_append(&numbers, &val);
}
for (int i=0; i<numbers.size; i++) {
    size_t val;
    roc_embedded_array_get(numbers, i, &val);
    printf("%zu ", val);
}
roc_embedded_array_free(&numbers);

Data Fields
int	element_size	`sizeof` of each element in data.
int	size	Number of elements in data.
char *	data	Buffer containing size elements.

Typedef Documentation

◆ roc_embedded_array

typedef struct roc_embedded_array roc_embedded_array

A very simple variable-length array implementation.

Example: The following example prints 0 1 4 9 .

roc_embedded_array numbers;
roc_embedded_array_initialize(&numbers, sizeof(size_t));
for (int i=0; i<4; i++) {
    const size_t val = i*i;
    roc_embedded_array_append(&numbers, &val);
}
for (int i=0; i<numbers.size; i++) {
    size_t val;
    roc_embedded_array_get(numbers, i, &val);
    printf("%zu ", val);
}
roc_embedded_array_free(&numbers);

Enumeration Type Documentation

◆ roc_embedded_error

enum roc_embedded_error

Embedded function return value error codes.

Enumerator
ROC_NOT_SUPPORTED	The function call is not supported on this platform.
ROC_SUCCESS	The function call completed successfully.
ROC_ERROR_LICENSE	Invalid license.
ROC_ERROR_MALLOC	Call to `malloc` failed.
ROC_ERROR_COLORSPACE	Expected ROC_GRAY8 image but provided a ROC_BGR24 image, or vice-versa.
ROC_ERROR_LICENSE_FILE	Error reading the license file.
ROC_ERROR_LICENSE_UNSUPPORTED	This license file can't be used for the Embedded SDK.
ROC_ERROR_LICENSE_LOCKED	This license file does not support unlocked feature vectors.
ROC_ERROR_SNPE_RUNTIME_NOT_INITALIZED	Attempted to use Snapdragon acceleration without first calling roc_enable_snpe.
ROC_ERROR_SNPE_EXECUTE_FAILED	Encountered internal error while attempting to use Snapdragon acceleration.

Function Documentation

◆ roc_embedded_initialize()

roc_embedded_error roc_embedded_initialize ( const char * license_file )

Call once at the start of the application before making any other calls to the API.

Similar interface to roc_initialize however Usage Logging is not supported.

Example: roc_embedded_initialize(NULL);

Parameters

[in] license_file See License File.

Remarks: This function is thread-unsafe and must only be called once.

See also: roc_embedded_finalize

◆ roc_embedded_finalize()

roc_embedded_error roc_embedded_finalize ( )

Call once at the end of the application after making all other calls to the API.

This will free memory allocated during initialization. Calling roc_embedded_initialize after this function to re-initialize the SDK is not supported.

Example: roc_embedded_finalize();

Remarks: This function is thread-unsafe and must only be called once.

See also: roc_initialize

◆ roc_embedded_error_to_string()

const char* roc_embedded_error_to_string ( roc_embedded_error error )

Convert an error to a string for messaging.

Memory for the returned string is managed internally and should not be freed. If error is ROC_SUCCESS this function returns NULL.

Example: roc_embedded_error error = ...;
roc_ensure(roc_embedded_error_to_string(error));

Parameters

[in] error Error to convert to a string.

Remarks: This function is thread-safe.

See also: roc_ensure

◆ roc_embedded_detect_faces()

roc_embedded_error roc_embedded_detect_faces	(	roc_image	image,
		size_t	min_size,
		int	k,
		float	false_detection_rate,
		size_t *	n,
		roc_detection *	detections
	)

Detect faces in an image.

Image must be ROC_GRAY8.

The initial n elements of faces will be ordered by face_confidence. The trailing k-n elements will be uninitialized.

Parameters

[in]	image	Image to detect faces in.
[in]	min_size	Minimum size face to detect, see Minimum Size.
[in]	k	The maximum number of faces to detect, see Maximum Faces.
[in]	false_detection_rate	The lower bound for face detection confidence, see False Detection Rate.
[out]	n	The number of faces actually detected.
[out]	detections	Array of `k` elements to store the detected faces.

Remarks: This function is thread-safe.

See also: roc_embedded_detect_faces_accurate

◆ roc_embedded_detect_faces_accurate()

roc_embedded_error roc_embedded_detect_faces_accurate	(	roc_image	image,
		size_t	min_size,
		int	k,
		float	false_detection_rate,
		size_t *	n,
		roc_detection *	detections
	)

Detect faces in an image. This uses a more accurate but slightly slower algorithm compared with roc_embedded_detect_faces.

Image must be ROC_BGR24.

The initial n elements of faces will be ordered by face_confidence. The trailing k-n elements will be uninitialized.

Parameters

[in]	image	Image to detect faces in.
[in]	min_size	Minimum size face to detect, see Minimum Size.
[in]	k	The maximum number of faces to detect, see Maximum Faces.
[in]	false_detection_rate	The lower bound for face detection confidence, see False Detection Rate.
[out]	n	The number of faces actually detected.
[out]	detections	Array of `k` elements to store the detected faces.

Remarks: This function is thread-safe.

See also: roc_embedded_detect_faces

◆ roc_landmarks_to_detection()

roc_error roc_landmarks_to_detection	(	const roc_landmark *	right_eye,
		const roc_landmark *	left_eye,
		const roc_landmark *	chin,
		roc_detection *	detection
	)

Estimate the face detection bounding box and pose from landmarks.

Used for face representation with ROC_MANUAL_DETECTION. The eyes and chin may come from another source (e.g. human annotator or third-party algorithm) provided that the eye locations correspond to the center of the eye socket and the chin location corresponds to the bottom-center of the lower jaw.

Frontal vs. Profile

A face is considered profile if the head yaw is severe enough to make only one eye visible.

To indicate an eye or the chin is not visible, provide a NULL value to the relevant landmark. Two of the three landmarks must be non-null. If all three landmarks are non-null the face is considered frontal.

Right vs. Left

The right and left sides of the face are defined from the perspective of the subject, not the image. Thus, for a frontal facing image, the right eye is the one with the lesser x location, and the left eye is the one with the greater x location. Similarly, for a profile facing image, a right-profile face is one where only the right eye is visible, and a left-profile face is one where only the left eye is visible.

Example: roc_landmark right_eye = ...;
roc_landmark left_eye = ...;
roc_landmark chin = ...;
roc_detection detection;
roc_landmarks_to_detection(&right_eye,
&left_eye,
&chin,
&detection);

Parameters

[in]	right_eye	Right eye location if visible, or `NULL`.
[in]	left_eye	Left eye location if visible, or `NULL`.
[in]	chin	Chin location if visible, or `NULL`.
[out]	detection	Face detection, see roc_detection.

◆ roc_num_landmarks_for_pose()

int roc_num_landmarks_for_pose ( roc_pose pose )

Returns the number of landmarks computed for the specified pose.

Parameters

[in] pose Pose that determines the number of landmarks.

Remarks: This function is thread-safe.

◆ roc_embedded_landmark_face()

roc_embedded_error roc_embedded_landmark_face	(	roc_image	image,
		roc_detection *	detection,
		roc_landmark *	landmarks,
		roc_landmark *	right_eye,
		roc_landmark *	left_eye,
		roc_landmark *	chin,
		float *	pitch,
		float *	yaw
	)

Landmark a face detection.

Image must be ROC_GRAY8.

Pose values pitch and yaw may be NULL to skip computation of these values if they are not needed.

Parameters

[in]	image	Image to landmark face detection in.
[in,out]	detection	Face to landmark, updated with fine-grained rotation.
[out]	landmarks	Array of length roc_num_landmarks_for_pose to store the detected landmarks.
[out]	right_eye	Right eye location.
[out]	left_eye	Left eye location.
[out]	chin	Chin location.
[out]	pitch	Optional face pitch (degrees), see ROC_PITCHYAW.
[out]	yaw	Optional face yaw (degrees), see ROC_PITCHYAW.

Remarks: This function is thread-safe.

◆ roc_embedded_liveness()

roc_embedded_error roc_embedded_liveness	(	roc_image	image,
		roc_landmark	right_eye,
		roc_landmark	left_eye,
		roc_landmark	chin,
		float *	spoof
	)

Compute ROC_SPOOF face liveness metric.

Image must be ROC_GRAY8. To maximize accuracy, average the response from this function with the spoof response from roc_embedded_represent_face.

Parameters

[in]	image	Image to compute liveness from.
[in]	right_eye	Right eye location from roc_embedded_landmark_face.
[in]	left_eye	Left eye location from roc_embedded_landmark_face.
[in]	chin	Chin location from roc_embedded_landmark_face.
[out]	spoof	Output liveness response.

Remarks: This function is thread-safe.

See also: roc_embedded_represent_face

◆ roc_embedded_represent_face()

roc_embedded_error roc_embedded_represent_face	(	roc_image	image,
		roc_detection	detection,
		roc_landmark	right_eye,
		roc_landmark	left_eye,
		roc_landmark	chin,
		uint8_t *	feature_vector,
		float *	quality,
		float *	age,
		float *	facial_hair,
		roc_embedded_gender *	gender,
		roc_embedded_geographic_origin *	geographic_origin,
		roc_embedded_emotion *	emotion,
		roc_embedded_artwork *	artwork,
		roc_embedded_glasses *	glasses,
		roc_embedded_mask *	mask,
		float *	spoof,
		float *	gaussianblur
	)

Extract a ROC_FAST_REPRESENTATION feature vector from a face detection.

Image must be ROC_BGR24.

Parameters

[in]	image	Image to landmark face detection in.
[in]	detection	Face to extract feature vector from.
[in]	right_eye	Right eye location.
[in]	left_eye	Left eye location.
[in]	chin	Chin location.
[out]	feature_vector	Optional pre-allocated uninitialized buffer of ROC_FAST_FV_SIZE bytes to hold the template.
[out]	quality	Optional Face Quality.
[out]	age	Optional age estimation, see ROC_ANALYTICS.
[out]	facial_hair	Optional facial hair estimation, see ROC_ANALYTICS.
[out]	gender	Optional gender estimation, see ROC_ANALYTICS.
[out]	geographic_origin	Optional geographic origin estimation, see ROC_ANALYTICS.
[out]	emotion	Optional emotion estimation, see ROC_ANALYTICS.
[out]	artwork	Optional artwork estimation, see ROC_ANALYTICS.
[out]	glasses	Optional glasses estimation, see ROC_ANALYTICS.
[out]	mask	Optional mask estimation, see ROC_ANALYTICS.
[out]	spoof	Optional spoof response, see ROC_SPOOF. Average this value with roc_embedded_liveness.
[out]	gaussianblur	Optional gaussian blur estimation, see ROC_ANALYTICS.

Remarks: This function is thread-safe.

◆ roc_embedded_represent_face_unlocked()

roc_embedded_error roc_embedded_represent_face_unlocked	(	roc_image	image,
		roc_detection	detection,
		roc_landmark	right_eye,
		roc_landmark	left_eye,
		roc_landmark	chin,
		float *	unlocked_feature_vector,
		float *	quality,
		float *	age,
		float *	facial_hair,
		roc_embedded_gender *	gender,
		roc_embedded_geographic_origin *	geographic_origin,
		roc_embedded_emotion *	emotion,
		roc_embedded_artwork *	artwork,
		roc_embedded_glasses *	glasses,
		roc_embedded_mask *	mask,
		float *	spoof,
		float *	gaussianblur
	)

Extract an "unlocked" ROC_FAST_REPRESENTATION feature vector from a face detection.

Image must be ROC_GRAY8.

Parameters

[in]	image	Image to landmark face detection in.
[in]	detection	Face to extract feature vector from.
[in]	right_eye	Right eye location.
[in]	left_eye	Left eye location.
[in]	chin	Chin location.
[out]	unlocked_feature_vector	Pre-allocated uninitialized array of 512 elements to hold the unlocked feature vector that can be compared to other unlocked feature vectors using a Euclidean distance.
[out]	quality	Optional Face Quality.
[out]	age	Optional age estimation, see ROC_ANALYTICS.
[out]	facial_hair	Optional facial hair estimation, see ROC_ANALYTICS.
[out]	gender	Optional gender estimation, see ROC_ANALYTICS.
[out]	geographic_origin	Optional geographic origin estimation, see ROC_ANALYTICS.
[out]	emotion	Optional emotion estimation, see ROC_ANALYTICS.
[out]	artwork	Optional artwork estimation, see ROC_ANALYTICS.
[out]	glasses	Optional glasses estimation, see ROC_ANALYTICS.
[out]	mask	Optional mask estimation, see ROC_ANALYTICS.
[out]	spoof	Optional spoof response, see ROC_SPOOF. Average this value with roc_embedded_liveness.
[out]	gaussianblur	Optional gaussian blur estimation, see ROC_ANALYTICS

Remarks: This function is thread-safe.

◆ roc_embedded_compare_templates()

roc_similarity roc_embedded_compare_templates	(	const uint8_t *	a,
		size_t	a_size,
		const uint8_t *	b,
		size_t	b_size
	)

Static alternative to roc_compare_templates.

See roc_compare_templates for details.

Parameters

[in]	a	Feature vector for the first template.
[in]	a_size	Length of `a`.
[in]	b	Feature vector for the second template.
[in]	b_size	Length of `b`.

Remarks: This function is thread-safe.

◆ roc_embedded_array_initialize()

void roc_embedded_array_initialize	(	roc_embedded_array *	array,
		int	element_size
	)

Initialize a roc_array for use by informing it of the element size it will contain.

Parameters

[in]	array	Un-initialized array to initialize.
[in]	element_size	Size of each element to be held in `array`.

Remarks: This function is thread-safe.

◆ roc_embedded_array_append()

roc_embedded_error roc_embedded_array_append	(	roc_embedded_array *	array,
		const void *	element
	)

Append an element to the end of the array.

Parameters

[in]	array	Array to append the element to.
[in]	element	Element to append to the array.

Remarks: This function is reentrant.

◆ roc_embedded_array_get()

void roc_embedded_array_get	(	roc_embedded_array	array,
		int	index,
		void *	element
	)

Retrieve an element from the array.

Index is assumed to be within bounds.

Parameters

[in]	array	Array to retrieve the element from.
[in]	index	Index of the element to retrieve.
[out]	element	Pre-allocated memory to hold the value.

Remarks: This function is thread-safe.

◆ roc_embedded_array_free()

void roc_embedded_array_free ( roc_embedded_array * array )

Free memory associated with the array.

Parameters

[in] array Array to deallocate.

Remarks: This function is reentrant.

◆ roc_embedded_checksum()

uint32_t roc_embedded_checksum	(	const uint8_t *	data,
		const int	size
	)

32-bit CRC checksum.

Parameters

[in]	data	Data to checksum.
[in]	size	Length of `data`.

Remarks: This function is thread-safe.

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Usage

Data Structure Documentation

◆ roc_embedded_gender

◆ roc_embedded_geographic_origin

◆ roc_embedded_emotion

◆ roc_embedded_artwork

◆ roc_embedded_glasses

◆ roc_embedded_mask

◆ roc_embedded_array

Typedef Documentation

◆ roc_embedded_array

Enumeration Type Documentation

◆ roc_embedded_error

Function Documentation

◆ roc_embedded_initialize()

◆ roc_embedded_finalize()

◆ roc_embedded_error_to_string()

◆ roc_embedded_detect_faces()

◆ roc_embedded_detect_faces_accurate()

◆ roc_landmarks_to_detection()

Frontal vs. Profile

Right vs. Left

◆ roc_num_landmarks_for_pose()

◆ roc_embedded_landmark_face()

◆ roc_embedded_liveness()

◆ roc_embedded_represent_face()

◆ roc_embedded_represent_face_unlocked()

◆ roc_embedded_compare_templates()

◆ roc_embedded_array_initialize()

◆ roc_embedded_array_append()

◆ roc_embedded_array_get()

◆ roc_embedded_array_free()

◆ roc_embedded_checksum()