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.
-