Group a gallery into identities. More...

Data Structures
struct	roc_adjudication
	An adjudication is used to specify the identity match/non-match relationship between two templates with absolute certainty. More...

Typedefs
typedef struct roc_adjudication	roc_adjudication
	An adjudication is used to specify the identity match/non-match relationship between two templates with absolute certainty. More...

Functions
roc_error	roc_cluster (roc_gallery gallery, size_t k, const roc_candidate *neighbors, roc_similarity similarity, bool incremental, roc_progress progress)
	Construct clusters from a k-nearest neighbors graph. More...

roc_error	roc_adjudicate_knn (size_t gallery_size, size_t k, roc_candidate neighbors, const roc_adjudication adjudications, size_t num_adjudications)
	Update a KNN graph with ground truth identity information. More...

roc_error	roc_adjudicate_gallery (roc_gallery gallery, const roc_adjudication *adjudications, size_t num_adjudications)
	Update a gallery with ground truth identity information. More...

roc_error	roc_extend (roc_gallery gallery, roc_const_gallery probes, roc_similarity threshold, bool spawn)
	Extend a labeled gallery with additional templates based on similarity. More...

roc_error	roc_consolidate (roc_gallery gallery, roc_similarity max_similarity, size_t max_count)
	Downsample a gallery by removing redundant templates for each roc_template::person_id. More...

roc_error	roc_consolidate_persons (roc_gallery gallery, roc_similarity max_similarity)
	Downsample a gallery by removing redundant persons. More...

roc_error	roc_consolidate_fingerprints (roc_gallery gallery)
	Consolidate multiple fingerprints from the same person into a single template. More...

roc_error	roc_get_template_id (roc_gallery gallery, roc_template_index index, roc_template_id *template_id)
	Get a template's unique id. More...

roc_error	roc_get_person_id (roc_gallery gallery, roc_template_index index, roc_person_id *person_id)
	Get a template's identity label. More...

roc_error	roc_set_person_id (roc_gallery gallery, roc_template_index index, roc_person_id person_id)
	Set a template's identity label. More...

roc_error	roc_all_person_ids (roc_const_gallery gallery, roc_person_id_array person_ids, size_t num_person_ids)
	Retrieve the roc_template::person_id for each template in a gallery. More...

roc_error	roc_unique_person_ids (roc_const_gallery gallery, roc_person_id_array person_ids, size_t num_person_ids)
	Retrieve the set of unique roc_template::person_id in a gallery. More...

roc_error	roc_indicies_for_person_id (roc_const_gallery gallery, roc_person_id person_id, roc_template_index_array template_indicies, size_t num_template_indicies)
	Retrieve the set of roc_template_index for a roc_person_id. More...

roc_error	roc_indicies_for_media_id (roc_const_gallery gallery, roc_media_id media_id, roc_template_index_array template_indicies, size_t num_template_indicies)
	Retrieve the set of roc_template_index for a roc_media_id. More...

Detailed Description

Group a gallery into identities.

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.

Data Structure Documentation

◆ roc_adjudication

struct roc_adjudication

An adjudication is used to specify the identity match/non-match relationship between two templates with absolute certainty.

This information is used by roc_cluster, and the order of operations should be:

As implied by the existence of roc_adjudicate_knn, the functions roc_search and roc_knn do not consider adjudication information assigned by roc_adjudicate_gallery.

Template indicies roc_adjudication::a and roc_adjudication::b are presumed to be unequal valid indicies into same gallery.

An array of roc_adjudication need not be exhaustive, but should be free of contradictions: if A=B and B=C the software will infer A=C, and it should not be the case that A!=C is also specified.

Data Fields
roc_template_index	a	First template index.
roc_template_index	b	Second template index.
bool	same_person	`true` if the templates are the same person, `false` if they are different people.

Typedef Documentation

◆ roc_adjudication

typedef struct roc_adjudication roc_adjudication

An adjudication is used to specify the identity match/non-match relationship between two templates with absolute certainty.

This information is used by roc_cluster, and the order of operations should be:

As implied by the existence of roc_adjudicate_knn, the functions roc_search and roc_knn do not consider adjudication information assigned by roc_adjudicate_gallery.

Template indicies roc_adjudication::a and roc_adjudication::b are presumed to be unequal valid indicies into same gallery.

An array of roc_adjudication need not be exhaustive, but should be free of contradictions: if A=B and B=C the software will infer A=C, and it should not be the case that A!=C is also specified.

Function Documentation

◆ roc_cluster()

roc_error roc_cluster	(	roc_gallery	gallery,
		size_t	k,
		const roc_candidate *	neighbors,
		roc_similarity	similarity,
		bool	incremental,
		roc_progress	progress
	)

Construct clusters from a k-nearest neighbors graph.

Clustering groups templates by similarity. This function modifies gallery to store clustering results persistently in the roc_template::person_id field for each template in gallery, which can be retrieved by calling roc_all_person_ids. roc_person_id values are assigned to clusters randomly with roc_uuid_get_random. The order of the templates in gallery remains the same.

The input to this function is the output from roc_knn. When calling roc_knn a min_similarity of 0 is advised, and k of approximately double (or more) the expected average cluster size.

This function is exposed in the Command Line Interface as roc-cluster.

Clustering Similarity

The similarity threshold controls the average pairwise similarity in a cluster.

Adjudication

To apply ground truth knowledge to clustering, call roc_adjudicate_knn on neighbors before this function and roc_adjudicate_gallery on gallery after this function.

incremental_clustering

If incremental is true, clustering will begin with templates pre-grouped by their current roc_person_id. Because the clustering algorithm uses a bottom-up approach, clusters will only be further combined, and never separated. Templates with roc_uuid_is_null roc_template::person_id will each begin in their own cluster assigned to a roc_uuid_get_random roc_person_id. If incremental is false, clustering begins from scratch with each template in its own cluster and a roc_uuid_get_random roc_person_id.

Example: roc_gallery gallery = ...;
size_t k = ...;
roc_candidate *neighbors = ...;
roc_cluster(gallery, k, neighbors, ROC_DEFAULT_SEARCH_THRESHOLD, false, NULL);

Parameters

[in,out]	gallery	The gallery used to construct `neighbors`.
[in]	k	Number of nearest neighbors kept for each template in `neighbors`.
[in]	neighbors	Nearest neighbor graph computed from roc_knn with `gallery`.
[in]	similarity	Clustering similarity threshold, see Clustering Similarity.
[in]	incremental	See incremental_clustering.
[in]	progress	Optional progress callback or `NULL`.

Remarks: This function is thread-safe.

See also: roc_extend

◆ roc_adjudicate_knn()

roc_error roc_adjudicate_knn	(	size_t	gallery_size,
		size_t	k,
		roc_candidate *	neighbors,
		const roc_adjudication *	adjudications,
		size_t	num_adjudications
	)

Update a KNN graph with ground truth identity information.

Entries in neighbors that are known to be the same person based on adjudications will be assigned a roc_candidate::similarity of 1. Entries that are known to be different people will be assigned a roc_candidate::similarity of 0 and roc_candidate::index of ROC_INVALID_TEMPLATE_INDEX. The candidate lists will then be re-sorted.

Parameters

gallery_size	Size of gallery used to construct `neighbors`.
k	Number of candidates for each template.
neighbors	KNN graph to update.
adjudications	Array of ground truth identity information.
num_adjudications	Length of `adjudications`.

Remarks: This function is reentrant.

See also: roc_knn roc_adjudicate_gallery

◆ roc_adjudicate_gallery()

roc_error roc_adjudicate_gallery	(	roc_gallery	gallery,
		const roc_adjudication *	adjudications,
		size_t	num_adjudications
	)

Update a gallery with ground truth identity information.

Update roc_person_id entries in gallery to respect adjudications. This function makes two passes through gallery. The first pass checks for cases where two templates have the same roc_person_id but adjudications indicate they are different people, and assigns roc_uuid_get_null to the template with the higher index. The second pass assigns the same roc_person_id when adjudications indicates they are the same person using the following rules:

If both templates are roc_uuid_is_null, a new unique roc_person_id is used.
The one template is roc_uuid_is_null, the other roc_person_id is used.
If neither template is roc_uuid_is_null, the lower roc_person_id is used.

Parameters

gallery	Gallery to update identity information.
adjudications	Array of ground truth identity information.
num_adjudications	Length of `adjudications`.

Remarks: This function is thread-safe.

See also: roc_cluster roc_adjudicate_knn

◆ roc_extend()

roc_error roc_extend	(	roc_gallery	gallery,
		roc_const_gallery	probes,
		roc_similarity	threshold,
		bool	spawn
	)

Extend a labeled gallery with additional templates based on similarity.

For each template in probes, this function considers enrolling it to gallery as follows. The mean similarity is computed between the probe and each set of templates with the same roc_person_id in gallery. If the greatest mean similarity meets or exceeds threshold then the template is enrolled to gallery with the associated roc_person_id.

If spawn is true, and the probe template does not meet the similarity threshold, then the probe will be enrolled with a unique roc_person_id equal to one more than the maximum existing roc_person_id in gallery. Otherwise the probe won't be enrolled if it doesn't satisfy threshold.

If the probe's roc_template::person_id does not roc_uuid_is_null then the probe will only be considered against the single set of templates in gallery with the same roc_person_id.

Probes are considered one at a time, so that a later template in probes may be assigned to the same roc_person_id as an earlier probe that spawned a new roc_person_id. Therefore, this function is not invariant to the order or templates in probes. Duplicate probes (those with a roc_similarity of 1.0 to a template in the gallery) will be ignored.

Templates in gallery where roc_template::person_id is roc_uuid_is_null will be ignored.

This function is exposed in the Command Line Interface as roc-consolidate.

Example: roc_gallery gallery = ...;
roc_const_gallery probes = ...;
roc_extend(gallery, probes, 0.5, true);

Parameters

[in,out]	gallery	The gallery to be extended by `probes`.
[in]	probes	The templates to consider adding to `gallery`.
[in]	threshold	The similarity required to add templates in `probes` to `gallery`.
[in]	spawn	Add template as a new roc_person_id if it does not satisfy `threshold`.

Remarks: This function is thread-safe.

See also: roc_cluster

◆ roc_consolidate()

roc_error roc_consolidate	(	roc_gallery	gallery,
		roc_similarity	max_similarity,
		size_t	max_count
	)

Downsample a gallery by removing redundant templates for each roc_template::person_id.

For each set of templates with the same roc_template::person_id in gallery, this function greedily removes the "most redundant template" until both of the following conditions are met:

The maximum pairwise similarity between all remaining templates is less than or equal to max_similarity. See Maximum Similarity.
The number of remaining templates is less than or equal to max_count. See Maximum Count.

When searching for the "most redundant template" the pair of templates with highest roc_similarity is found, and in the pair the template with the lesser Face Quality is removed.

Templates with roc_template::person_id roc_uuid_is_null in gallery are retained automatically. This function is generally called after roc_cluster to discard superfluous templates.

This function is exposed in the Command Line Interface as roc-consolidate.

Note: This function removes templates from gallery using roc_remove. Therefore, it does not change the position or order of the templates in gallery.

Maximum Similarity

The maximum pairwise similarity between templates in a consolidated identity, between zero and one inclusive. After consolidation no two templates belonging to the same person will have a similarity score greater than max_similarity. The suggested default value for max_similarity is 0.9.

Maximum Count

The maximum number of templates in a consolidated identity, greater than zero. After consolidation no person will have more than max_count templates. The suggested default value for max_count is 10.

Example: roc_gallery gallery = ...;
roc_consolidate(gallery, 0.9, 10);

Parameters

[in,out]	gallery	The gallery containing the persons to consolidate.
[in]	max_similarity	The maximum intra-person pairwise similarity, see Maximum Similarity.
[in]	max_count	The maximum number of templates per person, see Maximum Count.

Remarks: This function is thread-safe.

See also: roc_consolidate_persons

◆ roc_consolidate_persons()

roc_error roc_consolidate_persons	(	roc_gallery	gallery,
		roc_similarity	max_similarity
	)

Downsample a gallery by removing redundant persons.

For each set of templates with the same roc_template::person_id in gallery, this function greedily removes the "most redundant subject" until the following condition is met:

The maximum pairwise similarity between all remaining subjects is less than or equal to max_similarity. The similarity between two subjects is the average similarity between their templates.

When searching for the "most redundant subject" the pair of subjects with highest average roc_similarity is found, and in the pair the subject with the smaller template count is removed. If both subjects have the same template count, the one with the greater roc_person_id is removed.

Templates with roc_template::person_id roc_uuid_is_null in gallery are retained automatically.

This function is exposed in the Command Line Interface as roc-consolidate.

Note: This function removes templates from gallery using roc_remove. Therefore, it does not change the position or order of the templates in gallery.

Example: roc_gallery gallery = ...;
roc_consolidate_persons(gallery, 0.9);

Parameters

[in,out]	gallery	The gallery containing the persons to consolidate.
[in]	max_similarity	The maximum inter-person similarity.

Remarks: This function is thread-safe.

See also: roc_consolidate

◆ roc_consolidate_fingerprints()

roc_error roc_consolidate_fingerprints ( roc_gallery gallery )

Consolidate multiple fingerprints from the same person into a single template.

For each set of templates with the same roc_template::person_id in gallery, this function combines all templates into a single template. Single templates are useful for comparison and can produce more accurate search results.

Templates with roc_template::person_id roc_uuid_is_null in gallery are retained automatically.

This function is exposed in the Command Line Interface as roc-consolidate.

Note: This function removes templates from gallery using roc_remove. Therefore, it does not change the position or order of the templates in gallery.

Example: roc_gallery gallery = ...;
roc_consolidate_fingerprints(gallery);

Parameters

[in,out] gallery The gallery containing the fingerprints to consolidate.

Remarks: This function is thread-safe.

See also: roc_consolidate_persons

◆ roc_get_template_id()

roc_error roc_get_template_id	(	roc_gallery	gallery,
		roc_template_index	index,
		roc_template_id *	template_id
	)

Get a template's unique id.

Parameters

[in]	gallery	The gallery containing the template for which to obtain the `template_id` field.
[in]	index	Index of the template in `gallery` for which to obtain the `template_id` field.
[out]	template_id	Unique id for the template in `gallery` at `index`.

Remarks: This function is thread-safe.

See also: roc_get_person_id roc_index_for_id

◆ roc_get_person_id()

roc_error roc_get_person_id	(	roc_gallery	gallery,
		roc_template_index	index,
		roc_person_id *	person_id
	)

Get a template's identity label.

Parameters

[in]	gallery	The gallery containing the template for which to obtain the `person_id` field.
[in]	index	Index of the template in `gallery` for which to obtain the `person_id` field.
[out]	person_id	Identity label for the template in `gallery` at `index`.

Remarks: This function is thread-safe.

See also: roc_set_person_id roc_all_person_ids roc_get_template_id

◆ roc_set_person_id()

roc_error roc_set_person_id	(	roc_gallery	gallery,
		roc_template_index	index,
		roc_person_id	person_id
	)

Set a template's identity label.

Parameters

[in]	gallery	The gallery containing the template for which to update the `person_id` field.
[in]	index	Index of the template in `gallery` for which to update the `person_id` field.
[in]	person_id	The new identity label for the template.

Remarks: This function is thread-safe.

See also: roc_get_person_id

◆ roc_all_person_ids()

roc_error roc_all_person_ids	(	roc_const_gallery	gallery,
		roc_person_id_array *	person_ids,
		size_t *	num_person_ids
	)

Retrieve the roc_template::person_id for each template in a gallery.

The roc_person_id at index i in person_ids corresponds to the ith template in gallery, retrievable by roc_at.

Free person_ids after use with roc_free_uuid_array.

Example: roc_const_gallery gallery = ...;
roc_person_id_array person_ids;
size_t num_person_ids;
roc_all_person_ids(gallery, &person_ids, &num_person_ids);

Parameters

[in]	gallery	The gallery to retrieve all roc_template::person_id from.
[out]	person_ids	Dynamically allocated array of roc_template::person_id for each template in `gallery`.
[out]	num_person_ids	Length of `person_ids`.

Remarks: This function is thread-safe.

See also: roc_unique_person_ids

◆ roc_unique_person_ids()

roc_error roc_unique_person_ids	(	roc_const_gallery	gallery,
		roc_person_id_array *	person_ids,
		size_t *	num_person_ids
	)

Retrieve the set of unique roc_template::person_id in a gallery.

Free person_ids after use with roc_free_uuid_array.

Example: roc_const_gallery gallery = ...;
roc_person_id_array person_ids;
size_t num_person_ids;
roc_unique_person_ids(gallery, &person_ids, &num_person_ids);

Parameters

[in]	gallery	The gallery to retrieve the unique roc_template::person_id from.
[out]	person_ids	Dynamically allocated array of all unique roc_template::person_id in `gallery`.
[out]	num_person_ids	Length of `person_ids`.

Remarks: This function is thread-safe.

See also: roc_set_person_id

◆ roc_indicies_for_person_id()

roc_error roc_indicies_for_person_id	(	roc_const_gallery	gallery,
		roc_person_id	person_id,
		roc_template_index_array *	template_indicies,
		size_t *	num_template_indicies
	)

Retrieve the set of roc_template_index for a roc_person_id.

Querying with a roc_uuid_get_null person_id will return 0 results.

Free template_indicies after use with roc_free_template_index_array.

Example: roc_const_gallery gallery = ...;
roc_person_id person_id = ...;
roc_template_index_array template_indicies;
size_t num_template_indicies;
roc_indicies_for_person_id(gallery, person_id, &template_indicies, &num_template_indicies);

Parameters

[in]	gallery	The gallery to retrieve the template indicies for `person_id` from.
[in]	person_id	Person to find templates for.
[out]	template_indicies	Indicies for templates matching `person_id`.
[out]	num_template_indicies	Length of `template_indicies`.

Remarks: This function is thread-safe.

See also: roc_indicies_for_media_id

◆ roc_indicies_for_media_id()

roc_error roc_indicies_for_media_id	(	roc_const_gallery	gallery,
		roc_media_id	media_id,
		roc_template_index_array *	template_indicies,
		size_t *	num_template_indicies
	)

Retrieve the set of roc_template_index for a roc_media_id.

Querying with a roc_hash_get_null media_id will return 0 results.

Free template_indicies after use with roc_free_template_index_array.

Example: roc_const_gallery gallery = ...;
roc_media_id media_id = ...;
roc_template_index_array template_indicies;
size_t num_template_indicies;
roc_indicies_for_media_id(gallery, media_id, &template_indicies, &num_template_indicies);

Parameters

[in]	gallery	The gallery to retrieve the template indicies for `media_id` from.
[in]	media_id	Media to find templates for.
[out]	template_indicies	Indicies for templates matching `media_id`.
[out]	num_template_indicies	Length of `template_indicies`.

Remarks: This function is thread-safe.

See also: roc_indicies_for_person_id

Data Structures

Typedefs

Functions

Detailed Description

Data Structure Documentation

◆ roc_adjudication

Typedef Documentation

◆ roc_adjudication

Function Documentation

◆ roc_cluster()

Clustering Similarity

Adjudication

incremental_clustering

◆ roc_adjudicate_knn()

◆ roc_adjudicate_gallery()

◆ roc_extend()

◆ roc_consolidate()

Maximum Similarity

Maximum Count

◆ roc_consolidate_persons()

◆ roc_consolidate_fingerprints()

◆ roc_get_template_id()

◆ roc_get_person_id()

◆ roc_set_person_id()

◆ roc_all_person_ids()

◆ roc_unique_person_ids()

◆ roc_indicies_for_person_id()

◆ roc_indicies_for_media_id()