ApiKeyMeta

ApiKeyMeta contains key information.

class encord.orm.api_key.ApiKeyMeta(dic)

ORM:

title, resource_type

  • DB_FIELDS: collections.OrderedDict = {'resource_type': <class 'str'>, 'title': <class 'str'>}

  • NON_UPDATABLE_FIELDS: set = {'resource_type'}

class ApiKeyMeta(base_orm.BaseORM):
    """
    ApiKeyMeta contains key information.

    ORM:

    title,
    resource_type

    """

    DB_FIELDS = OrderedDict(
        [
            ("title", str),
            ("resource_type", str),
        ]
    )

    NON_UPDATABLE_FIELDS = {
        "resource_type",
    }

BaseORM

Base ORM for all database objects.

class encord.orm.base_orm.BaseORM(dic)
  • DB_FIELDS: collections.OrderedDict = {}

  • NON_UPDATABLE_FIELDS: set = {}

Source
class BaseORM(dict):
    """Base ORM for all database objects."""

    DB_FIELDS: OrderedDict = OrderedDict()
    NON_UPDATABLE_FIELDS: set = set()

    def __init__(self, dic):
        """
        Construct client ORM compatible database object from dict object.
        Ensures strict type and attribute name check.
        The real k,v is stored in inner dict.
        :param dic:
        """
        try:
            if not isinstance(dic, dict):
                raise TypeError("Need dict object")
            value = {}
            for k, v in dic.items():
                if k in self.DB_FIELDS:
                    types = self.DB_FIELDS[k]
                    # Convert all types to tuple
                    if not isinstance(types, tuple):
                        types = (types,)
                    # None value is allowed for some cases
                    if v is None:
                        value[k] = v
                    # Normal cases where type matches required types
                    elif isinstance(v, types):
                        value[k] = v
                    # Bool value is same as 0,1 in db
                    elif v in (0, 1) and bool in types:
                        value[k] = v
                    # Datetime type but actually a datetime str is provided
                    elif datetime.datetime in types:
                        real_v = datetime.datetime.strptime(v, "%Y-%m-%d %H:%M:%S")
                        value[k] = real_v
                    elif dict in types:
                        value[k] = v
            super().__init__(**value)
        except Exception as e:
            logger.error("Error init", exc_info=True)
            raise Exception(f"Convert failed {e}")

    def __getattr__(self, name):
        """
        Override attribute method for easy access of field value.
        To be used instead of ["attr"].
        Return None if there is no such attribute
        :param name:
        :return:
        """
        if name in self:
            try:
                return self[name]
            except KeyError:
                return None
        else:
            raise AttributeError(f"Attribute does not exist: {name}")

    def __setattr__(self, name, value):
        """
        Strict attribute name and type check.
        :param name:
        :param value:
        :return:
        """
        if name in self.DB_FIELDS and (value is None or isinstance(value, self.DB_FIELDS[name])):
            self[name] = value
        else:
            raise AttributeError(f"Attribute name or type not match: {name}")

    def __delattr__(self, name):
        if name in self and name in self.DB_FIELDS:
            del self[name]
        else:
            super().__delattr__(name)

    @staticmethod
    def from_db_row(row, db_field):
        """
        Static method for conveniently converting db row to client object.
        :param row:
        :param db_field:
        :return:
        """
        return {attribute: row[i] for i, attribute in enumerate(db_field)}


    def to_dic(self, time_str: bool = True):
        """
        Conveniently set client object as dict.
        Only considers the dict items, no other object attr will be counted

        Args:
            time_str: if set to True, will convert datetime field
                      to str with format %Y-%m-%d %H:%M:%S.
                      If False, will keep the original datetime type.
                      Default will be True.

        """
        res = {}
        for k, v in self.items():
            if isinstance(v, datetime.datetime) and time_str:
                v = v.strftime("%Y-%m-%d %H:%M:%S")
            elif isinstance(v, dict):
                v = json.dumps(v)
            res[k] = v

        return res


    def updatable_fields(self):
        for k, v in self.items():
            if k not in self.NON_UPDATABLE_FIELDS and v is not None:
                yield k, v

from_db_row

Static method for conveniently converting db row to client object. :param row: :param db_field: :return:

static from_db_row(row, db_field)
    @staticmethod
    def from_db_row(row, db_field):
        """
        Static method for conveniently converting db row to client object.
        :param row:
        :param db_field:
        :return:
        """
        return {attribute: row[i] for i, attribute in enumerate(db_field)}

to_dic

Conveniently sets client object as dict. Only considers the dict items, no other object attributes will be counted.

to_dic(time_str=True)

Parameters:

time_str (bool) – if set to True, will convert datetime field to str with format %Y-%m-%d %H:%M:%S. If False, will keep the original datetime type. Default will be True.

    def to_dic(self, time_str: bool = True):
        """
        Conveniently set client object as dict.
        Only considers the dict items, no other object attr will be counted

        Args:
            time_str: if set to True, will convert datetime field
                      to str with format %Y-%m-%d %H:%M:%S.
                      If False, will keep the original datetime type.
                      Default will be True.

        """
        res = {}
        for k, v in self.items():
            if isinstance(v, datetime.datetime) and time_str:
                v = v.strftime("%Y-%m-%d %H:%M:%S")
            elif isinstance(v, dict):
                v = json.dumps(v)
            res[k] = v

        return res

updatable_fields

updatable_fields()
    def updatable_fields(self):
        for k, v in self.items():
            if k not in self.NON_UPDATABLE_FIELDS and v is not None:
                yield k, v

Complete Source

#
# Copyright (c) 2023 Cord Technologies Limited
#
# Licensed under the Apache License, Version 2.0 (the "License"); you may
# not use this file except in compliance with the License. You may obtain
# a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
# License for the specific language governing permissions and limitations
# under the License.

import datetime
import json
import logging
from collections import OrderedDict, abc

logger = logging.getLogger(__name__)


class BaseORM(dict):
    """Base ORM for all database objects."""

    DB_FIELDS: OrderedDict = OrderedDict()
    NON_UPDATABLE_FIELDS: set = set()

    def __init__(self, dic):
        """
        Construct client ORM compatible database object from dict object.
        Ensures strict type and attribute name check.
        The real k,v is stored in inner dict.
        :param dic:
        """
        try:
            if not isinstance(dic, dict):
                raise TypeError("Need dict object")
            value = {}
            for k, v in dic.items():
                if k in self.DB_FIELDS:
                    types = self.DB_FIELDS[k]
                    # Convert all types to tuple
                    if not isinstance(types, tuple):
                        types = (types,)
                    # None value is allowed for some cases
                    if v is None:
                        value[k] = v
                    # Normal cases where type matches required types
                    elif isinstance(v, types):
                        value[k] = v
                    # Bool value is same as 0,1 in db
                    elif v in (0, 1) and bool in types:
                        value[k] = v
                    # Datetime type but actually a datetime str is provided
                    elif datetime.datetime in types:
                        real_v = datetime.datetime.strptime(v, "%Y-%m-%d %H:%M:%S")
                        value[k] = real_v
                    elif dict in types:
                        value[k] = v
            super().__init__(**value)
        except Exception as e:
            logger.error("Error init", exc_info=True)
            raise Exception(f"Convert failed {e}")

    def __getattr__(self, name):
        """
        Override attribute method for easy access of field value.
        To be used instead of ["attr"].
        Return None if there is no such attribute
        :param name:
        :return:
        """
        if name in self:
            try:
                return self[name]
            except KeyError:
                return None
        else:
            raise AttributeError(f"Attribute does not exist: {name}")

    def __setattr__(self, name, value):
        """
        Strict attribute name and type check.
        :param name:
        :param value:
        :return:
        """
        if name in self.DB_FIELDS and (value is None or isinstance(value, self.DB_FIELDS[name])):
            self[name] = value
        else:
            raise AttributeError(f"Attribute name or type not match: {name}")

    def __delattr__(self, name):
        if name in self and name in self.DB_FIELDS:
            del self[name]
        else:
            super().__delattr__(name)

    @staticmethod
    def from_db_row(row, db_field):
        """
        Static method for conveniently converting db row to client object.
        :param row:
        :param db_field:
        :return:
        """
        return {attribute: row[i] for i, attribute in enumerate(db_field)}

    def to_dic(self, time_str: bool = True):
        """
        Conveniently set client object as dict.
        Only considers the dict items, no other object attr will be counted

        Args:
            time_str: if set to True, will convert datetime field
                      to str with format %Y-%m-%d %H:%M:%S.
                      If False, will keep the original datetime type.
                      Default will be True.

        """
        res = {}
        for k, v in self.items():
            if isinstance(v, datetime.datetime) and time_str:
                v = v.strftime("%Y-%m-%d %H:%M:%S")
            elif isinstance(v, dict):
                v = json.dumps(v)
            res[k] = v

        return res

    def updatable_fields(self):
        for k, v in self.items():
            if k not in self.NON_UPDATABLE_FIELDS and v is not None:
                yield k, v


class BaseListORM(list):
    """A wrapper for a list of objects of a specific ORM."""

    BASE_ORM_TYPE = BaseORM

    def __init__(self, iter_):
        if not isinstance(iter_, abc.Iterable):
            raise Exception("Convert failed. The object is not an iterable.")

        values = []
        for item in iter_:
            try:
                v = self.BASE_ORM_TYPE(item)
                values.append(v)
            except Exception as e:
                logger.error("Error init", exc_info=True)
                raise Exception(f"Convert failed {e}")
        super().__init__(values)

BaseListORM

A wrapper for a list of objects of a specific ORM.

class encord.orm.base_orm.BaseListORM(iter_)

BASE_ORM_TYPE: alias of encord.orm.base_orm.BaseORM

class BaseListORM(list):
    """A wrapper for a list of objects of a specific ORM."""

    BASE_ORM_TYPE = BaseORM

    def __init__(self, iter_):
        if not isinstance(iter_, abc.Iterable):
            raise Exception("Convert failed. The object is not an iterable.")

        values = []
        for item in iter_:
            try:
                v = self.BASE_ORM_TYPE(item)
                values.append(v)
            except Exception as e:
                logger.error("Error init", exc_info=True)
                raise Exception(f"Convert failed {e}")
        super().__init__(values)

CloudIntegration

class encord.orm.cloud_integration.CloudIntegration(id, title)

Parameters:

  • id: str
  • title: str
from dataclasses import dataclass


@dataclass(frozen=True)
class CloudIntegration:
    id: str
    title: str

DatasetUserRole

An enumeration.

class encord.orm.dataset.DatasetUserRole(value)

Parameters:

  • ADMIN = 0
  • USER = 1
class DatasetUserRole(IntEnum):
    ADMIN = 0
    USER = 1

DatasetUser

class encord.orm.dataset.DatasetUser(user_email, user_role, dataset_hash)

Parameters:

  • user_email: str
  • user_role: encord.orm.dataset.DatasetUserRole
  • dataset_hash: str

from_dict

classmethod from_dict(json_dict)
    @classmethod
    def from_dict(cls, json_dict: Dict):
        return DatasetUser(
            user_email=json_dict["user_email"],
            user_role=DatasetUserRole(json_dict["user_role"]),
            dataset_hash=json_dict["dataset_hash"],
        )

Source

@dataclasses.dataclass(frozen=True)
class DatasetUser(Formatter):
    user_email: str
    user_role: DatasetUserRole
    dataset_hash: str

    @classmethod
    def from_dict(cls, json_dict: Dict):
        return DatasetUser(
            user_email=json_dict["user_email"],
            user_role=DatasetUserRole(json_dict["user_role"]),
            dataset_hash=json_dict["dataset_hash"],
        )

DatasetUsers

class encord.orm.dataset.DatasetUsers
class DatasetUsers:
    pass

DataClientMetadata

class encord.orm.dataset.DataClientMetadata(payload)

Parameters:

payload: dict

@dataclasses.dataclass(frozen=True)
class DataClientMetadata:
    payload: dict

ImageData

Information about individual images within a single DataRow of type DataType.IMG_GROUP. Get this information using the [DataRow.images] property.

class encord.orm.dataset.ImageData(image_hash, title, file_link, file_type, file_size, storage_location, created_at, last_edited_at, width, signed_url, height)

property image_hash: str

Return Type

str

property title: str

Return Type

str

property file_link: str

Return Type

str

property file_type: str

The MIME type of the file.

Return Type

str

property file_size: int

The size of the file in bytes.

Return Type

int

property storage_location: encord.orm.dataset.StorageLocation

Return Type

[StorageLocation]

property created_at: datetime.datetime

Return Type

datetime

property last_edited_at: datetime.datetime

Return Type

datetime

property height: int

Return Type

int

property width: int

Return Type

int

property signed_url: Optional[str]

The signed URL if one was generated when this class was created.

Return Type

Optional[str]

from_dict

classmethod from_dict(json_dict)

Return type:

[ImageData]

    @classmethod
    def from_dict(cls, json_dict: Dict) -> ImageData:
        return ImageData(
            title=json_dict["title"],
            file_link=json_dict["file_link"],
            file_type=json_dict["file_type"],
            file_size=json_dict["file_size"],
            image_hash=json_dict["image_hash"],
            storage_location=json_dict["storage_location"],
            created_at=parser.parse(json_dict["created_at"]),
            last_edited_at=parser.parse(json_dict["last_edited_at"]),
            height=json_dict["height"],
            width=json_dict["width"],
            signed_url=json_dict.get("signed_url"),
        )

from_list

classmethod from_list(json_list)

Return type:

List[ImageData]

    @classmethod
    def from_list(cls, json_list: List) -> List[ImageData]:
        return [cls.from_dict(json_dict) for json_dict in json_list]

Source

class ImageData:
    """
    Information about individual images within a single :class:`~encord.orm.dataset.DataRow` of type
    :meth:`DataType.IMG_GROUP <encord.constants.enums.DataType.IMG_GROUP>`. Get this information
    via the :meth:`DataRow.images <encord.orm.dataset.DataRow.images>` property.
    """

    def __init__(
        self,
        image_hash: UUID,
        title: str,
        file_link: str,
        file_type: str,
        file_size: int,
        storage_location: StorageLocation,
        created_at: datetime,
        last_edited_at: datetime,
        width: int,
        signed_url: Optional[str],
        height: int,
    ):
        self._image_hash = image_hash
        self._title = title
        self._file_link = file_link
        self._file_type = file_type
        self._file_size = file_size
        self._storage_location = storage_location
        self._created_at = created_at
        self._last_edited_at = last_edited_at
        self._height = height
        self._width = width
        self._signed_url = signed_url

    @property
    def image_hash(self) -> str:
        return str(self._image_hash)

    @property
    def title(self) -> str:
        return self._title

    @property
    def file_link(self) -> str:
        return self._file_link

    @property
    def file_type(self) -> str:
        """
        The MIME type of the file.
        """
        return self._file_type

    @property
    def file_size(self) -> int:
        """
        The size of the file in bytes.
        """
        return self._file_size

    @property
    def storage_location(self) -> StorageLocation:
        return self._storage_location

    @property
    def created_at(self) -> datetime:
        return self._created_at

    @property
    def last_edited_at(self) -> datetime:
        return self._last_edited_at

    @property
    def height(self) -> int:
        return self._height

    @property
    def width(self) -> int:
        return self._width

    @property
    def signed_url(self) -> Optional[str]:
        """The signed URL if one was generated when this class was created."""
        return self._signed_url

    @classmethod
    def from_dict(cls, json_dict: Dict) -> ImageData:
        return ImageData(
            title=json_dict["title"],
            file_link=json_dict["file_link"],
            file_type=json_dict["file_type"],
            file_size=json_dict["file_size"],
            image_hash=json_dict["image_hash"],
            storage_location=json_dict["storage_location"],
            created_at=parser.parse(json_dict["created_at"]),
            last_edited_at=parser.parse(json_dict["last_edited_at"]),
            height=json_dict["height"],
            width=json_dict["width"],
            signed_url=json_dict.get("signed_url"),
        )


    @classmethod
    def from_list(cls, json_list: List) -> List[ImageData]:
        return [cls.from_dict(json_dict) for json_dict in json_list]


    def __repr__(self):
        return f"ImageData(title={self.title}, image_hash={self.image_hash})"

DataRow

Each individual DataRow is one upload of a video, image group, single image, or DICOM series.

This class has dict-style accessors for backwards compatibility. Clients who are using this class for the first time are encouraged to use the property accessors and setters instead of the underlying dictionary. The mixed use of the dict style member functions and the property accessors and setters is discouraged.

🚧

WARNING:

Do NOT use the .data member of this class. Its usage could corrupt the correctness of the datastructure.

class encord.orm.dataset.DataRow(uid, title, data_type, created_at, last_edited_at, width, height, file_link, file_size, file_type, storage_location, client_metadata, frames_per_second, duration, images_data, signed_url, is_optimised_image_group)

property uid: str

The unique identifier for this data row. Note that the setter does not update the data on the server.

Return Type

str

property title: str

The data title.

The setter updates the custom client metadata. This queues a request for the backend which will be executed on a call of DataRow.upload().

Return Type

str

property data_type: encord.constants.enums.DataType

Return Type

DataType

property created_at: datetime.datetime

Return Type

datetime

property frames_per_second: Optional[int]

If the data type is DataType.VIDEO this returns the actual number of frames per second for the video. Otherwise, it returns None as a frames_per_second field is not applicable.

Return Type

Optional[int]

property duration: Optional[int]

If the data type is DataType.VIDEO this returns the actual duration for the video. Otherwise, it returns None as a duration field is not applicable.

Return Type

Optional[int]

property client_metadata: Optional[dict]

The currently cached client metadata. To cache the client metadata, use the refetch_data() function.

The setter updates the custom client metadata. This queues a request for the backend which will be executed on a call of DataRow.upload().

Return Type

Optional[dict]

property width: Optional[int]

An actual width of the data asset. This is None for data types of DataType.IMG_GROUP where is_image_sequence is False, because each image in this group can have a different dimension. Inspect the images to get the height of individual images.

Return Type

Optional[int]

property height: Optional[int]

An actual height of the data asset. This is None for data types of DataType.IMG_GROUP where is_image_sequence is False, because each image in this group can have a different dimension. Inspect the images to get the height of individual images.

Return Type

Optional[int]

property last_edited_at: datetime.datetime

Return Type

datetime

property file_link: Optional[str]

A permanent file link of the given data asset. When stored in StorageLocation.CORD_STORAGE this will be the internal file path. In private bucket storage location this will be the full path to the file. If the data type is DataType.DICOM then this returns None as no single file is associated with the series.

Return Type

Optional[str]

property signed_url: Optional[str]

The cached signed url of the given data asset. To cache the signed url, use the refetch_data() function.

Return Type

Optional[str]

property file_size: int

The file size of the given data asset in bytes.

Return Type

int

property file_type: str

A MIME file type of the given data asset as a string

Return Type

str

property storage_location: encord.orm.dataset.StorageLocation

Return Type

StorageLocation

property images_data: Optional[List[encord.orm.dataset.ImageData]]

A list of the cached ImageData objects for the given data asset. Fetch the images with appropriate settings in the refetch_data() function. If the data type is not DataType.IMG_GROUP then this returns None.

Return Type

Optional[List[ImageData]]

DEPRECATED: property is_optimised_image_group: Optional[bool]

If the data type is an DataType.IMG_GROUP, returns whether this is a performance optimised image group. Returns None for other data types.

DEPRECATED: This method is deprecated and will be removed in the upcoming library version. Please use [is_image_sequence()] instead

Return Type

Optional[bool]

property is_image_sequence: Optional[bool]

If the data type is an DataType.IMG_GROUP, returns whether this is an image sequence. Returns None for other data types.

For more details refer to the documentation on image sequences.

Return Type

Optional[bool]

Source
class DataRow(dict, Formatter):
    """
    Each individual DataRow is one upload of a video, image group, single image, or DICOM series.

    This class has dict-style accessors for backwards compatibility.
    Clients who are using this class for the first time are encouraged to use the property accessors and setters
    instead of the underlying dictionary.
    The mixed use of the `dict` style member functions and the property accessors and setters is discouraged.

    WARNING: Do NOT use the `.data` member of this class. Its usage could corrupt the correctness of the
    datastructure.
    """

    def __init__(
        self,
        uid: str,
        title: str,
        data_type: DataType,
        created_at: datetime,
        last_edited_at: datetime,
        width: Optional[int],
        height: Optional[int],
        file_link: Optional[str],
        file_size: Optional[int],
        file_type: Optional[str],
        storage_location: StorageLocation,
        client_metadata: Optional[dict],
        frames_per_second: Optional[int],
        duration: Optional[int],
        images_data: Optional[List[dict]],
        signed_url: Optional[str],
        is_optimised_image_group: Optional[bool],
    ):
        parsed_images = None
        if images_data is not None:
            parsed_images = [ImageData.from_dict(image_data) for image_data in images_data]

        super().__init__(
            {
                "data_hash": uid,
                "data_title": title,
                "data_type": data_type.to_upper_case_string(),
                "created_at": created_at.strftime(DATETIME_STRING_FORMAT),
                "last_edited_at": last_edited_at.strftime(DATETIME_STRING_FORMAT),
                "width": width,
                "height": height,
                "file_link": file_link,
                "file_size": file_size,
                "file_type": file_type,
                "storage_location": storage_location,
                "frames_per_second": frames_per_second,
                "duration": duration,
                "client_metadata": client_metadata,
                "_querier": None,
                "images_data": parsed_images,
                "signed_url": signed_url,
                "is_optimised_image_group": is_optimised_image_group,
                "_dirty_fields": [],
            }
        )

    @property
    def uid(self) -> str:
        """
        The unique identifier for this data row. Note that the setter does not update the data on the server.
        """
        return self["data_hash"]

    @uid.setter
    def uid(self, value: str) -> None:
        self["data_hash"] = value

    @property
    def title(self) -> str:
        """
        The data title.

        The setter updates the custom client metadata. This queues a request for the backend which will be
        executed on a call of :meth:`.DataRow.upload`.
        """
        return self["data_title"]

    @title.setter
    def title(self, value: str) -> None:
        self["_dirty_fields"].append("data_title")
        self["data_title"] = value

    @property
    def data_type(self) -> DataType:
        return DataType.from_upper_case_string(self["data_type"])

    @data_type.setter
    def data_type(self, value: DataType) -> None:
        """DEPRECATED. Do not this function as it will never update the created_at in the server."""
        self["data_type"] = value.to_upper_case_string()

    @property
    def created_at(self) -> datetime:
        return parser.parse(self["created_at"])

    @created_at.setter
    def created_at(self, value: datetime) -> None:
        """DEPRECATED. Do not this function as it will never update the created_at in the server."""
        self["created_at"] = value.strftime(DATETIME_STRING_FORMAT)

    @property
    def frames_per_second(self) -> Optional[int]:
        """
        If the data type is :meth:`DataType.VIDEO <encord.constants.enums.DataType.VIDEO>` this returns the
        actual number of frames per second for the video. Otherwise, it returns `None` as a frames_per_second
        field is not applicable.
        """
        return self["frames_per_second"]

    @property
    def duration(self) -> Optional[int]:
        """
        If the data type is :meth:`DataType.VIDEO <encord.constants.enums.DataType.VIDEO>` this returns the
        actual duration for the video. Otherwise, it returns `None` as a duration field is not applicable.
        """
        if self.data_type != DataType.VIDEO:
            return None
        return self["duration"]

    @property
    def client_metadata(self) -> Optional[dict]:
        """
        The currently cached client metadata. To cache the client metadata, use the
        :meth:`~encord.orm.dataset.DataRow.refetch_data()` function.

        The setter updates the custom client metadata. This queues a request for the backend which will
        be executed on a call of :meth:`.DataRow.upload`.
        """
        return self["client_metadata"]

    @client_metadata.setter
    def client_metadata(self, new_client_metadata: Dict) -> None:
        self["_dirty_fields"].append("client_metadata")
        self["client_metadata"] = new_client_metadata

    @property
    def width(self) -> Optional[int]:
        """
        An actual width of the data asset. This is `None` for data types of
        :meth:`DataType.IMG_GROUP <encord.constants.enums.DataType.IMG_GROUP>` where
        :meth:`is_image_sequence <encord.data.DataRow.is_image_sequence>` is `False`, because
        each image in this group can have a different dimension. Inspect the
        :meth:`images <encord.data.DataRow.images>` to get the height of individual images.
        """
        return self["width"]

    @property
    def height(self) -> Optional[int]:
        """
        An actual height of the data asset. This is `None` for data types of
        :meth:`DataType.IMG_GROUP <encord.constants.enums.DataType.IMG_GROUP>` where
        :meth:`is_image_sequence <encord.data.DataRow.is_image_sequence>` is `False`, because
        each image in this group can have a different dimension. Inspect the
        :meth:`images <encord.data.DataRow.images>` to get the height of individual images.
        """
        return self["height"]

    @property
    def last_edited_at(self) -> datetime:
        return parser.parse(self["last_edited_at"])

    @property
    def file_link(self) -> Optional[str]:
        """
        A permanent file link of the given data asset. When stored in
        :meth:`StorageLocation.CORD_STORAGE <encord.orm.dataset.StorageLocation.CORD_STORAGE>` this will be the
        internal file path. In private bucket storage location this will be the full path to the file.
        If the data type is `DataType.DICOM` then this returns None as no single file is associated with the
        series.
        """
        return self["file_link"]

    @property
    def signed_url(self) -> Optional[str]:
        """
        The cached signed url of the given data asset. To cache the signed url, use the
        :meth:`~encord.orm.dataset.DataRow.refetch_data()` function.
        """
        return self["signed_url"]

    @property
    def file_size(self) -> int:
        """
        The file size of the given data asset in bytes.
        """
        return self["file_size"]

    @property
    def file_type(self) -> str:
        """
        A MIME file type of the given data asset as a string
        """
        return self["file_type"]

    @property
    def storage_location(self) -> StorageLocation:
        return self["storage_location"]

    @property
    def images_data(self) -> Optional[List[ImageData]]:
        """
        A list of the cached :class:`~encord.orm.dataset.ImageData` objects for the given data asset.
        Fetch the images with appropriate settings in the :meth:`~encord.orm.dataset.DataRow.refetch_data()` function.
        If the data type is not :meth:`DataType.IMG_GROUP <encord.constants.enums.DataType.IMG_GROUP>`
        then this returns None.
        """
        return self["images_data"]

    @property
    def is_optimised_image_group(self) -> Optional[bool]:
        """
        If the data type is an :meth:`DataType.IMG_GROUP <encord.constants.enums.DataType.IMG_GROUP>`,
        returns whether this is a performance optimised image group. Returns `None` for other data types.

        DEPRECATED: This method is deprecated and will be removed in the upcoming library version.
        Please use :meth:`.is_image_sequence` instead
        """
        return self.is_image_sequence

    @property
    def is_image_sequence(self) -> Optional[bool]:
        """
        If the data type is an :meth:`DataType.IMG_GROUP <encord.constants.enums.DataType.IMG_GROUP>`,
        returns whether this is an image sequence. Returns `None` for other data types.

        For more details refer to the
        :ref:`documentation on image sequences <https://docs.encord.com/docs/annotate-supported-data#image-sequences>`
        """
        return self["is_optimised_image_group"]

    def refetch_data(
        self,
        *,
        signed_url: bool = False,
        images_data_fetch_options: Optional[ImagesDataFetchOptions] = None,
        client_metadata: bool = False,
    ):
        """
        Fetches all the most up-to-date data. If any of the parameters are falsy, the current values will not be
        updated.

        Args:
            signed_url: If True, this will fetch a generated signed url of the data asset.
            images_data_fetch_options: If not None, this will fetch the image data of the data asset. You can
                additionally specify what to fetch with the :class:`.ImagesDataFetchOptions` class.
            client_metadata: If True, this will fetch the client metadata of the data asset.
        """
        if self["_querier"] is not None:
            if images_data_fetch_options is not None:
                images_data_fetch_options_dict = dataclasses.asdict(images_data_fetch_options)
            else:
                images_data_fetch_options_dict = None

            payload = {
                "additional_data": {
                    "signed_url": signed_url,
                    "images_data_fetch_options": images_data_fetch_options_dict,
                    "client_metadata": client_metadata,
                }
            }
            res = self["_querier"].basic_getter(DataRow, uid=self.uid, payload=payload)
            self._update_current_class(res)

        else:
            raise EncordException("Could not fetch data. The DataRow is in an invalid state.")


    def save(self) -> None:
        """
        Sync local state to the server, if updates are made. This is a blocking function.

        The newest values from the Encord server will update the current :class:`.DataRow` object.
        """
        if self["_querier"] is not None:
            payload = {}
            for dirty_field in self["_dirty_fields"]:
                payload[dirty_field] = self[dirty_field]
            self["_dirty_fields"] = []

            res = self["_querier"].basic_setter(DataRow, uid=self.uid, payload=payload)
            if res:
                self._compare_upload_payload(res, payload)
                data_row_dict = res["data_row"]
                self._update_current_class(DataRow.from_dict(data_row_dict))
            else:
                raise EncordException(f"Could not upload data for DataRow with uid: {self.uid}")
        else:
            raise EncordException("Could not upload data. The DataRow is in an invalid state.")


    @classmethod
    def from_dict(cls, json_dict: Dict) -> DataRow:
        data_type = DataType.from_upper_case_string(json_dict["data_type"])

        return DataRow(
            uid=json_dict["data_hash"],
            title=json_dict["data_title"],
            # The API server currently returns upper-cased DataType strings.
            data_type=data_type,
            created_at=parser.parse(json_dict["created_at"]),
            client_metadata=json_dict.get("client_metadata"),
            last_edited_at=parser.parse(json_dict["last_edited_at"]),
            width=json_dict["width"],
            height=json_dict["height"],
            file_link=json_dict["file_link"],
            file_size=json_dict["file_size"],
            file_type=json_dict["file_type"],
            storage_location=StorageLocation(json_dict["storage_location"]),
            frames_per_second=json_dict["frames_per_second"],
            duration=json_dict["duration"],
            signed_url=json_dict.get("signed_url"),
            is_optimised_image_group=json_dict.get("is_optimised_image_group"),
            images_data=json_dict.get("images_data"),
        )


    @classmethod
    def from_dict_list(cls, json_list: List) -> List[DataRow]:
        ret: List[DataRow] = list()
        for json_dict in json_list:
            ret.append(cls.from_dict(json_dict))
        return ret


    def _compare_upload_payload(self, upload_res: dict, initial_payload: dict) -> None:
        """
        Compares the upload payload with the response from the server.

        NOTE: this could also compare the new fields, field by field and update the current DataRow.
        """
        updated_fields = set(upload_res["updated_fields"])
        fields_requested_for_update = set(initial_payload.keys())
        if updated_fields != fields_requested_for_update:
            raise EncordException(
                f"The actually updated fields `{updated_fields}` do not match the fields that are requested for update."
            )

    def _update_current_class(self, new_class: DataRow) -> None:
        res_dict = _get_dict_without_none_keys(dict(new_class))
        self.update(res_dict)

refetch_data

Fetches all the most up-to-date data. If any of the parameters are falsy, the current values will not be updated.

refetch_data(*, signed_url=False, images_data_fetch_options=None, client_metadata=False)

Parameters:

  • signed_url (bool) – If True, this will fetch a generated signed url of the data asset.

  • images_data_fetch_options (Optional[ImagesDataFetchOptions]) – If not None, this will fetch the image data of the data asset. You can additionally specify what to fetch with the ImagesDataFetchOptions class.

  • client_metadata (bool) – If True, this will fetch the client metadata of the data asset.

    def refetch_data(
        self,
        *,
        signed_url: bool = False,
        images_data_fetch_options: Optional[ImagesDataFetchOptions] = None,
        client_metadata: bool = False,
    ):
        """
        Fetches all the most up-to-date data. If any of the parameters are falsy, the current values will not be
        updated.

        Args:
            signed_url: If True, this will fetch a generated signed url of the data asset.
            images_data_fetch_options: If not None, this will fetch the image data of the data asset. You can
                additionally specify what to fetch with the :class:`.ImagesDataFetchOptions` class.
            client_metadata: If True, this will fetch the client metadata of the data asset.
        """
        if self["_querier"] is not None:
            if images_data_fetch_options is not None:
                images_data_fetch_options_dict = dataclasses.asdict(images_data_fetch_options)
            else:
                images_data_fetch_options_dict = None

            payload = {
                "additional_data": {
                    "signed_url": signed_url,
                    "images_data_fetch_options": images_data_fetch_options_dict,
                    "client_metadata": client_metadata,
                }
            }
            res = self["_querier"].basic_getter(DataRow, uid=self.uid, payload=payload)
            self._update_current_class(res)

        else:
            raise EncordException("Could not fetch data. The DataRow is in an invalid state.")

save

Sync local state to the server, if updates are made. This is a blocking function.

The newest values from the Encord server will update the current [DataRow] object.

save()

Return type:

None

    def save(self) -> None:
        """
        Sync local state to the server, if updates are made. This is a blocking function.

        The newest values from the Encord server will update the current :class:`.DataRow` object.
        """
        if self["_querier"] is not None:
            payload = {}
            for dirty_field in self["_dirty_fields"]:
                payload[dirty_field] = self[dirty_field]
            self["_dirty_fields"] = []

            res = self["_querier"].basic_setter(DataRow, uid=self.uid, payload=payload)
            if res:
                self._compare_upload_payload(res, payload)
                data_row_dict = res["data_row"]
                self._update_current_class(DataRow.from_dict(data_row_dict))
            else:
                raise EncordException(f"Could not upload data for DataRow with uid: {self.uid}")
        else:
            raise EncordException("Could not upload data. The DataRow is in an invalid state.")

from_dict

classmethod from_dict(json_dict)

Return type:

[DataRow]

    @classmethod
    def from_dict(cls, json_dict: Dict) -> DataRow:
        data_type = DataType.from_upper_case_string(json_dict["data_type"])

        return DataRow(
            uid=json_dict["data_hash"],
            title=json_dict["data_title"],
            # The API server currently returns upper-cased DataType strings.
            data_type=data_type,
            created_at=parser.parse(json_dict["created_at"]),
            client_metadata=json_dict.get("client_metadata"),
            last_edited_at=parser.parse(json_dict["last_edited_at"]),
            width=json_dict["width"],
            height=json_dict["height"],
            file_link=json_dict["file_link"],
            file_size=json_dict["file_size"],
            file_type=json_dict["file_type"],
            storage_location=StorageLocation(json_dict["storage_location"]),
            frames_per_second=json_dict["frames_per_second"],
            duration=json_dict["duration"],
            signed_url=json_dict.get("signed_url"),
            is_optimised_image_group=json_dict.get("is_optimised_image_group"),
            images_data=json_dict.get("images_data"),
        )

from_dict_list

classmethod from_dict_list(json_list)

Return type:

ListDataRow

    @classmethod
    def from_dict_list(cls, json_list: List) -> List[DataRow]:
        ret: List[DataRow] = list()
        for json_dict in json_list:
            ret.append(cls.from_dict(json_dict))
        return ret

DataRows

This is a helper class that forms request for filtered dataset rows. Not intended to be used directly.

class encord.orm.dataset.DataRows(data_rows)
@dataclasses.dataclass(frozen=True)
class DataRows(dict, Formatter):
    """
    This is a helper class that forms request for filtered dataset rows
    Not intended to be used directly
    """

    def __init__(self, data_rows: List[DataRow]):
        super().__init__(
            {
                "data_rows": data_rows,
            }
        )

    @classmethod
    def from_dict(cls, json_dict: Dict) -> DataRow:  # type: ignore[override]
        return DataRow.from_dict(json_dict)

from_dict

classmethod from_dict(json_dict)

Return type

[DataRow]

    @classmethod
    def from_dict(cls, json_dict: Dict) -> DataRow:  # type: ignore[override]
        return DataRow.from_dict(json_dict)

DatasetInfo

This class represents a dataset in the context of listing.

class encord.orm.dataset.DatasetInfo(dataset_hash, user_hash, title, description, type, created_at, last_edited_at, backing_folder_uuid=None)
  • dataset_hash: str
  • user_hash: str
  • title: str
  • description: str
  • type: int
  • created_at: datetime.datetime
  • last_edited_at: datetime.datetime
  • backing_folder_uuid: Optional[uuid.UUID] = None
@dataclasses.dataclass(frozen=True)
class DatasetInfo:
    """
    This class represents a dataset in the context of listing
    """

    dataset_hash: str
    user_hash: str
    title: str
    description: str
    type: int
    created_at: datetime
    last_edited_at: datetime
    backing_folder_uuid: Optional[UUID] = None

Dataset

class encord.orm.dataset.Dataset(title, storage_location, data_rows, dataset_hash, description=None, backing_folder_uuid=None)

property dataset_hash: str

Return Type

str

property title: str

Return Type

str

property description: str

Return Type

str

property storage_location: encord.orm.dataset.StorageLocation

Return Type

StorageLocation

property data_rows: List[encord.orm.dataset.DataRow]

Return Type

ListDataRow

property backing_folder_uuid: Optional[uuid.UUID]

Return Type

Optional[UUID]

class Dataset(dict, Formatter):
    def __init__(
        self,
        title: str,
        storage_location: str,
        data_rows: List[DataRow],
        dataset_hash: str,
        description: Optional[str] = None,
        backing_folder_uuid: Optional[UUID] = None,
    ):
        """
        DEPRECATED - prefer using the :class:`encord.dataset.Dataset` class instead.

        This class has dict-style accessors for backwards compatibility.
        Clients who are using this class for the first time are encouraged to use the property accessors and setters
        instead of the underlying dictionary.
        The mixed use of the `dict` style member functions and the property accessors and setters is discouraged.

        WARNING: Do NOT use the `.data` member of this class. Its usage could corrupt the correctness of the
        datastructure.
        """
        super().__init__(
            {
                "dataset_hash": dataset_hash,
                "title": title,
                "description": description,
                "dataset_type": storage_location,
                "data_rows": data_rows,
                "backing_folder_uuid": backing_folder_uuid,
            }
        )

    @property
    def dataset_hash(self) -> str:
        return self["dataset_hash"]

    @property
    def title(self) -> str:
        return self["title"]

    @title.setter
    def title(self, value: str) -> None:
        self["title"] = value

    @property
    def description(self) -> str:
        return self["description"]

    @description.setter
    def description(self, value: str) -> None:
        self["description"] = value

    @property
    def storage_location(self) -> StorageLocation:
        return StorageLocation.from_str(self["dataset_type"])

    @storage_location.setter
    def storage_location(self, value: StorageLocation) -> None:
        self["dataset_type"] = value.get_str()

    @property
    def data_rows(self) -> List[DataRow]:
        return self["data_rows"]

    @data_rows.setter
    def data_rows(self, value: List[DataRow]) -> None:
        self["data_rows"] = value

    @property
    def backing_folder_uuid(self) -> Optional[UUID]:
        return self["backing_folder_uuid"]

    @backing_folder_uuid.setter
    def backing_folder_uuid(self, value: Optional[UUID]) -> None:
        self["backing_folder_uuid"] = value

    @classmethod
    def from_dict(cls, json_dict: Dict) -> Dataset:
        backing_folder_uuid_value = json_dict.get("backing_folder_uuid")

        return Dataset(
            title=json_dict["title"],
            description=json_dict["description"],
            storage_location=json_dict["dataset_type"],
            dataset_hash=json_dict["dataset_hash"],
            backing_folder_uuid=UUID(backing_folder_uuid_value) if backing_folder_uuid_value else None,
            data_rows=DataRow.from_dict_list(json_dict.get("data_rows", [])),
        )

from_dict

classmethod from_dict(json_dict)

Return type

Dataset

    @classmethod
    def from_dict(cls, json_dict: Dict) -> Dataset:
        backing_folder_uuid_value = json_dict.get("backing_folder_uuid")

        return Dataset(
            title=json_dict["title"],
            description=json_dict["description"],
            storage_location=json_dict["dataset_type"],
            dataset_hash=json_dict["dataset_hash"],
            backing_folder_uuid=UUID(backing_folder_uuid_value) if backing_folder_uuid_value else None,
            data_rows=DataRow.from_dict_list(json_dict.get("data_rows", [])),
        )

DatasetDataInfo

class encord.orm.dataset.DatasetDataInfo(data_hash, title, backing_item_uuid)
  • data_hash: str
  • title: str
  • backing_item_uuid: Optional[uuid.UUID]
@dataclasses.dataclass(frozen=True)
class DatasetDataInfo(Formatter):
    data_hash: str
    title: str
    backing_item_uuid: Optional[UUID]

    @classmethod
    def from_dict(cls, json_dict: Dict) -> DatasetDataInfo:
        backing_item_uuid_value = json_dict.get("backing_item_uuid")
        return DatasetDataInfo(
            json_dict["data_hash"],
            json_dict["title"],
            UUID(backing_item_uuid_value) if backing_item_uuid_value else None,
        )

from_dict

classmethod from_dict(json_dict)

Return type

DatasetDataInfo

    @classmethod
    def from_dict(cls, json_dict: Dict) -> DatasetDataInfo:
        backing_item_uuid_value = json_dict.get("backing_item_uuid")
        return DatasetDataInfo(
            json_dict["data_hash"],
            json_dict["title"],
            UUID(backing_item_uuid_value) if backing_item_uuid_value else None,
        )

AddPrivateDataResponse

class encord.orm.dataset.AddPrivateDataResponse(dataset_data_list)

Response of add_private_data_to_dataset.

dataset_data_list: List[encord.orm.dataset.DatasetDataInfo]

@dataclasses.dataclass(frozen=True)
class AddPrivateDataResponse(Formatter):
    """Response of add_private_data_to_dataset"""

    dataset_data_list: List[DatasetDataInfo]

    @classmethod
    def from_dict(cls, json_dict: Dict) -> AddPrivateDataResponse:
        data_info = json_dict["dataset_data_info"]
        dataset_data_info_list = []
        for mapping in data_info:
            dataset_data_info_list.append(DatasetDataInfo.from_dict(mapping))
        return AddPrivateDataResponse(dataset_data_info_list)

from_dict

classmethod from_dict(json_dict)

Return type

AddPrivateDataResponse

    @classmethod
    def from_dict(cls, json_dict: Dict) -> AddPrivateDataResponse:
        data_info = json_dict["dataset_data_info"]
        dataset_data_info_list = []
        for mapping in data_info:
            dataset_data_info_list.append(DatasetDataInfo.from_dict(mapping))
        return AddPrivateDataResponse(dataset_data_info_list)

DatasetAPIKey

References to encord.orm.dataset.DatasetAPIKey:

class encord.orm.dataset.DatasetAPIKey(dataset_hash, api_key, title, key_hash, scopes)
  • dataset_hash: str
  • api_key: str
  • title: str
  • key_hash: str
  • scopes: List[encord.orm.dataset.DatasetScope]
@dataclasses.dataclass(frozen=True)
class DatasetAPIKey(Formatter):
    dataset_hash: str
    api_key: str
    title: str
    key_hash: str
    scopes: List[DatasetScope]

    @classmethod
    def from_dict(cls, json_dict: Dict) -> DatasetAPIKey:
        if isinstance(json_dict["scopes"], str):
            json_dict["scopes"] = json.loads(json_dict["scopes"])
        scopes = [DatasetScope(scope) for scope in json_dict["scopes"]]
        return DatasetAPIKey(
            json_dict["resource_hash"],
            json_dict["api_key"],
            json_dict["title"],
            json_dict["key_hash"],
            scopes,
        )

from_dict

classmethod from_dict(json_dict)

Return type

DatasetAPIKey

    @classmethod
    def from_dict(cls, json_dict: Dict) -> DatasetAPIKey:
        if isinstance(json_dict["scopes"], str):
            json_dict["scopes"] = json.loads(json_dict["scopes"])
        scopes = [DatasetScope(scope) for scope in json_dict["scopes"]]
        return DatasetAPIKey(
            json_dict["resource_hash"],
            json_dict["api_key"],
            json_dict["title"],
            json_dict["key_hash"],
            scopes,
        )

CreateDatasetResponse

References to encord.orm.dataset.CreateDatasetResponse:

Create a dataset

class encord.orm.dataset.CreateDatasetResponse(title, storage_location, dataset_hash, user_hash, backing_folder_uuid)

property title: str

Return Type

str

property storage_location: encord.orm.dataset.StorageLocation

Return Type

StorageLocation

property dataset_hash: str

Return Type

str

property user_hash: str

Return Type

str

property backing_folder_uuid: Optional[uuid.UUID]

Return Type

Optional[UUID]

class CreateDatasetResponse(dict, Formatter):
    def __init__(
        self,
        title: str,
        storage_location: int,
        dataset_hash: str,
        user_hash: str,
        backing_folder_uuid: Optional[UUID],
    ):
        """
        This class has dict-style accessors for backwards compatibility.
        Clients who are using this class for the first time are encouraged to use the property accessors and setters
        instead of the underlying dictionary.
        The mixed use of the `dict` style member functions and the property accessors and setters is discouraged.

        WARNING: Do NOT use the `.data` member of this class. Its usage could corrupt the correctness of the
        datastructure.
        """

        super().__init__(
            {
                "title": title,
                "type": storage_location,
                "dataset_hash": dataset_hash,
                "user_hash": user_hash,
                "backing_folder_uuid": backing_folder_uuid,
            }
        )

    @property
    def title(self) -> str:
        return self["title"]

    @title.setter
    def title(self, value: str) -> None:
        self["title"] = value

    @property
    def storage_location(self) -> StorageLocation:
        return StorageLocation(self["type"])

    @storage_location.setter
    def storage_location(self, value: StorageLocation) -> None:
        self["type"] = value.value

    @property
    def dataset_hash(self) -> str:
        return self["dataset_hash"]

    @dataset_hash.setter
    def dataset_hash(self, value: str) -> None:
        self["dataset_hash"] = value

    @property
    def user_hash(self) -> str:
        return self["user_hash"]

    @user_hash.setter
    def user_hash(self, value: str) -> None:
        self["user_hash"] = value

    @property
    def backing_folder_uuid(self) -> Optional[UUID]:
        return self["backing_folder_uuid"]

    @backing_folder_uuid.setter
    def backing_folder_uuid(self, value: Optional[UUID]) -> None:
        self["backing_folder_uuid"] = value

@classmethod
    def from_dict(cls, json_dict: Dict) -> CreateDatasetResponse:
        backing_folder_uuid_value = json_dict.get("backing_folder_uuid")
        return CreateDatasetResponse(
            title=json_dict["title"],
            storage_location=json_dict["type"],
            dataset_hash=json_dict["dataset_hash"],
            user_hash=json_dict["user_hash"],
            backing_folder_uuid=UUID(backing_folder_uuid_value) if backing_folder_uuid_value else None,
        )

from_dict(json_dict)

classmethod from_dict(json_dict)

Return type:

CreateDatasetResponse

    @classmethod
    def from_dict(cls, json_dict: Dict) -> CreateDatasetResponse:
        backing_folder_uuid_value = json_dict.get("backing_folder_uuid")
        return CreateDatasetResponse(
            title=json_dict["title"],
            storage_location=json_dict["type"],
            dataset_hash=json_dict["dataset_hash"],
            user_hash=json_dict["user_hash"],
            backing_folder_uuid=UUID(backing_folder_uuid_value) if backing_folder_uuid_value else None,
        )

StorageLocation

An enumeration.

class encord.orm.dataset.StorageLocation(value)

References to encord.orm.dataset.StorageLocation:

Creating a dataset

  • CORD_STORAGE = 0
  • AWS = 1
  • GCP = 2
  • AZURE = 3
  • OTC = 4
  • NEW_STORAGE = -99
    This is a placeholder for a new storage location that is not yet supported by your SDK version. Please update your SDK to the latest version.
class StorageLocation(IntEnum):
    CORD_STORAGE = (0,)
    AWS = (1,)
    GCP = (2,)
    AZURE = 3
    OTC = 4

    NEW_STORAGE = -99
    """
    This is a placeholder for a new storage location that is not yet supported by your SDK version.
    Please update your SDK to the latest version. 
    """

    @staticmethod
    def from_str(string_location: str) -> StorageLocation:
        return STORAGE_LOCATION_BY_STR[string_location]


    def get_str(self) -> str:
        if self == StorageLocation.CORD_STORAGE:
            return "CORD_STORAGE"
        elif self == StorageLocation.AWS:
            return "AWS_S3"
        elif self == StorageLocation.GCP:
            return "GCP_STR"
        elif self == StorageLocation.AZURE:
            return "AZURE_STR"
        elif self == StorageLocation.OTC:
            return "OTC_STR"
        else:
            return "NEW_STORAGE"


    @classmethod
    def _missing_(cls, value: Any) -> StorageLocation:
        return StorageLocation.NEW_STORAGE

from_str

static from_str(string_location)

Return type

StorageLocation

    @staticmethod
    def from_str(string_location: str) -> StorageLocation:
        return STORAGE_LOCATION_BY_STR[string_location]

get_str

get_str()
    def get_str(self) -> str:
        if self == StorageLocation.CORD_STORAGE:
            return "CORD_STORAGE"
        elif self == StorageLocation.AWS:
            return "AWS_S3"
        elif self == StorageLocation.GCP:
            return "GCP_STR"
        elif self == StorageLocation.AZURE:
            return "AZURE_STR"
        elif self == StorageLocation.OTC:
            return "OTC_STR"
        else:
            return "NEW_STORAGE"

DatasetType

For backwards compatibility

encord.orm.dataset.DatasetType

DatasetScope

An enumeration.

class encord.orm.dataset.DatasetScope(value)

References to encord.orm.dataset.DatasetScope:

Creating a dataset API key with specific rights

  • READ = 'dataset.read'
  • WRITE = 'dataset.write'
class DatasetScope(Enum):
    READ = "dataset.read"
    WRITE = "dataset.write"

DatasetData

Video base ORM.

class encord.orm.dataset.DatasetData(dic)

DB_FIELDS: collections.OrderedDict = {'data_hash': <class 'str'>, 'images': <class 'list'>, 'video': <class 'dict'>}

class DatasetData(base_orm.BaseORM):
    """
    Video base ORM.
    """

    DB_FIELDS = OrderedDict(
        [
            ("data_hash", str),
            ("video", dict),
            ("images", list),
        ]
    )

SignedVideoURL

A signed URL object with supporting information.

class encord.orm.dataset.SignedVideoURL(dic)

DB_FIELDS: collections.OrderedDict = {'data_hash': <class 'str'>, 'file_link': <class 'str'>, 'signed_url': <class 'str'>, 'title': <class 'str'>}

class SignedVideoURL(base_orm.BaseORM):
    """A signed URL object with supporting information."""

    DB_FIELDS = OrderedDict([("signed_url", str), ("data_hash", str), ("title", str), ("file_link", str)])

SignedImageURL

A signed URL object with supporting information.

class encord.orm.dataset.SignedImageURL(dic)

DB_FIELDS: collections.OrderedDict = {'data_hash': <class 'str'>, 'file_link': <class 'str'>, 'signed_url': <class 'str'>, 'title': <class 'str'>}

class SignedImageURL(base_orm.BaseORM):
    """A signed URL object with supporting information."""

    DB_FIELDS = OrderedDict([("signed_url", str), ("data_hash", str), ("title", str), ("file_link", str)])

SignedImagesURL

A signed URL object with supporting information.

class encord.orm.dataset.SignedImagesURL(iter_)

BASE_ORM_TYPE

alias of encord.orm.dataset.SignedImageURL

class SignedImagesURL(base_orm.BaseListORM):
    """A signed URL object with supporting information."""

    BASE_ORM_TYPE = SignedImageURL

SignedDicomURL

A signed URL object with supporting information.

class encord.orm.dataset.SignedDicomURL(dic)

DB_FIELDS: collections.OrderedDict = {'data_hash': <class 'str'>, 'file_link': <class 'str'>, 'signed_url': <class 'str'>, 'title': <class 'str'>}

class SignedDicomURL(base_orm.BaseORM):
    """A signed URL object with supporting information."""

    DB_FIELDS = OrderedDict([("signed_url", str), ("data_hash", str), ("title", str), ("file_link", str)])

SignedDicomsURL

A signed URL object with supporting information.

class encord.orm.dataset.SignedDicomsURL(iter_)

BASE_ORM_TYPE: alias of encord.orm.dataset.SignedDicomURL

class SignedDicomsURL(base_orm.BaseListORM):
    """A signed URL object with supporting information."""

    BASE_ORM_TYPE = SignedDicomURL

Video

A video object with supporting information.

class encord.orm.dataset.Video(dic)
  • DB_FIELDS: collections.OrderedDict = {'backing_item_uuid': <class 'uuid.UUID'>, 'data_hash': <class 'str'>, 'file_link': <class 'str'>, 'title': <class 'str'>}
  • NON_UPDATABLE_FIELDS: set = {'backing_item_uuid', 'data_hash'}
class Video(base_orm.BaseORM):
    """A video object with supporting information."""

    DB_FIELDS = OrderedDict([("data_hash", str), ("title", str), ("file_link", str), ("backing_item_uuid", UUID)])

    NON_UPDATABLE_FIELDS = {
        "data_hash",
        "backing_item_uuid",
    }

ImageGroup

An image group object with supporting information.

class encord.orm.dataset.ImageGroup(dic)
  • DB_FIELDS: collections.OrderedDict = {'data_hash': <class 'str'>, 'file_link': <class 'str'>, 'title': <class 'str'>}
  • NON_UPDATABLE_FIELDS: set = {'data_hash'}
class ImageGroup(base_orm.BaseORM):
    """An image group object with supporting information."""

    DB_FIELDS = OrderedDict(
        [
            ("data_hash", str),
            ("title", str),
            ("file_link", str),
        ]
    )

    NON_UPDATABLE_FIELDS = {
        "data_hash",
    }

Image

An image object with supporting information.

class encord.orm.dataset.Image(dic)
  • DB_FIELDS: collections.OrderedDict = {'data_hash': <class 'str'>, 'file_link': <class 'str'>, 'image_hash': <class 'str'>, 'title': <class 'str'>}
  • NON_UPDATABLE_FIELDS: set = {'data_hash'}
class Image(base_orm.BaseORM):
    """An image object with supporting information."""

    DB_FIELDS = OrderedDict(
        [
            ("data_hash", str),
            ("image_hash", str),
            ("title", str),
            ("file_link", str),
        ]
    )

    NON_UPDATABLE_FIELDS = {
        "data_hash",
    }

SingleImage

For native single image upload.

class encord.orm.dataset.SingleImage(dic)

Return type:

boolean - true if successful, otherwise false.

class SingleImage(Image):
    """For native single image upload."""

    success: bool

Images

Uploading multiple images in a batch mode.

class encord.orm.dataset.Images(success)

Return type:

boolean - true if successful, otherwise false.

@dataclasses.dataclass(frozen=True)
class Images:
    """Uploading multiple images in a batch mode."""

    success: bool

DicomSeries

class encord.orm.dataset.DicomSeries(data_hash, title)
  • data_hash: str
  • title: str
@dataclasses.dataclass(frozen=True)
class DicomSeries:
    data_hash: str
    title: str

DicomDeidentifyTask

class encord.orm.dataset.DicomDeidentifyTask(dicom_urls, integration_hash)

Return type:

  • dicom_urls: List[str]
  • integration_hash: str
@dataclasses.dataclass(frozen=True)
class DicomDeidentifyTask:
    dicom_urls: List[str]
    integration_hash: str

ImageGroupOCR

class encord.orm.dataset.ImageGroupOCR(processed_texts)

Return type:

Dict

@dataclasses.dataclass(frozen=True)
class ImageGroupOCR:
    processed_texts: Dict

ReEncodeVideoTaskResult

class encord.orm.dataset.ReEncodeVideoTaskResult(data_hash, signed_url, bucket_path)

Return type:

  • data_hash: str
  • signed_url: Optional[str]
  • bucket_path: str
@dataclasses.dataclass(frozen=True)
class ReEncodeVideoTaskResult:
    data_hash: str
    # The signed url is only present when using StorageLocation.CORD_STORAGE
    signed_url: Optional[str]
    bucket_path: str

ReEncodeVideoTask

A re encode video object with supporting information.

class encord.orm.dataset.ReEncodeVideoTask(status, result=None)

References to encord.orm.dataset.ReEncodeVideoTask:

Check the status of a re-encoding task

Return type:

  • status: str
  • result: Optional[List[encord.orm.dataset.ReEncodeVideoTaskResult]] = None
@dataclasses.dataclass(frozen=True)
class ReEncodeVideoTask(Formatter):
    """A re encode video object with supporting information."""

    status: str
    result: Optional[List[ReEncodeVideoTaskResult]] = None

[docs]    @classmethod
    def from_dict(cls, json_dict: Dict):
        if "result" in json_dict:
            dict_results = json_dict["result"]
            results = [
                ReEncodeVideoTaskResult(result["data_hash"], result.get("signed_url"), result["bucket_path"])
                for result in dict_results
            ]
            return ReEncodeVideoTask(json_dict["status"], results)
        else:
            return ReEncodeVideoTask(json_dict["status"])

from_dict

classmethod from_dict(json_dict)
    @classmethod
    def from_dict(cls, json_dict: Dict):
        if "result" in json_dict:
            dict_results = json_dict["result"]
            results = [
                ReEncodeVideoTaskResult(result["data_hash"], result.get("signed_url"), result["bucket_path"])
                for result in dict_results
            ]
            return ReEncodeVideoTask(json_dict["status"], results)
        else:
            return ReEncodeVideoTask(json_dict["status"])

DatasetAccessSettings

Settings for using the dataset object.

class encord.orm.dataset.DatasetAccessSettings(fetch_client_metadata)

Return type:

boolean - true if successful, otherwise false.

@dataclasses.dataclass
class DatasetAccessSettings:
    """Settings for using the dataset object."""

    fetch_client_metadata: bool
    """Whether client metadata should be retrieved for each `data_row`."""

ImagesDataFetchOptions

class encord.orm.dataset.ImagesDataFetchOptions(fetch_signed_urls=False)

boolean - false.

Whether to fetch signed urls for each individual image. Only set this to true if you need to download the images.

@dataclasses.dataclass
class ImagesDataFetchOptions:
    fetch_signed_urls: bool = False
    """
    Whether to fetch signed urls for each individual image. Only set this to true if you need to download the 
    images.
    """

LongPollingStatus

An enumeration.

class encord.orm.dataset.LongPollingStatus(value)

PENDING = 'PENDING'

Job will automatically start soon (waiting in queue) or already started processing.

DONE = 'DONE'

Job has finished successfully (possibly with errors if ignore_errors=True) If ignore_errors=False was specified in encord.dataset.Dataset.add_private_data_to_dataset_start() , job will only have the status DONE if there were no errors. If ignore_errors=True was specified in encord.dataset.Dataset.add_private_data_to_dataset_start() , job will always show the status DONE once complete and will never show ERROR status if this flag was set to True. There could be errors that were ignored. Information about number of errors and stringified exceptions is available in the units_error_count: int and errors: List[str] attributes.

ERROR = 'ERROR'

Job has completed with errors. This only happens if ignore_errors was set to False. Information about errors is available in the units_error_count: int and errors: List[str] attributes.

class LongPollingStatus(str, Enum):
    PENDING = "PENDING"
    """Job will automatically start soon (waiting in queue) or already started processing."""

    DONE = "DONE"
    """
    Job has finished successfully (possibly with errors if `ignore_errors=True`)
    If `ignore_errors=False` was specified in :meth:`encord.dataset.Dataset.add_private_data_to_dataset_start`
    , job will only have the status `DONE` if there were no errors.
    If `ignore_errors=True` was specified in :meth:`encord.dataset.Dataset.add_private_data_to_dataset_start`
    , job will always show the status `DONE` once complete and will never show `ERROR`
    status if this flag was set to `True`. There could be errors that were ignored.
    Information about number of errors and stringified exceptions is available in the
    `units_error_count: int` and `errors: List[str]` attributes.
    """

    ERROR = "ERROR"
    """
    Job has completed with errors. This can only happen if `ignore_errors` was set to `False`.
    Information about errors is available in the `units_error_count: int` and `errors: List[str]` attributes.
    """

DatasetDataLongPolling

Response of the upload job’s long polling request.

ℹ️

Note

An upload job consists of job units, where job unit could be either a video, image group, DICOM series, or a single image.

status: encord.orm.dataset.LongPollingStatus

Status of the upload job. Documented in detail in LongPollingStatus()

data_hashes_with_titles: List[encord.orm.dataset.DatasetDataInfo]

Information about data which was added to the dataset.

errors: List[str]

Stringified list of exceptions.

units_pending_count: int

Number of upload job units that have pending status.

units_done_count: int

Number of upload job units that have done status.

units_error_count: int

Number of upload job units that have error status.

@dataclasses.dataclass(frozen=True)
class DatasetDataLongPolling(Formatter):
    """
    Response of the upload job's long polling request.

    Note: An upload job consists of job units, where job unit could be
    either a video, image group, dicom series, or a single image.
    """

    status: LongPollingStatus
    """Status of the upload job. Documented in detail in :meth:`LongPollingStatus`"""

    data_hashes_with_titles: List[DatasetDataInfo]
    """Information about data which was added to the dataset."""

    errors: List[str]
    """Stringified list of exceptions."""

    units_pending_count: int
    """Number of upload job units that have pending status."""

    units_done_count: int
    """Number of upload job units that have done status."""

    units_error_count: int
    """Number of upload job units that have error status."""

    @classmethod
    def from_dict(cls, json_dict: Dict) -> DatasetDataLongPolling:
        return DatasetDataLongPolling(
            status=LongPollingStatus(json_dict["status"]),
            data_hashes_with_titles=[DatasetDataInfo.from_dict(x) for x in json_dict["data_hashes_with_titles"]],
            errors=json_dict["errors"],
            units_pending_count=json_dict["units_pending_count"],
            units_done_count=json_dict["units_done_count"],
            units_error_count=json_dict["units_error_count"],
        )

from_dict

classmethod from_dict(json_dict)

Return type

DatasetDataLongPolling

    @classmethod
    def from_dict(cls, json_dict: Dict) -> DatasetDataLongPolling:
        return DatasetDataLongPolling(
            status=LongPollingStatus(json_dict["status"]),
            data_hashes_with_titles=[DatasetDataInfo.from_dict(x) for x in json_dict["data_hashes_with_titles"]],
            errors=json_dict["errors"],
            units_pending_count=json_dict["units_pending_count"],
            units_done_count=json_dict["units_done_count"],
            units_error_count=json_dict["units_error_count"],
        )

DatasetLinkItems

class encord.orm.dataset.DatasetLinkItems
class encord.orm.dataset.DatasetLinkItems

DatasetWithUserRole

This is a helper class denoting the relationship between the current user and a project

class encord.orm.dataset_with_user_role.DatasetWithUserRole(user_role, dataset)
  • user_role: int
  • dataset: dict
from dataclasses import dataclass


@dataclass(frozen=True)
class DatasetWithUserRole:
    """
    This is a helper class denoting the relationship between the current user and a project
    """

    user_role: int
    dataset: dict

Formatter

class encord.orm.formatter.Formatter
from abc import ABC, abstractmethod
from typing import Any, Dict, Type, TypeVar

T = TypeVar("T", bound="Formatter")


class Formatter(ABC):
    @classmethod
    @abstractmethod
    def from_dict(cls: Type[T], json_dict: Dict[str, Any]) -> T:
        pass

from_dict

abstract classmethod from_dict(json_dict)

Return type:

~T

    @classmethod
    @abstractmethod
    def from_dict(cls: Type[T], json_dict: Dict[str, Any]) -> T:
        pass

LabelLog

class encord.orm.label_log.LabelLog(log_hash, user_hash, user_email, annotation_hash, identifier, data_hash, feature_hash, action, label_name, time_taken, created_at, frame)
  • log_hash: str
  • user_hash: str
  • user_email: str
  • annotation_hash: str
  • identifier: str
  • data_hash: str
  • feature_hash: str
  • action: encord.orm.label_log.Action
  • label_name: str
  • time_taken: int
  • created_at: datetime.datetime
  • frame: int
@dataclass(frozen=True)
class LabelLog:
    log_hash: str
    user_hash: str
    user_email: str
    annotation_hash: str  # Legacy value. Replaced by identifier.
    identifier: str
    data_hash: str
    feature_hash: str
    action: Action
    label_name: str
    time_taken: int
    created_at: datetime
    frame: int

Action

An enumeration.

class encord.orm.label_log.Action(value)
  • ADD = 0
  • EDIT = 1
  • DELETE = 2
  • START = 3
  • END = 4
  • MARK_AS_NOT_LABELLED = 5
  • MARK_AS_IN_PROGRESS = 6
  • MARK_AS_LABELLED = 7
  • MARK_AS_REVIEW_REQUIRED = 8
  • MARK_AS_REVIEWED = 9
  • MARK_AS_REVIEWED_TWICE = 10
  • SUBMIT_TASK = 11
  • APPROVE_LABEL = 12
  • REJECT_LABEL = 13
  • CLICK_SAVE = 14
  • CLICK_UNDO = 15
  • CLICK_REDO = 16
  • CLICK_BULK = 17
  • CLICK_ZOOM = 19
  • CLICK_BRIGHTNESS = 20
  • CLICK_HOTKEYS = 21
  • CLICK_SETTINGS = 22
  • ADD_ATTRIBUTE = 23
  • EDIT_ATTRIBUTE = 24
  • DELETE_ATTRIBUTE = 25
  • APPROVE_NESTED_ATTRIBUTE = 26
  • REJECT_NESTED_ATTRIBUTE = 27
  • SUBMIT_LABEL = 28
  • SUBMIT_NESTED_ATTRIBUTE = 29
  • BUFFERING_OVERLAY_SHOWN = 30
  • BITRATE_WARNING_SHOWN = 31
  • SEEKING_OVERLAY_SHOWN = 32
class Action(IntEnum):
    ADD = 0
    EDIT = 1
    DELETE = 2
    START = 3
    END = 4
    MARK_AS_NOT_LABELLED = 5
    MARK_AS_IN_PROGRESS = 6
    MARK_AS_LABELLED = 7
    MARK_AS_REVIEW_REQUIRED = 8
    MARK_AS_REVIEWED = 9
    MARK_AS_REVIEWED_TWICE = 10
    SUBMIT_TASK = 11
    APPROVE_LABEL = 12
    REJECT_LABEL = 13
    CLICK_SAVE = 14
    CLICK_UNDO = 15
    CLICK_REDO = 16
    CLICK_BULK = 17
    CLICK_ZOOM = 19
    CLICK_BRIGHTNESS = 20
    CLICK_HOTKEYS = 21
    CLICK_SETTINGS = 22
    ADD_ATTRIBUTE = 23
    EDIT_ATTRIBUTE = 24
    DELETE_ATTRIBUTE = 25
    APPROVE_NESTED_ATTRIBUTE = 26
    REJECT_NESTED_ATTRIBUTE = 27
    SUBMIT_LABEL = 28
    SUBMIT_NESTED_ATTRIBUTE = 29
    BUFFERING_OVERLAY_SHOWN = 30
    BITRATE_WARNING_SHOWN = 31
    SEEKING_OVERLAY_SHOWN = 32

LabelLogParams

class encord.orm.label_log.LabelLogParams(**data)
  • user_hash: Optional[str]
  • data_hash: Optional[str]
  • start_timestamp: Optional[int]
  • end_timestamp: Optional[int]
  • user_email: Optional[str]
  • include_user_email_and_interface_key: bool
class LabelLogParams(BaseDTO):
    user_hash: Optional[str]
    data_hash: Optional[str]
    start_timestamp: Optional[int]
    end_timestamp: Optional[int]
    user_email: Optional[str]
    # Flag for backwards compatibility
    include_user_email_and_interface_key: bool = True

LabelRow

class encord.orm.label_row.LabelRow(dic)

A label row contains a data unit or a collection of data units and associated labels, and is specific to a data asset with type video or img_group:

A label row with a data asset of type video contains a single data unit.

A label row with a data asset of type img_group contains any number of data units.

The label row ORM is as follows:

  • label_hash (uid) is the unique identifier of the label row

  • dataset_hash (uid) is the unique identifier of the dataset which contains the particular video or image group

  • dataset_title is the title of the dataset which contains the particular video or image group

  • data_title is the title of the video or image group

  • data_type either video or img_group depending on data type

  • data_units a dictionary with (key: data hash, value: data unit) pairs.

  • object_answers is a dictionary with (key: object hash, value: object answer) pairs.

  • classification_answers is a dictionary with (key: classification hash, value: classification answer) pairs.

  • object_actions is a dictionary with (key: <object_hash>, value: object action) pairs.

  • label_status is a string indicating label status. It can take the values enumerated in encord.orm.label_row.LabelStatus.

    ℹ️

    Note

    This does not reflect the status shown in the Projects -> Labels section on the Encord platform.

A data unit, mentioned for the dictionary entry data_units above, has in the form:

label_row = {  # The label row
    # ...
    "data_units": {
        "<data_hash>": {
            "data_hash": "<data_hash>",  # A data_hash (uid) string
            "data_title": "A data title",
            "data_link": "<data_link>",  # Signed URL that expiring after 7 days
            "data_type": "<data_type>",  # (video/mp4, image/jpeg, etc.)
            "data_fps": 24.95,           # For video, the frame rate
            "data_sequence": "0",        # Defines order of data units
            "width": 640,                # The width of the content
            "height": 610,               # The height of the content
            "labels": {
                # ...
            }
        },
        # ...,
    }
}

A data unit can have any number of vector labels (for example: bounding box, polygon, keypoint) and classifications.

Objects and classifications

A data unit can have any number of vector labels (e.g., bounding boxes, polygons, polylines, keypoints) and classifications. Each frame-level object and classification has unique identifiers ‘objectHash’ and ‘classificationHash’. Each frame-level entity has a unique feature identifier ‘featureHash’, defined in the editor ontology.

The object and classification answers are contained separately from the individual data units to preserve space for video, sequential images, DICOM, etc.

The objects and classifications answer dictionaries contain classification ‘answers’ (i.e. attributes that describe the object or classification). This is to avoid storing the information at every frame in the blurb, of particular importance for videos.

A labels dictionary for video is in the form:

label_row["data_units"]["<data_hash>"]["labels"] = {
    "<frame_number>": {
        "objects": [
            # { object 1 },
            # { object 2 },
            # ...
        ],
        "classifications": [
            # { classification 1 },
            # { classification 2 },
            # ...
        ],
    }
}

A labels dictionary for an img_group data unit is in the form:

label_row["data_units"]["<data_hash>"]["labels"] = {
    "objects": [
        # { object 1 },
        # { object 2 },
        # ...
    ],
    "classifications": [
        # { classification 1 },
        # { classification 2 },
        # ...
    ],
}

The object answers dictionary is in the form:

label_row["object_answers"] = {
    "<object_hash>": {
        "objectHash": "<object_hash>",
        "classifications": [
            # {answer 1},
            # {answer 2},
            # ...
        ]
    },
    # ...
}

The classification answers dictionary is in the form:

label_row["classification_answers"] = {
    "<classification_hash>": {
        "classificationHash": "<classification_hash>",
        "classifications": [
            # {answer 1},
            # {answer 2},
            # ...
        ],
    },
    # ...
}

The object actions dictionary is in the form:

label_row["object_actions"] = {
    "<object_hash>": {
        "objectHash": "<object_hash>",
        "actions": [
            # {answer 1},
            # {answer 2},
            # ...
        ],
    },
    # ...
}
  • DB_FIELDS: collections.OrderedDict = {'annotation_task_status': <class 'str'>, 'classification_answers': <class 'dict'>, 'created_at': <class 'str'>, 'data_hash': <class 'str'>, 'data_title': <class 'str'>, 'data_type': <class 'str'>, 'data_units': <class 'dict'>, 'dataset_hash': <class 'str'>, 'dataset_title': <class 'str'>, 'label_hash': <class 'str'>, 'label_status': <class 'str'>, 'last_edited_at': <class 'str'>, 'object_actions': <class 'dict'>, 'object_answers': <class 'dict'>}
  • NON_UPDATABLE_FIELDS: set = {'label_hash'}
class LabelRow(base_orm.BaseORM):
    """
    A label row contains a data unit or a collection of data units and associated
    labels, and is specific to a data asset with type ``video`` or ``img_group``:

    * A label row with a data asset of type video contains a single data unit.
    * A label row with a data asset of type img_group contains any number of data units.

    The label row ORM is as follows:

    * ``label_hash`` (uid) is the unique identifier of the label row
    * ``dataset_hash`` (uid) is the unique identifier of the dataset which contains the
      particular video or image group
    * ``dataset_title`` is the title of the dataset which contains the particular video
      or image group
    * ``data_title`` is the title of the video or image group
    * ``data_type`` either ``video`` or ``img_group`` depending on data type
    * ``data_units`` a dictionary with (key: data hash, value: data unit) pairs.
    * ``object_answers`` is a dictionary with (key: object hash, value: object answer)
      pairs.
    * ``classification_answers`` is a dictionary with (key: classification hash, value:
      classification answer) pairs.
    * ``object_actions`` is a dictionary with (key: ``<object_hash>``, value: object
      action) pairs.
    * ``label_status`` is a string indicating label status. It can take the values
      enumerated in :class:`encord.orm.label_row.LabelStatus`. *Note* that this does
      *not* reflect thes status shown in the Projects->Labels section on the Encord platform.

    A data unit, mentioned for the dictionary entry ``data_units`` above, has in the
    form::

        label_row = {  # The label row
            # ...
            "data_units": {
                "<data_hash>": {
                    "data_hash": "<data_hash>",  # A data_hash (uid) string
                    "data_title": "A data title",
                    "data_link": "<data_link>",  # Signed URL that expiring after 7 days
                    "data_type": "<data_type>",  # (video/mp4, image/jpeg, etc.)
                    "data_fps": 24.95,           # For video, the frame rate
                    "data_sequence": "0",        # Defines order of data units
                    "width": 640,                # The width of the content
                    "height": 610,               # The height of the content
                    "labels": {
                        # ...
                    }
                },
                # ...,
            }
        }

    A data unit can have any number of vector labels (e.g. bounding box, polygon, keypoint) and classifications.

    **Objects and classifications**

    A data unit can have any number of vector labels (e.g., bounding boxes, polygons,
    polylines, keypoints) and classifications.
    Each frame-level object and classification has unique identifiers 'objectHash' and
    'classificationHash'. Each frame-level entity has a unique feature identifier
    'featureHash', defined in the editor ontology.

    The object and classification answers are contained separately from the individual
    data units to preserve space for video, sequential images, DICOM, etc.

    The objects and classifications answer dictionaries contain classification 'answers'
    (i.e. attributes that describe the object or classification). This is to avoid
    storing the information at every frame in the blurb, of particular importance for
    videos.

    A labels dictionary for video is in the form::

        label_row["data_units"]["<data_hash>"]["labels"] = {
            "<frame_number>": {
                "objects": [
                    # { object 1 },
                    # { object 2 },
                    # ...
                ],
                "classifications": [
                    # { classification 1 },
                    # { classification 2 },
                    # ...
                ],
            }
        }

    A labels dictionary for an img_group data unit is in the form::

        label_row["data_units"]["<data_hash>"]["labels"] = {
            "objects": [
                # { object 1 },
                # { object 2 },
                # ...
            ],
            "classifications": [
                # { classification 1 },
                # { classification 2 },
                # ...
            ],
        }

    The object answers dictionary is in the form::

        label_row["object_answers"] = {
            "<object_hash>": {
                "objectHash": "<object_hash>",
                "classifications": [
                    # {answer 1},
                    # {answer 2},
                    # ...
                ]
            },
            # ...
        }

    The classification answers dictionary is in the form::

        label_row["classification_answers"] = {
            "<classification_hash>": {
                "classificationHash": "<classification_hash>",
                "classifications": [
                    # {answer 1},
                    # {answer 2},
                    # ...
                ],
            },
            # ...
        }

    The object actions dictionary is in the form::

        label_row["object_actions"] = {
            "<object_hash>": {
                "objectHash": "<object_hash>",
                "actions": [
                    # {answer 1},
                    # {answer 2},
                    # ...
                ],
            },
            # ...
        }

    """

    DB_FIELDS = OrderedDict(
        [
            ("label_hash", str),
            ("created_at", str),
            ("last_edited_at", str),
            ("dataset_hash", str),
            ("dataset_title", str),
            ("data_title", str),
            ("data_hash", str),
            ("data_type", str),
            ("data_units", dict),
            ("object_answers", dict),
            ("classification_answers", dict),
            ("object_actions", dict),
            ("label_status", str),
            ("annotation_task_status", str),
        ]
    )

    NON_UPDATABLE_FIELDS = {
        "label_hash",
    }

Review

class encord.orm.label_row.Review
class Review:
    pass

AnnotationTaskStatus

An enumeration.

class encord.orm.label_row.AnnotationTaskStatus(value)
  • QUEUED = 'QUEUED'
  • ASSIGNED = 'ASSIGNED'
  • IN_REVIEW = 'IN_REVIEW'
  • RETURNED = 'RETURNED'
  • COMPLETED = 'COMPLETED'
class AnnotationTaskStatus(Enum):
    QUEUED = "QUEUED"
    ASSIGNED = "ASSIGNED"
    IN_REVIEW = "IN_REVIEW"
    RETURNED = "RETURNED"
    COMPLETED = "COMPLETED"

ShadowDataState

Specifies the kind of data to fetch when working with a BenchmarkQa project.

class encord.orm.label_row.ShadowDataState(value)

ALL_DATA = 'ALL_DATA'

Fetch all the label rows

SHADOW_DATA = 'SHADOW_DATA'

The annotator’s view of the benchmark

Type

Only fetch the label rows that were submitted against “shadow data”

NOT_SHADOW_DATA = 'NOT_SHADOW_DATA'

Only fetch the label rows for “production” data

class ShadowDataState(Enum):
    """Specifies the kind of data to fetch when working with a BenchmarkQa project"""

    ALL_DATA = "ALL_DATA"
    """ Fetch all the label rows """
    SHADOW_DATA = "SHADOW_DATA"
    """ Only fetch the label rows that were submitted against "shadow data": the annotator's view of the benchmark """
    NOT_SHADOW_DATA = "NOT_SHADOW_DATA"
    """ Only fetch the label rows for "production" data """

LabelStatus

An enumeration.

class encord.orm.label_row.LabelStatus(value)
  • NOT_LABELLED = 'NOT_LABELLED'
  • LABEL_IN_PROGRESS = 'LABEL_IN_PROGRESS'
  • LABELLED = 'LABELLED'
  • REVIEW_IN_PROGRESS = 'REVIEW_IN_PROGRESS'
  • REVIEWED = 'REVIEWED'
  • REVIEWED_TWICE = 'REVIEWED_TWICE'
  • MISSINGLABEL_STATUS = '_MISSING_LABEL_STATUS'
    This value is displayed if the Encord platform has a new label status and your SDK version does not understand it yet. Update your SDK to the latest version to resolve the issue.
class LabelStatus(Enum):
    NOT_LABELLED = "NOT_LABELLED"
    LABEL_IN_PROGRESS = "LABEL_IN_PROGRESS"
    LABELLED = "LABELLED"
    REVIEW_IN_PROGRESS = "REVIEW_IN_PROGRESS"
    REVIEWED = "REVIEWED"
    REVIEWED_TWICE = "REVIEWED_TWICE"

    MISSING_LABEL_STATUS = "_MISSING_LABEL_STATUS_"
    """
    This value will be displayed if the Encord platform has a new label status and your SDK version does not understand
    it yet. Please update your SDK to the latest version.
    """

    @classmethod
    def _missing_(cls, value: Any) -> LabelStatus:
        return cls.MISSING_LABEL_STATUS

WorkflowGraphNode

class encord.orm.label_row.WorkflowGraphNode(uuid, title)
  • uuid: str
  • title: str
@dataclass(frozen=True)
class WorkflowGraphNode:
    uuid: str
    title: str

    @classmethod
    def from_optional_dict(cls, json_dict: Optional[Dict]) -> Optional[WorkflowGraphNode]:
        if json_dict is None:
            return None
        return WorkflowGraphNode(uuid=json_dict["uuid"], title=json_dict["title"])

from_optional_dict

classmethod from_optional_dict(json_dict)

Return type:

Optional[WorkflowGraphNode]

    @classmethod
    def from_optional_dict(cls, json_dict: Optional[Dict]) -> Optional[WorkflowGraphNode]:
        if json_dict is None:
            return None
        return WorkflowGraphNode(uuid=json_dict["uuid"], title=json_dict["title"])

LabelRowMetadata

Contains helpful information about a label row.

class encord.orm.label_row.LabelRowMetadata(label_hash, created_at, last_edited_at, data_hash, dataset_hash, dataset_title, data_title, data_type, data_link, label_status, annotation_task_status, workflow_graph_node, is_shadow_data, number_of_frames, duration, frames_per_second, height, width)
  • label_hash: Optional[str] : Only present if the label row is initiated
  • created_at: Optional[datetime.datetime] : Only present if the label row is initiated
  • last_edited_at: Optional[datetime.datetime] : Only present if the label row is initiated
  • data_hash: str
  • dataset_hash: str
  • dataset_title: str
  • data_title: str
  • data_type: str
  • data_link: Optional[str] : Can be None for label rows of image groups or DICOM series.
  • label_status: encord.orm.label_row.LabelStatus : Can be None for TMS2 projects
  • annotation_task_status: OptionalAnnotationTaskStatus : Only available for TMS2 project
  • workflow_graph_node: OptionalWorkflowGraphNode
  • is_shadow_data: bool
  • number_of_frames: int
  • duration: Optional[float] : Only available for the VIDEO data_type
  • frames_per_second: Optional[int] : Only available for the VIDEO data_type
  • height: Optional[int]
  • width: Optional[int]
@dataclass(frozen=True)
class LabelRowMetadata(Formatter):
    """
    Contains helpful information about a label row.
    """

    label_hash: Optional[str]
    """Only present if the label row is initiated"""
    created_at: Optional[datetime.datetime]
    """Only present if the label row is initiated"""
    last_edited_at: Optional[datetime.datetime]
    """Only present if the label row is initiated"""

    data_hash: str
    dataset_hash: str
    dataset_title: str
    data_title: str
    data_type: str
    data_link: Optional[str]
    """Can be `None` for label rows of image groups or DICOM series."""
    label_status: LabelStatus
    """Can be `None` for TMS2 projects"""
    annotation_task_status: Optional[AnnotationTaskStatus]
    """Only available for TMS2 project"""
    workflow_graph_node: Optional[WorkflowGraphNode]
    is_shadow_data: bool
    number_of_frames: int
    duration: Optional[float]
    """Only available for the VIDEO data_type"""
    frames_per_second: Optional[int]
    """Only available for the VIDEO data_type"""
    height: Optional[int]
    width: Optional[int]

[docs]    @classmethod
    def from_dict(cls, json_dict: Dict) -> LabelRowMetadata:
        created_at = json_dict.get("created_at", None)
        if created_at is not None:
            created_at = datetime.datetime.fromisoformat(created_at)
        last_edited_at = json_dict.get("last_edited_at", None)
        if last_edited_at is not None:
            last_edited_at = datetime.datetime.fromisoformat(last_edited_at)

        annotation_task_status = (
            AnnotationTaskStatus(json_dict["annotation_task_status"])
            if json_dict["annotation_task_status"] is not None
            else None
        )

        return LabelRowMetadata(
            label_hash=json_dict.get("label_hash", None),
            created_at=created_at,
            last_edited_at=last_edited_at,
            data_hash=json_dict["data_hash"],
            dataset_hash=json_dict["dataset_hash"],
            dataset_title=json_dict["dataset_title"],
            data_title=json_dict["data_title"],
            data_type=json_dict["data_type"],
            data_link=json_dict["data_link"],
            label_status=LabelStatus(json_dict["label_status"]),
            annotation_task_status=annotation_task_status,
            workflow_graph_node=WorkflowGraphNode.from_optional_dict(json_dict.get("workflow_graph_node")),
            is_shadow_data=json_dict.get("is_shadow_data", False),
            number_of_frames=json_dict["number_of_frames"],
            duration=json_dict.get("duration", None),
            frames_per_second=json_dict.get("frames_per_second", None),
            height=json_dict.get("height"),
            width=json_dict.get("width"),
        )


[docs]    @classmethod
    def from_list(cls, json_list: list) -> List[LabelRowMetadata]:
        ret = []
        for i in json_list:
            ret.append(cls.from_dict(i))
        return ret


[docs]    def to_dict(self) -> dict:
        """
        Returns:
            The dict equivalent of LabelRowMetadata.
        """

        def transform(value: Any):
            if isinstance(value, Enum):
                return value.value
            elif isinstance(value, datetime.datetime):
                return value.isoformat()
            return value

        return {k: transform(v) for k, v in asdict(self).items()}

from_dict

classmethod from_dict(json_dict)

Return type:

LabelRowMetadata

    @classmethod
    def from_dict(cls, json_dict: Dict) -> LabelRowMetadata:
        created_at = json_dict.get("created_at", None)
        if created_at is not None:
            created_at = datetime.datetime.fromisoformat(created_at)
        last_edited_at = json_dict.get("last_edited_at", None)
        if last_edited_at is not None:
            last_edited_at = datetime.datetime.fromisoformat(last_edited_at)

        annotation_task_status = (
            AnnotationTaskStatus(json_dict["annotation_task_status"])
            if json_dict["annotation_task_status"] is not None
            else None
        )

        return LabelRowMetadata(
            label_hash=json_dict.get("label_hash", None),
            created_at=created_at,
            last_edited_at=last_edited_at,
            data_hash=json_dict["data_hash"],
            dataset_hash=json_dict["dataset_hash"],
            dataset_title=json_dict["dataset_title"],
            data_title=json_dict["data_title"],
            data_type=json_dict["data_type"],
            data_link=json_dict["data_link"],
            label_status=LabelStatus(json_dict["label_status"]),
            annotation_task_status=annotation_task_status,
            workflow_graph_node=WorkflowGraphNode.from_optional_dict(json_dict.get("workflow_graph_node")),
            is_shadow_data=json_dict.get("is_shadow_data", False),
            number_of_frames=json_dict["number_of_frames"],
            duration=json_dict.get("duration", None),
            frames_per_second=json_dict.get("frames_per_second", None),
            height=json_dict.get("height"),
            width=json_dict.get("width"),
        )

from_list

classmethod from_list(json_list)

Return type:

List[LabelRowMetadata]

    @classmethod
    def from_list(cls, json_list: list) -> List[LabelRowMetadata]:
        ret = []
        for i in json_list:
            ret.append(cls.from_dict(i))
        return ret

to_dict

to_dict()

Return type:

dict

Returns:

The dict equivalent of LabelRowMetadata.

    def to_dict(self) -> dict:
        """
        Returns:
            The dict equivalent of LabelRowMetadata.
        """

        def transform(value: Any):
            if isinstance(value, Enum):
                return value.value
            elif isinstance(value, datetime.datetime):
                return value.isoformat()
            return value

        return {k: transform(v) for k, v in asdict(self).items()}

LabelingAlgorithm

Labeling algorithm base ORM.

class encord.orm.labeling_algorithm.LabelingAlgorithm(dic)

ORM: algorithm_name, algorithm_params

DB_FIELDS: collections.OrderedDict = {'algorithm_name': <class 'str'>, 'algorithm_parameters': <class 'dict'>}

class LabelingAlgorithm(base_orm.BaseORM):
    """
    Labeling algorithm base ORM.

    ORM:

    algorithm_name,
    algorithm_params

    """

    DB_FIELDS = OrderedDict(
        [
            ("algorithm_name", str),
            ("algorithm_parameters", dict),  # Algorithm params
        ]
    )

ObjectInterpolationParams

Labeling algorithm parameters for interpolation algorithm.

class encord.orm.labeling_algorithm.ObjectInterpolationParams(dic)

ORM: key_frames, objects_to_interpolate

DB_FIELDS: collections.OrderedDict = {'key_frames': <class 'dict'>, 'objects_to_interpolate': <class 'list'>}

class ObjectInterpolationParams(base_orm.BaseORM):
    """
    Labeling algorithm parameters for interpolation algorithm

    ORM:

    key_frames,
    objects_to_interpolate

    """

    DB_FIELDS = OrderedDict(
        [
            ("key_frames", dict),
            ("objects_to_interpolate", list),
        ]
    )

BoundingBoxFittingParams

Labeling algorithm parameters for bounding box fitting algorithm.

class encord.orm.labeling_algorithm.BoundingBoxFittingParams(dic)

ORM: labels, video

DB_FIELDS: collections.OrderedDict = {'labels': <class 'dict'>, 'video': <class 'dict'>}

class BoundingBoxFittingParams(base_orm.BaseORM):
    """
    Labeling algorithm parameters for bounding box fitting algorithm

    ORM:

    labels,
    video

    """

    DB_FIELDS = OrderedDict(
        [
            ("labels", dict),
            ("video", dict),
        ]
    )

ModelOperations

class encord.orm.model.ModelOperations(value)

An enumeration.

  • INFERENCE = 0
  • TRAIN = 1
  • CREATE = 2
class ModelOperations(Enum):
    INFERENCE = 0
    TRAIN = 1
    CREATE = 2

Model

Model base ORM.

class encord.orm.model.Model(dic)

ORM: model_operation, model_parameters,

DB_FIELDS: collections.OrderedDict = {'model_operation': <class 'int'>, 'model_parameters': <class 'dict'>}

class Model(base_orm.BaseORM):
    """
    Model base ORM.

    ORM:

    model_operation,
    model_parameters,

    """

    DB_FIELDS = OrderedDict([("model_operation", int), ("model_parameters", dict)])

ModelConfiguration

class encord.orm.model.ModelConfiguration(model_uid, title, description, feature_node_hashes, model, model_iteration_uids)
  • model_uid: str
  • title: str
  • description: str
  • feature_node_hashes: List[str] : The corresponding feature node hashes of the ontology object
  • model: encord.constants.model.AutomationModels
  • model_iteration_uids: List[str] : All the UIDs of individual model training instances
@dataclass
class ModelConfiguration(Formatter):
    model_uid: str
    title: str
    description: str
    feature_node_hashes: List[str]
    """The corresponding feature node hashes of the ontology object"""
    model: AutomationModels
    model_iteration_uids: List[str]
    """All the UIDs of individual model training instances"""

    @classmethod
    def from_dict(cls, json_dict: dict):
        return ModelConfiguration(
            model_uid=json_dict["model_uid"],
            title=json_dict["title"],
            description=json_dict["description"],
            feature_node_hashes=cls._get_feature_node_hashes(json_dict["feature_node_hashes"]),
            model=cls._get_automation_model(json_dict["model"]),
            model_iteration_uids=json_dict["model_iteration_uids"],
        )


    @staticmethod
    def _get_feature_node_hashes(features: dict) -> List[str]:
        return list(features.keys())

    @staticmethod
    def _get_automation_model(automation_model_str: str) -> AutomationModels:
        try:
            return AutomationModels(automation_model_str)
        except ValueError as e:
            raise EncordException(
                "A model was returned which was not recognised. Please upgrade your SDK "
                f"to the latest version or contact support at {ENCORD_CONTACT_SUPPORT_EMAIL}."
            ) from e

from_dict

classmethod from_dict(json_dict)
    @classmethod
    def from_dict(cls, json_dict: dict):
        return ModelConfiguration(
            model_uid=json_dict["model_uid"],
            title=json_dict["title"],
            description=json_dict["description"],
            feature_node_hashes=cls._get_feature_node_hashes(json_dict["feature_node_hashes"]),
            model=cls._get_automation_model(json_dict["model"]),
            model_iteration_uids=json_dict["model_iteration_uids"],
        )

ModelTrainingLabelMetadata

class encord.orm.model.ModelTrainingLabelMetadata(label_uid, data_uid, data_link)
  • label_uid: str
  • data_uid: str
  • data_link: str
@dataclass
class ModelTrainingLabelMetadata:
    label_uid: str
    data_uid: str
    data_link: str

    @staticmethod
    def from_dict(json_dict: dict) -> "ModelTrainingLabelMetadata":
        return ModelTrainingLabelMetadata(
            label_uid=json_dict["label_uid"],
            data_uid=json_dict["data_uid"],
            data_link=json_dict["data_link"],
        )


    @classmethod
    def from_list(cls, json_list: list) -> List["ModelTrainingLabelMetadata"]:
        return [cls.from_dict(item) for item in json_list]

from_dict

static from_dict(json_dict)

Return type:

ModelTrainingLabelMetadata

    @staticmethod
    def from_dict(json_dict: dict) -> "ModelTrainingLabelMetadata":
        return ModelTrainingLabelMetadata(
            label_uid=json_dict["label_uid"],
            data_uid=json_dict["data_uid"],
            data_link=json_dict["data_link"],
        )

from_list

classmethod from_list(json_list)

Return type:

List[ModelTrainingLabelMetadata]

    @classmethod
    def from_list(cls, json_list: list) -> List["ModelTrainingLabelMetadata"]:
        return [cls.from_dict(item) for item in json_list]

ModelTrainingLabel

class encord.orm.model.ModelTrainingLabel(label_metadata_list, feature_uids)
  • label_metadata_list: List[encord.orm.model.ModelTrainingLabelMetadata]
  • feature_uids: List[str]
@dataclass
class ModelTrainingLabel:
    label_metadata_list: List[ModelTrainingLabelMetadata]
    feature_uids: List[str]

    @staticmethod
    def from_dict(json_dict: dict) -> "ModelTrainingLabel":
        return ModelTrainingLabel(
            label_metadata_list=ModelTrainingLabelMetadata.from_list(json_dict["label_metadata_list"]),
            feature_uids=json_dict["feature_uids"],
        )

from_dict

static from_dict(json_dict)

Return type:

ModelTrainingLabel

    @staticmethod
    def from_dict(json_dict: dict) -> "ModelTrainingLabel":
        return ModelTrainingLabel(
            label_metadata_list=ModelTrainingLabelMetadata.from_list(json_dict["label_metadata_list"]),
            feature_uids=json_dict["feature_uids"],
        )

TrainingMetadata

class encord.orm.model.TrainingMetadata(model_iteration_uid, created_at=None, training_final_loss=None, model_training_labels=None)
  • model_iteration_uid: str
  • created_at: Optional[datetime.datetime] = None
  • training_final_loss: Optional[float] = None
  • model_training_labels: Optional[encord.orm.model.ModelTrainingLabel] = None
@dataclass
class TrainingMetadata(Formatter):
    model_iteration_uid: str
    created_at: Optional[datetime] = None
    training_final_loss: Optional[float] = None
    model_training_labels: Optional[ModelTrainingLabel] = None

    @classmethod
    def from_dict(cls, json_dict: dict):
        return TrainingMetadata(
            model_iteration_uid=json_dict["model_iteration_uid"],
            created_at=cls.get_created_at(json_dict),
            training_final_loss=json_dict["training_final_loss"],
            model_training_labels=cls.get_model_training_labels(json_dict),
        )


    @staticmethod
    def get_created_at(json_dict: dict) -> Optional[datetime]:
        created_at = json_dict["created_at"]
        if created_at is None:
            return None

        return parse(created_at)


    @staticmethod
    def get_model_training_labels(json_dict: dict) -> Optional[ModelTrainingLabel]:
        model_training_labels = json_dict["model_training_labels"]
        if model_training_labels is None:
            return None

        return ModelTrainingLabel.from_dict(model_training_labels)

from_dict

classmethod from_dict(json_dict)
    @classmethod
    def from_dict(cls, json_dict: dict):
        return TrainingMetadata(
            model_iteration_uid=json_dict["model_iteration_uid"],
            created_at=cls.get_created_at(json_dict),
            training_final_loss=json_dict["training_final_loss"],
            model_training_labels=cls.get_model_training_labels(json_dict),
        )

get_created_at

static get_created_at(json_dict)

Return type:

Optional[datetime]

    @staticmethod
    def get_created_at(json_dict: dict) -> Optional[datetime]:
        created_at = json_dict["created_at"]
        if created_at is None:
            return None

        return parse(created_at)

get_model_training_labels

static get_model_training_labels(json_dict)

Return type:

Optional[ModelTrainingLabel]

    @staticmethod
    def get_model_training_labels(json_dict: dict) -> Optional[ModelTrainingLabel]:
        model_training_labels = json_dict["model_training_labels"]
        if model_training_labels is None:
            return None

        return ModelTrainingLabel.from_dict(model_training_labels)

ModelRow

A model row contains a set of features and a model (resnet18, resnet34, resnet50, resnet101, resnet152, vgg16, vgg19, faster_rcnn, mask_rcnn).

class encord.orm.model.ModelRow(dic)

ORM: model_hash (uid), title, description, features, model,

DB_FIELDS: collections.OrderedDict = {'description': <class 'str'>, 'features': <class 'list'>, 'model': <class 'str'>, 'model_hash': <class 'str'>, 'title': <class 'str'>}

class ModelRow(base_orm.BaseORM):
    """
    A model row contains a set of features and a model (resnet18, resnet34, resnet50, resnet101, resnet152,
    vgg16, vgg19, faster_rcnn, mask_rcnn).

    ORM:

    model_hash (uid),
    title,
    description,
    features,
    model,

    """

    DB_FIELDS = OrderedDict(
        [
            ("model_hash", str),
            ("title", str),
            ("description", str),
            ("features", list),
            ("model", str),
        ]
    )

ModelInferenceParams

Model inference parameters for running models trained via the platform.

class encord.orm.model.ModelInferenceParams(dic)

ORM: local_file_path, conf_thresh, iou_thresh, device detection_frame_range (optional)

DB_FIELDS: collections.OrderedDict = {'allocation_enabled': <class 'bool'>, 'conf_thresh': <class 'float'>, 'data_hashes': <class 'list'>, 'detection_frame_range': <class 'list'>, 'device': <class 'str'>, 'files': <class 'list'>, 'iou_thresh': <class 'float'>, 'rdp_thresh': <class 'float'>}

class ModelInferenceParams(base_orm.BaseORM):
    """
    Model inference parameters for running models trained via the platform.

    ORM:

    local_file_path,
    conf_thresh,
    iou_thresh,
    device
    detection_frame_range (optional)

    """

    DB_FIELDS = OrderedDict(
        [
            ("files", list),
            ("conf_thresh", float),  # Confidence threshold
            ("iou_thresh", float),  # Intersection over union threshold
            ("device", str),
            ("detection_frame_range", list),
            ("allocation_enabled", bool),
            ("data_hashes", list),
            ("rdp_thresh", float),
        ]
    )

ModelTrainingWeights

Model training weights.

class encord.orm.model.ModelTrainingWeights(dic)

ORM: training_config_link, training_weights_link,

DB_FIELDS: collections.OrderedDict = {'model': <class 'str'>, 'training_config_link': <class 'str'>, 'training_weights_link': <class 'str'>}

class ModelTrainingWeights(base_orm.BaseORM):
    """
    Model training weights.

    ORM:

    training_config_link,
    training_weights_link,

    """

    DB_FIELDS = OrderedDict(
        [
            ("model", str),
            ("training_config_link", str),
            ("training_weights_link", str),
        ]
    )

ModelTrainingParams

Model training parameters.

class encord.orm.model.ModelTrainingParams(dic)

ORM: model_hash, label_rows, epochs, batch_size, weights, device

DB_FIELDS: collections.OrderedDict = {'batch_size': <class 'int'>, 'device': <class 'str'>, 'epochs': <class 'int'>, 'label_rows': <class 'list'>, 'model_hash': <class 'str'>, 'weights': <class 'encord.orm.model.ModelTrainingWeights'>}

class ModelTrainingParams(base_orm.BaseORM):
    """
    Model training parameters.

    ORM:

    model_hash,
    label_rows,
    epochs,
    batch_size,
    weights,
    device

    """

    DB_FIELDS = OrderedDict(
        [
            ("model_hash", str),
            ("label_rows", list),
            ("epochs", int),
            ("batch_size", int),
            ("weights", ModelTrainingWeights),
            ("device", str),
        ]
    )

DEPRECATED - Project

DEPRECATED - use the encord.project.Project class instead.

A project defines a label ontology and is a collection of datasets and label rows.

DEPRECATED - class encord.orm.project.Project(dic)

ORM:

  • title,
  • description,
  • editor_ontology,
  • ontology_hash,
  • datasets:
    [
     {
          dataset_hash (uid),
          title,
          description,
          dataset_type (internal vs. AWS/GCP/Azure),
     },
     ...
    ],
    
- label_rows:

```python
  [
    {
        label_hash (uid),
        data_hash (uid),
        dataset_hash (uid),
        dataset_title,
        data_title,
        data_type,
        label_status
    },
    ...
]
  • annotation_task_status
class Project(base_orm.BaseORM):
    """
    DEPRECATED - prefer using the `encord.project.Project` class instead.

    A project defines a label ontology and is a collection of datasets and label rows.

    ORM:

    * title,
    * description,
    * editor_ontology,
    * ontology_hash,
    * datasets::

        [
           {
                dataset_hash (uid),
                title,
                description,
                dataset_type (internal vs. AWS/GCP/Azure),
           },
           ...
        ],
    * label_rows::

        [
            {
                label_hash (uid),
                data_hash (uid),
                dataset_hash (uid),
                dataset_title,
                data_title,
                data_type,
                label_status
            },
            ...
        ]
    * annotation_task_status

    """

    DB_FIELDS = OrderedDict(
        [
            ("project_hash", str),
            ("title", str),
            ("description", str),
            ("created_at", datetime.datetime),
            ("last_edited_at", datetime.datetime),
            ("editor_ontology", (dict, str)),
            ("datasets", (list, str)),
            ("label_rows", (list, str)),
            ("ontology_hash", str),
            ("source_projects", list),
        ]
    )

    NON_UPDATABLE_FIELDS = {"editor_ontology", "datasets", "label_rows"}

    def get_labels_list(self) -> List[Optional[str]]:
        """
        Returns a list of all optional label row IDs (label_hash uid) in a project. If no `label_hash` is found,
        a `None` value is appended. This can be useful for working with fetching additional label row data via
        :meth:`encord.project.Project.get_label_rows` for example.

        .. code::

                project = client_instance.get_project(<project_hash>)
                project_orm = project.get_project()

                labels_list = project_orm.get_labels_list()
                created_labels_list = []
                for label in labels_list:
                    if label is not None:  # None values will fail the operation
                        created_labels_list.append(label)

                label_rows = project.get_label_rows(created_labels_list, get_signed_url=False)
        """
        labels = self.to_dic().get("label_rows", [])
        return [label.get("label_hash") for label in labels]


    @property
    def project_hash(self) -> str:
        return self["project_hash"]

    @property
    def title(self) -> str:
        return self["title"]

    @property
    def description(self) -> str:
        return self["description"]

    @property
    def editor_ontology(self):
        return self["editor_ontology"]

    @property
    def datasets(self):
        return self["datasets"]

    @property
    def label_rows(self):
        return self["label_rows"]

    @property
    def ontology_hash(self) -> str:
        return self["ontology_hash"]

    @property
    def source_projects(self):
        return self["source_projects"]

    @property
    def created_at(self) -> datetime.datetime:
        return self["created_at"]

    @property
    def last_edited_at(self) -> datetime.datetime:
        return self["last_edited_at"]

DB_FIELDS

DB_FIELDS: collections.OrderedDict = {'created_at': <class 'datetime.datetime'>, 'datasets': (<class 'list'>, <class 'str'>), 'description': <class 'str'>, 'editor_ontology': (<class 'dict'>, <class 'str'>), 'label_rows': (<class 'list'>, <class 'str'>), 'last_edited_at': <class 'datetime.datetime'>, 'ontology_hash': <class 'str'>, 'project_hash': <class 'str'>, 'source_projects': <class 'list'>, 'title': <class 'str'>}

NON_UPDATABLE_FIELDS

NON_UPDATABLE_FIELDS: set = {'datasets', 'editor_ontology', 'label_rows'}

get_labels_list

get_labels_list()

Returns a list of all optional label row IDs (label_hash uid) in a project. If no label_hash is found, a None value is appended. This can be useful for working with fetching additional label row data using encord.project.Project.get_label_rows() for example.

project = client_instance.get_project(<project_hash>)
project_orm = project.get_project()

labels_list = project_orm.get_labels_list()
created_labels_list = []
for label in labels_list:
    if label is not None:  # None values will fail the operation
        created_labels_list.append(label)

label_rows = project.get_label_rows(created_labels_list, get_signed_url=False)

Return type:

List[Optional[str]]

property project_hash: str

Return type:

str

property title: str

Return type:

str

property description: str

Return type:

str

property editor_ontology

property datasets

property label_rows

property ontology_hash: str

Return type:

str

property source_projects

property created_at: datetime.datetime

Return type:

datetime

property last_edited_at: datetime.datetime

Return type:

datetime

    def get_labels_list(self) -> List[Optional[str]]:
        """
        Returns a list of all optional label row IDs (label_hash uid) in a project. If no `label_hash` is found,
        a `None` value is appended. This can be useful for working with fetching additional label row data via
        :meth:`encord.project.Project.get_label_rows` for example.

        .. code::

                project = client_instance.get_project(<project_hash>)
                project_orm = project.get_project()

                labels_list = project_orm.get_labels_list()
                created_labels_list = []
                for label in labels_list:
                    if label is not None:  # None values will fail the operation
                        created_labels_list.append(label)

                label_rows = project.get_label_rows(created_labels_list, get_signed_url=False)
        """
        labels = self.to_dic().get("label_rows", [])
        return [label.get("label_hash") for label in labels]

ProjectCopy

class encord.orm.project.ProjectCopy
class ProjectCopy:
    pass

ProjectUsers

class encord.orm.project.ProjectUsers
class ProjectUsers:
    pass

ProjectDataset

class encord.orm.project.ProjectDataset
class ProjectDataset:
    pass

ProjectCopyOptions

An enumeration.

class encord.orm.project.ProjectCopyOptions(value)
  • COLLABORATORS = 'collaborators'
  • DATASETS = 'datasets'
  • MODELS = 'models'
  • LABELS = 'labels'
class ProjectCopyOptions(str, Enum):
    COLLABORATORS = "collaborators"
    DATASETS = "datasets"
    MODELS = "models"
    LABELS = "labels"

ReviewApprovalState

An enumeration.

class encord.orm.project.ReviewApprovalState(value)

References to encord.orm.project.ReviewApprovalState:

Copying a project

  • APPROVED = 'APPROVED'
  • PENDING = 'PENDING'
  • REJECTED = 'REJECTED'
  • DELETED = 'DELETED'
  • NOT_SELECTED_FOR_REVIEW = 'NOT_SELECTED_FOR_REVIEW'
class ReviewApprovalState(str, Enum):
    APPROVED = "APPROVED"
    PENDING = "PENDING"
    REJECTED = "REJECTED"
    DELETED = "DELETED"
    NOT_SELECTED_FOR_REVIEW = "NOT_SELECTED_FOR_REVIEW"

CopyDatasetAction

An enumeration.

class encord.orm.project.CopyDatasetAction(value)

References to encord.orm.project.CopyDatasetAction

Copy projects

ATTACH = 'ATTACH'

Attach the datasets associated with the original project to the copy project.

CLONE = 'CLONE'

Clone the data units from the associated datasets into a new dataset an attach it to the copy project.

class CopyDatasetAction(str, Enum):
    ATTACH = "ATTACH"
    """ Attach the datasets associated with the original project to the copy project. """
    CLONE = "CLONE"
    """ Clone the data units from the associated datasets into a new dataset an attach it to the copy project. """

CopyDatasetOptions

Options for copying the datasets associated with a project.

class encord.orm.project.CopyDatasetOptions(action=CopyDatasetAction.ATTACH, dataset_title=None, dataset_description=None, datasets_to_data_hashes_map=<factory>)

References to encord.orm.project.CopyDatasetOptions:

Copy Projects

action: encord.orm.project.CopyDatasetAction = 'ATTACH'

One of CopyDatasetAction.ATTACH or CopyDatasetAction.CLONE. (defaults to ATTACH)

dataset_title: Optional[str] = None
dataset_description: Optional[str] = None
datasets_to_data_hashes_map: Dict[str, List[str]]
List[<data_unit_hash>]}`. When provided with a CLONE action filters the copied data units. When combined with CopyLabelsOptions, only labels from specific data units are copied.

Type
A dictionary of { <dataset_hash>}

@dataclass
class CopyDatasetOptions:
    """Options for copying the datasets associated with a project."""

    action: CopyDatasetAction = CopyDatasetAction.ATTACH
    """
    One of `CopyDatasetAction.ATTACH` or `CopyDatasetAction.CLONE`. (defaults to ATTACH)
    """
    dataset_title: Optional[str] = None
    dataset_description: Optional[str] = None
    datasets_to_data_hashes_map: Dict[str, List[str]] = field(default_factory=dict)
    """ A dictionary of `{ <dataset_hash>: List[<data_unit_hash>]}`.
    When provided with a CLONE action this will filter the copied data units.
    When combined with `CopyLabelsOptions`, only labels from specific data units will be copied.
    """

CopyLabelsOptions

Options for copying the labels associated with a project.

class encord.orm.project.CopyLabelsOptions(accepted_label_hashes=None, accepted_label_statuses=None)

Rreferences to encord.orm.project.CopyLabelsOptions:

Copy Projects

accepted_label_hashes: Optional[List[str]] = None

A list of label hashes that will be copied to the new project

accepted_label_statuses: Optional[List[encord.orm.project.ReviewApprovalState]] = None

A list of label statuses to filter the labels copied to the new project, defined in ReviewApprovalState

@dataclass
class CopyLabelsOptions:
    """Options for copying the labels associated with a project."""

    accepted_label_hashes: Optional[List[str]] = None
    """ A list of label hashes that will be copied to the new project  """
    accepted_label_statuses: Optional[List[ReviewApprovalState]] = None
    """ A list of label statuses to filter the labels copied to the new project, defined in `ReviewApprovalState`"""

ProjectWorkflowType

An enumeration.

class encord.orm.project.ProjectWorkflowType(value)
  • MANUAL_QA = 'manual'
  • BENCHMARK_QA = 'benchmark'
class ProjectWorkflowType(Enum):
    MANUAL_QA = "manual"
    BENCHMARK_QA = "benchmark"

ManualReviewWorkflowSettings

Sets the project QA workflow to “manual reviews”. There are currently no available settings for this workflow

class encord.orm.project.ManualReviewWorkflowSettings
class ManualReviewWorkflowSettings:
    """Sets the project QA workflow to "manual reviews". There are currently no available settings for this workflow"""

    pass

BenchmarkQaWorkflowSettings

Sets the project QA workflow to “Automatic”, with benchmark data being presented to all the annotators.

class encord.orm.project.BenchmarkQaWorkflowSettings(source_projects=<factory>)

source_projects: List[str]

For Benchmark QA projects, a list of project ids (project_hash-es) that contain the benchmark source data.

@dataclass
class BenchmarkQaWorkflowSettings:
    """Sets the project QA workflow to "Automatic", with benchmark data being presented to all the annotators"""

    source_projects: List[str] = field(default_factory=list)
    """
    For Benchmark QA projects, a list of project ids (project_hash-es)
        that contain the benchmark source data
    """

ProjectWorkflowSettings

A variant type that allows you to select the type of quality assurance workflow for the project, and configure it.

encord.orm.project.ProjectWorkflowSettings

Currently one of:
ManualReviewWorkflowSettings: a workflow with optional manual reviews BenchmarkQaWorkflowSettings: annotators are presented with “benchmark” or “honeypot” data

alias of Union[encord.orm.project.ManualReviewWorkflowSettings, encord.orm.project.BenchmarkQaWorkflowSettings]

ReviewMode

class encord.orm.project.ReviewMode(value)

UNLABELLED:

UNLABELLED = 'unlabelled'

The labels are added to the images. However, the one person must still go over all of the labels before submitting them for review.

LABELLED:

LABELLED = 'labelled'

The labels are added to the images and are marked as labelled. A reviewer still needs to approve those.

REVIEWED:

REVIEWED = 'reviewed'

The labels are added to the images and considered reviewed. No more action is required from the labeler or reviewer.

class ReviewMode(StringEnum):
    """
    UNLABELLED:
        The labels are added to the images. However, the one person must still go over
            all of the labels before submitting them for review.
    LABELLED:
        The labels are added to the images and are marked as labelled. A reviewer will
            still need to approve those.
    REVIEWED:
        The labels are added to the images and considered reviewed. No more action is
            required from the labeler or reviewer.
    """

    UNLABELLED = "unlabelled"
    LABELLED = "labelled"
    REVIEWED = "reviewed"

ProjectImporter

class encord.orm.project.ProjectImporter(dic)

DB_FIELDS: collections.OrderedDict = {'errors': <class 'list'>, 'project_hash': typing.Union[str, NoneType]}

class ProjectImporter(base_orm.BaseORM):
    DB_FIELDS = OrderedDict(
        [
            ("project_hash", Optional[str]),
            ("errors", list),
        ]
    )

CvatExportType

An enumeration.

class encord.orm.project.CvatExportType(value)

PROJECT = 'project'
TASK = 'task'

class CvatExportType(Enum):
    PROJECT = "project"
    TASK = "task"

ProjectImporterCvatInfo

class encord.orm.project.ProjectImporterCvatInfo(dic)

DB_FIELDS: collections.OrderedDict = {'export_type': <enum 'CvatExportType'>}

class ProjectImporterCvatInfo(base_orm.BaseORM):
    DB_FIELDS = OrderedDict(
        [
            ("export_type", CvatExportType),
        ]
    )

TaskPriorityParams

class encord.orm.project.TaskPriorityParams(**data)

priorities: List[Tuple[str, float]]

ProjectAPIKey

class encord.orm.project_api_key.ProjectAPIKey(api_key, title, scopes)

References to encord.orm.project_api_key:

Fetching project API keys

api_key: str
title: str
scopes: List[encord.utilities.client_utilities.APIKeyScopes]

import json
from dataclasses import dataclass
from typing import Dict, List

from encord.orm.formatter import Formatter
from encord.utilities.client_utilities import APIKeyScopes


@dataclass(frozen=True)
class ProjectAPIKey(Formatter):
    api_key: str
    title: str
    scopes: List[APIKeyScopes]

    @classmethod
    def from_dict(cls, json_dict: Dict):
        if isinstance(json_dict["scopes"], str):
            json_dict["scopes"] = json.loads(json_dict["scopes"])
        scopes = [APIKeyScopes(scope) for scope in json_dict["scopes"]]
        return ProjectAPIKey(json_dict["api_key"], json_dict["title"], scopes)

from_dict

classmethod from_dict(json_dict)
    @classmethod
    def from_dict(cls, json_dict: Dict):
        if isinstance(json_dict["scopes"], str):
            json_dict["scopes"] = json.loads(json_dict["scopes"])
        scopes = [APIKeyScopes(scope) for scope in json_dict["scopes"]]
        return ProjectAPIKey(json_dict["api_key"], json_dict["title"], scopes)

ProjectWithUserRole

This is a helper class denoting the relationship between the current user an a project.

class encord.orm.project_with_user_role.ProjectWithUserRole(user_role, project)
  • user_role: int
  • project: dict
#
# Copyright (c) 2022 Cord Technologies Limited
#
# Licensed under the Apache License, Version 2.0 (the "License"); you may
# not use this file except in compliance with the License. You may obtain
# a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
# License for the specific language governing permissions and limitations
# under the License.

from dataclasses import dataclass


[docs]@dataclass(frozen=True)
class ProjectWithUserRole:
    """
    This is a helper class denoting the relationship between the current user an a project
    """

    user_role: int
    project: dict

CamelStrEnum

class encord.orm.analytics.CamelStrEnum(value)[source]

An enumeration.

class CamelStrEnum(str, Enum):
    # noinspection PyMethodParameters
    def _generate_next_value_(name, start, count, last_values) -> str:  # type: ignore
        return snake_to_camel(name)

CollaboratorTimersGroupBy

class encord.orm.analytics.CollaboratorTimersGroupBy(value)

An enumeration.

DATA_UNIT = 'dataUnit'
PROJECT = 'project'

class CollaboratorTimersGroupBy(CamelStrEnum):
    DATA_UNIT = auto()
    PROJECT = auto()

CollaboratorTimerParams

class encord.orm.analytics.CollaboratorTimerParams(**data)

project_hash: str
after: datetime.datetime
before: Optional[datetime.datetime]
group_by: encord.orm.analytics.CollaboratorTimersGroupBy
page_size: int
page_token: Optional[str]

CollaboratorTimer

class encord.orm.analytics.CollaboratorTimer(**data)

user_email: str
user_role: encord.utilities.project_user.ProjectUserRole
data_title: Optional[str]
time_seconds: float