Open, read, edit and close galleries. More...

Typedefs
typedef const char *	roc_gallery_file
	A list of flattened templates written to disk. More...

typedef struct roc_gallery_type *	roc_gallery
	An array of templates. More...

typedef const struct roc_gallery_type *	roc_const_gallery
	A constant roc_gallery.

typedef size_t	roc_template_index
	The index of a template in a gallery. More...

typedef roc_template_index *	roc_template_index_array
	A dynamically allocated array of roc_template_index. More...

Functions
roc_error	roc_open_gallery (roc_gallery_file gallery_file, roc_gallery *gallery, roc_progress progress)
	Open a gallery from a file. More...

roc_template_index	roc_get_invalid_template_index ()
	Returns ROC_INVALID_TEMPLATE_INDEX. More...

void	roc_free_template_index_array (roc_template_index_array *template_index_array)
	Deallocate a roc_template_index_array. More...

roc_error	roc_enroll (roc_gallery gallery, const roc_template template_, roc_template_index *index)
	Add a template to a gallery. More...

roc_error	roc_fsync (roc_gallery gallery)
	Force templates to be written to disk. More...

roc_error	roc_size (roc_const_gallery gallery, size_t *size)
	Retrieve the number of templates in a gallery. More...

roc_error	roc_last_modified (roc_const_gallery gallery, roc_time *timestamp)
	Last time the gallery was modified. More...

roc_error	roc_take_snapshot (roc_const_gallery gallery, const char *file_path, bool defragment)
	Copy a gallery to a new file. More...

roc_error	roc_at (roc_const_gallery gallery, roc_template_index index, roc_template *template_)
	Retrieve a template from a gallery at the specified roc_template_index. More...

roc_error	roc_at_n (roc_const_gallery gallery, roc_template_index start_index, size_t n, roc_template *templates)
	Retrieve multiple templates from a gallery in the specified range. More...

roc_error	roc_get (roc_const_gallery gallery, roc_template_id template_id, roc_template *template_)
	Retrieve a template from a gallery with the specified roc_template_id. More...

roc_error	roc_index_for_id (roc_const_gallery gallery, roc_template_id template_id, roc_template_index *index)
	Obtain the index of a template at the specified roc_template_id. More...

roc_error	roc_replace (roc_gallery gallery, roc_template_index index, const roc_template template_)
	Replace a template in a gallery. More...

roc_error	roc_remove (roc_gallery gallery, roc_template_index index)
	Remove the template at the specified index. More...

roc_error	roc_remove_n (roc_gallery gallery, roc_template_index start_index, size_t n)
	Remove multiple templates in the specified range. More...

roc_error	roc_remove_id (roc_gallery gallery, roc_template_id template_id)
	Remove the template for the specified id. More...

roc_error	roc_remove_before (roc_gallery gallery, roc_time timestamp)
	Remove all templates older than the specified timestamp. More...

roc_error	roc_close_gallery (roc_gallery gallery)
	Close an open gallery. More...

roc_error	roc_template_limit (size_t *template_limit)
	The number of templates available in the license. More...

roc_error	roc_defragment (roc_gallery_file input, roc_gallery_file output)
	Delete empty templates from a gallery. More...

roc_error	roc_validate (roc_gallery_file gallery, bool truncate, size_t templates, int64_t bytes_read, int64_t *bytes_unread)
	Check and/or correct a gallery file for data corruption. More...

Variables
const roc_template_index	ROC_INVALID_TEMPLATE_INDEX
	An invalid roc_template_index. More...

Detailed Description

Open, read, edit and close galleries.

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.

Typedef Documentation

◆ roc_gallery_file

typedef const char* roc_gallery_file

A list of flattened templates written to disk.

Gallery I/O

There are several ways to write to a gallery that all result in the same file:

fopen + roc_write_template
open + roc_write_template_fd
fopen + roc_flatten + fwrite
roc_open_gallery + roc_enroll
roc_open_template_pipe + roc_template_pipe_transmit

There are several ways to read from a gallery that all result in the same templates:

fopen + roc_read_template
open + roc_read_template_fd
fopen + fread + roc_unflatten
roc_open_gallery + roc_at

Interoperability

Gallery files produced from the Command Line Interface and Explore are interoperable with those produced from the Application Programming Interface. By convention this file format is identified using a .t suffix.

Concatenation

An important aspect of gallery files is that two or more of them can be concatenated together to produce one larger gallery file. For example:

$ cat a.t b.t > ab.t

Format

The exact format of a flattened template is defined by roc_flatten which is implemented as:

    memcpy(output_byte_array, &template_, roc_template_header_size);
    output_byte_array += roc_template_header_size;
    if (template_.md_size > 0) {
        memcpy(output_byte_array, template_.md, template_.md_size);
        output_byte_array += template_.md_size;
    }
    if (template_.fv_size > 0) {
        memcpy(output_byte_array, template_.fv, template_.fv_size);
        output_byte_array += template_.fv_size;
    }
    if (template_.tn_size > 0) {
        memcpy(output_byte_array, template_.tn, template_.tn_size);
        output_byte_array += template_.tn_size;
    }

◆ roc_gallery

typedef struct roc_gallery_type* roc_gallery

An array of templates.

Templates are held in memory for efficient search.

Initialize with roc_open_gallery, search with roc_search, and free with roc_close_gallery.

All functions involving a gallery are designed to be thread-safe, and are protected with a read-write lock internally to ensure correctness.

An immutable gallery is a roc_const_gallery.

◆ roc_template_index

typedef size_t roc_template_index

The index of a template in a gallery.

Retrieve the corresponding template with roc_at. The value ROC_INVALID_TEMPLATE_INDEX indicates an invalid template index.

◆ roc_template_index_array

typedef roc_template_index* roc_template_index_array

A dynamically allocated array of roc_template_index.

Free after use with roc_free_template_index_array.

Function Documentation

◆ roc_open_gallery()

roc_error roc_open_gallery	(	roc_gallery_file	gallery_file,
		roc_gallery *	gallery,
		roc_progress	progress
	)

Open a gallery from a file.

If gallery_file does not exist, an empty file will be created automatically. Release the gallery after use with roc_close_gallery. gallery_file must have both read and write permission. See roc_gallery_file for a description of the gallery file format.

Note: 32-bit SDK builds only support gallery files up to 2^31-1 bytes.

Your license file includes a limit on the maximum number of templates in a gallery, see roc_template_limit for details.

Temporary (Memory-Only) Galleries

If gallery_file is NULL, a memory-only gallery will be initialized. This is offered as a convenience when working with galleries that are short-lived in nature. Memory-only galleries are not nearly as efficient as disk-backed galleries, and therefore should not be used when memory utilization is a concern. Furthermore, temporary galleries cannot be defragmented by roc_defragment.

Example: roc_gallery gallery;
roc_open_gallery("faces.t", &gallery, NULL);

Parameters

[in]	gallery_file	File name to read/append templates from/to.
[out]	gallery	Address to store the opened gallery.
[in]	progress	Optional progress callback or `NULL`.

Remarks: This function is reentrant.

◆ roc_get_invalid_template_index()

roc_template_index roc_get_invalid_template_index ( )

Returns ROC_INVALID_TEMPLATE_INDEX.

Workaround for platforms that have trouble linking against exported constants.

Remarks: This function is thread-safe.

◆ roc_free_template_index_array()

void roc_free_template_index_array ( roc_template_index_array * template_index_array )

Deallocate a roc_template_index_array.

Parameters

[in] template_index_array Array to deallocate.

Remarks: This function is reentrant.

◆ roc_enroll()

roc_error roc_enroll	(	roc_gallery	gallery,
		const roc_template	template_,
		roc_template_index *	index
	)

Add a template to a gallery.

This function is similar to roc_write_template, appending the template to the end of the corresponding roc_gallery_file, akin to a std::vector. The enrolled template is now a potential candidate returned by roc_search.

To remove an enrolled template see roc_remove.

Templates in a gallery are not designed to have their metadata edited, see roc_replace for the specific limitations. Applications that require frequent editing of metadata should maintain this information in a separate datastructure.

In the case of Temporary (Memory-Only) Galleries with prior calls made to roc_remove, this function will attempt to insert template_ into one of the previously removed indicies.

Example: roc_gallery gallery = ...;
roc_template template_ = ...;
roc_template_index index;
roc_enroll(gallery, template_, &index);

Parameters

[in]	gallery	Gallery to add `template_` to.
[in]	template_	Template to add to `gallery`.
[out]	index	Optional parameter to obtain the index the template was appended at, or `NULL`.

Remarks: This function is thread-safe.

See also: roc_fsync

◆ roc_fsync()

roc_error roc_fsync ( roc_gallery gallery )

Force templates to be written to disk.

This function calls fsync on the gallery, which will force a write to disk of any changes currently buffered in memory by the OS. The purpose of this function is to protect data in the event of an unexpected power loss or abnormal program termination. This function has no effect supported on Windows, which does not support fsync.

Parameters

[in] gallery Gallery to sync.

◆ roc_size()

roc_error roc_size	(	roc_const_gallery	gallery,
		size_t *	size
	)

Retrieve the number of templates in a gallery.

Example: roc_const_gallery gallery = ...;
size_t size;
roc_size(gallery, &size);

Parameters

[in]	gallery	The gallery to retrieve the number of templates.
[out]	size	The number of templates in `gallery`.

Remarks: This function is thread-safe.

See also: roc_at

◆ roc_last_modified()

roc_error roc_last_modified	(	roc_const_gallery	gallery,
		roc_time *	timestamp
	)

Last time the gallery was modified.

The functions that trigger a timestamp change are roc_enroll, roc_replace, and roc_remove.

Example: roc_const_gallery gallery = ...;
roc_time timestamp;
roc_last_modified(gallery, &timestamp);

Parameters

[in]	gallery	The gallery to retrieve the last modified timestamp.
[out]	timestamp	The last time `gallery` was modified.

Remarks: This function is thread-safe.

◆ roc_take_snapshot()

roc_error roc_take_snapshot	(	roc_const_gallery	gallery,
		const char *	file_path,
		bool	defragment
	)

Copy a gallery to a new file.

Save the current state of the gallery to a new location (to be used for future backups).

Defragmenting

For each template in gallery, write it to file_path if and only if it has a feature vector (if and only if it is not an Empty Template). A template without a feature vector is most often the result of calling roc_remove. This has the effect of changing the roc_template_index for templates in file_path.

Example: roc_const_gallery gallery = ...;
roc_take_snapshot(gallery, "example/gallery_name.t", true);

Parameters

[in]	gallery	The gallery to copy the contents of.
[in]	file_path	Location to copy `gallery` to.
[in]	defragment	Defragment the snapshot, see Defragmenting.

Remarks: This function is thread-safe.

◆ roc_at()

roc_error roc_at	(	roc_const_gallery	gallery,
		roc_template_index	index,
		roc_template *	template_
	)

Retrieve a template from a gallery at the specified roc_template_index.

This function returns a copy of the gallery template. Free the copy after use with roc_free_template.

A gallery preserves the order of templates in its corresponding roc_gallery_file.

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

Example: roc_const_gallery gallery = ...;
roc_template_index index = ...;
roc_template template_;
roc_at(gallery, index, &template_);

Parameters

[in]	gallery	The gallery to retrieve a template from.
[in]	index	The index of the template to retrieve, between 0 and (roc_size - 1).
[out]	template_	A copy of the template in `gallery` at `index`.

Remarks: This function is thread-safe.

See also: roc_get roc_index_for_id roc_size roc_replace roc_at_n

◆ roc_at_n()

roc_error roc_at_n	(	roc_const_gallery	gallery,
		roc_template_index	start_index,
		size_t	n,
		roc_template *	templates
	)

Retrieve multiple templates from a gallery in the specified range.

This function returns a copy of the n gallery templates starting at start_index. The entire range must be valid. Free the copies after use with roc_free_template.

Parameters

[in]	gallery	The gallery to retrieve templates from.
[in]	start_index	The first index to retrieve.
[in]	n	The number of templates to retrieve.
[out]	templates	An uninitialized array of length `n`.

Remarks: This function is thread-safe.

See also: roc_at

◆ roc_get()

roc_error roc_get	(	roc_const_gallery	gallery,
		roc_template_id	template_id,
		roc_template *	template_
	)

Retrieve a template from a gallery with the specified roc_template_id.

This function returns a copy of the gallery template. Free the copy after use with roc_free_template. If template_id does not exist in gallery an error is returned and template_ is not initialized.

Example: roc_const_gallery gallery = ...;
roc_template_id template_id = ...;
roc_template template_;
roc_get(gallery, template_id, &template_);

Parameters

[in]	gallery	The gallery to retrieve a template from.
[in]	template_id	The ID the template to retrieve.
[out]	template_	A copy of the template in `gallery`.

Remarks: This function is thread-safe.

See also: roc_at

◆ roc_index_for_id()

roc_error roc_index_for_id	(	roc_const_gallery	gallery,
		roc_template_id	template_id,
		roc_template_index *	index
	)

Obtain the index of a template at the specified roc_template_id.

index will be set to ROC_INVALID_TEMPLATE_INDEX if id is not in gallery.

Example: roc_const_gallery gallery = ...;
roc_template_id template_id = ...;
roc_template_index index;
roc_index_for_id(gallery, template_id, &index);

Parameters

[in]	gallery	The gallery to retrieve the template index from.
[in]	template_id	The ID of the template.
[out]	index	The template index in `gallery` with `id`.

Remarks: This function is thread-safe.

See also: roc_at roc_get_template_id

◆ roc_replace()

roc_error roc_replace	(	roc_gallery	gallery,
		roc_template_index	index,
		const roc_template	template_
	)

Replace a template in a gallery.

This function has two limitations due to the way that galleries are organized for efficient search. Use cases that can't meet these limitations should consider using roc_remove and roc_enroll instead.

The first limitation is that the length of the feature vectors for both the current template and the one replacing it must be the equal. For normal use this will always be the case, unless attempting to replace a template without a feature vector with one that has one (or vice versa), an operation that is not supported by this function.

The second limitation is that this function will only succeed if roc_flattened_bytes of template_ is less than or equal to that of the existing template it is to replace, in which case it will be expanded using roc_realloc_metadata to be exactly the size of the current template. If you anticipate needing to replace templates with larger ones, most commonly because you intend to grow the template metadata, you should call roc_realloc_metadata on a template prior to roc_enroll so there is available space for later expansion. This limitation only exists for disk-backed galleries, for Temporary (Memory-Only) Galleries this is not a limitation.

This function assumes that template_index is less than roc_size of gallery.

Example: roc_gallery gallery = ...;
roc_template template_ = ...;
roc_template_index template_index = ...;
roc_replace(gallery, template_index, template_);

Parameters

[in]	gallery	Gallery to add `template_` to.
[in]	index	Index of the template to replace in `gallery`.
[in]	template_	The new template to replace the gallery template with.

Remarks: This function is thread-safe.

See also: roc_at

◆ roc_remove()

roc_error roc_remove	(	roc_gallery	gallery,
		roc_template_index	index
	)

Remove the template at the specified index.

For efficiency purposes, this function will replace the removed template with an Empty Template. Therefore roc_size will remain the same, as will the roc_template_index of the remaining templates. To truly delete the templates, reducing the gallery size and increasing the template limit, use roc_defragment.

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

Example: roc_gallery gallery = ...;
roc_remove(gallery, 3);

Parameters

[in]	gallery	Gallery to remove template from.
[in]	index	Index of the template to remove.

Remarks: This function is thread-safe.

See also: roc_remove_id roc_remove_before

◆ roc_remove_n()

roc_error roc_remove_n	(	roc_gallery	gallery,
		roc_template_index	start_index,
		size_t	n
	)

Remove multiple templates in the specified range.

A generalized version of roc_remove.

Example: roc_gallery gallery = ...;
roc_remove_n(gallery, 0, 2);

Parameters

[in]	gallery	Gallery to remove templates from.
[in]	start_index	Index of the first template to remove.
[in]	n	Number of templates to remove.

Remarks: This function is thread-safe.

◆ roc_remove_id()

roc_error roc_remove_id	(	roc_gallery	gallery,
		roc_template_id	template_id
	)

Remove the template for the specified id.

See roc_remove for considerations when removing a template. If template_id does not exist in gallery this function will return an error.

Example: roc_gallery gallery = ...;
roc_template_id template_id = ...;
roc_remove_id(gallery, 3);

Parameters

[in]	gallery	Gallery to remove template from.
[in]	template_id	ID of the template to remove.

Remarks: This function is thread-safe.

◆ roc_remove_before()

roc_error roc_remove_before	(	roc_gallery	gallery,
		roc_time	timestamp
	)

Remove all templates older than the specified timestamp.

See roc_remove for considerations when removing a template.

Example: roc_gallery gallery = ...;
roc_timestamp timestamp = ...;
roc_remove_before(gallery, timestamp);

Parameters

[in]	gallery	Gallery to remove template from.
[in]	timestamp	Any template with a timestamp older than this value will be removed.

Remarks: This function is thread-safe.

◆ roc_close_gallery()

roc_error roc_close_gallery ( roc_gallery gallery )

Close an open gallery.

This will free memory associated with gallery.

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

Parameters

[in] gallery The gallery to close.

Remarks: This function is reentrant.

See also: roc_open_gallery

◆ roc_template_limit()

roc_error roc_template_limit ( size_t * template_limit )

The number of templates available in the license.

A ROC SDK license includes a limit on the number of templates that can be used at once. The number of templates in use is the sum of roc_size for all galleries in use. Templates are put in and out of use by roc_open_gallery and roc_close_gallery respectively. This function returns the number of templates specified in the license file less the number of templates in use.

Example: size_t template_limit;
roc_template_limit(&template_limit);

Parameters

[out] template_limit The remaining number of templates available.

Remarks: This function is thread-safe.

See also: roc_stream_limit

◆ roc_defragment()

roc_error roc_defragment	(	roc_gallery_file	input,
		roc_gallery_file	output
	)

Delete empty templates from a gallery.

An Empty Template in a gallery is most often the result of calling roc_remove.

For each template in input, write it to output if and only if it has a feature vector. This operation preserves the order of non-empty templates. If output exists then it will be overwritten. If input == output the operation will occur in-place. Close any gallery dependent on output before calling this function.

Parameters

[in]	input	Gallery to read templates from.
[in]	output	Gallery to write non-empty templates to.

Remarks: This function is reentrant.

◆ roc_validate()

roc_error roc_validate	(	roc_gallery_file	gallery,
		bool	truncate,
		size_t *	templates,
		int64_t *	bytes_read,
		int64_t *	bytes_unread
	)

Check and/or correct a gallery file for data corruption.

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

Parameters

[in]	gallery	Gallery to processes for data corruption.
[in]	truncate	Truncate the gallery to remove any data that couldn't be parsed.
[out]	templates	Number of templates successfully read.
[out]	bytes_read	Number of bytes starting from the beginning of the file that could be parsed.
[out]	bytes_unread	Number of bytes at the end of the file that couldn't be parsed.

Remarks: This function is reentrant.

Variable Documentation

◆ ROC_INVALID_TEMPLATE_INDEX

const roc_template_index ROC_INVALID_TEMPLATE_INDEX

An invalid roc_template_index.

The value of this constant is std::numeric_limits<size_t>::max().

Typedefs

Functions

Variables

Detailed Description

Typedef Documentation

◆ roc_gallery_file

Gallery I/O

Interoperability

Concatenation

Format

◆ roc_gallery

◆ roc_template_index

◆ roc_template_index_array

Function Documentation

◆ roc_open_gallery()

Temporary (Memory-Only) Galleries

◆ roc_get_invalid_template_index()

◆ roc_free_template_index_array()

◆ roc_enroll()

◆ roc_fsync()

◆ roc_size()

◆ roc_last_modified()

◆ roc_take_snapshot()

Defragmenting

◆ roc_at()

◆ roc_at_n()

◆ roc_get()

◆ roc_index_for_id()

◆ roc_replace()

◆ roc_remove()

◆ roc_remove_n()

◆ roc_remove_id()

◆ roc_remove_before()

◆ roc_close_gallery()

◆ roc_template_limit()

◆ roc_defragment()

◆ roc_validate()

Variable Documentation

◆ ROC_INVALID_TEMPLATE_INDEX