Skip to content

1:N Face Identification Module

The current module lets you create a database with identities providing various search capabilities.

The main module entities are:

  • Person. Identity with a name, a set of images and metadata. Metadata is a regular json object, specified by the end app.
  • Image. Photo of Person.
  • Group. A set of Persons. You can create any number of Groups, add or remove Persons from them at any time. By default, Person doesn't belong to any Group. Each Person can be a member of many Groups.
  • Storage. Storage for Images of Person. There can be multiple storages per application.

Please keep in mind the following info:

  • During the Person creation, you specify which Storage to use for saving photos. Thus, you can split your photo catalog for further processing or other needs.
  • The main property of Storage is uri that allows you to use not only the local file system, but other remote stuff as well, for example, aws s3 buckets, etc. (Currently on the file system is supported).
  • Each Person can have only one Storage.

How to use 1:N Face Identification Module

  1. Install Docker Compose.
  2. Download the docker-compose.yml file.
  3. Create folders to save information at volumes. Ensure the group is root and group members have write & execute permissions over the created folder:

    mkdir -p ~/id-module/sql_data
    mkdir -p ~/id-module/face_resources
    chmod -R g+wx ~/id-module
    sudo chgrp -R root ~/id-module
  4. Put your license to your user's home (/home/username/) directory.

  5. From the directory with the docker-compose.yml file, run:

    docker-compose up


    The "WORKERS" option must be set to "1" if you use 1:N Face Identification Module.

  6. 1:N Python service usage example

    # import all sdk modules
    from client.api.sdk import Sdk
    from client.model.image import Image
    from import Storage
    from import Group
    from client.model.person import Person
    from client.model.recognition import SearchParams, SearchSource
    import base64
    # SDK object creating
    sdk = Sdk(url)

    6.1 Group and Storage creating and deleting. Group stores all persons and Storage stores persons images

    sdk.groups.create(Group(1, "persons", {})) # 1 - group id, "persons" - group name, "default")) # 1 - storage id, "default" - storage name # 1 - storage id

    # equal to"{base_url}/groups", json=vars(Group(1, "persons", {})))"{base_url}/storage", json=vars(Storage(1, "default")))
    requests.put(f"{base_url}/storage/default", json=storage_id)
    # delete group
    # equal to

    6.2 Person. Person creating, deleting. Images adding

    # creating and adding a person to group
    person = Person(None, "default", {}, # None - person id (optinonal), "default" - person_name, "{}" - metadata
    person = sdk.persons.create(person)
    sdk.groups.update_persons(1, [], []) # 1 - group id, [] - array with persons to add, [] - array with persons to remove

    # equal to"{base_url}/persons", json=vars(Person(None, "default", {},
    response = requests.put(f'{base_url}/{group_id}/persons', json={"addItems": [], "removeItems": []})
    # attach image to person
    image = Image(id=None, person_id=person_id, content=image_b64) # Image object
    sdk.persons.attach_image(image, force=False)
    # equal to'{base_url}/{person_id}/images', params={"force": force}, json={"searchParams": None, "image": vars(Image(id=None, person_id=person_id, content=image_b64))})
    # detach image from person
    self.sdk.persons.detach_image(person_id, image_id)
    # to get person images
    self.sdk.persons.get_all_images(PageArgs(1, 1000), person_id)
    # equal to
    requests.get(f'{self.base_url}/persons/{person_id}/images', params=vars(PageArgs(1, 1000)))

    6.3 Search method

    # image searching
    search_params = SearchParams(distance, similarity, count)
    with open(image_path, 'rb') as image_file:
      image_b64 = base64.b64encode("utf-8")
    results =, SearchSource(image_b64, [1])) # SearchSource(image bytes, groups to search)

    # equal to'{base_url}/search', params=vars(SearchParams(distance, similarity, count)), json=vars(SearchSource(image_b64, [1])))