C++ Face ID API

oneML model for face verification and face identification.

class oneML::face::FaceId : public oneML::oneMLAPI

The oneML FaceId API object.

Class to create and use oneML face id model.

Public Functions

explicit FaceId(oneML::LicenseManager &manager)

Construct a FaceId object.

Parameters

explicit FaceId(FaceEmbedder &embedder, oneML::LicenseManager &manager)

Construct a FaceId object.

Parameters

ReturnStatus predict(const MultiImage &imgs, std::vector<FaceIdResult> &results)

predict images to registered ids

Return

ReturnStatus: status of operation

Parameters

  • [in] imgs: vector of raw images

  • [out] results: vector of result objects

ReturnStatus predict(const MultiImage &imgs, float same_person_dist_threshold, std::vector<FaceIdResult> &results)

predict images to registered ids

Return

ReturnStatus: status of operation

Parameters

  • [in] imgs: vector of raw images

  • [in] same_person_dist_threshold: same person dist threshold

  • [out] results: vector of result objects

ReturnStatus predict(const Image &img, FaceIdResult &result)

predict an image to registered ids

Return

ReturnStatus: status of operation

Parameters

  • [in] img: raw image

  • [out] result: result object

ReturnStatus predict(const Image &img, float same_person_dist_threshold, FaceIdResult &result)

predict an image to registered ids

Return

ReturnStatus: status of operation

Parameters

  • [in] img: raw image

  • [in] same_person_dist_threshold: same person dist threshold

  • [out] result: result object

std::pair<ReturnStatus, bool> is_the_same_person(const Image &face_img1, const Image &face_img2)

Verify if 2 face images are the same.

Return

a pair of ReturnStatus and bool, true if 2 faces are from the same person, false otherwise

Parameters

  • [in] face_img1: image of first person

  • [in] face_img2: image of second person

std::pair<ReturnStatus, bool> is_the_same_person(const Image &face_img1, const Image &face_img2, float same_person_dist_threshold)

Verify if 2 face images are the same.

Return

a pair of ReturnStatus and bool, true if 2 faces are from the same person, false otherwise

Parameters

  • [in] face_img1: image of first person

  • [in] face_img2: image of second person

  • [in] same_person_dist_threshold: same person dist threshold

std::pair<ReturnStatus, bool> is_the_same_person(const Embedding &face_emb, const Image &face_img, Embedding &img_emb)

Verify if a face images is the same as a face embedding.

Return

a pair of ReturnStatus and bool: true if the same person, false otherwise

Parameters

  • [in] face_emb: embedding of first person

  • [in] face_img: image of second person

  • [out] img_emb: embedding of second person

std::pair<ReturnStatus, bool> is_the_same_person(const Embedding &face_emb, const Image &face_img, float same_person_dist_threshold, Embedding &img_emb)

Verify if a face images is the same as a face embedding.

Return

a pair of ReturnStatus and bool: true if the same person, false otherwise

Parameters

  • [in] face_emb: embedding of first person

  • [in] face_img: image of second person

  • [in] same_person_dist_threshold: same person dist threshold

  • [out] img_emb: embedding of second person

std::pair<ReturnStatus, int> register_id_emb(const std::string &id, const Embedding &emb)

Register a new ID with embedding vectors.

If an ID exists, its embedding vectors will be replaced by new one and the classifier will be rebuilt.

Return

a pair of ReturnStatus and the embedding size

Parameters

  • [in] id: string id

  • [in] emb: embedding array size EMB_SIZE

std::pair<ReturnStatus, Embedding> register_id_images(const std::string &id, const MultiImage &images, const bool &avg_emb)

Register a new ID with images.

if avg_emb is true, we will register with average embedding vector, else we will register embedding from first image.

Return

a pair of ReturnStatus and an embedding

Parameters

  • [in] id: string id

  • [in] images: MultiImage

  • [in] avg_emb: boolean to average embedding images or not

std::pair<ReturnStatus, Embedding> register_id_images(const std::string &id, const Image &image)

Register a new ID with an image.

Return

a pair of ReturnStatus and an embedding

Parameters

  • [in] id: string id

  • [in] image: Image

ReturnStatus update_embedding_dynamically(const std::string &id, const Image &img, const Embedding &ori_emb)

Dynamically update data inside a gallery_matrix classier by a face image and original embedding array.

Return

ReturnStatus: status of operation

Parameters

  • [in] id: string id

  • [in] img: cropped and aligned face image

  • [in] ori_emb: an original embedding vector used when the ID is registered

ReturnStatus update_embedding_dynamically(const std::string &id, const Embedding &probe_emb, const Embedding &ori_emb)

Dynamically update data inside a gallery_matrix classier by a probe embedding and original embedding array.

Return

ReturnStatus: status of operation

Parameters

  • [in] id: string id

  • [in] probe_emb: An embedding array got from embedding a probe image

  • [in] ori_emb: an original embedding vector used when the ID is registered

ReturnStatus update_embedding(const std::string &id, const Embedding &emb)

Directly update an embedding vector inside a gallery_matrix classifier.

Return

ReturnStatus: status of operation

Parameters

  • [in] id: string id

  • [in] emb: embedding array

ReturnStatus remove_id(const std::string &id)

remove id from store and array

Return

ReturnStatus: status of operation

Parameters

  • [in] id: string id

ReturnStatus get_ids(std::vector<std::string> &ids) const

get set of all id

Return

ReturnStatus: status of operation

Parameters

  • [out] ids: vector of string IDs

class oneML::face::FaceIdResult : public oneML::oneMLResult

The result object for oneML FaceId API.

Helper class to access all the results from an API call.

Public Functions

std::string get_id() const

get id

Return

string: identified ID

float get_nearest_node_distance() const

get nearest node distance

Return

float: distance to nearest ID

float get_combined_distance() const

get combined distance

Return

float: combined distance to first two candidate IDs

bool is_identifiable() const

check if distance result is above the threshold for detecting unknown ID

Return

bool: True if the result is valid or False for unknown ID

oneML::face::FaceIdStatus get_return_status() const

get return status

Return

return status

enum oneML::face::FaceIdStatus

A FaceIdStatus enum to use as return status.

Values:

enumerator Empty

Default return status.

enumerator Success

Success.

enumerator Fail

Fail.