index_search_c_api.h File Reference

#include "constants.h"
#include "api_types.h"

Go to the source code of this file.

Functions
void *	rf_index_search_init_from_vectors (rf_float_vector_type enrolled_vectors, const char *hnsw_file_name, rf_error_type *error)
void *	rf_index_search_init_from_vectors_list (rf_object_list_type vectors_list, rf_object_list_type external_ids, const char *hnsw_file_name, rf_error_type *error)
void *	rf_index_search_init_empty (const char *hnsw_file_name, rf_error_type *error)
void *	rf_index_search_init_from_file (const char *hnsw_file_name, rf_error_type *error)
void	rf_index_search_close (void *index_search_handle, rf_error_type *error)
void	rf_index_search_by_index (void *index_search_handle, rf_float_vector_type query_vector, int top_k, float search_threshold, rf_int_vector_type *output_vector_ids, rf_error_type *error)
void	rf_index_search_by_index_external_ids (void *index_search_handle, rf_float_vector_type query_vector, int top_k, float search_threshold, rf_int_vector_type *output_vector_ids, rf_object_list_type *external_ids_out, rf_float_vector_type *confidence, rf_error_type *error)
void	rf_face_get_enrolled_vectors (void *index_search_handle, rf_float_vector_type *enrolled_vectors_out, rf_error_type *error)
void	rf_face_get_enrolled_vectors_list (void *index_search_handle, rf_object_list_type *enrolled_vectors_out, rf_error_type *error)
void	rf_face_get_external_ids (void *index_search_handle, rf_object_list_type *enrolled_vectors_external_ids_out, rf_error_type *error)
void	rf_face_enroll (void *index_search_handle, rf_object_list_type vectors_to_enroll, rf_object_list_type external_ids_to_enroll, rf_error_type *error)
void	rf_face_remove_by_external_id (void *index_search_handle, const char *external_id_to_remove, rf_error_type *error)
void	rf_face_remove_by_external_ids (void *index_search_handle, rf_object_list_type external_ids_to_remove, rf_error_type *error)
float	rf_face_get_simularity (void *index_search_handle, rf_float_vector_type item1, rf_float_vector_type item2, rf_error_type *error)
void	rf_face_cluster_embeddings (rf_float_vector_type embedding_vectors, rf_int_vector_type *out_ids, rf_error_type *error)

Function Documentation

rf_face_cluster_embeddings()

void rf_face_cluster_embeddings	(	rf_float_vector_type	embedding_vectors,
		rf_int_vector_type *	out_ids,
		rf_error_type *	error
	)

Cluster embeddings into groups.

Parameters

embedding_vectors	A flattened array that contains embedding vectors concatenated, (use rf_face_recognition_get_embedding or rf_face_recognition_get_embedding_from_aligned_face to create)
out_ids	output parameter to return array of group ids for all embedding vectors. For example 5 embedding vectors will return array of size 5 with values e.g. {0, 1, 0, 2, 2} meaning that 1st and 3rd vectors belong to group #0, 2nd vector belongs to group #1, 4th and 5th belong to group #2
error	output parameter to return an error details

rf_face_enroll()

void rf_face_enroll	(	void *	index_search_handle,
		rf_object_list_type	vectors_to_enroll,
		rf_object_list_type	external_ids_to_enroll,
		rf_error_type *	error
	)

Enroll / add additional feature vectors to the index

Parameters

index_search_handle	HNSW search handle
vectors_to_enroll	a list of feature vectors as a rf_object_list_type with objects of RF_OBJECT_TYPE_FLOAT_VECTOR type
external_ids_to_enroll	a list vectors' external ids to enroll, as a rf_object_list_type with objects of RF_OBJECT_TYPE_STRING type
error	output parameter to return an error details

rf_face_get_enrolled_vectors()

void rf_face_get_enrolled_vectors	(	void *	index_search_handle,
		rf_float_vector_type *	enrolled_vectors_out,
		rf_error_type *	error
	)

Get all of the currently enrolled vectors in the same order as they were enrolled

Parameters

index_search_handle	HNSW search handle
enrolled_vectors_out	float vector that contains all of the currently enrolled wectors of size 128, layed out continuesly in a flat vector
error	output parameter to return an error details

rf_face_get_enrolled_vectors_list()

void rf_face_get_enrolled_vectors_list	(	void *	index_search_handle,
		rf_object_list_type *	enrolled_vectors_out,
		rf_error_type *	error
	)

Get all of the currently enrolled vectors in the same order as they were enrolled

Parameters

index_search_handle	HNSW search handle
enrolled_vectors_out	float vector that contains all of the currently enrolled wectors of size 128 as a rf_object_list_type with objects of RF_OBJECT_TYPE_FLOAT_VECTOR type
error	output parameter to return an error details

rf_face_get_external_ids()

void rf_face_get_external_ids	(	void *	index_search_handle,
		rf_object_list_type *	enrolled_vectors_external_ids_out,
		rf_error_type *	error
	)

Get all of the currently enrolled vectors in the same order as they were enrolled

Parameters

index_search_handle	HNSW search handle
enrolled_vectors_out	vector that contains all of the currently enrolled vectors' external ids as a rf_object_list_type with objects of RF_OBJECT_TYPE_STRING type
error	output parameter to return an error details

rf_face_get_simularity()

float rf_face_get_simularity	(	void *	index_search_handle,
		rf_float_vector_type	item1,
		rf_float_vector_type	item2,
		rf_error_type *	error
	)

Remove feature vectors from the index by a single serial id

Parameters

index_search_handle	HNSW search handle
id_to_remove	an id of an item(s) to remove
error	output parameter to return an error detailsRemove feature vectors from the index by a vector of serial ids
index_search_handle	HNSW search handle
ids_to_remove	an rf_int_vector_type with indexes that specify which items to remove from the index
error	output parameter to return an error detailsCompare two vectors/faces and return the similarity score between 0 and 1, where 0 is no simalarity and 1 is identical, usually items with similarity above 0.4 represent the same faces.
index_search_handle	HNSW search handle
item1	float vector of size 128 which contains first item to compare
item2	float vector of size 128 which contains second item to compare
error	output parameter to return an error details

rf_face_remove_by_external_id()

void rf_face_remove_by_external_id	(	void *	index_search_handle,
		const char *	external_id_to_remove,
		rf_error_type *	error
	)

Remove feature vectors from the index by a single external id

Parameters

index_search_handle	HNSW search handle
external_id_to_remove	an external id of an item(s) to remove
error	output parameter to return an error details

rf_face_remove_by_external_ids()

void rf_face_remove_by_external_ids	(	void *	index_search_handle,
		rf_object_list_type	external_ids_to_remove,
		rf_error_type *	error
	)

Remove feature vectors from the index by a vector of external ids

Parameters

index_search_handle	HNSW search handle
external_ids_to_remove	an rf_object_list_type list with items of RF_OBJECT_TYPE_STRING type, that specify which items to remove from the index
error	output parameter to return an error details

rf_index_search_by_index()

void rf_index_search_by_index	(	void *	index_search_handle,
		rf_float_vector_type	query_vector,
		int	top_k,
		float	search_threshold,
		rf_int_vector_type *	output_vector_ids,
		rf_error_type *	error
	)

Search in all enrolled faces for the match of given query vector

Parameters

index_search_handle	HNSW search handle
query_vector	Query vector to search for similar vectors in the list of enrolled vectors
top_k	A hyper-parameter for the KNN algorithm - number of top "k" candidates to look for in the query.
search_threshold	Optional parameter. The threshold for similarity between vectors. Should be between 0 and 1, but we've found that generally it shouldn't be lower than 0.4 with our current model. Very similar faces (of the same person) will get higher similarity values, so if you want a more strict decision boundary you can set it higher.
output_vector_ids	output parameter that returns an array of all vectors' INDICES that belong to the same person in the query vector, retrieved by the similarity threshold. So far we used the value of 0.4 for this threshold. The returned indices correspond to the indices order as they were inserted to the enrolled vectors list. If you use the flattened array of the enrolled vectors, make sure to mulyiply each index by 128. If you use a list of the enrolled vectors, using the indices as they are here is the way to go.
error	output parameter to return an error details

rf_index_search_by_index_external_ids()

void rf_index_search_by_index_external_ids	(	void *	index_search_handle,
		rf_float_vector_type	query_vector,
		int	top_k,
		float	search_threshold,
		rf_int_vector_type *	output_vector_ids,
		rf_object_list_type *	external_ids_out,
		rf_float_vector_type *	confidence,
		rf_error_type *	error
	)

Search in all enrolled faces for the match of given query vector

Parameters

index_search_handle	HNSW search handle
query_vector	Query vector to search for similar vectors in the list of enrolled vectors
top_k	A hyper-parameter for the KNN algorithm - number of top "k" candidates to look for in the query.
search_threshold	Optional parameter. The threshold for similarity between vectors. Should be between 0 and 1, but we've found that generally it shouldn't be lower than 0.4 with our current model. Very similar faces (of the same person) will get higher similarity values, so if you want a more strict decision boundary you can set it higher.
output_vector_ids	output parameter that returns an array of all vectors' INDICES that belong to the same person in the query vector, retrieved by the similarity threshold. So far we used the value of 0.4 for this threshold. The returned indices correspond to the indices order as they were inserted to the enrolled vectors list. If you use the flattened array of the enrolled vectors, make sure to mulyiply each index by 128. If you use a list of the enrolled vectors, using the indices as they are here is the way to go.
external_ids_out	output parameters that returns an arrays of all vectors' external STRINGS identifiers that belong to the same person in the query vector, retrieved by the similarity threshold.
error	output parameter to return an error details

rf_index_search_close()

void rf_index_search_close	(	void *	index_search_handle,
		rf_error_type *	error
	)

Deletes HNSW search

Parameters

index_search_handle	HNSW search handle
error	output parameter to return an error details

rf_index_search_init_empty()

void* rf_index_search_init_empty	(	const char *	hnsw_file_name,
		rf_error_type *	error
	)

A constructor for creating an empty HNSW instance for efficient search and retrieval from enrolled vectors

Parameters

hnsw_file_name	A string for saving the HNSW instance for future loading
error	output parameter to return an error details

Returns

An HNSW instance for efficient search and retrieval from enrolled vectors

rf_index_search_init_from_file()

void* rf_index_search_init_from_file	(	const char *	hnsw_file_name,
		rf_error_type *	error
	)

A constructor for loading a HNSW instance for efficient search and retrieval from enrolled vectors

Parameters

hnsw_file_name	path to saved index HNSW file
error	output parameter to return an error details

Returns

An HNSW instance for efficient search and retrieval from enrolled vectors

rf_index_search_init_from_vectors()

void* rf_index_search_init_from_vectors	(	rf_float_vector_type	enrolled_vectors,
		const char *	hnsw_file_name,
		rf_error_type *	error
	)

A constructor for creating a HNSW instance for efficient search and retrieval from enrolled vectors

Parameters

enrolled_vectors	A flattened array that contains all enrolled vectors concatenated, (use rf_face_recognition_get_embedding or rf_face_recognition_get_embedding_from_aligned_face to create)
hnsw_file_name	A string for saving the HNSW instance for future loading
error	output parameter to return an error details

Returns

An HNSW instance for efficient search and retrieval from enrolled vectors

rf_index_search_init_from_vectors_list()

void* rf_index_search_init_from_vectors_list	(	rf_object_list_type	vectors_list,
		rf_object_list_type	external_ids,
		const char *	hnsw_file_name,
		rf_error_type *	error
	)

A constructor for creating a HNSW instance for efficient search and retrieval from enrolled vectors

Parameters

enrolled_vectors	A flattened array that contains all enrolled vectors concatenated, (use rf_face_recognition_get_embedding or rf_face_recognition_get_embedding_from_aligned_face to create)
external_ids	A list of RF_OBJECT_TYPE_STRING typed rf_object_type objects, optional way to specify externsl_ids (in the same order as enrolled_vectors)
hnsw_file_name	A string for saving the HNSW instance for future loading
error	output parameter to return an error details

Returns

An HNSW instance for efficient search and retrieval from enrolled vectorsA constructor for creating a HNSW instance for efficient search and retrieval from enrolled vectors

Parameters

vectors_list	A list of RF_OBJECT_TYPE_FLOAT_VECTOR typed rf_object_type objects, where each item contains an embedding (use rf_face_recognition_get_embedding or rf_face_recognition_get_embedding_from_aligned_face to create)
external_ids	A list of RF_OBJECT_TYPE_STRING typed rf_object_type objects, optional way to specify externsl_ids (in the same order as vectors_list)
hnsw_file_name	A string for saving the HNSW instance for future loading
error	output parameter to return an error details

Returns

An HNSW instance for efficient search and retrieval from enrolled vectors