Identities

Identities are known specific instances of an object that can be later recognized. For example, a picture of a person’s face can be encoded and associated with that person’s identity so that they can be recognized when they’re in a video stream.

Identities can also be associated with vectors directly in cases where the encoding of an object is known ahead-of-time, like in the case of a fiducial tag.

"""Creates an identity for a specific skew of car using a picture of that
car.
"""
from pathlib import Path

from brainframe.api import BrainFrameAPI
from brainframe.bf_codecs import Identity

api = BrainFrameAPI("http://localhost")

civic_image_bytes = Path("civic.jpg").read_bytes()
# Upload the image to the server
storage_id = api.new_storage(civic_image_bytes, "image/jpeg")

# Create the new identity for the car skew
identity = api.set_identity(Identity(
    unique_name="g10-R16B-blue-sedan",
    nickname="Honda Civic 2018 Blue Sedan",
))
# Encode an image of the skew and associate that encoding with the identity
api.new_identity_image(identity.id, "car", storage_id)

API Methods

BrainFrameAPI.get_identity(identity_id: int, timeout=30) → brainframe.api.bf_codecs.identity_codecs.Identity

Gets the identity with the given ID.

Parameters

  • identity_id – The ID of the identity to get

  • timeout – The timeout to use for this request

Returns

Identity

BrainFrameAPI.get_identities(unique_name: str = None, encoded_for_class: str = None, search: Optional[str] = None, limit: int = None, offset: int = None, sort_by: brainframe.api.bf_codecs.sorting.SortOptions = None, timeout=30) → Tuple[List[brainframe.api.bf_codecs.identity_codecs.Identity], int]

Returns all identities from the server.

Parameters

  • unique_name – If provided, identities will be filtered by only those who have the given unique name

  • encoded_for_class – If provided, identities will be filtered for only those that have been encoded at least once for the given class

  • search – If provided, only identities that in some way contain the given search query are returned. This is intended for UI search features, and as such the specific semantics of how the search is performed are subject to change.

  • limit – If provided, the number of returned identities is limited to this value.

  • offset – The offset to start limiting results from. This is only useful when providing a limit.

  • sort_by – If provided, the results will be sorted by the given configuration

  • timeout – The timeout to use for this request

Returns

A list of identities, and the total number of identities that fit this criteria, ignoring pagination (the limit and offset)

BrainFrameAPI.set_identity(identity: brainframe.api.bf_codecs.identity_codecs.Identity, timeout=30) → brainframe.api.bf_codecs.identity_codecs.Identity

Updates or creates an identity. If the identity does not already exist, identity.id must be None. The returned identity will have an assigned ID.

Parameters

  • identity – The identity to save or create

  • timeout – The timeout to use for this request

Returns

the saved identity

BrainFrameAPI.delete_identity(identity_id: int, timeout=30)

Deletes the identity with the given ID.

Parameters

  • identity_id – The ID of the identity to delete

  • timeout – The timeout to use for this request

BrainFrameAPI.new_identity_image(identity_id: int, class_name: str, storage_id: int, timeout=30)

Saves and encodes an image under the identity with the given ID.

Parameters

  • identity_id – Identity to associate the image with

  • class_name – The type of object this image shows and should be encoded for

  • storage_id – The ID of the image in storage to encode

  • timeout – The timeout to use for this request

BrainFrameAPI.new_identity_vector(identity_id: int, class_name: str, vector: List[float], timeout=30) → int

Saves the given vector under the identity with the given ID. In this case, a vector is simply a list of one or more numbers that describe some object in an image.

Parameters

  • identity_id – Identity to associate the vector with

  • class_name – The type of object this vector describes

  • vector – The vector to save

  • timeout – The timeout to use for this request

Returns

The vector ID

BrainFrameAPI.get_encoding(encoding_id, timeout=30) → brainframe.api.bf_codecs.identity_codecs.Encoding

Get the encoding with the given ID.

Parameters

  • encoding_id – The encoding ID to get an encoding for

  • timeout – The timeout to use for this request

Returns

The corresponding encoding

BrainFrameAPI.get_encodings(identity_id: Optional[int] = None, class_name: Optional[str] = None, timeout=30) → List[brainframe.api.bf_codecs.identity_codecs.Encoding]

Gets all encodings from the server that match the given filters.

Parameters

  • identity_id – If specified, only encodings attached to this identity will be returned

  • class_name – If specified, only encodings for the given class name will be returned

  • timeout – The timeout to use for this request

Returns

All encodings that match this filter

BrainFrameAPI.get_encoding_class_names(identity_id: Optional[int] = None, timeout=30) → List[str]

Get all unique class names for encodings that match the given filter.

Parameters

  • identity_id – If specified, only class names for encodings attached to this identity will be returned

  • timeout – The timeout to use for this request

Returns

All class names from encodings that match this filter

BrainFrameAPI.delete_encoding(encoding_id, timeout=30)

Deletes the encoding with the given ID.

Parameters

  • encoding_id – The ID of the encoding to delete

  • timeout – The timeout to use for this request

BrainFrameAPI.delete_encodings(identity_id=None, class_name=None, timeout=30)

Deletes all encodings that match the given filter.

Parameters

  • identity_id – If specified, only encodings that are associated with this identity will be deleted

  • class_name – If specified, only encodings that are for this class will be deleted

  • timeout – The timeout to use for this request

Data Structures

class Encoding(identity_id: int, class_name: str, from_image: Optional[int], vector: List[int], id: Optional[int] = None)

An encoding attached to an identity.

class_name: str

The class of object this encoding is for.

from_image: Optional[int]

The storage ID of the image that this encoding was created from, or None if this encoding was not created from an image.

id: Optional[int] = None

The unique ID of the encoding.

identity_id: int

The ID of the identity this encoding is associated with.

vector: List[int]

A low-dimensional representation of the object’s appearance. This is what objects found in streams will be compared to in order to decide if the object is of the identity this encoding is associated with.

class Identity(unique_name: str, nickname: str, metadata: dict = <factory>, id: Optional[int] = None)

A specific, recognizable object or person.

id: Optional[int] = None

A unique identifier.

metadata: dict

Any additional user-defined information about the identity.

nickname: str

A display name for the identity which may not be unique, like a person’s name.

unique_name: str

The unique id of the identified detection.

Not to be confused with the id of the object which is a field used by the database.