 |
ROC SDK
2.4.0
Scalable Face Recognition Software
|
|
ROC SDK
2.4.0
Scalable Face Recognition Software
|
Initializing the SDK. More...
Typedefs | |
| typedef enum roc_license_term | roc_license_term |
| Optional license terms. | |
| typedef void(* | roc_progress) (float) |
| Pointer to a callback function used to report progress on a long running task. More... | |
Enumerations | |
| enum | roc_license_term { ROC_INITIALIZED, ROC_ANALYTICS_ONLY, ROC_EXPLORE, ROC_TATTOO_ENABLED, ROC_LIVENESS_ENABLED, ROC_ICAO_ENABLED, ROC_OCR_ENABLED, ROC_OBJECT_ENABLED, ROC_WATCH, ROC_GPU, ROC_UNLOCKED_FV, ROC_FACE_ENABLED, ROC_FINGERPRINT_ENABLED } |
| Optional license terms. More... | |
Functions | |
| roc_error | roc_initialize (const char *license_file, const char *log_file) |
| Call once at the start of the application before making any other calls to the API. More... | |
| roc_error | roc_set_keylok_keys (int validateCode1, int validateCode2, int validateCode3, int clientIDCode1, int clientIDCode2, int readCode3) |
| Set Keylok device specific keys. More... | |
| roc_error | roc_set_floating_license_server (const char *hostname) |
| Set floating license server IP address. More... | |
| roc_error | roc_set_cuda_benchmarking (bool benchmark, bool clear_cache) |
| Control CUDA benchmarking. More... | |
| roc_error | roc_set_cuda_device (int device) |
| Control which GPU to use. More... | |
| roc_error | roc_enable_cuda (bool enabled, roc_progress progress) |
| Enabled/disable CUDA acceleration. More... | |
| roc_error | roc_get_cuda_utilization (float *gpu_utilization_percentage, float *memory_utilization_percentage) |
| Retrieve performance characteristics for a GPU. More... | |
| roc_error | roc_set_opportunistic_batching (int ideal_batch_size, int maximum_latency) |
| Control batch processing across threads. More... | |
| roc_error | roc_enable_snpe (bool enabled, roc_string snpe_model_path) |
| Enable/disable Qualcomm Snapdragon chipset acceleration. More... | |
| roc_error | roc_cuda_device_count (unsigned int *device_count) |
Wraps nvmlDeviceGetCount. More... | |
| roc_error | roc_cuda_utilization (unsigned int index, unsigned int *gpu, unsigned int *memory) |
Wraps nvmlDeviceGetUtilizationRates. More... | |
| roc_error | roc_finalize () |
| Call once at the end of the application after making all other calls to the API. More... | |
| roc_error | roc_get_hostname (roc_string *hostname) |
| Retrieve the hostname of the current machine. More... | |
| roc_error | roc_get_host_id_extended (roc_string *host_id) |
| Obtain more complete information about the host system. More... | |
| roc_error | roc_get_application_certificate (roc_string *app_cert) |
| Retrieve the Application Certificate of the current process. More... | |
| roc_error | roc_get_license_term (roc_license_term license_term, bool *enabled) |
| Check if a license term is enabled. More... | |
| roc_error | roc_get_thread_limit (int *limit) |
| Get the thread count limit. More... | |
| roc_error | roc_set_thread_limit (int limit) |
| Set the thread count limit. More... | |
| roc_error | roc_get_floating_license_limit (uint32_t *clients_remaining, uint64_t *comparisons_remaining) |
| Query the floating license server for limits. More... | |
| roc_error | roc_get_floating_license_status (bool *is_connected) |
| Check the status of the floating license connection. More... | |
| roc_error | roc_set_icao_background_color (uint8_t r, uint8_t g, uint8_t b) |
| Assign the color used by ROC_ICAO_BACKGROUND for thumbnail generation. More... | |
| roc_error | roc_get_host_id (roc_string *host_id) |
| Retrieve the Host ID of the current machine. More... | |
| roc_error | roc_is_hardware_compatible () |
| Compare the system hardware against the SDK requirements. More... | |
Initializing the SDK.
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.
| typedef void(* roc_progress) (float) |
Pointer to a callback function used to report progress on a long running task.
The function should return void and take one float parameter which will range from 0.0 to 100.0 indicating the percent completed.
Any function taking a roc_progress parameter will accept a NULL value indicating not to report progress.
| enum roc_license_term |
Optional license terms.
| Enumerator | |
|---|---|
| ROC_INITIALIZED | True if roc_initialize has been called successfully. |
| ROC_ANALYTICS_ONLY | A license that disables feature vector construction. |
| ROC_EXPLORE | A license that enables the Explore GUI. |
| ROC_TATTOO_ENABLED | A license that enables ROC_TATTOO_REPRESENTATION. |
| ROC_LIVENESS_ENABLED | A license that allows ROC_SPOOF. |
| ROC_ICAO_ENABLED | A license that allows ROC_ICAO_METRICS. |
| ROC_OCR_ENABLED | A license that allows ROC_TEXT_DETECTION and ROC_TEXT_REPRESENTATION. |
| ROC_OBJECT_ENABLED | A license that allows ROC_ALL_OBJECT_DETECTION. |
| ROC_WATCH | A license that enables the Watch VMS system. |
| ROC_GPU | A license that allows roc_enable_cuda. |
| ROC_UNLOCKED_FV | A license that allows unlocked feature vectors. For licenses that allow it, the unlocked feature vector can be obtained by calling roc_get_metadata with key |
| ROC_FACE_ENABLED | A license that allows ROC_STANDARD_DETECTION, ROC_FRONTAL_DETECTION, ROC_FAST_REPRESENTATION, ROC_STANDARD_REPRESENTATION and ROC_DEEP_REPRESENTATION. |
| ROC_FINGERPRINT_ENABLED | A license that allows ROC_FINGERPRINT_REPRESENTATION. |
| roc_error roc_initialize | ( | const char * | license_file, |
| const char * | log_file | ||
| ) |
Call once at the start of the application before making any other calls to the API.
When using the Android SDK call roc_preinitialize_android first.
The license_file is the path to ROC.lic or the contents thereof.
license_file ends with .lic then it is treated as a file path, otherwise it is treated as the file contents.If license_file is NULL (as is the case for the Command Line Interface and Explore), this function will use the value from the ROC_LIC environment variable if it exists. Otherwise it will check for ../ROC.lic first relative to the current working directory, and second relative to the application binary directory (not always possible to determine). It is permissible for ROC.lic to be read-only. See roc_get_host_id for details on obtaining ROC.lic.
For certain applications the ROC SDK is licensed on a per-function-call basis. In these cases the ROC.lic license file will contain a logging requirement and log_file should be provided, otherwise log_file may be NULL.
log_file is a file path to which the ROC SDK will write encrypted usage statistics. By convention, log_file is named ROC.log. If log_file does not exist then it will be created, otherwise it will be appended to. To satisfy licensing requirements log_file should be periodically sent to Rank One Computing, and may then be deleted locally (when the application is not running). log_file contains no sensitive information, just simple usage statistics.
If log_file is NULL, but the license requires logging, this function will use the value from the ROC_LOG environment variable if it exists, otherwise this function will return an error.
The Command Line Interface uses the ROC_LOG idiom. The contents of log_file can be printed using roc-log.
Most licenses impose a limit on the number of threads across all running processes that can use the ROC SDK simultaneously. If you recieve the error QSystemSemaphore::handle: permission denied please ensure the TMPDIR environment variable is set to a folder for which you have read+write permission.
| [in] | license_file | See License File. |
| [in] | log_file | File path to write usage statistics to, or NULL if Usage Logging is not required. |
| roc_error roc_set_keylok_keys | ( | int | validateCode1, |
| int | validateCode2, | ||
| int | validateCode3, | ||
| int | clientIDCode1, | ||
| int | clientIDCode2, | ||
| int | readCode3 | ||
| ) |
Set Keylok device specific keys.
All codes will be contained within the Client.h file provided by Keylok.
| [in] | validateCode1 | ValidateCode1. |
| [in] | validateCode2 | ValidateCode2. |
| [in] | validateCode3 | ValidateCode3. |
| [in] | clientIDCode1 | ClientIDCode1. |
| [in] | clientIDCode2 | ClientIDCode2. |
| [in] | readCode3 | ReadCode3. |
| roc_error roc_set_floating_license_server | ( | const char * | hostname | ) |
Set floating license server IP address.
In the typical case, the floating license server IP address is hard-coded in the client license file. However, if it is not specified then it must be set by calling this function before calling roc_initialize.
| [in] | hostname | Hostname or IP address of the floating license server. |
| roc_error roc_set_cuda_benchmarking | ( | bool | benchmark, |
| bool | clear_cache | ||
| ) |
Control CUDA benchmarking.
On load the first time, this function will benchmark and cache execution paths to select the fastest for the particular GPU model. In the unusual case that abnormal results are being observed, you can disable or reset benchmarking by calling this function.
This function should be called before roc_enable_cuda.
| [in] | benchmark | Enable/disable CUDA kernel benchmarking, default is true. |
| [in] | clear_cache | Clear kernel benchmarking cache, default is false. |
| roc_error roc_set_cuda_device | ( | int | device | ) |
Control which GPU to use.
This function corresponds to the cudaSetDevice API call.
This function should be called before roc_enable_cuda.
| [in] | device | GPU index, default is 0 (the fastest device on the system). |
| roc_error roc_enable_cuda | ( | bool | enabled, |
| roc_progress | progress | ||
| ) |
Enabled/disable CUDA acceleration.
By default CUDA acceleration is disabled. Call this function after calling roc_initialize. If you choose to enable CUDA, we advise disabling it at the end of the application, before calling roc_finalize, to cleanly deallocate GPU resources.
"bin", "lib" and "include" folders to "C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v11.4\" | [in] | enabled | Enable/disable CUDA acceleration. |
| [in] | progress | Optional progress callback or NULL. |
| roc_error roc_get_cuda_utilization | ( | float * | gpu_utilization_percentage, |
| float * | memory_utilization_percentage | ||
| ) |
Retrieve performance characteristics for a GPU.
This function can only be called after both roc_enable_cuda and roc_set_cuda_device. gpu_utilization_percentage is determined from a sample period that may be between 1 second and 1/6 second, depending on the GPU being queried.
| [in] | gpu_utilization_percentage | Percent of time over the past sample period during which one or more kernels was executing on the GPU. |
| [in] | memory_utilization_percentage | Percent of device memory in use. |
| roc_error roc_set_opportunistic_batching | ( | int | ideal_batch_size, |
| int | maximum_latency | ||
| ) |
Control batch processing across threads.
By default ideal_batch_size equals 1 and threads calling roc_represent will process their data independently. However, there are certain circumstances where greater bandwidth can be achieved by syncing threads at the same stages in the computation. The primary case for this is when using CUDA with roc_enable_cuda, in which case batch sizes that are powers-of-two (up to 32 on current hardware) will result in increasingly greater overall bandwidth, at the expense of increasing latency. An ideal_batch_size of 8 works well for a variety of modern CUDA GPUs supporting tensor cores. When setting ideal_batch_size to a value greater than 1 it is critical to spawn extra threads to feed images to roc_represent, as many threads at any given moment will be waiting for their queued data to be processed by the batch execution engine. For a CPU with C cores we recommend using a thread pool with C + ideal_batch_size threads. Furthermore we recommend using ROC_SERIAL to limit parallelization to one thread per image. Threads will wait until either ideal_batch_size is reached or maximum_latency milliseconds has elapsed, whichever comes first.
| [in] | ideal_batch_size | Control the maximum batch size, default is 1 which means no batching takes place. |
| [in] | maximum_latency | Maximum allowed latency in milliseconds when accumulating data across threads, default is 1000. |
| roc_error roc_enable_snpe | ( | bool | enabled, |
| roc_string | snpe_model_path | ||
| ) |
Enable/disable Qualcomm Snapdragon chipset acceleration.
The ROC SDK supports hardware acceleration for ROC_DEEP_REPRESENTATION on Android and Linux Snapdragon chipset devices. By default, Snapdragon acceleration is disabled. Call this function after calling roc_initialize. If you choose to enable SNPE, we advise disabling it at the end of the application, before calling roc_finalize, to cleanly deallocate Snapdragon resources. In order to use Snapdragon acceleration, an "ff-deep.dlc" file (supplied by Rank One) must be placed in a readable location on your device. For example, the path, "/sdcard/roc/" would work well on a mobile Android device.
| [in] | enabled | Enable/disable Snapdragon acceleration. |
| [in] | snpe_model_path | Path to Rank One-supplied .dlc file. |
| roc_error roc_cuda_device_count | ( | unsigned int * | device_count | ) |
Wraps nvmlDeviceGetCount.
roc_cuda shared library.| [out] | device_count | The number of accessible devices. |
| roc_error roc_cuda_utilization | ( | unsigned int | index, |
| unsigned int * | gpu, | ||
| unsigned int * | memory | ||
| ) |
Wraps nvmlDeviceGetUtilizationRates.
roc_cuda shared library.| [in] | index | The index of the target GPU. |
| [out] | gpu | Percent of time over the past sample period during which one or more kernels was executing on the GPU. |
| [out] | memory | Percent of time over the past sample period during which global (device) memory was being read or written. |
| roc_error roc_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_initialize after this function to re-initialize the SDK is not supported.
| roc_error roc_get_hostname | ( | roc_string * | hostname | ) |
Retrieve the hostname of the current machine.
| [out] | hostname | The hostname for the current machine. |
| roc_error roc_get_host_id_extended | ( | roc_string * | host_id | ) |
Obtain more complete information about the host system.
This function extends roc_get_host_id with additional context. Free host_id after use with roc_free_string.
| [out] | host_id | Output host information. |
| roc_error roc_get_application_certificate | ( | roc_string * | app_cert | ) |
Retrieve the Application Certificate of the current process.
Every Android app is signed with a signing certificate. As an alternative way to check the signing certificate, click on the Gradle menu in Android Studio, expand the Tasks tree, and click on "android" then "signingReport". Look for SHA-256 hash of the corresponding build(s). See this Stack Overflow question for details.
| [out] | app_cert | The signing certificate SHA-256 hash for the current application. |
| roc_error roc_get_license_term | ( | roc_license_term | license_term, |
| bool * | enabled | ||
| ) |
Check if a license term is enabled.
| [in] | license_term | The term to query. |
| [out] | enabled | The value for license_term. |
| roc_error roc_get_thread_limit | ( | int * | limit | ) |
Get the thread count limit.
The thread count limit is the maximum number of concurrent calls that can be made to ROC SDK functions as specified by the threads value in the ROC.lic license file.
| [out] | limit | The thread count limit. |
| roc_error roc_set_thread_limit | ( | int | limit | ) |
Set the thread count limit.
If limit is greater than the thread limit specified in the license file then it will be ignored.
| [in] | limit | Maximum number threads to use. |
| roc_error roc_get_floating_license_limit | ( | uint32_t * | clients_remaining, |
| uint64_t * | comparisons_remaining | ||
| ) |
Query the floating license server for limits.
The value for clients_remaining is the instances specified in the client license file less the number of currently active clients (including the client making the request). The value for comparisons_remaining is the roc_comparison_limit reported by the server.
If the license file specified for roc_initialize is not floating then clients_remaining and comparisons_remaining will be set to zero and this function will return without error. If the license does not require Usage Logging then the value returned for comparisons_remaining should be ignored.
| [out] | clients_remaining | Number of client licenses available. |
| [out] | comparisons_remaining | Number of comparisons remaining for licenses that require Usage Logging. |
| roc_error roc_get_floating_license_status | ( | bool * | is_connected | ) |
Check the status of the floating license connection.
| [out] | is_connected | true if the most recent attempt to connect to the license server was successful, false otherwise. |
| roc_error roc_set_icao_background_color | ( | uint8_t | r, |
| uint8_t | g, | ||
| uint8_t | b | ||
| ) |
Assign the color used by ROC_ICAO_BACKGROUND for thumbnail generation.
The default color is white (255, 255, 255).
| [in] | r | Red (0-255). |
| [in] | g | Green (0-255). |
| [in] | b | Blue (0-255). |
| roc_error roc_get_host_id | ( | roc_string * | host_id | ) |
Retrieve the Host ID of the current machine.
The Host ID is a null-terminated JSON string uniquely identifying the current machine.
Rank One uses the Host ID to generate the ROC.lic license file that should be copied to the ROC SDK root directory, overwriting the placeholder license file of the same name. See License Generation for details.
Free host_id after use with roc_free_string.
This function can be called before roc_initialize.
| [out] | host_id | The Host ID for the current machine. |
| roc_error roc_is_hardware_compatible | ( | ) |
Compare the system hardware against the SDK requirements.
This function calls _cpuid to check the availble instruction sets of the CPU and compares them against the requirements of the ROC SDK. Returns NULL if the hardware matches the API.
Current checks:
1.8.15