All ROC SDK capabilities are accessible via a C-language Application Programming Interface (API). This approach is well suited for software engineers looking to build custom applications using ROC SDK face recognition technology.

Getting Started

Add /path/to/ROC_SDK/include to your include directories and /path/to/ROC_SDK/lib to your lib directories. #include "roc.h" and link against roc. Additionally link against roc_video for Video Decoding.

Examples

Source code for these examples is available in the examples folder.

Overview

Versioning
The SDK version is comprised of three values: ROC_VERSION_MAJOR, ROC_VERSION_MINOR and ROC_VERSION_PATCH.

Error Handling
All ROC functions return a printable roc_error message by design. The ROC_ATTEMPT macro and roc_ensure function are provided as basic error handling methods.

Image Format
Copy an image with roc_copy_image, rotate an image with roc_rotate, and free an image with roc_free_image.

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

Similarity
See roc_similarity for details.

Android
Call roc_preinitialize_android before calling roc_initialize.

Initialization
A ROC application begins with a call to roc_initialize, and ends with a call to roc_finalize. For license management see roc_get_host_id.

Identifiers and Hashes
Construct UUIDs with roc_uuid_get_random and convert them to/from strings with roc_uuid_to_string / roc_uuid_from_string.

Construct hashes with roc_hash_calc_sha1 and convert them to/from strings with roc_hash_to_string / roc_hash_from_string.

Image Decoding
Decode a roc_image from a file with roc_read_image or from a buffer with roc_decode_image.

Video Decoding
Open a roc_video with roc_open_video or roc_open_spinnaker. On Linux, open a live stream for CPU or GPU-accelerated decoding with roc_open_gst_video. Read frames sequentially with roc_read_frame, seek to a frame or keyframe with roc_seek_frame or roc_seek_keyframe and close a video with roc_close_video.

Video Streaming
Start a stream with roc_stream_start and stop it with roc_stream_stop. Control the stream with roc_stream_set_frame_rate and roc_stream_set_paused.

Template Generation
Process faces in an image with roc_represent. Free a face roc_template after use with roc_free_template.

Template I/O
Copy a template with roc_copy_template. Serialize and deserialze templates to memory buffers with roc_flatten and roc_unflatten. Read and write templates using file pointers with roc_read_template and roc_write_template, or file descriptors with roc_read_template_fd and roc_write_template_fd. Read and write template metadata with roc_get_metadata and roc_set_metadata or roc_get_metadata_double and roc_set_metadata_double.

Gallery Construction
Open a roc_gallery_file with roc_open_gallery and close it with roc_close_gallery. Treat a gallery as a list of templates with roc_enroll, roc_size and roc_at, and roc_remove. Query the template limit with roc_template_limit.

Comparison
Measure the roc_similarity between individual face templates with roc_compare_templates or galleries with roc_compare_galleries.

Search
Retrieve a sorted list of the top candidate templates for a single probe with roc_search or multiple independent probes with roc_knn. Re-order search results based on commonly occuring roc_person_id with roc_rerank.

Media Database
A roc_database is simply a folder on the file system managed by the ROC SDK.

Add data with roc_database_add_file, roc_database_add_link, or roc_database_add_data. Obtain a previously added file with roc_database_retrieve_file or roc_database_retrieve_data.

Foreground Modeling
Detect foreground movement in video frames by looking for changes relative to a static background.

Tracking
In the typical case, for tracking and watchlisting one or more live-streams or pre-recorded videos, use roc_tracker and see roc_tracker_add_template for details.

Identity Discovery
Identities are managed using the roc_template::person_id field. Cluster faces into identities with roc_cluster. Downsample identities with roc_consolidate. Retrieve identities from a gallery with roc_all_person_ids. Apply ground truth with roc_adjudicate_knn and roc_adjudicate_gallery.

Remote Data Structures
Host a roc_gallery for remote access with roc_start_gallery_server. Host a roc_database for remote access with roc_start_database_server. Host a roc_template_pipe for remote access with roc_start_template_pipe_server.

Thread Safety

All functions are marked one of:

thread-safe Can be called simultaneously from multiple threads, even when the invocations use the same data.
reentrant Can be called simultaneously from multiple threads, but only if each invocation uses different data.
thread-unsafe Can not be called simultaneously from multiple threads.

A function may also be marked:

parallel The workload for this function is automatically parallelized to make use of all CPU cores belonging to the system.