VisageCloud makes face recognition as easy as possible, so you can focus your energy on your creativity and the specifics of your app, without having to worry about managing deep learning, classifiers, perspective alignment, color space and all the other hassles. In this document, we’ll go through the domain model and some example API calls.
In the VisageCloud domain model there are only four key elements: Account, Collection, Profile and Face. To understand the domain model in a nutshell, consider the following:
Now let’s look at the entities in more detail.
The Account identifies your access and your permissions to use the API. Specifically, it identifies how many requests you can make, how many collections you can create and how many profiles (individual identities) you can store. To perform operations in the API, you will authenticate with accessKey and secretKey for read-write operations (eg. creating a new collection, creating a new profile in a collection and adding a new face to a profile) and you will authenticate with accessKey and readOnlyKey for read-only, stateless operations (eg. running an analysis on a photo or comparing the people in photo to an existent collection of profiles). In case you are using VisageCloud as a service, you’ll receive the an accessKey, a secretKey and a readOnlyKey. In case you are using VisageCloud in an on-premise installation, you will receive a masterKey that will allow you to create an account with whatever permission you like.
The Collection groups together several individuals who belong to the same set. Examples of such sets would be “employees”, “actors”, “models”, “high-value-customers”. Each collection is uniquely identified by an identifier and it belongs to only one account which can manage its contents. A collection contains several profiles.
A Profile is the representation of a specific person’s face under several circumstances. A profile can belong to Mary or John or Jane or Tom or Anna. All the known face instances belonging to that person should be added to that person’s profile. A profile can only belong to one collection. In order to give more flexibility in querying the face collection, you can compare the face in a new picture to all profiles in collection “actors” which have the label “oscar-winner” or “oscar-nominee”. This allows you more freedom than when managing different collections with overlapping profiles. The profile also has an externalReference, which is enforced as unique in a collection. This is helpful for mapping the profile entity to an external system (like a CRM, an identity manager or your application’s database). Think of this as a foreign key from an external system. As an optional parameter, each profile has a screenName, which is not constrained as unique and which you can use to make results from the API more human readable (eg. “Anne Koch” or “Thomas Yong”).
The Face defines a recognized photo from an image. It is described by the features used in the recognition process, by the keypoints (eg. nose, jaw, mouth) resulting from the face detection and alignment and by the attributes coming from the face classification (gender, age group, hair color, skin color, eye color). Without being associated to a profile, a face is originally anonymous. After such an association is done, a face can be used for comparison to other faces. A profile can have several faces, which improves the accuracy of the recognition. For instance, each profile in the “actors” collection can have five faces, each coming from a different picture. When presented with a new, untagged, unknown photo, VisageCloud can then see which of the existent profiles has all of its faces closer to the newly presented picture.
Let us explore together how VisageCloud can best work for your use case