Skip to content

Persons

Persons are people you would like to recognize/verify using our API.

You can use the API to add persons to the database, group them into collections, and manage them later.

Create a Person

Let's get started with creating a person:

from opencv.fr.persons.schemas import PersonBase
from pathlib import Path

image_base_path = Path("sample_images")
image_path = image_base_path / "varun.jpg"

# The only mandatory parameter for a person is images
# If id is unspecified, it will be auto-generated
# If name is unspecified, it will be set to the person's id
person = PersonBase([image_path], name="Varun")

Here, we have initialized the person object with a name and the path to an image. In addition to a path to an image, you could also have passed in an image loaded with cv2.imread(), or using pillow Image.open()

We now need to send this object to the server:

person = sdk.persons.create(person)

We now have a created Person.

A person has the following class properties listed below:

  • name - mandatory name of the person (we used this while creating the person)
  • images - at least 1 and a maximum of 3 images of the person (we used one image)
  • id - if specified, the system uses this as the id of the person. If unspecified, the system uses a unique identifier.
  • gender - the gender of the person
  • date_of_birth - the person's date of birth
  • nationality - the person's nationality
  • collections - a list of collections that the person belongs to
  • notes - any additional notes about the person

List Persons

Now that we have created a Person let's list all persons (as we did with collections).

persons = sdk.persons.list()
print(persons)

This should give you a result like the following:

{
    'count': 1, 
    'persons': [
        {
            'id': 'bb106660-85cd-44d0-8b80-2dc288503890', 
            'name': 'Varun', 
            'images': [<PIL.Image.Image image mode=RGB size=112x112 at 0x7FD1E654FE50>], 
            'gender': None, 
            'collections': [], 
            'date_of_birth': None, 
            'nationality': None, 
            'notes': None, 
            'create_date': '2022-07-13 13:33:17.133421', 
            'modified_date': '2022-07-13 13:33:17.133423'
        }
    ]
}

As with collections, the count tells you that there are a total number of 1 persons in your database. The next attribute persons shows you the actual persons (as a list).

Filtering Persons

In the previous example, we called sdk.persons.list() without specifying any qualifiers.

Like in collections, we can call sdk.persons.list() with additional parameters that determine what results will be returned.

    class PersonOrderBy(enum.Enum):
        NAME = "name"
        DATE_OF_BIRTH = "date_of_birth"
        GENDER = "gender"
        NATIONALITY = "nationality"
        MODIFIED_DATE = "modified_date"
        CREATE_DATE = "create_date"

    def list(self, skip:Optional[int]=0, 
             take:Optional[int]=20, 
             order_by:Optional[PersonOrderBy]=PersonOrderBy.NAME, 
             order:Optional[SortOrder]=SortOrder.ASC, 
             search:Optional[str]=None) -> PersonList:
        """Get a persons list 

        :param skip: skip the specified number of initial rows, defaults to 0
        :type skip:Optional[int]
        :param take: get the specified number of rows, defaults to 20
        :type take:Optional[int]
        :param order: order ascending(SortOrder.ASC) or descending(SortOrder.DESC)
        :type order:Optional[SortOrder]
        :param order_by: the column to choose for the ordering
        :type order_by:Optional[PersonOrderBy]
        :param search: a search string to filter collections by name/description
        :type search:Optional[str]

        :raises ApiError: an API error if unsuccessful

        :return: a CollectionList object
        :rtype: CollectionList
        """

The following snippet shows how to get the first five results that have a person matching the string "Varun" while ordering them by the date they were created:

from opencv.fr.persons.schemas import PersonOrderBy
from opencv.fr.schemas import SortOrder
persons = sdk.persons.list(skip=0, take=5, 
                           order=SortOrder.ASC, 
                           order_by=PersonOrderBy.CREATE_DATE,
                           search="Varun")
print(persons)

As with collections, you can choose a sort order, a column to order the results by order_by, a search string, and take and skip parameters to help you implement paging.

Updating a Person

You can update a Person either after creating one, or after getting one:

Create:

from opencv.fr.persons.schemas import PersonBase
from pathlib import Path

import cv2
from PIL import Image
from opencv.fr.persons.schemas import PersonBase
from pathlib import Path

# Different ways of using images!

# Passing an image using OpenCV
image = cv2.imread("sample_images/varun.jpg")
person = PersonBase([image], name="Varun")

# Passing an image using Path
image_path = Path("sample_images") / "varun.jpg"
person = PersonBase([image_path], name="Varun")

# Passing an image using pillow
image = Image.open("sample_images/varun.jpg")
person = PersonBase([image_path], name="Varun")

# Passing an image using a plain string
image = "sample_images/varun.jpg"
person = PersonBase([image_path], name="Varun")

Get:

my_person = sdk.persons.get(my_person.id)

As long as my_person is a valid reference to a person, you can update it like so:

my_person.name = "Speedy Gonzalves"
my_person = sdk.persons.update(my_person)
print(sdk.persons.list())
Updating the images of a Person

To update the images of a person, you can set the images property:

my_person.images = ["sample_images/varun.jpg"]

It is to be noted, that this property has no getter. The images property should to set with full images which are at least 224x224 pixels.

If you retrieved the person using sdk.persons.get(my_person.id), then all images should be set in one go.

You should NOT do the following:

my_person.images = [my_person.get_image(0), "sample_images/varun.jpg"]

Doing the above will mean that the first image is actually a thumbnail from the server - which is smaller than 224x224 pixels, and should not be sent to the server again.

Using new, full size images to update the person's images is the intended way to use this SDK.

After setting the images, you can use the get_image(index: int) to get an image:

my_image = my_person.get_image(0)
Adding a Person to a Collection

To add a Person to a Collection, you can specify the Collection in the collections list of the person during a create, or update operation.

During creation:

# Here we get an existing collection, but this could also
# be a collection you created
my_collection = sdk.collections.get(my_collection.id)

# Create PersonBase
image = cv2.imread("sample_images/varun.jpg")
person = PersonBase([image], name="Varun")

# Add collection to the person's collections
person.collections.append(my_collection)

# Create the person
person = sdk.persons.create(person)

Update a person:

my_collection = sdk.collections.get(my_collection.id)
my_person = sdk.persons.get(my_person.id)
my_person.collections.append(my_collection)
my_person = sdk.persons.update(my_person)

Deleting multiple Person objects at once

If you know a series of id to delete, you can delete multiple persons at once in this manner: 

from opencv.fr.persons.schemas import UpdatePersonsRequest,Action
update_persons_request = UpdatePersonsRequest(Action.DELETE,[my_person.id])
update_persons_response = sdk.persons.update_person(update_persons_request)
print(sdk.persons.list())

Deleting a specific Person

If you know the id of a person, you can delete the person like so:

sdk.persons.delete(my_person.id)
print(sdk.persons.list())