KanduAI SDK API

Table Of Contents

Index Search

Index Search description

Functions

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

Return

An 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

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

Return

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

Return

An 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

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

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

Return

An 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

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

Return

An 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

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

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

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

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

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

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

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

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

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

void rf_face_remove_by_id(void *index_search_handle, int id_to_remove, 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 details

void rf_face_remove_by_ids(void *index_search_handle, rf_int_vector_type ids_to_remove, rf_error_type *error)

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

Parameters

• 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 details

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

Compare 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.

Parameters

• 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

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

arrow_back

Previous

Image API

arrow_forward

Next

Processor