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 hassle. In this document, we’ll go through the domain model and some example API calls.
1. The VisageCloud Domain Model
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 hassle. In this document, we’ll go
through the domain model and some example API calls.
Domain Model
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:
● An account gives you access to manage several collections
● A collection groups together several profile of distinct persons. Eg. actors, employees.
● A profile identifies a distinct individual (eg. Jane, John, Anna, Tom) which belong a
collection.
● A face is an instance of an individual’s face, as capture in a photo. Having several faces
associated profile (preferably with different lighting, perspective, make-up, facial expression
or other contextual features) helps improve the accuracy of facial recognition.
Now let’s look at the entities in more detail.
2. Account
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
3. you are using VisageCloud in an on-premise installation, you will receive a masterKey that will allow
you to create account with the whatever permission you like.
Collection
The Collection groups together several individual who belong to the same set. Example 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 profile.
Profile
A Profile is the representation of a specific person’s face under several circumstance. 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 a 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 to manage 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”).
Face
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 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.