Comparison

Compare face templates. More...

Functions
roc_error	roc_compare_templates (const roc_template a, const roc_template b, roc_similarity *similarity)
	Measure the similarity between two templates. More...
roc_error	roc_acquire_search_thread ()
	Unlock the full speed of roc_compare_templates. More...
roc_error	roc_release_search_thread ()
	Return the calling thread's access to roc_compare_templates to normal speed. More...
roc_error	roc_compare_galleries (roc_const_gallery target, roc_const_gallery query, roc_similarity *similarity_matrix)
	Measure the pairwise similarity between all templates in two galleries. More...
roc_error	roc_comparison_limit (size_t *comparison_limit)
	Query the remaining comparison limit. More...

Detailed Description

Compare face templates.

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

Function Documentation

roc_compare_templates()

roc_error roc_compare_templates	(	const roc_template	a,
		const roc_template	b,
		roc_similarity *	similarity
	)

Measure the similarity between two templates.

Higher scores indicate greater similarity. This function is a specialized version of roc_compare_galleries.

Note

Comparisons involving many templates should make use of the other Functions That Measure Similarity as they will be much faster than making repeated calls this this function.

Symmetry

The returned similarity score is symmetric. In other words, swapping the order of a and b will not change similarity.

Empty Template

A template is said to be empty if it has a NULL feature vector. By convention, a comparison involving one or both empty templates results in a similarity of ROC_INVALID_SIMILARITY.

Example

roc_template a = ...;
roc_template b = ...;
roc_similarity similarity;
roc_compare_templates(a, b, &similarity);

Parameters

[in]	a	The first template to compare.
[in]	b	The second template to compare.
[out]	similarity	Similarity between a and b.

Remarks

This function is thread-safe.

See also

roc_acquire_search_thread

roc_acquire_search_thread()

roc_error roc_acquire_search_thread

(

)

Unlock the full speed of roc_compare_templates.

Customers with search-grade licenses of at least 100K templates may implement their own search functionality using roc_compare_templates. To realize the maximum speed offered by roc_compare_templates, the calling thread should first call this function before making subsequent calls to roc_compare_templates. Customers may call this function concurrently for as many threads as are allowed in their license file. Release the optimization by calling roc_release_search_thread. Please note the Threads limit is global to all SDK function calls, so using all threads for search would block functions like roc_represent.

Remarks

This function is thread-safe.

roc_release_search_thread()

roc_error roc_release_search_thread

(

)

Return the calling thread's access to roc_compare_templates to normal speed.

Remarks

This function is thread-safe.

roc_compare_galleries()

roc_error roc_compare_galleries	(	roc_const_gallery	target,
		roc_const_gallery	query,
		roc_similarity *	similarity_matrix
	)

Measure the pairwise similarity between all templates in two galleries.

This function is a generalized version of roc_compare_templates and is exposed in the Command Line Interface as roc-compare.

When a and b refer to the same gallery, similarities is called a self-similarity matrix.

Example

roc_const_gallery target = ...;
roc_const_gallery query = ...;
size_t target_size, query_size;
roc_size(target, &target_size);
roc_size(query, &query_size);
roc_similarity *similarity_matrix = (roc_similarity*) malloc(target_size *
                                                             query_size *
                                                     sizeof(roc_similarity));
roc_compare_galleries(a, b, similarities);

Parameters

[in]	target	Gallery whose templates constitute the columns in similaries.
[in]	query	Gallery whose templates constitute the rows in similarities.
[out]	similarity_matrix	Buffer large enough to hold roc_size(target) * roc_size(query) similarity scores, populated in row-major order.

Remarks

This function is thread-safe and parallel.

roc_comparison_limit()

roc_error roc_comparison_limit

(

size_t *

comparison_limit

)

Query the remaining comparison limit.

Some licenses of the ROC SDK include a limit to the number of comparisons that can be made over the lifetime of the license. The number of comparisons is the number of times roc_compare_templates or roc_compare_galleries or roc_search or roc_knn has been called. This function returns the number of comparisons specified in the license file less the number of comparisons used to date.

Example

size_t comparison_limit;
roc_comparison_limit(&comparison_limit);

Parameters

[out]

comparison_limit

The remaining number of comparisons available.

Remarks

This function is thread-safe.

See also

roc_representation_limit roc_template_limit