Skip to content

Object reference

The following class initialization docstrings should give you an idea of the objects that are used in the OpenCV FR Python package.

APIError

An exception that may be raised when interacting with the backend.

from opencv.fr.api_error import APIError
class APIError(Exception):
    """Class that defines an API Error
    :param http_status_code: the HTTP status code of the error
    :type int
    :param err_code: the API error code
    :type str
    :param messsage: the API error message
    :type str
    :param retry_after: if present, specifies the time 
        in seconds when the request can be retried to meet rate limit checks
    :type Union[int, None]
    """

APIDataValidationError

An exception that may be raised when interacting with the backend and using a field value that is invalid.

from opencv.fr.api_error import APIDataValidationError
class APIDataValidationError(Exception):
    """Class that defines an API Data Validation Error
    :param details: Error details from API Server
    :type dict
    """

SortOrder

An enum specifying the sort order

from opencv.fr.schemas import SortOrder
class SortOrder(enum.Enum):
    '''Sort order of collections'''
    ASC = "ASC"
    DESC = "DESC"

CollectionBase

An object to create a Collection

from opencv.fr.collections.schemas import CollectionBase
class CollectionBase:
    '''A minimal collection object for creation

    :param name: the name of the collection
    :type name:str
    :param description: the description of the collection
    :type description: str
    '''

Collection

An object representing a previously created Collection

from opencv.fr.collections.schemas import Collection
class Collection(CollectionBase):
    '''A previously created collection object

    :param id: the id of a previously created collection
    :type id:str
    :param name: the name of the collection
    :type name:str
    :param description: the description of the collection
    :type description: str
    :param count: the number of persons in this collection
    :type count: int
    :param create_date: date that this collection was created
    :type create_date: datetime
    :param modified_date: date that this collection was modified
    :type modified_date: datetime
    '''

CollectionList

An object representing a list of collections matching specifying paging and search criteria

from opencv.fr.collections.schemas import CollectionList
class CollectionList:
    '''A list of collections

    :param count: the total count of all collections in the database
    :type count:int
    :param collections: the collections matching the criteria
    :type collections:List[Collection]
    '''

PersonBase

An object to create a Person

from opencv.fr.persons.schemas import PersonBase
class PersonBase:
    '''A person object

    :param images: a list of images (max 3), with each image 
        being either a numpy array (obtained with cv2.imread), 
        a string (path to a file), a Pillow image (obtained with 
        PIL.Image.open()), or a pathlib path
    :type images:List[Union[np.ndarray, str, Image, Path]]
    :param id: a unique identifier for the person. 
        If unspecified a new id will be generated, defaults to None
    :type id: Optional[str]
    :param name: the name of the person
    :type name:Optional[str]
    :param gender: the gender of the person, defaults to None
    :type gender: Optional[PersonGender]
    :param date_of_birth: the date of birth of the person, defaults to None
    :type date_of_birth: Optional[datetime]
    :param nationality: the nationality of the person, defaults to None
    :type nationality: Optional[str]
    :param collections: a list containing either Collection, 
        CollectionBase objects, or strings representing the 
        id of the collections that this person belongs to, 
        defaults to empty list []
    :type collections: Optional[List[Union[Collection, CollectionBase, str]]]
    :param notes: any additional notes about the person, defaults to None
    :type notes: Optional[str]
    :param is_bulk_insert: whether this person is part of a 
        bulk insert batch, defaults to False
    :type is_bulk_insert: Optional[bool]
    '''

Person

An object representing a previously created Person

from opencv.fr.persons.schemas import Person
class Person(PersonBase):
    '''A previously created person object

    :param images: a list of images (max 3), with each image 
        being either a numpy array (obtained with cv2.imread), 
        a string (path to a file), a Pillow image (obtained with 
        PIL.Image.open()), or a pathlib path
    :type images:List[Union[numpy.ndarray, str, PIL.Image.Image, pathlib.Path]]
    :param id: a unique identifier for the person.
    :type id: Optional[str]
    :param name: the name of the person
    :type name:Optional[str]
    :param gender: the gender of the person, defaults to None
    :type gender: Optional[PersonGender]
    :param date_of_birth: the date of birth of the person, defaults to None
    :type date_of_birth: Optional[datetime]
    :param nationality: the nationality of the person, defaults to None
    :type nationality: Optional[str]
    :param collections: a list containing either Collection, 
        CollectionBase objects, or strings representing the 
        id of the collections that this person belongs to, 
        defaults to empty list []
    :type collections: Optional[List[Union[Collection, CollectionBase, str]]]
    :param notes: any additional notes about the person, defaults to None
    :type notes: Optional[str]
    :param is_bulk_insert: whether this person is part of a 
        bulk insert batch, defaults to False
    :type is_bulk_insert: Optional[bool]
    :param create_date: date that this person was created
    :type create_date: datetime
    :param modified_date: date that this person was modified
    :type modified_date: datetime
    '''

PersonList

An object representing a list of collections matching specifying paging and search criteria

from opencv.fr.persons.schemas import PersonList
class PersonList:
    '''A list of persons

    :param count: the total count of all persons in the database
    :type count:int
    :param persons: the persons matching the criteria
    :type persons:List[Person]
    '''

SearchMode

An enum specifying search mode

from opencv.fr.search.schemas import SearchMode
class SearchMode(enum.Enum):
    ACCURATE = 'ACCURATE'
    FAST = 'FAST'

SearchRequest

An object specifying a search request

from opencv.fr.search.schemas import SearchRequest
class SearchRequest:
    """A search request object

    :param collection_id: the collection id to restrict the search
    :type collection_id:str
    :param images: a list of images (max 3), with each image 
        being either a numpy array (obtained with cv2.imread), 
        a string (path to a file), a Pillow image (obtained with 
        PIL.Image.open()), or a pathlib path
    :type images:List[Union[numpy.ndarray, str, PIL.Image.Image, pathlib.Path]]
    :param min_score: a minimum score to match the person, defaults to 0.7
    :type min_score: Optional[float]
    :param search_mode: the model to search FAST or ACCURATE, defaults to FAST
    :type search_mode: Optional[SearchMode]
    """

PersonSearchResult

An item in a search response

from opencv.fr.search.schemas import PersonSearchResult
class PersonSearchResult:
    '''A Person and an associated similarity score

    :param person: the person
    :type person: Person
    :param score: the similarity score
    :type score: float
    '''

SearchOptions

Options for a search

from opencv.fr.search.schemas import SearchOptions
class SearchOptions:
    '''Class to specify search options

    :param collection_id: the collection id to restrict the search
    :type collection_id: str
    :param min_score: a minimum score to optionally search 
        for a person, defaults to 0.7
    :type min_score: Optional[float]
    :param search_mode: the mode to use for the SearchMode.FAST 
        or SearchMode.ACCURATE, defaults to FAST
    :type search_mode: Optional[SearchMode]
    '''

DetectionRequest

An object specifying a detection request

from opencv.fr.search.schemas import DetectionRequest
class DetectionRequest:
    '''A detect object

    :param images: a list of images (max 3), with each image 
        being either a numpy array (obtained with cv2.imread), 
        a string (path to a file), a Pillow image (obtained with 
        PIL.Image.open()), or a pathlib path
    :type image: Union[numpy.ndarray, str, PIL.Image.Image, pathlib.Path]
    :param search_options: optional search options, defaults to None. 
        If not specified, the search will not be performed
    :type search_options: SearchOptions
    '''

Box

An object specifying a bounding box in a detection response item

from opencv.fr.search.schemas import Box
class Box:
    '''A bounding box

    :param left: left ordinate
    :type left: int
    :param top: top ordinate
    :type top: int
    :param right: right ordinate
    :type right: int
    :param bottom: bottom ordinate
    :type bottom: int
    '''

Coordinate

An object specifying x and y coordinates

from opencv.fr.search.schemas import Coordinate
class Coordinate:
    '''A coordinate

    :param x: x ordinate
    :type x: int
    :param y: y ordinate
    :type y: int
    '''

Landmarks

An object specifying facial landmarks

from opencv.fr.search.schemas import Landmarks
class Landmarks:
    '''Landmarks of a face

    :param left_eye: left eye
    :type left_eye: Coordinate
    :param right_eye: right eye
    :type right_eye: Coordinate
    :param nose: nose
    :type nose: Coordinate
    :param left_mouth: left mouth
    :type left_mouth: Coordinate
    :param right_mouth: right mouth
    :type right_mouth: Coordinate
    '''

DetectionResponseItem

A single item in the list of items returned when calling the detect API

from opencv.fr.search.schemas import DetectionResponseItem
class DetectionResponseItem:
    '''A detection response item (one face) of a detection response
    which consists of a bounding box, landmarks, thumbnail, 
    detection score, and list of matching persons

    :param box: bounding box
    :type box: Box
    :param landmarks: landmarks
    :type landmarks: Landmarks
    :param thumbnail: thumbnail
    :type thumbnail: Image
    :param score: detection score
    :type score: float
    :param persons: list of matching persons
    :type persons: List[PersonSearchResult]
    '''

VerificationRequest

A object specifying a verification request

from opencv.fr.search.schemas import VerificationRequest
class VerificationRequest:
    '''A verification request object

    :param id: the id of a person being verified
    :type id:str
    :param images: a list of images (max 3), with each image 
        being either a numpy array (obtained with cv2.imread), 
        a string (path to a file), a Pillow image (obtained with 
        PIL.Image.open()), or a pathlib path
    :type images:List[Union[numpy.ndarray, str, PIL.Image.Image, pathlib.Path]]
    :param min_score: a minimum score to match the person, defaults to 0.7
    :type min_score: Optional[float]
    :param search_mode: the model to search FAST or ACCURATE, defaults to ACCURATE
    :type search_mode: Optional[SearchMode]
    '''

VerificationResponse

An object specifying a verification response

from opencv.fr.search.schemas import VerificationResponse
class VerificationResponse:
    '''A verification response object

    :param person: the person being verified
    :type person: Person
    :param score: the score of the verification
    :type score: float
    '''

DeviceType

An enum representing the type of image capture device for liveness analysis

from opencv.fr.liveness.schemas import DeviceType
class DeviceType(enum.Enum):
    DESKTOP = 'DESKTOP'
    ANDROID = 'ANDROID'
    IOS = 'IOS'

LivenessRequest

An object specifying a liveness request

from opencv.fr.liveness.schemas import LivenessRequest
class LivenessRequest:
    '''A liveness request object

    :param os: OS setting to choose being either DeviceType.DESKTOP, 
        DeviceType.ANDROID, or DeviceType.IOS
    :type os: Optional[DeviceType]
    :param image: image being either a numpy array (obtained with cv2.imread), 
        a string (path to a file), a Pillow image 
        (obtained with PIL.Image.open()), or a pathlib path
    :type image: Union[numpy.ndarray, str, PIL.Image.Image, pathlib.Path]
    '''

LivenessResponse

An object specifying a liveness response

from opencv.fr.liveness.schemas import LivenessResponse
class LivenessResponse:
    '''A liveness response object

    :param score: the score of the liveness
    :type score: float
    '''

CompareRequest

from opencv.fr.compare.schemas import CompareRequest
class CompareRequest:
    '''A compare request object

    :param gallery: a list of images (max 3), with each image 
        being either a numpy array (obtained with cv2.imread), 
        a string (path to a file), a Pillow image (obtained with 
        PIL.Image.open()), or a pathlib path
    :type gallery: List[Union[numpy.ndarray, str, PIL.Image.Image, pathlib.Path]]
    :param probe: another list of images (like gallery)
    :type probe: List[Union[numpy.ndarray, str, PIL.Image.Image, pathlib.Path]]
    :param search_mode: the model to search FAST or ACCURATE, defaults to FAST
    :type search_mode: Optional[SearchMode]
    '''