Biometric data storage format and related functions. More...

Data Structures
struct	roc_landmark
	Data structure for a landmark detection. More...

struct	roc_detection
	Data structure for a face detection. More...

struct	roc_template
	A digital encoding of a face. More...

Macros
#define	ROC_SUGGESTED_RELATIVE_MIN_SIZE 0.04f
	Suggested relative minimum face size. More...

#define	ROC_SUGGESTED_ABSOLUTE_MIN_SIZE 20
	Suggested absolute minimum face size. More...

#define	ROC_SUGGESTED_FALSE_DETECTION_RATE 0.02f
	Suggested false detection rate. More...

#define	ROC_OBJECT_SUGGESTED_FALSE_DETECTION_RATE 0.005f
	Suggested false detection rate for ROC_ALL_OBJECT_DETECTION. More...

#define	ROC_GUN_SUGGESTED_FALSE_DETECTION_RATE 0.1f
	Suggested false detection rate for ROC_GUN_DETECTION. More...

#define	ROC_TEXT_SUGGESTED_FALSE_DETECTION_RATE 0.02f
	Suggested false detection rate for ROC_TEXT_DETECTION. More...

#define	ROC_FINGERPRINT_SUGGESTED_FALSE_DETECTION_RATE 0.5f
	Suggested false detection rate for ROC_FINGERPRINT_DETECTION. More...

#define	ROC_NO_MIN_QUALITY -FLT_MAX
	Disable minimum quality threshold. More...

#define	ROC_NO_MIN_QUALITY -FLT_MAX
	Disable minimum quality threshold. More...

#define	ROC_TEXT_SUGGESTED_MIN_QUALITY 0.8f
	Suggested minimum quality threshold for ROC_TEXT_REPRESENTATION. More...

#define	ROC_TEXT_SUGGESTED_MIN_QUALITY 0.8f
	Suggested minimum quality threshold for ROC_TEXT_REPRESENTATION. More...

#define	ROC_TATTOO_SUGGESTED_MIN_QUALITY 0.0f
	Suggested minimum quality threshold for ROC_TATTOO_REPRESENTATION. More...

#define	ROC_TATTOO_SUGGESTED_MIN_QUALITY 0.0f
	Suggested minimum quality threshold for ROC_TATTOO_REPRESENTATION. More...

#define	ROC_FINGERPRINT_SUGGESTED_MIN_QUALITY -3.0f
	Suggested minimum quality threshold for ROC_FINGERPRINT_REPRESENTATION. More...

#define	ROC_FINGERPRINT_SUGGESTED_MIN_QUALITY -3.0f
	Suggested minimum quality threshold for ROC_FINGERPRINT_REPRESENTATION. More...

#define	ROC_DEEP_SUGGESTED_MIN_QUALITY -0.2f
	Suggested minimum quality threshold for ROC_DEEP_REPRESENTATION. More...

#define	ROC_DEEP_SUGGESTED_MIN_QUALITY -0.2f
	Suggested minimum quality threshold for ROC_DEEP_REPRESENTATION. More...

#define	ROC_FAST_SUGGESTED_MIN_QUALITY -FLT_MAX
	Suggested minimum quality threshold for ROC_FAST_REPRESENTATION. More...

#define	ROC_FAST_SUGGESTED_MIN_QUALITY -FLT_MAX
	Suggested minimum quality threshold for ROC_FAST_REPRESENTATION. More...

#define	ROC_STANDARD_SUGGESTED_MIN_QUALITY -FLT_MAX
	Suggested minimum quality threshold for ROC_STANDARD_REPRESENTATION. More...

#define	ROC_STANDARD_SUGGESTED_MIN_QUALITY -FLT_MAX
	Suggested minimum quality threshold for ROC_STANDARD_REPRESENTATION. More...

#define	ROC_STANDARD_FV_SIZE 261
	Length of a ROC_STANDARD_REPRESENTATION feature vector in bytes.

#define	ROC_DEEP_FV_SIZE 261
	Length of a ROC_DEEP_REPRESENTATION feature vector in bytes.

#define	ROC_OBJECT_FV_SIZE 262
	Length of a ROC_OBJECT_REPRESENTATION feature vector in byte.

#define	ROC_FAST_FV_SIZE 261
	Length of a ROC_FAST_REPRESENTATION feature vector in bytes.

#define	ROC_TATTOO_FV_SIZE 37
	Length of a ROC_TATTOO_REPRESENTATION feature vector in bytes.

#define	ROC_FINGERPRINT_FV_SIZE 262
	Length of a ROC_FINGERPRINT_REPRESENTATION feature vector in bytes.

#define	ROC_TEMPLATE_VERSION (((int64_t) ROC_VERSION_MAJOR << 61) + ((int64_t) ROC_VERSION_MINOR << 55))
	The format of roc_template::fv changes between most releases, this field is used to check template compatibility. More...

#define	ROC_FAST_COMPATIBILITY_VERSION (((int64_t) 2 << 61) + ((int64_t) 3 << 55))
	Minimum compatible version for templates generated with ROC_FAST_REPRESENTATION. More...

#define	ROC_STANDARD_COMPATIBILITY_VERSION (((int64_t) 2 << 61) + ((int64_t) 1 << 55))
	Minimum compatible version for templates generated with ROC_STANDARD_REPRESENTATION. More...

#define	ROC_DEEP_COMPATIBILITY_VERSION (((int64_t) 2 << 61) + ((int64_t) 4 << 55))
	Minimum compatible version for templates generated with ROC_DEEP_REPRESENTATION. More...

#define	ROC_TATTOO_COMPATIBILITY_VERSION (((int64_t) 2 << 61) + ((int64_t) 3 << 55))
	Minimum compatible version for templates generated with ROC_TATTOO_REPRESENTATION. More...

#define	ROC_FINGERPRINT_COMPATIBILITY_VERSION (((int64_t) 2 << 61) + ((int64_t) 4 << 55))
	Minimum compatible version for templates generated with ROC_FINGERPRINT_REPRESENTATION. More...

#define	ROC_OBJECT_COMPATIBILITY_VERSION (((int64_t) 2 << 61) + ((int64_t) 1 << 55))
	Minimum compatible version for templates generated with ROC_OBJECT_REPRESENTATION. More...

#define	ROC_TEMPLATE_VERSION_MASK 0x7F80000000000000
	See ROC_TEMPLATE_VERSION.

Typedefs
typedef enum roc_pose_options	roc_pose_options
	Coarse face pose.

typedef uint32_t	roc_pose
	See roc_pose_options.

typedef struct roc_landmark	roc_landmark
	Data structure for a landmark detection. More...

typedef struct roc_detection	roc_detection
	Data structure for a face detection.

typedef int64_t	roc_algorithm_id
	A combination of roc_algorithm_options. More...

typedef enum roc_color_options	roc_color_options
	Supported colors in ROC_COLOR_REPRESENTATION. More...

typedef int64_t	roc_color_selection
	A combination of roc_color_options.

typedef uint8_t	roc_finger_id
	A single roc_finger_options. More...

typedef enum roc_finger_options	roc_finger_options
	Supported fingerprint indices for use in roc_represent_fingerprint. More...

typedef struct roc_template	roc_template
	A digital encoding of a face. More...

Enumerations
enum	roc_pose_options { ROC_POSE_FRONTAL = 0, ROC_POSE_LEFT_PROFILE = 1, ROC_POSE_RIGHT_PROFILE = 2, ROC_POSE_NUM_POSES = 3 }
	Coarse face pose. More...

enum	roc_algorithm_options : roc_algorithm_id { ROC_NO_ALGORITHM_OPTIONS = 0x0, ROC_STANDARD_REPRESENTATION = 0x1, ROC_FAST_REPRESENTATION = 0x2, ROC_OBJECT_REPRESENTATION = 0x4, ROC_DEEP_REPRESENTATION = 0x8, ROC_TATTOO_REPRESENTATION = 0x10, ROC_COLOR_REPRESENTATION = 0x20, ROC_TEXT_REPRESENTATION = 0x40, ROC_FINGERPRINT_REPRESENTATION = 0x80, ROC_STANDARD_DETECTION = 0x100, ROC_FRONTAL_DETECTION = 0x200, ROC_TATTOO_DETECTION = 0x400, ROC_TEXT_DETECTION = 0x800, ROC_MANUAL_DETECTION = 0x1000, ROC_ENHANCE_CONTRAST = 0x2000, ROC_IGNORE_PARTIAL = 0x4000, ROC_ANALYTICS = 0x10000, ROC_IGNORE_ARTWORK = 0x20000, ROC_LANDMARKS = 0x40000, ROC_PITCHYAW = 0x80000, ROC_ICAO_METRICS = 0x100000, ROC_ICAO_BACKGROUND = 0x400000, ROC_SPOOF = 0x200000, ROC_THUMBNAIL = 0x1000000, ROC_SERIAL = 0x2000000, ROC_FILTER_TEXT = 0x4000000, ROC_AIRPLANE_DETECTION = 0x100000000, ROC_BICYCLE_DETECTION = 0x200000000, ROC_BOAT_DETECTION = 0x400000000, ROC_BUS_DETECTION = 0x800000000, ROC_CAR_DETECTION = 0x1000000000, ROC_GUN_DETECTION = 0x2000000000, ROC_LICENSE_PLATE_DETECTION = 0x4000000000, ROC_MILITARY_VEHICLE_DETECTION = 0x8000000000, ROC_MOTORCYCLE_DETECTION = 0x10000000000, ROC_PERSON_DETECTION = 0x20000000000, ROC_TRUCK_DETECTION = 0x40000000000, ROC_ALL_OBJECT_DETECTION, ROC_FINGERPRINT_DETECTION = 0x80000000000 }
	Supported algorithm configurations for use in roc_represent. More...

enum	roc_color_options { ROC_COLOR_NONE = 0x0, ROC_COLOR_WHITE = 0x1, ROC_COLOR_GREY = 0x2, ROC_COLOR_BLACK = 0x4, ROC_COLOR_RED = 0x8, ROC_COLOR_ORANGE = 0x10, ROC_COLOR_YELLOW = 0x20, ROC_COLOR_GREEN = 0x40, ROC_COLOR_BLUE = 0x80, ROC_COLOR_VIOLET = 0x100, ROC_COLOR_PINK = 0x200, ROC_COLOR_BROWN = 0x400 }
	Supported colors in ROC_COLOR_REPRESENTATION. More...

enum	roc_finger_options { ROC_NO_FINGER = 0x0, ROC_THUMB = 0x1, ROC_INDEX_FINGER = 0x2, ROC_MIDDLE_FINGER = 0x4, ROC_RING_FINGER = 0x8, ROC_LITTLE_FINGER = 0x10, ROC_EXTRA_FINGER = 0x20, ROC_RIGHT_HAND = 0x40, ROC_LEFT_HAND = 0x80, ROC_FOUR_FINGERS, ROC_ANY_FINGER = ROC_THUMB \| ROC_FOUR_FINGERS, ROC_ANY_HAND = ROC_RIGHT_HAND \| ROC_LEFT_HAND, ROC_UNKNOWN_FINGER = ROC_ANY_HAND \| ROC_ANY_FINGER }
	Supported fingerprint indices for use in roc_represent_fingerprint. More...

Functions
const char *	roc_pose_to_string (roc_pose pose)
	A printable roc_pose. More...

bool	roc_landmark_is_visible (roc_landmark l)
	Determine if a landmark is visible. More...

roc_error	roc_adaptive_minimum_size (size_t image_width, size_t image_height, float relative_min_size, size_t absolute_min_size, size_t *adaptive_min_size)
	A method for determining the minimum face detection size as a fraction of the image size. More...

roc_error	roc_algorithm_option_to_string (roc_algorithm_options algorithm_option, const char **str)
	String representation of a roc_algorithm_options. More...

roc_error	roc_algorithm_option_from_string (const char str, roc_algorithm_options algorithm_option)
	The opposite of roc_algorithm_option_to_string. More...

roc_error	roc_finger_id_to_string (roc_finger_id finger_id, roc_string *str)
	String representation of a roc_finger_id. More...

roc_error	roc_finger_id_from_string (roc_string str, roc_finger_id *finger_id)
	The opposite of roc_finger_id_to_string. More...

roc_error	roc_check_template_version (roc_algorithm_id algorithm_id)
	Return an error if the specified roc_algorithm_id is incompatible with this version of the SDK. More...

float	roc_get_suggested_quality_threshold (roc_algorithm_id algorithm_id)
	Returns the suggested quality threshold for roc_represent for the specified representation. More...

roc_error	roc_new_template (roc_template *template_, uint32_t md_size, uint32_t fv_size, uint32_t tn_size)
	Allocate memory for a new template. More...

roc_error	roc_new_color_template (roc_template template_, const roc_color_selection color_selection, const char object_type)
	Construct a new template for color-based searching. More...

roc_error	roc_new_person_color_template (roc_template *template_, const roc_color_selection torso_color_selection, const roc_color_selection thigh_color_selection)
	Construct a new person template for color-based searching. More...

roc_error	roc_free_template (roc_template *template_)
	Call this function on a template after it is no longer needed. More...

roc_error	roc_copy_template (const roc_template src, roc_template *dst)
	Deep-copy a template. More...

roc_error	roc_flatten (const roc_template template_, uint8_t *output_byte_array)
	Serialize a template to a memory buffer. More...

roc_error	roc_unflatten (const uint8_t input_byte_array, roc_template template_)
	Deserialize a template from a memory buffer. More...

roc_error	roc_flattened_bytes (const roc_template template_, size_t *bytes)
	Calculate the bytes required to flatten a template. More...

void	roc_flattened_version (const uint8_t input_byte_array, int major_version, int *minor_version)
	Obtain the SDK version of a flattened template. More...

void *	roc_cast (uint8_t *pointer)
	Cast and return a `uint8_t` as a `void`. More...

Variables
const size_t	roc_template_header_size
	Size of the fixed-length portion of a roc_template. More...

Detailed Description

Biometric data storage format and related functions.

Copy a template with roc_copy_template, flatten a template with roc_flatten, and free a template with roc_free_template.

Data Structure Documentation

◆ roc_landmark

struct roc_landmark

Data structure for a landmark detection.

If roc_landmark::x and roc_landmark::y are both 0 this indicates the landmark is not visible.

Data Fields
float	x	Landmark horizontal position (pixels).
float	y	Landmark vertical position (pixels).

◆ roc_detection

struct roc_detection

Data structure for a face detection.

Data Fields
float	x	Detection center horizontal offset (pixels).
float	y	Detection center vertical offset (pixels).
float	width	Detection horizontal size (pixels).
float	height	Detection vertical size (pixels).
float	rotation	Detection rotation (degrees).
float	confidence	Detection confidence.
roc_pose	pose	See roc_pose_options.
roc_landmark	right_eye	Subject's right eye location.
roc_landmark	left_eye	Subject's left eye location.
roc_landmark	nose	Subject's nose location.
roc_landmark	right_mouth_corner	Subject's right mouth corner location.
roc_landmark	left_mouth_corner	Subject's left mouth corner location.
roc_landmark	chin	Subject's chin location.
int32_t	image_width	Detection source image width (pixels).
int32_t	image_height	Detection source image height (pixels).

◆ roc_template

struct roc_template

A digital encoding of a face.

A pair of templates can be compared for similarity.

Templates are designed with the following considerations in mind:

Maximizing the retention of the unique identifying characteristics of a face.
Minimizing the computation time needed to compare two templates.
Minimizing the computation time needed to generate a template.
Minimizing the storage space required to save a template.

Metadata

A template's metadata string is a Java Script Object Notation (JSON) object containing at least the following keys:

Key	Definition
`IOD`	Interocular distance between the right and left eyes (pixels). Not reported for profile faces where one eye is present.
`OCD`	Distance between the eyes and chin tip (pixels).
`Quality`	See Face Quality.

Additional keys exist for the requested Metadata Options, including:

Key	Definition
`Pitch`	See ROC_PITCHYAW.
`Yaw`	See ROC_PITCHYAW.
`Lips`	See ROC_PITCHYAW.
`Age`	See ROC_ANALYTICS.
`GaussianBlur`	See ROC_ANALYTICS.
`Gender`	See ROC_ANALYTICS.
`Male`	See ROC_ANALYTICS.
`Female`	See ROC_ANALYTICS.
`GeographicOrigin`	See ROC_ANALYTICS.
`African`	See ROC_ANALYTICS.
`EastAsian`	See ROC_ANALYTICS.
`European`	See ROC_ANALYTICS.
`LatinAmerican`	See ROC_ANALYTICS.
`MiddleEastern`	See ROC_ANALYTICS.
`SouthAsian`	See ROC_ANALYTICS.
`SoutheastAsian`	See ROC_ANALYTICS.
`Emotion`	See ROC_ANALYTICS.
`Anger`	See ROC_ANALYTICS.
`Disgust`	See ROC_ANALYTICS.
`Fear`	See ROC_ANALYTICS.
`Joy`	See ROC_ANALYTICS.
`Neutral`	See ROC_ANALYTICS.
`Sadness`	See ROC_ANALYTICS.
`Surprise`	See ROC_ANALYTICS.
`Glasses`	See ROC_ANALYTICS.
`None`	See ROC_ANALYTICS.
`Eye`	See ROC_ANALYTICS.
`Sun`	See ROC_ANALYTICS.
`FacialHair`	See ROC_ANALYTICS.
`Artwork`	See ROC_ANALYTICS.
`Cartoon`	See ROC_ANALYTICS.
`Human`	See ROC_ANALYTICS.
`Painting`	See ROC_ANALYTICS.
`Mask`	See ROC_ANALYTICS.
`NoMask`	See ROC_ANALYTICS.
`Spoof`	See ROC_SPOOF.

Metadata may be queried and edited using roc_get_metadata and roc_set_metadata.

Feature Vector

A template's feature vector is the statistical model of the distinguishing characteristics of a face and is the basis for measuring roc_similarity. It is stored in the template as roc_template::fv and has length roc_template::fv_size.

Data Fields
roc_algorithm_id	algorithm_id	The value of roc_algorithm_id passed to roc_represent to construct this template bitwise OR'd with ROC_TEMPLATE_VERSION.
roc_time	timestamp	Face video timestamp or ROC_NO_TIMESTAMP by default.
roc_template_id	template_id	Unique identifier for the template.
roc_person_id	person_id	Unique identifier for the person or roc_uuid_get_null by default.
roc_media_id	media_id	Origin image roc_image::media_id.
roc_camera_id	camera_id	Origin image roc_image::camera_id.
roc_archive_id	archive_id	Output image/video, if any.
roc_detection	detection	Face position, see roc_detection.
uint32_t	md_size	Length of metadata buffer md. This value is greater than or equal to `strlen+1` of md.
uint32_t	fv_size	Length of the feature vector fv.
uint32_t	tn_size	Length of face thumbnail tn.
const char *	md	Null-terminated JSON string, or `NULL` if empty.
const uint8_t *	fv	Feature Vector of length fv_size, or `NULL` if empty.
const uint8_t *	tn	JPEG-encoded ROC_THUMBNAIL of length tn_size, or `NULL` if empty.

Macro Definition Documentation

◆ ROC_SUGGESTED_RELATIVE_MIN_SIZE

#define ROC_SUGGESTED_RELATIVE_MIN_SIZE 0.04f

Suggested relative minimum face size.

4% of image width/height.

See also: Default Versus Suggested Parameters

◆ ROC_SUGGESTED_ABSOLUTE_MIN_SIZE

#define ROC_SUGGESTED_ABSOLUTE_MIN_SIZE 20

Suggested absolute minimum face size.

20 pixels.

See also: Default Versus Suggested Parameters

◆ ROC_SUGGESTED_FALSE_DETECTION_RATE

#define ROC_SUGGESTED_FALSE_DETECTION_RATE 0.02f

Suggested false detection rate.

Approximately one non-face detected in every 50 images (1 / 50 = 0.02).

See also: Default Versus Suggested Parameters ROC_TEXT_SUGGESTED_FALSE_DETECTION_RATE

◆ ROC_OBJECT_SUGGESTED_FALSE_DETECTION_RATE

#define ROC_OBJECT_SUGGESTED_FALSE_DETECTION_RATE 0.005f

Suggested false detection rate for ROC_ALL_OBJECT_DETECTION.

See also: Default Versus Suggested Parameters ROC_SUGGESTED_FALSE_DETECTION_RATE

◆ ROC_GUN_SUGGESTED_FALSE_DETECTION_RATE

#define ROC_GUN_SUGGESTED_FALSE_DETECTION_RATE 0.1f

Suggested false detection rate for ROC_GUN_DETECTION.

See also: Default Versus Suggested Parameters ROC_SUGGESTED_FALSE_DETECTION_RATE

◆ ROC_TEXT_SUGGESTED_FALSE_DETECTION_RATE

#define ROC_TEXT_SUGGESTED_FALSE_DETECTION_RATE 0.02f

Suggested false detection rate for ROC_TEXT_DETECTION.

See also: Default Versus Suggested Parameters ROC_SUGGESTED_FALSE_DETECTION_RATE

◆ ROC_FINGERPRINT_SUGGESTED_FALSE_DETECTION_RATE

#define ROC_FINGERPRINT_SUGGESTED_FALSE_DETECTION_RATE 0.5f

Suggested false detection rate for ROC_FINGERPRINT_DETECTION.

See also: Default Versus Suggested Parameters ROC_SUGGESTED_FALSE_DETECTION_RATE

◆ ROC_NO_MIN_QUALITY [1/2]

#define ROC_NO_MIN_QUALITY -FLT_MAX

Disable minimum quality threshold.

See also: ROC_SUGGESTED_MIN_QUALITY ROC_TEXT_SUGGESTED_MIN_QUALITY

◆ ROC_NO_MIN_QUALITY [2/2]

#define ROC_NO_MIN_QUALITY -FLT_MAX

Disable minimum quality threshold.

See also: ROC_SUGGESTED_MIN_QUALITY ROC_TEXT_SUGGESTED_MIN_QUALITY

◆ ROC_TEXT_SUGGESTED_MIN_QUALITY [1/2]

#define ROC_TEXT_SUGGESTED_MIN_QUALITY 0.8f

Suggested minimum quality threshold for ROC_TEXT_REPRESENTATION.

See also: Default Versus Suggested Parameters ROC_NO_MIN_QUALITY

◆ ROC_TEXT_SUGGESTED_MIN_QUALITY [2/2]

#define ROC_TEXT_SUGGESTED_MIN_QUALITY 0.8f

Suggested minimum quality threshold for ROC_TEXT_REPRESENTATION.

See also: Default Versus Suggested Parameters ROC_NO_MIN_QUALITY

◆ ROC_TATTOO_SUGGESTED_MIN_QUALITY [1/2]

#define ROC_TATTOO_SUGGESTED_MIN_QUALITY 0.0f

Suggested minimum quality threshold for ROC_TATTOO_REPRESENTATION.

See also: Default Versus Suggested Parameters ROC_NO_MIN_QUALITY

◆ ROC_TATTOO_SUGGESTED_MIN_QUALITY [2/2]

#define ROC_TATTOO_SUGGESTED_MIN_QUALITY 0.0f

Suggested minimum quality threshold for ROC_TATTOO_REPRESENTATION.

See also: Default Versus Suggested Parameters ROC_NO_MIN_QUALITY

◆ ROC_FINGERPRINT_SUGGESTED_MIN_QUALITY [1/2]

#define ROC_FINGERPRINT_SUGGESTED_MIN_QUALITY -3.0f

Suggested minimum quality threshold for ROC_FINGERPRINT_REPRESENTATION.

See also: Default Versus Suggested Parameters ROC_NO_MIN_QUALITY

◆ ROC_FINGERPRINT_SUGGESTED_MIN_QUALITY [2/2]

#define ROC_FINGERPRINT_SUGGESTED_MIN_QUALITY -3.0f

Suggested minimum quality threshold for ROC_FINGERPRINT_REPRESENTATION.

See also: Default Versus Suggested Parameters ROC_NO_MIN_QUALITY

◆ ROC_DEEP_SUGGESTED_MIN_QUALITY [1/2]

#define ROC_DEEP_SUGGESTED_MIN_QUALITY -0.2f

Suggested minimum quality threshold for ROC_DEEP_REPRESENTATION.

See also: Default Versus Suggested Parameters ROC_NO_MIN_QUALITY

◆ ROC_DEEP_SUGGESTED_MIN_QUALITY [2/2]

#define ROC_DEEP_SUGGESTED_MIN_QUALITY -0.2f

Suggested minimum quality threshold for ROC_DEEP_REPRESENTATION.

See also: Default Versus Suggested Parameters ROC_NO_MIN_QUALITY

◆ ROC_FAST_SUGGESTED_MIN_QUALITY [1/2]

#define ROC_FAST_SUGGESTED_MIN_QUALITY -FLT_MAX

Suggested minimum quality threshold for ROC_FAST_REPRESENTATION.

See also: Default Versus Suggested Parameters ROC_NO_MIN_QUALITY

◆ ROC_FAST_SUGGESTED_MIN_QUALITY [2/2]

#define ROC_FAST_SUGGESTED_MIN_QUALITY -FLT_MAX

Suggested minimum quality threshold for ROC_FAST_REPRESENTATION.

See also: Default Versus Suggested Parameters ROC_NO_MIN_QUALITY

◆ ROC_STANDARD_SUGGESTED_MIN_QUALITY [1/2]

#define ROC_STANDARD_SUGGESTED_MIN_QUALITY -FLT_MAX

Suggested minimum quality threshold for ROC_STANDARD_REPRESENTATION.

See also: Default Versus Suggested Parameters ROC_NO_MIN_QUALITY

◆ ROC_STANDARD_SUGGESTED_MIN_QUALITY [2/2]

#define ROC_STANDARD_SUGGESTED_MIN_QUALITY -FLT_MAX

Suggested minimum quality threshold for ROC_STANDARD_REPRESENTATION.

See also: Default Versus Suggested Parameters ROC_NO_MIN_QUALITY

◆ ROC_TEMPLATE_VERSION

#define ROC_TEMPLATE_VERSION (((int64_t) ROC_VERSION_MAJOR << 61) + ((int64_t) ROC_VERSION_MINOR << 55))

The format of roc_template::fv changes between most releases, this field is used to check template compatibility.

roc_template t = ...;
if (t->algorithm_id & ROC_TEMPLATE_VERSION_MASK == ROC_TEMPLATE_VERSION)
    ...; // generated with current SDK version

◆ ROC_FAST_COMPATIBILITY_VERSION

#define ROC_FAST_COMPATIBILITY_VERSION (((int64_t) 2 << 61) + ((int64_t) 3 << 55))

Minimum compatible version for templates generated with ROC_FAST_REPRESENTATION.

roc_template t = ...;
if (t->algorithm_id & ROC_TEMPLATE_VERSION_MASK >= ROC_FAST_COMPATIBILITY_VERSION)
    ...; // compatible with current SDK version

See also: ROC_TEMPLATE_VERSION

◆ ROC_STANDARD_COMPATIBILITY_VERSION

#define ROC_STANDARD_COMPATIBILITY_VERSION (((int64_t) 2 << 61) + ((int64_t) 1 << 55))

Minimum compatible version for templates generated with ROC_STANDARD_REPRESENTATION.

roc_template t = ...;
if (t->algorithm_id & ROC_TEMPLATE_VERSION_MASK >= ROC_STANDARD_COMPATIBILITY_VERSION)
    ...; // compatible with current SDK version

See also: ROC_TEMPLATE_VERSION

◆ ROC_DEEP_COMPATIBILITY_VERSION

#define ROC_DEEP_COMPATIBILITY_VERSION (((int64_t) 2 << 61) + ((int64_t) 4 << 55))

Minimum compatible version for templates generated with ROC_DEEP_REPRESENTATION.

roc_template t = ...;
if (t->algorithm_id & ROC_TEMPLATE_VERSION_MASK >= ROC_DEEP_COMPATIBILITY_VERSION)
    ...; // compatible with current SDK version

See also: ROC_TEMPLATE_VERSION

◆ ROC_TATTOO_COMPATIBILITY_VERSION

#define ROC_TATTOO_COMPATIBILITY_VERSION (((int64_t) 2 << 61) + ((int64_t) 3 << 55))

Minimum compatible version for templates generated with ROC_TATTOO_REPRESENTATION.

roc_template t = ...;
if (t->algorithm_id & ROC_TEMPLATE_VERSION_MASK >= ROC_TATTOO_COMPATIBILITY_VERSION)
    ...; // compatible with current SDK version

See also: ROC_TEMPLATE_VERSION

◆ ROC_FINGERPRINT_COMPATIBILITY_VERSION

#define ROC_FINGERPRINT_COMPATIBILITY_VERSION (((int64_t) 2 << 61) + ((int64_t) 4 << 55))

Minimum compatible version for templates generated with ROC_FINGERPRINT_REPRESENTATION.

roc_template t = ...;
if (t->algorithm_id & ROC_TEMPLATE_VERSION_MASK >= ROC_FINGERPRINT_COMPATIBILITY_VERSION)
    ...; // compatible with current SDK version

See also: ROC_TEMPLATE_VERSION

◆ ROC_OBJECT_COMPATIBILITY_VERSION

#define ROC_OBJECT_COMPATIBILITY_VERSION (((int64_t) 2 << 61) + ((int64_t) 1 << 55))

Minimum compatible version for templates generated with ROC_OBJECT_REPRESENTATION.

roc_template t = ...;
if (t->algorithm_id & ROC_TEMPLATE_VERSION_MASK >= ROC_OBJECT_COMPATIBILITY_VERSION)
    ...; // compatible with current SDK version

See also: ROC_TEMPLATE_VERSION

Typedef Documentation

◆ roc_landmark

typedef struct roc_landmark roc_landmark

Data structure for a landmark detection.

If roc_landmark::x and roc_landmark::y are both 0 this indicates the landmark is not visible.

◆ roc_algorithm_id

typedef int64_t roc_algorithm_id

A combination of roc_algorithm_options.

See also: Specifying an Algorithm ID

◆ roc_color_options

typedef enum roc_color_options roc_color_options

Supported colors in ROC_COLOR_REPRESENTATION.

An enumeratation used to represent the colors in ROC_COLOR_REPRESENTATION via roc_new_color_template and roc_new_person_color_template.

◆ roc_finger_id

typedef uint8_t roc_finger_id

A single roc_finger_options.

See also: Specifying a Finger ID

◆ roc_finger_options

typedef enum roc_finger_options roc_finger_options

Supported fingerprint indices for use in roc_represent_fingerprint.

See also: Specifying a Finger ID

◆ roc_template

typedef struct roc_template roc_template

A digital encoding of a face.

A pair of templates can be compared for similarity.

Templates are designed with the following considerations in mind:

Maximizing the retention of the unique identifying characteristics of a face.
Minimizing the computation time needed to compare two templates.
Minimizing the computation time needed to generate a template.
Minimizing the storage space required to save a template.

Metadata

A template's metadata string is a Java Script Object Notation (JSON) object containing at least the following keys:

Key	Definition
`IOD`	Interocular distance between the right and left eyes (pixels). Not reported for profile faces where one eye is present.
`OCD`	Distance between the eyes and chin tip (pixels).
`Quality`	See Face Quality.

Additional keys exist for the requested Metadata Options, including:

Key	Definition
`Pitch`	See ROC_PITCHYAW.
`Yaw`	See ROC_PITCHYAW.
`Lips`	See ROC_PITCHYAW.
`Age`	See ROC_ANALYTICS.
`GaussianBlur`	See ROC_ANALYTICS.
`Gender`	See ROC_ANALYTICS.
`Male`	See ROC_ANALYTICS.
`Female`	See ROC_ANALYTICS.
`GeographicOrigin`	See ROC_ANALYTICS.
`African`	See ROC_ANALYTICS.
`EastAsian`	See ROC_ANALYTICS.
`European`	See ROC_ANALYTICS.
`LatinAmerican`	See ROC_ANALYTICS.
`MiddleEastern`	See ROC_ANALYTICS.
`SouthAsian`	See ROC_ANALYTICS.
`SoutheastAsian`	See ROC_ANALYTICS.
`Emotion`	See ROC_ANALYTICS.
`Anger`	See ROC_ANALYTICS.
`Disgust`	See ROC_ANALYTICS.
`Fear`	See ROC_ANALYTICS.
`Joy`	See ROC_ANALYTICS.
`Neutral`	See ROC_ANALYTICS.
`Sadness`	See ROC_ANALYTICS.
`Surprise`	See ROC_ANALYTICS.
`Glasses`	See ROC_ANALYTICS.
`None`	See ROC_ANALYTICS.
`Eye`	See ROC_ANALYTICS.
`Sun`	See ROC_ANALYTICS.
`FacialHair`	See ROC_ANALYTICS.
`Artwork`	See ROC_ANALYTICS.
`Cartoon`	See ROC_ANALYTICS.
`Human`	See ROC_ANALYTICS.
`Painting`	See ROC_ANALYTICS.
`Mask`	See ROC_ANALYTICS.
`NoMask`	See ROC_ANALYTICS.
`Spoof`	See ROC_SPOOF.

Metadata may be queried and edited using roc_get_metadata and roc_set_metadata.

Feature Vector

A template's feature vector is the statistical model of the distinguishing characteristics of a face and is the basis for measuring roc_similarity. It is stored in the template as roc_template::fv and has length roc_template::fv_size.

Enumeration Type Documentation

◆ roc_pose_options

enum roc_pose_options

Coarse face pose.

Enumerator
ROC_POSE_FRONTAL	Both eyes visible.
ROC_POSE_LEFT_PROFILE	See Right vs. Left.
ROC_POSE_RIGHT_PROFILE	See Right vs. Left.
ROC_POSE_NUM_POSES	Number of coarse pose bins.

◆ roc_algorithm_options

enum roc_algorithm_options : roc_algorithm_id

Supported algorithm configurations for use in roc_represent.

See also: Specifying an Algorithm ID

Dynamically Loaded Model

In order to keep the core roc library reasonably sized, certain large algorithms are factored out into their own libraries. For example, ROC_DEEP_REPRESENTATION lives in libroc_deep_representation.so (roc_deep_representation.dll on Windows). This allows developers to omit algorithms that are not needed by their application. The SDK will automatically search for these libraries in standard system locations at runtime if they are invoked. If you recieve an error that the library can't be found then you will need to inform the SDK where to look using roc_set_model_path.

Enumerator
ROC_NO_ALGORITHM_OPTIONS	Type-safe default.
ROC_STANDARD_REPRESENTATION	Represent faces for comparison. See ROC_FAST_REPRESENTATION for a faster alternative, and ROC_DEEP_REPRESENTATION for a more accurate alternative. Suggested `min_quality` to roc_represent is ROC_STANDARD_SUGGESTED_MIN_QUALITY.
ROC_FAST_REPRESENTATION	Faster but less accurate alternative to ROC_STANDARD_REPRESENTATION. Approximately 6x faster at the cost of 7x the false negative rate. Suggested `min_quality` to roc_represent is ROC_FAST_SUGGESTED_MIN_QUALITY.
ROC_OBJECT_REPRESENTATION	Represent objects for comparison. This is primarily only used for object tracking.
ROC_DEEP_REPRESENTATION	Slower but more accurate alternative to ROC_STANDARD_REPRESENTATION. Approximately 3x slower for a 3x reduction in the false negative rate. Suggested `min_quality` to roc_represent is ROC_DEEP_SUGGESTED_MIN_QUALITY. This is a Dynamically Loaded Model.
ROC_TATTOO_REPRESENTATION	Represent a law enforcement booking-style scar/mark/tattoo (SMT) image. For law enforcement style booking images, where the tattoos are generally only in subregions of the image, ROC_TATTOO_DETECTION should be specified to localize the tattoos. In this case, the input image will be automatically cropped around each detection before being processed by ROC_TATTOO_REPRESENTATION. Conversely, for use cases that involve processing an image of a logo, drawing, or other image that is pre-cropped around the region of interest, ROC_TATTOO_DETECTION should be omitted and the entire image will be considered a single tattoo. In this case, the image will not be cropped before being processed by ROC_TATTOO_REPRESENTATION. Suggested `min_quality` to roc_represent is ROC_TATTOO_SUGGESTED_MIN_QUALITY. This is a Dynamically Loaded Model.
ROC_COLOR_REPRESENTATION	Estimate the color(s) of an object. A JSON-like object is stored in the `ColorResponse` of Metadata which contains color-score key-value pairs. Each score represents a percentage of the color's presense in an image and is a real-vaued number between 0.0 and 1.0. The possible colors are: red, orange, yellow, green, teal, blue, violet, pink, white, black, grey. For cases where the detected object is a `person` the entry of `ColorResponse` will have two entries `UpperClothingColor` and `LowerClothingColor`. These entires will have a similar JSON-like object where the possible colors are: red, orange, yellow, green, blue, violet, pink, brown/tan, white, black, grey.
ROC_TEXT_REPRESENTATION	Perform optical character recognition on text in images. Suggested `min_quality` to roc_represent is ROC_TEXT_SUGGESTED_MIN_QUALITY. Requires setting roc_set_model_path to the `models` folder. See also ROC_TEXT_DETECTION ROC_FILTER_TEXT
ROC_FINGERPRINT_REPRESENTATION	Represent fingerprints for comparison. Use with ROC_FINGERPRINT_DETECTION.
ROC_STANDARD_DETECTION	Detect faces from -100 to +100 degrees yaw with high accuracy. Slightly slower than ROC_FRONTAL_DETECTION. This algorithm can be accelerated on large images with a CUDA compatible GPU.
ROC_FRONTAL_DETECTION	Detect faces from -30 to +30 degrees yaw. Slightly faster than ROC_STANDARD_DETECTION. Recommended when using ROC_FAST_REPRESENTATION.
ROC_TATTOO_DETECTION	Detect tattoos in the image. See ROC_TATTOO_REPRESENTATION for details on when to specify this option.
ROC_TEXT_DETECTION	Detect text in an image. Requires setting roc_set_model_path to the `models` folder. Suggested `false_detection_rate` to roc_represent is ROC_TEXT_SUGGESTED_FALSE_DETECTION_RATE. See also ROC_TEXT_REPRESENTATION
ROC_MANUAL_DETECTION	Bypass automatic face detection by using caller-provided bounding boxes. Required Fields Templates passed to roc_represent are assumed to provide a valid roc_template::detection. All other fields in the template may be left uninitialized. When To Use The suggested use case for ROC_MANUAL_DETECTION is when the caller wishes to isolate face representation (e.g. ROC_STANDARD_REPRESENTATION) from face detection (e.g. ROC_STANDARD_DETECTION). The required fields must be obtained from a prior call to roc_represent or from roc_landmarks_to_detection. Face bounding boxes obtained from other means are not supported as they are not guaranteed to be the correct position and size.
ROC_ENHANCE_CONTRAST	If face detection fails, normalize the image using roc_enhance_contrast and re-attempt face detection. roc_enhance_contrast is called with a `clip_limit` of `2` and `num_tiles` of `8`.
ROC_IGNORE_PARTIAL	Ignore detections that are partially off-image. The minimum fraction of the detection which must be in frame should be provided to roc_represent_roi as `min_roi_overlap`.
ROC_ANALYTICS	Estimate age, emotion, gaussian blur, geographic origin, gender, glasses, facial hair, artwork and mask detection. The unit `Age` is years old. The value for `FacialHair` ranges from 0 to 100 indicating no facial hair to thick mustache and beard. The value for `GaussianBlur` ranges from 0 to 1 indicating the severity of gaussian or focus blur. For emotion estimation seven probability values are reported for `Anger`, `Disgust`, `Fear`, `Joy`, `Neutral`, `Sadness` and `Surprise`. For geographic origin estimation four probability values are reported for `African`, `EastAsian`, `European`, `LatinAmerican`, `MiddleEastern`, `SouthAsian` and `SoutheastAsian`. For gender estimation two probability values are reported for `Male` and `Female`. For glasses estimation three probability values are reported for `None`, `Eye`, and `Sun`. For artwork estimation three probability values are reported for `Human`, `Cartoon` and `Painting`. For mask estimation two probability values are reported for `Mask` and `NoMask`. For convenience, the max value for each of emotion, gender, geographic origin, glasses, artwork and mask detection is provided as a string value under their respective category name. See also ROC_IGNORE_ARTWORK
ROC_IGNORE_ARTWORK	Do not return templates for faces classified as `Cartoon` or `Painting` by the `Artwork` estimator. Eliminate templates with a low `Human` response. In addition to scrubbing templates of paintings, statues, emojis, animals, and other non-living human faces, this flag has the additional benefit of significantly reducing the false positive face detection rate. However, this flag is not effective as a Face Liveness metric. This flag implies ROC_ANALYTICS.
ROC_LANDMARKS	Add the full set of landmark locations to the template metadata. The `Landmarks` metadata key is an array of coordinates for each facial landmark detected.
ROC_PITCHYAW	Add `Yaw` and `Pitch` (degrees) estimation to the template metadata. Yaw is defined to be negative when the subject's face is oriented towards the subject's left shoulder (positive `x` direction, toward the right hand side of the image). Pitch is defined to be negative when the subject's face is below the camera. `Yaw` and `Pitch` estimation are expected to be accurate on faces in the -30 to +30 degree range. This algorithm will also add `Lips` position estimation to the template metadata, whose value is either `Together` or `Apart`.
ROC_ICAO_METRICS	Compute ICAO face portrait quality measures. In roc_represent, compute a subset of ICAO quality metrics. See ICAO for more information on these metrics. Metrics will be added to the template metadata. See also ROC_ICAO_BACKGROUND
ROC_ICAO_BACKGROUND	Compute ICAO uniform background face portrait quality metric. Compute the uniform background face quality metric. See ICAO for more information on this metric. Metric will be added to the template metadata. If ROC_THUMBNAIL is specified roc_template::tn will be populated with a `PNG` image of the face with the background removed. Configure the background color with roc_set_icao_background_color. See also ROC_ICAO_METRICS
ROC_SPOOF	Add `Spoof` metric for static Face Liveness detection. A real-valued number between 0.0 and 1.0 where a higher value indicates a greater chance of a spoof face and a lower value indicates a greater chance of a live face. See ROC_CONVENIENT_SPOOF_THRESHOLD and ROC_SECURE_SPOOF_THRESHOLD for recommended default thresholds. Due to the diverse nature of camera sensors, a single threshold may not be optimal across multiple sensors. Please thoroughly test the performance on sensors of interest to select an appropriate threshold for your needs. Note This metric is specifically designed with front-facing mobile cameras in mind. Therefore, the following engineering constraints should be observed: Interocular distance (`IOD` as reported in the Metadata) should be at least 100 pixels (typical of a "selfie" image). Images may be compressed, although very heavy compression may negatively impact performance Faces must be frontal. Non-frontal faces will not be processed. ROC_ANALYTICS will automatically be ran. This algorithm will only be run for ROC_POSE_FRONTAL faces.
ROC_THUMBNAIL	An aligned and cropped face image suitable for displaying. Align, scale, crop, `JPEG` encode, and store the face image in roc_template::tn and set roc_template::tn_size accordingly. Control thumbnail quality with roc_set_thumbnail_parameters. Decode a thumbnail with roc_decode_image or write it to a file and open it with roc_read_image. Example roc_image image = ...; roc_template t; roc_represent(image, ROC_FRONTAL_DETECTION \| ROC_THUMBNAIL, ROC_SUGGESTED_ABSOLUTE_MIN_SIZE, 1, ROC_SUGGESTED_FALSE_DETECTION_RATE, &t); if (t.algorithm_id & ROC_INVALID == 0) { FILE *thumbnail_file = fopen("thumbnail.jpg", "wb"); fwrite(t.tn, t.tn_size, 1, thumbnail_file); fclose(thumbnail_file); } roc_free_template(&t);
ROC_SERIAL	Don't parallelize face representation or search. In roc_represent, by default each detected face is processed in parallel up to the thread count limitation imposed by the license file. In roc_search and roc_knn, by default gallery templates are compared in parallel up to the thread count limitation imposed by the license file.
ROC_FILTER_TEXT	Filter non-compliant text results. Requires that ROC_TEXT_REPRESENTATION is set. Automatically filter out text results that don't match a set of user defined regular expressions. The list of regular expressions can be passed to roc_represent_roi.
ROC_AIRPLANE_DETECTION	Detect airplanes in the image.
ROC_BICYCLE_DETECTION	Detect bicycles in the image.
ROC_BOAT_DETECTION	Detect boats in the image.
ROC_BUS_DETECTION	Detect buses in the image.
ROC_CAR_DETECTION	Detect cars in the image.
ROC_GUN_DETECTION	Detect guns in the image. Suggested false detection rate is ROC_GUN_SUGGESTED_FALSE_DETECTION_RATE.
ROC_LICENSE_PLATE_DETECTION	Detect license plates in the image.
ROC_MILITARY_VEHICLE_DETECTION	Detect military vehicles in the image.
ROC_MOTORCYCLE_DETECTION	Detect motorcycles in the image.
ROC_PERSON_DETECTION	Detect people in the image.
ROC_TRUCK_DETECTION	Detect trucks in the image.
ROC_ALL_OBJECT_DETECTION	Detect all objects in an image. The following types of objects can be detected: airplane, bicycle, boat, bus, car, gun, military_vehicle, motorcycle, person, truck. Note Detection for `license_plate` is not enabled with this flag, for license plate detection, please see ROC_LICENSE_PLATE_DETECTION. The type of object is stored in the `Label` of Metadata. A real-valued number between `0.0` and `1.0` indicating the predicted object confidence will be stored in roc_detection::confidence. Suggested `false_detection_rate` to roc_represent is ROC_OBJECT_SUGGESTED_FALSE_DETECTION_RATE.
ROC_FINGERPRINT_DETECTION	Detect fingerprints in the image. Use with ROC_FINGERPRINT_REPRESENTATION.

◆ roc_color_options

enum roc_color_options

Supported colors in ROC_COLOR_REPRESENTATION.

An enumeratation used to represent the colors in ROC_COLOR_REPRESENTATION via roc_new_color_template and roc_new_person_color_template.

Enumerator
ROC_COLOR_NONE	Type-safe default.
ROC_COLOR_WHITE	Color ID corresponding to `white`.
ROC_COLOR_GREY	Color ID corresponding to `grey`.
ROC_COLOR_BLACK	Color ID corresponding to `black`.
ROC_COLOR_RED	Color ID corresponding to `red`.
ROC_COLOR_ORANGE	Color ID corresponding to `orange`.
ROC_COLOR_YELLOW	Color ID corresponding to `yellow`.
ROC_COLOR_GREEN	Color ID corresponding to `green`.
ROC_COLOR_BLUE	Color ID corresponding to `blue`.
ROC_COLOR_VIOLET	Color ID corresponding to `violet`.
ROC_COLOR_PINK	Color ID corresponding to `violet`.
ROC_COLOR_BROWN	Color ID corresponding to `brown/tan`.

◆ roc_finger_options

enum roc_finger_options

Supported fingerprint indices for use in roc_represent_fingerprint.

See also: Specifying a Finger ID

Enumerator
ROC_NO_FINGER	Ignored finger, fingers with this value won't be used.
ROC_THUMB	The subject's left or right thumb. To specify a hand combine with ROC_RIGHT_HAND or ROC_LEFT_HAND. For example, the left thumb would be specified as `ROC_LEFT_HAND \| ROC_THUMB`. If the hand is unknown specify `ROC_ANY_HAND \| ROC_THUMB`.
ROC_INDEX_FINGER	The subject's left or right index finger. To specify a hand combine with ROC_RIGHT_HAND or ROC_LEFT_HAND. For example, the left index finger would be specified as `ROC_LEFT_HAND \| ROC_INDEX_FINGER`. If the hand is unknown specify `ROC_ANY_HAND \| ROC_INDEX_FINGER`.
ROC_MIDDLE_FINGER	The subject's left or right middle finger. To specify a hand combine with ROC_RIGHT_HAND or ROC_LEFT_HAND. For example, the left middle finger would be specified as `ROC_LEFT_HAND \| ROC_MIDDLE_FINGER`. If the hand is unknown specify `ROC_ANY_HAND \| ROC_MIDDLE_FINGER`.
ROC_RING_FINGER	The subject's left or right ring finger. To specify a hand combine with ROC_RIGHT_HAND or ROC_LEFT_HAND. For example, the left ring finger would be specified as `ROC_LEFT_HAND \| ROC_RING_FINGER`. If the hand is unknown specify `ROC_ANY_HAND \| ROC_RING_FINGER`.
ROC_LITTLE_FINGER	The subject's left or right little finger. To specify a hand combine with ROC_RIGHT_HAND or ROC_LEFT_HAND. For example, the left little finger would be specified as `ROC_LEFT_HAND \| ROC_LITTLE_FINGER`. If the hand is unknown specify `ROC_ANY_HAND \| ROC_LITTLE_FINGER`.
ROC_EXTRA_FINGER	An extra finger that is not a thumb, index, middle, ring, or little.
ROC_RIGHT_HAND	The finger belongs to the subjects right hand. Can be combined with one or more fingers.
ROC_LEFT_HAND	The finger belongs to the subjects left hand. Can be combined with one or more fingers.
ROC_FOUR_FINGERS	A utility value to indicate the 4 non-thumb fingers.
ROC_ANY_FINGER	A utility value to indicate all 5 fingers.
ROC_ANY_HAND	A utility value to indicate either the left or right hands.
ROC_UNKNOWN_FINGER	A utility value to indicate any of the ten fingers.

Function Documentation

◆ roc_pose_to_string()

const char* roc_pose_to_string ( roc_pose pose )

A printable roc_pose.

The return value is statically allocated and should not be modified or freed.

Parameters

[in] pose Pose to convert to a string.

Remarks: This function is thread-safe.

◆ roc_landmark_is_visible()

bool roc_landmark_is_visible ( roc_landmark l )

Determine if a landmark is visible.

A landmark is visible if either roc_landmark::x or roc_landmark::y is not 0.

Parameters

[in] l Landmark to determine the visibility of.

Remarks: This function is thread-safe.

◆ roc_adaptive_minimum_size()

roc_error roc_adaptive_minimum_size	(	size_t	image_width,
		size_t	image_height,
		float	relative_min_size,
		size_t	absolute_min_size,
		size_t *	adaptive_min_size
	)

A method for determining the minimum face detection size as a fraction of the image size.

In the interest of efficiency, it is recommended to set a lower bound on the minimum face detection size as a fraction of the image size. Given a relative minimum size of 4% of the image dimensions, and an absolute minimum size of 20 pixels, the adaptive minimum size is: max(max(image.width, image.height) * 0.04f, 20).

Example: roc_image image = ...;
size_t adaptive_min_size;
roc_adaptive_minimum_size(image.width, image.height, ROC_SUGGESTED_RELATIVE_MIN_SIZE, ROC_SUGGESTED_ABSOLUTE_MIN_SIZE, &adaptive_min_size);

Parameters

[in]	image_width	Image width dimension to use for the relative minimum size calculation.
[in]	image_height	Image height dimension to use for the relative minimum size calculation.
[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.
[out]	adaptive_min_size	Maximum of the relative and absolute minimum sizes.

Remarks: This function is thread-safe.

◆ roc_algorithm_option_to_string()

roc_error roc_algorithm_option_to_string	(	roc_algorithm_options	algorithm_option,
		const char **	str
	)

String representation of a roc_algorithm_options.

The string form uses the same character sequence as the code form. For example, ROC_FRONTAL_DETECTION is "ROC_FRONTAL_DETECTION". The returned str is statically-allocated data and should not be freed.

Parameters

[in]	algorithm_option	Algorithm option to convert to a string.
[out]	str	String version of `algorithm_option`.

Remarks: This function is thread-safe.

See also: roc_algorithm_option_from_string.

◆ roc_algorithm_option_from_string()

roc_error roc_algorithm_option_from_string	(	const char *	str,
		roc_algorithm_options *	algorithm_option
	)

The opposite of roc_algorithm_option_to_string.

Parameters

[in]	str	String to convert to a `algorithm_option`.
[out]	algorithm_option	Code version of `str`.

Remarks: This function is thread-safe.

◆ roc_finger_id_to_string()

roc_error roc_finger_id_to_string	(	roc_finger_id	finger_id,
		roc_string *	str
	)

String representation of a roc_finger_id.

The string form uses an aggregate formulation of the bit field. For example, ROC_RIGHT_HAND | ROC_THUMB is "Right+Thumb". ROC_ANY_HAND | ROC_ANY_FINGER is "Right+Left+Thumb+Index+Middle+Ring+Pinky". The returned str is dynamically-allocated data and must be freed with a call to roc_free_string.

Parameters

[in]	finger_id	Finger ID to convert to a string.
[out]	str	String version of `finger_option`.

Remarks: This function is reentrant.

See also: roc_finger_id_from_string.

◆ roc_finger_id_from_string()

roc_error roc_finger_id_from_string	(	roc_string	str,
		roc_finger_id *	finger_id
	)

The opposite of roc_finger_id_to_string.

Parameters

[in]	str	String to convert to a `finger_option`.
[out]	finger_id	Finger ID version of `str`.

Remarks: This function is thread-safe

◆ roc_check_template_version()

roc_error roc_check_template_version ( roc_algorithm_id algorithm_id )

Return an error if the specified roc_algorithm_id is incompatible with this version of the SDK.

Parameters

[in] algorithm_id Value to check for compatibility.

Remarks: This function is thread-safe.

◆ roc_get_suggested_quality_threshold()

float roc_get_suggested_quality_threshold ( roc_algorithm_id algorithm_id )

Returns the suggested quality threshold for roc_represent for the specified representation.

Parameters

[in] algorithm_id Representation for which to return the suggested quality threshold.

Representation	Value
ROC_DEEP_REPRESENTATION	ROC_DEEP_SUGGESTED_MIN_QUALITY
ROC_STANDARD_REPRESENTATION	ROC_STANDARD_SUGGESTED_MIN_QUALITY
ROC_FAST_REPRESENTATION	ROC_FAST_SUGGESTED_MIN_QUALITY
ROC_TATTOO_REPRESENTATION	ROC_TATTOO_SUGGESTED_MIN_QUALITY
ROC_TEXT_REPRESENTATION	ROC_TEXT_SUGGESTED_MIN_QUALITY
ROC_FINGERPRINT_REPRESENTATION	ROC_FINGERPRINT_SUGGESTED_MIN_QUALITY
Default	ROC_NO_MIN_QUALITY

Returns: Suggested quality threshold.

Remarks: This function is thread-safe.

◆ roc_new_template()

roc_error roc_new_template	(	roc_template *	template_,
		uint32_t	md_size,
		uint32_t	fv_size,
		uint32_t	tn_size
	)

Allocate memory for a new template.

This function should be used when you have stored template fields in an external database and wish to reconstruct the roc_template. Generally you don't need to call this function because templates are constructed by calling roc_represent.

Free templates after use with roc_free_template.

Parameters

[out]	template_	Template to initialize.
[in]	md_size	roc_template::md_size.
[in]	fv_size	roc_template::fv_size.
[in]	tn_size	roc_template::tn_size.

◆ roc_new_color_template()

roc_error roc_new_color_template	(	roc_template *	template_,
		const roc_color_selection	color_selection,
		const char *	object_type
	)

Construct a new template for color-based searching.

This function creates a new template which can be used for searching a gallery based on color. Templates must have been generated with ROC_COLOR_REPRESENTATION. The generated template will have no metadata and should only be used to perform searches.

Parameters

[out]	template_	Template to initialize.
[in]	color_selection	roc_color_selection.
[in]	object_type	String representing the object being searched for (see ROC_ALL_OBJECT_DETECTION for strings).

See also: roc_new_person_color_template

◆ roc_new_person_color_template()

roc_error roc_new_person_color_template	(	roc_template *	template_,
		const roc_color_selection	torso_color_selection,
		const roc_color_selection	thigh_color_selection
	)

Construct a new person template for color-based searching.

This function creates a new template which can be used for searching a gallery based on color. Templates must have been generated with ROC_COLOR_REPRESENTATION. The generated template will have no metadata and should only be used to perform searches.

This function differs from roc_new_color_template because it is specific to the person object class. It requires a color for both the torso and thigh regions to match (color can be ROC_COLOR_NONE to ignore a region).

Parameters

[out]	template_	Template to initialize.
[in]	torso_color_selection	roc_color_selection.
[in]	thigh_color_selection	roc_color_selection.

See also: roc_new_color_template

◆ roc_free_template()

roc_error roc_free_template ( roc_template * template_ )

Call this function on a template after it is no longer needed.

Frees the memory previously allocated for roc_template::fv, roc_template::md, and roc_template::tn. Sets roc_template::algorithm_id to ROC_NO_ALGORITHM_OPTIONS. If template_ is NULL, this function does nothing.

Parameters

[in,out] template_ The template to deallocate.

Remarks: This function is reentrant.

◆ roc_copy_template()

roc_error roc_copy_template	(	const roc_template	src,
		roc_template *	dst
	)

Deep-copy a template.

In-place copying is supported with dst pointing to src.

Free dst after use with roc_free_template.

Example: roc_template src = ...;
roc_template dst;
roc_copy_template(src, &dst);

Parameters

[in]	src	Template to copy.
[out]	dst	Unallocated pointer to hold a copy of `src`.

Remarks: This function is reentrant.

◆ roc_flatten()

roc_error roc_flatten	(	const roc_template	template_,
		uint8_t *	output_byte_array
	)

Serialize a template to a memory buffer.

Use roc_flattened_bytes to determine the appropriate size for buffer.

Example: roc_template template_ = ...;
size_t bytes = ...;
uint8_t *output_byte_array = (uint8_t*) malloc(bytes);
roc_flatten(template_, output_byte_array);

Parameters

[in]	template_	Template to serialize.
[out]	output_byte_array	Pre-allocated buffer to hold the serialized template.

Remarks: This function is reentrant.

See also: roc_unflatten

◆ roc_unflatten()

roc_error roc_unflatten	(	const uint8_t *	input_byte_array,
		roc_template *	template_
	)

Deserialize a template from a memory buffer.

Free template_ after use with roc_free_template.

Example: uint8_t *input_byte_array = ...;
roc_template template_;
roc_unflatten(input_byte_array, &template_);

Parameters

[in]	input_byte_array	Buffer holding the serialized template.
[out]	template_	Uninitialized address to hold the deserialized template.

Remarks: This function is reentrant.

See also: roc_flatten

◆ roc_flattened_bytes()

roc_error roc_flattened_bytes	(	const roc_template	template_,
		size_t *	bytes
	)

Calculate the bytes required to flatten a template.

Use this function to determine the appropriate buffer size for roc_flatten.

Example: roc_template template_ = ...;
size_t bytes;
roc_flattened_bytes(template_, &bytes);

Parameters

[in]	template_	Template to calculate the serialized size.
[out]	bytes	Bytes required to serialize the template.

Remarks: This function is thread-safe.

◆ roc_flattened_version()

void roc_flattened_version	(	const uint8_t *	input_byte_array,
		int *	major_version,
		int *	minor_version
	)

Obtain the SDK version of a flattened template.

To be used when you have an old template and are unsure what version of the ROC SDK was used to construct it.

Parameters

[in]	input_byte_array	Flattened template.
[out]	major_version	SDK roc_version_major used to construct `input_byte_array`.
[out]	minor_version	SDK roc_version_minor used to construct `input_byte_array`.

◆ roc_cast()

void* roc_cast ( uint8_t * pointer )

Cast and return a uint8_t* as a void*.

Helper function for some of the API language wrappers that don't support this type cast.

Parameters

[in] pointer Input pointer.

Remarks: This function is thread-safe.

Variable Documentation

◆ roc_template_header_size

const size_t roc_template_header_size

Size of the fixed-length portion of a roc_template.

Remarks: This function is thread-safe.

Data Structures

Macros

Typedefs

Enumerations

Functions

Variables

Detailed Description

Data Structure Documentation

◆ roc_landmark

◆ roc_detection

◆ roc_template

Metadata

Feature Vector

Macro Definition Documentation

◆ ROC_SUGGESTED_RELATIVE_MIN_SIZE

◆ ROC_SUGGESTED_ABSOLUTE_MIN_SIZE

◆ ROC_SUGGESTED_FALSE_DETECTION_RATE

◆ ROC_OBJECT_SUGGESTED_FALSE_DETECTION_RATE

◆ ROC_GUN_SUGGESTED_FALSE_DETECTION_RATE

◆ ROC_TEXT_SUGGESTED_FALSE_DETECTION_RATE

◆ ROC_FINGERPRINT_SUGGESTED_FALSE_DETECTION_RATE

◆ ROC_NO_MIN_QUALITY [1/2]

◆ ROC_NO_MIN_QUALITY [2/2]

◆ ROC_TEXT_SUGGESTED_MIN_QUALITY [1/2]

◆ ROC_TEXT_SUGGESTED_MIN_QUALITY [2/2]

◆ ROC_TATTOO_SUGGESTED_MIN_QUALITY [1/2]

◆ ROC_TATTOO_SUGGESTED_MIN_QUALITY [2/2]

◆ ROC_FINGERPRINT_SUGGESTED_MIN_QUALITY [1/2]

◆ ROC_FINGERPRINT_SUGGESTED_MIN_QUALITY [2/2]

◆ ROC_DEEP_SUGGESTED_MIN_QUALITY [1/2]

◆ ROC_DEEP_SUGGESTED_MIN_QUALITY [2/2]

◆ ROC_FAST_SUGGESTED_MIN_QUALITY [1/2]

◆ ROC_FAST_SUGGESTED_MIN_QUALITY [2/2]

◆ ROC_STANDARD_SUGGESTED_MIN_QUALITY [1/2]

◆ ROC_STANDARD_SUGGESTED_MIN_QUALITY [2/2]

◆ ROC_TEMPLATE_VERSION

◆ ROC_FAST_COMPATIBILITY_VERSION

◆ ROC_STANDARD_COMPATIBILITY_VERSION

◆ ROC_DEEP_COMPATIBILITY_VERSION

◆ ROC_TATTOO_COMPATIBILITY_VERSION

◆ ROC_FINGERPRINT_COMPATIBILITY_VERSION

◆ ROC_OBJECT_COMPATIBILITY_VERSION

Typedef Documentation

◆ roc_landmark

◆ roc_algorithm_id

◆ roc_color_options

◆ roc_finger_id

◆ roc_finger_options

◆ roc_template

Metadata

Feature Vector

Enumeration Type Documentation

◆ roc_pose_options

◆ roc_algorithm_options

Dynamically Loaded Model

◆ roc_color_options

◆ roc_finger_options

Function Documentation

◆ roc_pose_to_string()

◆ roc_landmark_is_visible()

◆ roc_adaptive_minimum_size()

◆ roc_algorithm_option_to_string()

◆ roc_algorithm_option_from_string()

◆ roc_finger_id_to_string()

◆ roc_finger_id_from_string()

◆ roc_check_template_version()

◆ roc_get_suggested_quality_threshold()

◆ roc_new_template()

◆ roc_new_color_template()

◆ roc_new_person_color_template()

◆ roc_free_template()

◆ roc_copy_template()

◆ roc_flatten()

◆ roc_unflatten()

◆ roc_flattened_bytes()

◆ roc_flattened_version()

◆ roc_cast()

Variable Documentation

◆ roc_template_header_size