1N Identification¶
In order to avoid loading the same collection into memory multiple times (which becomes an issue when the collection sizes become very large),
instances of the SDK created within the same process will share the same collection in memory (RAM). This means when you enroll a template into the collection
using one instance of the SDK, it will be available in all other instances of the SDK in the same process.
For this same reason, applications which have multiple instances of the SDK in a single process only need to call createDatabaseConnection and createLoadCollection
on a single instance of the SDK and all other instances will automatically be connected to the same database and collection.
The PostgreSQL backend option also has built in synchronization across multiple processes. Let’s take an example where you have two processes on different machines, A and B, connected to the same PostgreSQL backend. Each of these processes will initially connect to the same database and collection and therefore load all the templates from the database into memory (RAM). If process A then enrolls a template into the collection, this will both add the template to the in-memory (RAM) collection of process A and will update the PostgreSQL database. In doing so, it will also automatically push out a notification to all the subscribed processes which are connected to the same database and collection. Any process connected to the same database and collection is automatically subscribed to updates, no additional action is required from the developer. Process B will therefore receive a notification that an update was made and will therefore automatically enroll the same template into its in-memory (RAM) collection. Process A and B therefore have synchronized collections in memory. Note, it can take up to 30 seconds for subscribed processes to receive the notification.
This sort of multi-process synchronization is not supported by the sqlite backend. With the sqlite backend, if process A makes a change to the database,
process B will not know of the changes. Process B must re-call createLoadCollection in order to register the changes that were made to the database from process A.
Note doing so will not perform an incremental update, but will instead discard then re-load all the data into memory, which can be slow if the collection size is large.
This is why it is advised to use the sqlite backend option only for use cases which involve only a single process connecting to the database.
If multiple processes need to connect to a database (and require synchronization), it is advised to use the PostgreSQL backend.
With the frVectorCompression flag enabled, at a conservative average, each face template and corresponding metadata is roughly 750 bytes in size,
though this ultimately depends on the length of the identity string you choose. You can therefore calculate approximately how much RAM is required for various collection sizes.
For example, a collection of size 1 million templates will require 750 bytes * 1,000,000 templates = 750Mb of RAM, a collection of size 10 million templates will require 7.5Gb of RAM, and so on.
For most use cases, even embedded devices have enough RAM to search through collections of medium to even large sizes (ex. An RPI 4 can handle a few million templates).
However, when running 1 to N identification on massive collections (10s or 100s of millions of templates) on a lightweight embedded device, you may find the device does
not have sufficient RAM to store the entire collection in memory. In these situations, you will want to run the actual 1 to N search on a beefy server which has sufficient RAM.
Process the video streams on the embedded devices at the edge to generate feature vectors for the detected faces, then send these feature vectors to the server (or cluster of servers)
to run the actual 1 to N identification functions (ex. identifyTopCandidate). The server should also handle enrolling and deleting templates from the collection as required
(these functions can also be exposed to the edge devices as REST API endpoints). Hence, the edge devices only generate feature vectors, while only the beefy servers are connected to the database and perform the searches.
To simplify things (and avoid having to write your own REST API server), you can have your edge devices send the feature vectors to an instance of the Trueface Visionbox running on your server
to perform the matching.
-
ErrorCode
Trueface::SDK::createDatabaseConnection(const std::string &databaseConnectionString)¶ Create a connection to a new or existing database. If the database does not exist, a new one will be created with the provided name. If the NONE DatabaseManagementSystem (memory only) configuration option is selected, this function does not need to be called (and is a harmless no-op).
If POSTGRESQL DatabaseManagementSystem is selected, this should be a database connection string. For a list of PostgreSQL connection parameters, visit:
https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-PARAMKEYWORDS ex. “hostaddr=192.168.1.0 port=5432 dbname=face_recognition user=postgres password=my_password” ex. “host=localhost port=5432 dbname=face_recognition user=postgres password=m_password”- Parameters
databaseConnectionString: If SQLITE DatabaseManagementSystem is selected, this should be the filepath to the database. ex. “/myPath/myDatabase.db”
- Return
error code, see ErrorCode.
-
ErrorCode
Trueface::SDK::createLoadCollection(const std::string &collectionName)¶ Create a new collection, or load data from an existing collection into memory (RAM) if one with the provided name already exists in the database.
- Return
error code, see ErrorCode.
- Parameters
[in] collectionName: the name of the collection.
-
ErrorCode
Trueface::SDK::enrollTemplate(const Faceprint &faceprint, const std::string &identity, std::string &UUID)¶ Enroll a template for a new or existing identity in the collection.
- Return
error code, see ErrorCode.
- Parameters
[in] faceprint: the template to enroll in the collection.[in] identity: the identity corresponding to the template.[out] UUID: universally unique identifier corresponding to the template.
-
ErrorCode
Trueface::SDK::removeByUUID(const std::string &UUID)¶ Remove a template from the collection using the UUID.
- Return
error code, see ErrorCode.
- Parameters
[in] UUID: the universally unique identifier corresponding to the template to be removed from the collection.
-
ErrorCode
Trueface::SDK::removeByIdentity(const std::string &identity)¶ Remove all templates in the collection corresponding to the identity.
- Return
error code, see ErrorCode.
- Parameters
[in] identity: the identity to remove from the collection.
-
ErrorCode
Trueface::SDK::identifyTopCandidate(const Faceprint &faceprint, Candidate &candidate, bool &found, float threshold = 0.3f)¶ Get the top candidate identity in the collection and the corresponding similarity score and match probability.
- Return
error code, see ErrorCode.
- Parameters
[in] faceprint: the template to be identified.[out] candidate: the top candidate identity.[out] found: set to true if a match is found.[in] threshold: the similarity score threshold above which it is considered a match. Higher thresholds may result in faster queries. Refer to https://performance.trueface.ai/ when selecting a threshold.
-
ErrorCode
Trueface::SDK::batchIdentifyTopCandidate(const std::vector<Faceprint> &faceprints, std::vector<Candidate> &candidates, std::vector<bool> &found, float threshold = 0.3f)¶ Get the top candidate identity in the collection and the corresponding similarity score and match probability for each probe faceprint. Like identifyTopCandidate, but runs search queries in parallel and improves throughput.
- Return
error code, see ErrorCode.
- Parameters
[in] faceprints: a vector of templates to be identified.[out] candidates: the top candidate identity for each probe faceprint.[out] found: set to true if a match is found for the probe faceprint.[in] threshold: the similarity score threshold above which it is considered a match. Higher thresholds may result in faster queries. Refer to https://performance.trueface.ai/ when selecting a threshold.
-
ErrorCode
Trueface::SDK::identifyTopCandidates(const Faceprint &faceprint, std::vector<Candidate> &candidates, bool &found, unsigned int numCandidates, float threshold = 3.f)¶ Get a list of the top n candidate identities in the collection and their corresponding similarity scores and match probabilities.
- Return
error code, see ErrorCode.
- Parameters
[in] faceprint: the template to be identified.[out] candidates: a list of the top n matches (or fewer), ordered by descending similarity score.[out] found: set to true if at leaset one match is found.[in] numCandidates: max number of candidate identities to return.[in] threshold: the similarity score threshold above which it is considered a match. Higher thresholds may result in faster queries. Refer to https://performance.trueface.ai/ when selecting a threshold.
-
struct
Trueface::Candidate¶