Encord Python SDK API Reference#

User Client#

Expand for references to encord.user_client

Projects / API keys / Creating a project API key / Creating a master API key with full rights

Projects / Creating a Project

Projects / API keys / Creating a project API key / Creating a project API key with specific rights

Projects / API keys / Fetching project API keys

Projects / Listing existing projects

class encord.user_client.EncordUserClient(user_config, querier)[source]#

Expand for references to encord.user_client.EncordUserClient

Authentication / User authentication / Authenticate with Encord - user authentication

Quickstart

Configurations / Network configurations

Datasets / Data / Adding data / Adding data from a private cloud

Datasets / Creating a dataset

Datasets / API keys / Creating a dataset API key with specific rights

Datasets / API keys / Creating a master API key with full rights

Datasets / API keys / Fetching dataset API keys

Datasets / Listing existing datasets

Datasets / Managing a dataset

Projects / Ontology / Adding components to a project ontology / Adding a classification to an ontology

Projects / Ontology / Adding components to a project ontology / Adding an object to an ontology

Projects / Data / Adding datasets to a project

Projects / Adding users to projects

Projects / Copying a project

Projects / API keys / Creating a project API key / Creating a master API key with full rights

Projects / Creating a Project

Projects / API keys / Creating a project API key / Creating a project API key with specific rights

Projects / Ontology / Fetching a project’s ontology

Projects / API keys / Fetching project API keys

Projects / Labels / Getting label rows

Projects / Other Resources / CVAT Integration / Importing with the Encord SDK

Projects / Listing existing projects

Projects / Managing a project

Projects / Data / Removing datasets from a project

get_dataset(dataset_hash)[source]#

Get the Project class to access project fields and manipulate a project.

You will only have access to this project if you are one of the following

  • Dataset admin

  • Organisation admin of the project

Parameters

dataset_hash (str) – The Dataset ID

Return type

Dataset

Expand for references to encord.user_client.EncordUserClient.get_dataset

Authentication / User authentication / Authenticate with Encord - user authentication

Configurations / Network configurations

Datasets / Data / Adding data / Adding data from a private cloud

Datasets / Managing a dataset

get_project(project_hash)[source]#

Get the Project class to access project fields and manipulate a project.

You will only have access to this project if you are one of the following

  • Project admin

  • Project team manager

  • Organisation admin of the project

Parameters

project_hash (str) – The Project ID

Return type

Project

Expand for references to encord.user_client.EncordUserClient.get_project

Authentication / User authentication / Authenticate with Encord - user authentication

Quickstart

Projects / Ontology / Adding components to a project ontology / Adding a classification to an ontology

Projects / Ontology / Adding components to a project ontology / Adding an object to an ontology

Projects / Data / Adding datasets to a project

Projects / Adding users to projects

Projects / Copying a project

Projects / Ontology / Fetching a project’s ontology

Projects / Labels / Getting label rows

Projects / Managing a project

Projects / Data / Removing datasets from a project

get_ontology(ontology_hash)[source]#
Return type

Ontology

create_private_dataset(dataset_title, dataset_type, dataset_description=None)[source]#

DEPRECATED - please use create_dataset instead.

Return type

CreateDatasetResponse

create_dataset(dataset_title, dataset_type, dataset_description=None)[source]#
Parameters
  • dataset_title (str) – Title of dataset.

  • dataset_type (StorageLocation) – StorageLocation type where data will be stored.

  • dataset_description (Optional[str]) – Optional description of the dataset.

Return type

CreateDatasetResponse

Returns

CreateDatasetResponse

Expand for references to encord.user_client.EncordUserClient.create_dataset

Datasets / Creating a dataset

create_dataset_api_key(dataset_hash, api_key_title, dataset_scopes)[source]#
Return type

DatasetAPIKey

Expand for references to encord.user_client.EncordUserClient.create_dataset_api_key

Datasets / API keys / Creating a dataset API key with specific rights

get_dataset_api_keys(dataset_hash)[source]#
Return type

List[DatasetAPIKey]

Expand for references to encord.user_client.EncordUserClient.get_dataset_api_keys

Datasets / API keys / Fetching dataset API keys

get_or_create_dataset_api_key(dataset_hash)[source]#
Return type

DatasetAPIKey

Expand for references to encord.user_client.EncordUserClient.get_or_create_dataset_api_key

Datasets / API keys / Creating a master API key with full rights

get_datasets(title_eq=None, title_like=None, desc_eq=None, desc_like=None, created_before=None, created_after=None, edited_before=None, edited_after=None)[source]#

List either all (if called with no arguments) or matching datasets the user has access to.

Parameters
  • title_eq – optional exact title filter

  • title_like – optional fuzzy title filter; SQL syntax

  • desc_eq – optional exact description filter

  • desc_like – optional fuzzy description filter; SQL syntax

  • created_before – optional creation date filter, ‘less’

  • created_after – optional creation date filter, ‘greater’

  • edited_before – optional last modification date filter, ‘less’

  • edited_after – optional last modification date filter, ‘greater’

Returns

list of (role, dataset) pairs for datasets matching filter conditions.

Expand for references to encord.user_client.EncordUserClient.get_datasets

Datasets / Listing existing datasets

static create_with_ssh_private_key(ssh_private_key=None, password=None, requests_settings=RequestsSettings(max_retries=0, backoff_factor=0.1), **kwargs)[source]#
Return type

EncordUserClient

Expand for references to encord.user_client.EncordUserClient.create_with_ssh_private_key

Authentication / User authentication / Authenticate with Encord - user authentication

Quickstart

Configurations / Network configurations

Datasets / Data / Adding data / Adding data from a private cloud

Datasets / Creating a dataset

Datasets / API keys / Creating a dataset API key with specific rights

Datasets / API keys / Creating a master API key with full rights

Datasets / API keys / Fetching dataset API keys

Datasets / Listing existing datasets

Datasets / Managing a dataset

Projects / Ontology / Adding components to a project ontology / Adding a classification to an ontology

Projects / Ontology / Adding components to a project ontology / Adding an object to an ontology

Projects / Data / Adding datasets to a project

Projects / Adding users to projects

Projects / Copying a project

Projects / API keys / Creating a project API key / Creating a master API key with full rights

Projects / Creating a Project

Projects / API keys / Creating a project API key / Creating a project API key with specific rights

Projects / Ontology / Fetching a project’s ontology

Projects / API keys / Fetching project API keys

Projects / Labels / Getting label rows

Projects / Other Resources / CVAT Integration / Importing with the Encord SDK

Projects / Listing existing projects

Projects / Managing a project

Projects / Data / Removing datasets from a project

get_projects(title_eq=None, title_like=None, desc_eq=None, desc_like=None, created_before=None, created_after=None, edited_before=None, edited_after=None)[source]#

List either all (if called with no arguments) or matching projects the user has access to.

Parameters
  • title_eq – optional exact title filter

  • title_like – optional fuzzy title filter; SQL syntax

  • desc_eq – optional exact description filter

  • desc_like – optional fuzzy description filter; SQL syntax

  • created_before – optional creation date filter, ‘less’

  • created_after – optional creation date filter, ‘greater’

  • edited_before – optional last modification date filter, ‘less’

  • edited_after – optional last modification date filter, ‘greater’

Returns

list of (role, projects) pairs for project matching filter conditions.

Expand for references to encord.user_client.EncordUserClient.get_projects

Quickstart

Projects / Listing existing projects

create_project(project_title, dataset_hashes, project_description='', ontology_hash='')[source]#
Return type

str

Expand for references to encord.user_client.EncordUserClient.create_project

Projects / Creating a Project

create_project_api_key(project_hash, api_key_title, scopes)[source]#
Return type

str

Returns

The created project API key.

Expand for references to encord.user_client.EncordUserClient.create_project_api_key

Projects / API keys / Creating a project API key / Creating a project API key with specific rights

get_project_api_keys(project_hash)[source]#
Return type

List[ProjectAPIKey]

Expand for references to encord.user_client.EncordUserClient.get_project_api_keys

Projects / API keys / Fetching project API keys

get_or_create_project_api_key(project_hash)[source]#
Return type

str

Expand for references to encord.user_client.EncordUserClient.get_or_create_project_api_key

Projects / API keys / Creating a project API key / Creating a master API key with full rights

get_dataset_client(dataset_hash, **kwargs)[source]#

DEPRECATED - prefer using get_dataset() instead.

Return type

Union[EncordClientProject, EncordClientDataset]

Expand for references to encord.user_client.EncordUserClient.get_dataset_client

Configurations / Network configurations

get_project_client(project_hash, **kwargs)[source]#

DEPRECATED - prefer using get_project() instead.

Return type

Union[EncordClientProject, EncordClientDataset]

create_project_from_cvat(import_method, dataset_name, review_mode=ReviewMode.LABELLED, max_workers=None, *, transform_bounding_boxes_to_polygons=False)[source]#
Export your CVAT project with the “CVAT for images 1.1” option and use this function to import

your images and annotations into encord. Ensure that during you have the “Save images” checkbox enabled when exporting from CVAT.

Parameters
  • import_method (LocalImport) – The chosen import method. See the ImportMethod class for details.

  • dataset_name (str) – The name of the dataset that will be created.

  • review_mode (ReviewMode) –

    Set how much interaction is needed from the labeler and from the reviewer for the CVAT labels.

    See the ReviewMode documentation for more details.

  • max_workers (Optional[int]) – DEPRECATED: This argument will be ignored

  • transform_bounding_boxes_to_polygons – All instances of CVAT bounding boxes will be converted to polygons in the final Encord project.

Returns

If the project was successfully imported. CvatImporterError: If the project could not be imported.

Return type

CvatImporterSuccess

Raises

ValueError – If the CVAT directory has an invalid format.

Expand for references to encord.user_client.EncordUserClient.create_project_from_cvat

Projects / Other Resources / CVAT Integration / Importing with the Encord SDK

get_cloud_integrations()[source]#
Return type

List[CloudIntegration]

Expand for references to encord.user_client.EncordUserClient.get_cloud_integrations

Datasets / Data / Adding data / Adding data from a private cloud

get_ontologies(title_eq=None, title_like=None, desc_eq=None, desc_like=None, created_before=None, created_after=None, edited_before=None, edited_after=None)[source]#

List either all (if called with no arguments) or matching ontologies the user has access to.

Parameters
  • title_eq – optional exact title filter

  • title_like – optional fuzzy title filter; SQL syntax

  • desc_eq – optional exact description filter

  • desc_like – optional fuzzy description filter; SQL syntax

  • created_before – optional creation date filter, ‘less’

  • created_after – optional creation date filter, ‘greater’

  • edited_before – optional last modification date filter, ‘less’

  • edited_after – optional last modification date filter, ‘greater’

Returns

list of (role, projects) pairs for ontologies matching filter conditions.

create_ontology(title, description='', structure=None)[source]#
Return type

Ontology

class encord.user_client.ListingFilter(value)[source]#

Available properties_filter keys for get_projects() and get_datasets().

The values for _before and _after should be datetime objects.

TITLE_EQ = 'title_eq'#
TITLE_LIKE = 'title_like'#
DESC_EQ = 'desc_eq'#
DESC_LIKE = 'desc_like'#
CREATED_BEFORE = 'created_before'#
CREATED_AFTER = 'created_after'#
EDITED_BEFORE = 'edited_before'#
EDITED_AFTER = 'edited_after'#
encord.user_client.CordUserClient#

alias of encord.user_client.EncordUserClient

Project#

class encord.project.Project(client)[source]#

Access project related data and manipulate the project.

Expand for references to encord.project.Project

Authentication / User authentication / Authenticate with Encord - user authentication

Quickstart

Projects / Ontology / Adding components to a project ontology / Adding a classification to an ontology

Projects / Ontology / Adding components to a project ontology / Adding an object to an ontology

Projects / Data / Adding datasets to a project

Projects / Adding users to projects

Projects / Copying a project

Projects / Ontology / Fetching a project’s ontology

Projects / Managing a project

Projects / Data / Removing datasets from a project

property project_hash: str#

Get the project hash (i.e. the Project ID).

Return type

str

property title: str#

Get the title of the project.

Return type

str

property description: str#

Get the description of the project.

Return type

str

property created_at: datetime.datetime#

Get the time the project was created at.

Return type

datetime

property last_edited_at: datetime.datetime#

Get the time the project was last edited at.

Return type

datetime

property ontology: dict#

Get the ontology of the project.

BETA: Prefer using the encord.objects.ontology_structure.OntologyStructure class to work with the data.

from encord.objects.ontology_structure import OntologyStructure

project = user_client.get_project("<project_hash>")

ontology = OntologyStructure.from_dict(project.ontology)
Return type

dict

property datasets: list#

Get the associated datasets.

Prefer using the encord.objects.project.ProjectDataset() class to work with the data.

from encord.objects.project import ProjectDataset

project = user_client.get_project("<project_hash>")

project_datasets = ProjectDataset.from_list(project.datasets)
Return type

list

property label_rows: dict#

Get the label rows.

Prefer using the encord.orm.label_row.LabelRowMetadata() class to work with the data.

from encord.orm.label_row import LabelRowMetadata

project = user_client.get_project("<project_hash>")

label_rows = LabelRowMetadata.from_list(project.label_rows)
Return type

dict

Expand for references to encord.project.Project.label_rows

Quickstart

Projects / Labels / Getting label rows

refetch_data()[source]#

The Project class will only fetch its properties once. Use this function if you suspect the state of those properties to be dirty.

Return type

None

get_project()[source]#

This function is exposed for convenience. You are encouraged to use the property accessors instead.

Return type

Project

list_label_rows(edited_before=None, edited_after=None, label_statuses=None)[source]#
Return type

List[LabelRowMetadata]

set_label_status(label_hash, label_status)[source]#

Set the label status for a label row to a desired value.

Parameters
  • self – Encord client object.

  • label_hash (str) – unique identifier of the label row whose status is to be updated.

  • label_status (LabelStatus) – the new status that needs to be set.

Return type

bool

Returns

Bool.

Raises
  • AuthorisationError – If the label_hash provided is invalid or not a member of the project.

  • UnknownError – If an error occurs while updating the status.

add_users(user_emails, user_role)[source]#

Add users to project

Parameters
  • user_emails (List[str]) – list of user emails to be added

  • user_role (ProjectUserRole) – the user role to assign to all users

Return type

List[ProjectUser]

Returns

ProjectUser

Raises
  • AuthorisationError – If the project API key is invalid.

  • ResourceNotFoundError – If no project exists by the specified project EntityId.

  • UnknownError – If an error occurs while adding the users to the project

Expand for references to encord.project.Project.add_users

Projects / Adding users to projects

copy_project(copy_datasets=False, copy_collaborators=False, copy_models=False)[source]#

Copy the current project into a new one with copied contents including settings, datasets and users. Labels and models are optional.

Parameters
  • copy_datasets – if True, the datasets of the existing project are copied over, and new tasks are created from those datasets

  • copy_collaborators – if True, all users of the existing project are copied over with their current roles. If label and/or annotator reviewer mapping is set, this will also be copied over

  • copy_models – currently if True, all models with their training information will be copied into the new project

Return type

str

Returns

the EntityId of the newly created project

Raises
  • AuthorisationError – If the project API key is invalid.

  • ResourceNotFoundError – If no project exists by the specified project EntityId.

  • UnknownError – If an error occurs while copying the project.

Expand for references to encord.project.Project.copy_project

Projects / Copying a project

get_label_row(uid, get_signed_url=True, *, include_object_feature_hashes=None, include_classification_feature_hashes=None)[source]#

Retrieve label row. If you need to retrieved multiple label rows, prefer using encord.project.Project.get_label_rows() instead.

A code example using the include_object_feature_hashes and include_classification_feature_hashes filters can be found in encord.project.Project.get_label_row().

Parameters
  • uid (str) – A label_hash (uid) string.

  • get_signed_url (bool) – Whether to generate signed urls to the data asset. Generating these should be disabled if the signed urls are not used to speed up the request.

  • include_object_feature_hashes (Optional[Set[str]]) – If None all the objects will be included. Otherwise, only objects labels will be included of which the feature_hash has been added.

  • include_classification_feature_hashes (Optional[Set[str]]) – If None all the classifications will be included. Otherwise, only classification labels will be included of which the feature_hash has been added.

Returns

A label row instance.

Return type

LabelRow

Raises

Expand for references to encord.project.Project.get_label_row

Quickstart

get_label_rows(uids, get_signed_url=True, *, include_object_feature_hashes=None, include_classification_feature_hashes=None)[source]#

Retrieve a list of label rows. Duplicates will be dropped. The result will come back in a random order.

This return is undefined behaviour if any of the uids are invalid (i.e. it may randomly fail or randomly succeed and should not be relied upon).

# Code example of using the object filters.
from encord.objects.common import Shape
from encord.objects.ontology_structure import OntologyStructure

project = ... # assuming you already have instantiated this Project object

# Get all feature hashes of the objects which are of type `Shape.BOUNDING_BOX`
ontology = OntologyStructure.from_dict(project.ontology)
only_bounding_box_feature_hashes = set()
for object_ in ontology.objects:
    if object_.shape == Shape.BOUNDING_BOX:
        only_bounding_box_feature_hashes.add(object_.feature_node_hash)

no_classification_feature_hashes = set()  # deliberately left empty

# Get all labels of tasks that have already been initiated.
# Include only labels of bounding boxes and exclude all
# classifications
label_hashes = []
for label_row in project.label_rows:
    # Trying to run `get_label_row` on a label_row without a `label_hash` would fail.
    if label_row["label_hash"] is not None:
        label_hashes.append(label_row["label_hash"])

all_labels = project.get_label_rows(
    label_hashes,
    include_object_feature_hashes=only_bounding_box_feature_hashes,
    include_classification_feature_hashes=no_classification_feature_hashes,
)
Parameters
  • uids (List[str]) – A list of label_hash (uid).

  • get_signed_url (bool) –

    Whether to generate signed urls to the data asset. Generating these should be disabled

    if the signed urls are not used to speed up the request.

    include_object_feature_hashes:

    If None all the objects will be included. Otherwise, only objects labels will be included of which the feature_hash has been added.

    include_classification_feature_hashes:

    If None all the classifications will be included. Otherwise, only classification labels will be included of which the feature_hash has been added.

Raises
  • MultiLabelLimitError – If too many labels were requested. Check the error’s maximum_labels_allowed field to read the most up to date error limit.

  • AuthenticationError – If the project API key is invalid.

  • AuthorisationError – If access to the specified resource is restricted.

  • ResourceNotFoundError – If no label exists by the specified label_hash (uid).

  • UnknownError – If an error occurs while retrieving the label.

  • OperationNotAllowed – If the read operation is not allowed by the API key.

Return type

List[LabelRow]

Expand for references to encord.project.Project.get_label_rows

Projects / Labels / Getting label rows

save_label_row(uid, label)[source]#

Save existing label row.

If you have a series of frame labels and have not updated answer dictionaries, call the construct_answer_dictionaries utilities function to do so prior to saving labels.

Parameters
  • uid – A label_hash (uid) string.

  • label – A label row instance.

Returns

Bool.

Raises
create_label_row(uid)[source]#

Create a label row (for data in a project not previously been labeled).

Parameters

uid (str) – the data_hash (uid) of the data unit being labeled. Available in client.get_project().get(‘label_rows’) where label_status is NOT_LABELLED.

Returns

A label row instance.

Return type

LabelRow

Raises
  • AuthenticationError – If the project API key is invalid.

  • AuthorisationError – If access to the specified resource is restricted.

  • UnknownError – If an error occurs while saving the label.

  • OperationNotAllowed – If the write operation is not allowed by the API key.

  • AnswerDictionaryError – If an object or classification instance is missing in answer dictionaries.

  • CorruptedLabelError – If a blurb is corrupted (e.g. if the frame labels have more frames than the video).

  • ResourceExistsError – If a label row already exists for this project data. Avoids overriding existing work.

submit_label_row_for_review(uid)[source]#

Submit a label row for review.

Parameters

uid (str) – A label_hash (uid) string.

Returns

Bool.

Raises
add_datasets(dataset_hashes)[source]#

Add a dataset to a project

Parameters

dataset_hashes (List[str]) – List of dataset hashes of the datasets to be added

Return type

bool

Returns

Bool.

Raises
  • AuthenticationError – If the project API key is invalid.

  • AuthorisationError – If access to the specified resource is restricted.

  • ResourceNotFoundError – If one or more datasets don’t exist by the specified dataset_hashes.

  • UnknownError – If an error occurs while adding the datasets to the project.

  • OperationNotAllowed – If the write operation is not allowed by the API key.

Expand for references to encord.project.Project.add_datasets

Projects / Data / Adding datasets to a project

remove_datasets(dataset_hashes)[source]#

Remove datasets from project

Parameters

dataset_hashes (List[str]) – List of dataset hashes of the datasets to be removed

Return type

bool

Returns

Bool.

Raises

Expand for references to encord.project.Project.remove_datasets

Projects / Data / Removing datasets from a project

get_project_ontology()[source]#

DEPRECATED - prefer using the ontology property accessor instead.

Return type

Ontology

Expand for references to encord.project.Project.get_project_ontology

Projects / Ontology / Fetching a project’s ontology

add_object(name, shape)[source]#

Add object to an ontology.

ATTENTION: this legacy method will affect all the projects sharing the same ontology

Parameters
  • name (str) – the name of the object

  • shape (ObjectShape) – the shape of the object. (BOUNDING_BOX, POLYGON, POLYLINE or KEY_POINT)

Return type

bool

Returns

True if the object was added successfully and False otherwise.

Raises
  • AuthenticationError – If the project API key is invalid.

  • AuthorisationError – If access to the specified resource is restricted.

  • UnknownError – If an error occurs while add te object to the project ontology

  • OperationNotAllowed – If the operation is not allowed by the API key.

  • ValueError – If invalid arguments are supplied in the function call

Expand for references to encord.project.Project.add_object

Projects / Ontology / Adding components to a project ontology / Adding an object to an ontology

add_classification(name, classification_type, required, options=None)[source]#

Add classification to an ontology.

ATTENTION: this legacy method will affect all the projects sharing the same ontology

Parameters
  • name (str) – the name of the classification

  • classification_type (ClassificationType) – the classification type (RADIO, TEXT or CHECKLIST)

  • required (whether this classification is required by the annotator) –

  • options (Optional[Iterable[str]]) – the list of options for the classification (to be set to None for texts)

Raises
  • AuthenticationError – If the project API key is invalid.

  • AuthorisationError – If access to the specified resource is restricted.

  • UnknownError – If an error occurs while add te classification to the project ontology

  • OperationNotAllowed – If the operation is not allowed by the API key.

  • ValueError – If invalid arguments are supplied in the function call

Expand for references to encord.project.Project.add_classification

Projects / Ontology / Adding components to a project ontology / Adding a classification to an ontology

list_models()[source]#

List all models that are associated with the project. Use the encord.project.Project.get_training_metadata() to get more metadata about each training instance.

from encord.utilities.project_utilities import get_all_model_iteration_uids

project = client_instance.get_project(<project_hash>)

model_configurations = project.list_models()
all_model_iteration_uids = get_all_model_iteration_uids(model_configurations)
training_metadata = project.get_training_metadata(
    all_model_iteration_uids,
    get_model_training_labels=True,
)
Return type

List[ModelConfiguration]

get_training_metadata(model_iteration_uids, get_created_at=False, get_training_final_loss=False, get_model_training_labels=False)[source]#

Given a list of model_iteration_uids, get some metadata around each model_iteration.

Parameters
  • model_iteration_uids (Iterable[str]) – The model iteration uids

  • get_created_at (bool) – Whether the created_at field should be retrieved.

  • get_training_final_loss (bool) – Whether the training_final_loss field should be retrieved.

  • get_model_training_labels (bool) – Whether the model_training_labels field should be retrieved.

Return type

List[TrainingMetadata]

create_model_row(title, description, features, model)[source]#

Create a model row.

Parameters
  • title (str) – Model title.

  • description (str) – Model description.

  • features (List[str]) – List of <feature_node_hashes> which is id’s of ontology objects or classifications to be included in the model.

  • model (Union[AutomationModels, str]) – the model type to be used. For backwards compatibility purposes, we continuously allow strings corresponding to the values of the AutomationModels Enum.

Return type

str

Returns

The uid of the added model row.

Raises
model_delete(uid)[source]#

Delete a model created on the platform.

Parameters

uid (str) – A model_hash (uid) string.

Return type

bool

Returns

bool

Raises
model_inference(uid, file_paths=None, base64_strings=None, conf_thresh=0.6, iou_thresh=0.3, device='cuda', detection_frame_range=None, allocation_enabled=False, data_hashes=None, rdp_thresh=0.005)[source]#

Run inference with model trained on the platform.

Parameters
  • uid – A model_iteration_hash (uid) string.

  • file_paths – List of local file paths to image(s) or video(s) - if running inference on files.

  • base64_strings – List of base 64 strings of image(s) or video(s) - if running inference on base64 strings.

  • conf_thresh – Confidence threshold (default 0.6).

  • iou_thresh – Intersection over union threshold (default 0.3).

  • device – Device (CPU or CUDA, default is CUDA).

  • detection_frame_range – Detection frame range (for videos).

  • allocation_enabled – Object UID allocation (tracking) enabled (disabled by default).

  • data_hashes – list of hash of the videos/image_groups you’d like to run inference on.

  • rdp_thresh – parameter specifying the polygon coarseness to be used while running inference. The higher the value, the less points in the segmented image

Returns

A dict of inference results.

Return type

Inference results

Raises
model_train(uid, label_rows=None, epochs=None, batch_size=24, weights=None, device='cuda')[source]#

Train a model created on the platform.

Parameters
  • uid – A model_hash (uid) string.

  • label_rows – List of label row uid’s (hashes) for training.

  • epochs – Number of passes through training dataset.

  • batch_size – Number of training examples utilized in one iteration.

  • weights – Model weights.

  • device – Device (CPU or CUDA, default is CUDA).

Returns

A model iteration object.

Raises
object_interpolation(key_frames, objects_to_interpolate)[source]#

Run object interpolation algorithm on project labels (requires an editor ontology and feature uid’s).

Interpolation is supported for bounding box, polygon, and keypoint.

Parameters
  • key_frames

    Labels for frames to be interpolated. Key frames are consumed in the form:

    {
        "<frame_number>": {
            "objects": [
                {
                    "objectHash": "<object_hash>",
                    "featureHash": "<feature_hash>",
                    "polygon": {
                        "0": { "x": x1, "y": y1, },
                        "1": { "x": x2, "y": y2, },
                        # ...,
                    }
                },
                # ...
            ]
        },
        # ...,
    }
    

  • objects_to_interpolate – List of object uid’s (hashes) of objects to interpolate.

Returns

Full set of filled frames including interpolated objects.

Return type

Interpolation results

Raises
  • AuthenticationError – If the project API key is invalid.

  • AuthorisationError – If access to the specified resource is restricted.

  • UnknownError – If an error occurs while running interpolation.

fitted_bounding_boxes(frames, video)[source]#
Parameters
  • frames (dict) –

    Labels for frames to be fitted. Frames are consumed in the form:

    {
        "<frame_number>": {
            "objects": [
                {
                    "objectHash": "<object_hash>",
                    "featureHash": "<feature_hash>",
                    "polygon": {
                        "0": { "x": x1, "y": y1, },
                        "1": { "x": x2, "y": y2, },
                        # ...,
                    }
                },
                # ...
            ]
        },
        # ...,
    }
    

  • video (dict) –

    Metadata of the video for which bounding box fitting needs to be run:

    {
        "width" : w,
        "height" : h,
    }
    

Returns

Full set of filled frames including fitted objects.

Return type

Fitting results

Raises
  • AuthenticationError – If the project API key is invalid.

  • AuthorisationError – If access to the specified resource is restricted.

  • UnknownError – If an error occurs while running interpolation.

get_data(data_hash, get_signed_url=False)[source]#

Retrieve information about a video or image group.

Parameters
  • data_hash (str) – The uid of the data object

  • get_signed_url (bool) – Optionally return signed URLs for timed public access to that resource (default False)

Return type

Tuple[Optional[Video], Optional[List[Image]]]

Returns

A consisting of the video (if it exists) and a list of individual images (if they exist)

Raises
  • AuthenticationError – If the project API key is invalid.

  • AuthorisationError – If access to the specified resource is restricted.

  • UnknownError – If an error occurs while retrieving the object.

get_websocket_url()[source]#
Return type

str

get_label_logs(user_hash=None, data_hash=None, from_unix_seconds=None, to_unix_seconds=None)[source]#
Return type

List[LabelLog]

get_cloud_integrations()[source]#
Return type

List[CloudIntegration]

Dataset#

class encord.dataset.Dataset(client)[source]#

Access dataset related data and manipulate the dataset.

Expand for references to encord.dataset.Dataset

Authentication / User authentication / Authenticate with Encord - user authentication

Configurations / Network configurations

Datasets / Data / Adding data / Adding data from a private cloud

Datasets / Managing a dataset

property dataset_hash: str#

Get the dataset hash (i.e. the Dataset ID).

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

List[DataRow]

refetch_data()[source]#

The Dataset class will only fetch its properties once. Use this function if you suspect the state of those properties to be dirty.

Return type

None

get_dataset()[source]#

This function is exposed for convenience. You are encouraged to use the property accessors instead.

Return type

Dataset

upload_video(file_path, cloud_upload_settings=CloudUploadSettings(max_retries=None, backoff_factor=None, allow_failures=False), title=None)[source]#

Upload video to Encord storage.

Parameters
  • self – Encord client object.

  • file_path (str) – path to video e.g. ‘/home/user/data/video.mp4’

  • cloud_upload_settings (CloudUploadSettings) – Settings for uploading data into the cloud. Change this object to overwrite the default values.

  • title (Optional[str]) – The video title. If unspecified, this will be the file name. This title should include an extension. For example “encord_video.mp4”.

Returns

Bool.

Raises

UploadOperationNotSupportedError – If trying to upload to external datasets (e.g. S3/GPC/Azure)

create_image_group(file_paths, max_workers=None, cloud_upload_settings=CloudUploadSettings(max_retries=None, backoff_factor=None, allow_failures=False), title=None)[source]#

Create an image group in Encord storage. Choose this type of image upload for sequential images. Else, you can choose the Dataset.upload_image() function.

Parameters
  • self – Encord client object.

  • file_paths (Iterable[str]) – a list of paths to images, e.g. [‘/home/user/data/img1.png’, ‘/home/user/data/img2.png’]

  • max_workers (Optional[int]) – DEPRECATED: This argument will be ignored

  • cloud_upload_settings (CloudUploadSettings) – Settings for uploading data into the cloud. Change this object to overwrite the default values.

  • title (Optional[str]) – The title of the image group. If unspecified this will be randomly generated for you. This title should NOT include an extension. For example “encord_image_group”.

Returns

Bool.

Raises

UploadOperationNotSupportedError – If trying to upload to external datasets (e.g. S3/GPC/Azure)

create_dicom_series(file_paths, cloud_upload_settings=CloudUploadSettings(max_retries=None, backoff_factor=None, allow_failures=False), title=None)[source]#

Upload a DICOM series to Encord storage

Parameters
  • self – Encord client object.

  • file_paths (List[str]) – a list of paths to DICOM files, e.g. [‘/home/user/data/DICOM_1.dcm’, ‘/home/user/data/DICOM_2.dcm’]

  • cloud_upload_settings (CloudUploadSettings) – Settings for uploading data into the cloud. Change this object to overwrite the default values.

  • title (Optional[str]) – The title of the DICOM series. If unspecified this will be randomly generated for you. This title should NOT include an extension. For example “encord_image_group”.

Returns

Bool.

Raises

UploadOperationNotSupportedError – If trying to upload to external datasets (e.g. S3/GPC/Azure)

upload_image(file_path, title=None, cloud_upload_settings=CloudUploadSettings(max_retries=None, backoff_factor=None, allow_failures=False))[source]#

Upload a single image to Encord storage. If your images are sequential we recommend creating an image group via the Dataset.create_image_group() function. For more information please compare https://docs.encord.com/docs/annotate/editor/images and https://docs.encord.com/docs/annotate/editor/videos

Parameters
  • file_path (Union[Path, str]) – The file path to the image

  • title (Optional[str]) – The image title. If unspecified, this will be the file name. This title should include an extension. For example “encord_image.png”.

  • cloud_upload_settings (CloudUploadSettings) – Settings for uploading data into the cloud. Change this object to overwrite the default values.

Return type

Image

delete_image_group(data_hash)[source]#

Delete an image group in Encord storage.

Parameters

data_hash (str) – the hash of the image group to delete

delete_data(data_hashes)[source]#

Delete a video/image group from a dataset.

Parameters
  • self – Encord client object.

  • data_hashes (List[str]) – list of hash of the videos/image_groups you’d like to delete, all should belong to the same dataset

add_private_data_to_dataset(integration_id, private_files, ignore_errors=False)[source]#

Append data hosted on private clouds to existing dataset

Parameters
  • integration_id (str) – str EntityId of the cloud integration to be used when accessing those files

  • private_files (Union[str, Dict, Path, TextIO]) – A str path or Path object to a json file, json str or python dictionary of the files you wish to add

  • ignore_errors (bool) – bool, optional Ignore individual errors when trying to access the specified files

Return type

AddPrivateDataResponse

Returns

add_private_data_response List of DatasetDataInfo objects containing data_hash and title

Expand for references to encord.dataset.Dataset.add_private_data_to_dataset

Datasets / Data / Adding data / Adding data from a private cloud

update_data_item(data_hash, new_title)[source]#

Update a data item

Parameters
  • data_hash (str) – str Data hash of the item being updated

  • new_title (str) – String containing the new title of the data item being updated

Return type

bool

Returns

Returns a boolean for whether the update was successful

re_encode_data(data_hashes)[source]#

Launches an async task that can re-encode a list of videos.

Parameters
  • self – Encord client object.

  • data_hashes (List[str]) – list of hash of the videos you’d like to re_encode, all should belong to the same dataset

Returns

EntityId(integer) of the async task launched.

re_encode_data_status(job_id)[source]#

Returns the status of an existing async task which is aimed at re-encoding videos.

Parameters
  • self – Encord client object.

  • job_id (int) – id of the async task that was launched to re-encode the videos

Returns

Object containing the status of the task, along with info about the new encoded videos

in case the task has been completed

Return type

ReEncodeVideoTask

run_ocr(image_group_id)[source]#

Returns an optical character recognition result for a given image group :type image_group_id: str :param image_group_id: the id of the image group in this dataset to run OCR on

Return type

List[ImageGroupOCR]

Returns

Returns a list of ImageGroupOCR objects representing the text and corresponding coordinates found in each frame of the image group

get_cloud_integrations()[source]#
Return type

List[CloudIntegration]

Ontology#

class encord.ontology.Ontology(querier, config, instance=None)[source]#

Access ontology related data and manipulate the ontology.

property ontology_hash: str#

Get the ontology hash (i.e. the Ontology ID).

Return type

str

property title: str#

Get the title of the ontology.

Return type

str

property description: str#

Get the description of the ontology.

Return type

str

property created_at: datetime.datetime#

Get the time the ontology was created at.

Return type

datetime

property last_edited_at: datetime.datetime#

Get the time the ontology was last edited at.

Return type

datetime

property structure: encord.objects.ontology_structure.OntologyStructure#

Get the structure of the ontology.

Return type

OntologyStructure

refetch_data()[source]#

The Ontology class will only fetch its properties once. Use this function if you suspect the state of those properties to be dirty.

Return type

None

save()[source]#

Sync local state to the server, if updates are made to structure, title or description fields

Return type

None

Client#

encord.client provides a simple Python client that allows you to query project resources through the Encord API.

Here is a simple example for instantiating the client for a project and obtaining project info:

Expand for references to encord.client

Authentication / Resource authentication / Authenticate with Encord - resource authentication

Configurations / Network configurations

class encord.client.EncordClient(querier, config)[source]#

Encord client. Allows you to query db items associated with a project (e.g. label rows, datasets).

Expand for references to encord.client.EncordClient

Authentication / Resource authentication / Authenticate with Encord - resource authentication

static initialise(resource_id=None, api_key=None, domain='https://api.encord.com', requests_settings=RequestsSettings(max_retries=0, backoff_factor=0.1))[source]#

Create and initialize a Encord client from a resource EntityId and API key.

Parameters
  • resource_id (Optional[str]) –

    either of the following

    • A <project_hash>. If None, uses the ENCORD_PROJECT_ID environment variable. The CORD_PROJECT_ID environment variable is supported for backwards compatibility.

    • A <dataset_hash>. If None, uses the ENCORD_DATASET_ID environment variable. The CORD_DATASET_ID environment variable is supported for backwards compatibility.

  • api_key (Optional[str]) – An API key. If None, uses the ENCORD_API_KEY environment variable. The CORD_API_KEY environment variable is supported for backwards compatibility.

  • domain (str) – The encord api-server domain. If None, the encord.configs.ENCORD_DOMAIN is used

  • requests_settings (RequestsSettings) – The RequestsSettings from this config

Returns

A Encord client instance.

Return type

EncordClient

Expand for references to encord.client.EncordClient.initialise

Authentication / Resource authentication / Authenticate with Encord - resource authentication

static initialise_with_config(config)[source]#

Create and initialize a Encord client from a Encord config instance.

Parameters

config (ApiKeyConfig) – A Encord config instance.

Returns

A Encord client instance.

Return type

EncordClient

get_cloud_integrations()[source]#
Return type

List[CloudIntegration]

encord.client.CordClient#

alias of encord.client.EncordClient

class encord.client.EncordClientDataset(querier, config)[source]#

DEPRECATED - prefer using the encord.dataset.Dataset instead

Expand for references to encord.client.EncordClientDataset

Authentication / Resource authentication / Authenticate with Encord - resource authentication

Configurations / Network configurations

get_dataset()[source]#

Retrieve dataset info (pointers to data, labels).

Parameters

self – Encord client object.

Returns

A dataset record instance.

Return type

OrmDataset

Raises
  • AuthorisationError – If the dataset API key is invalid.

  • ResourceNotFoundError – If no dataset exists by the specified dataset EntityId.

  • UnknownError – If an error occurs while retrieving the dataset.

upload_video(file_path, cloud_upload_settings=CloudUploadSettings(max_retries=None, backoff_factor=None, allow_failures=False), title=None)[source]#

This function is documented in encord.dataset.Dataset.upload_video().

create_image_group(file_paths, max_workers=None, cloud_upload_settings=CloudUploadSettings(max_retries=None, backoff_factor=None, allow_failures=False), title=None)[source]#

This function is documented in encord.dataset.Dataset.create_image_group().

create_dicom_series(file_paths, title=None, cloud_upload_settings=CloudUploadSettings(max_retries=None, backoff_factor=None, allow_failures=False))[source]#

This function is documented in encord.dataset.Dataset.create_dicom_series().

upload_image(file_path, title=None, cloud_upload_settings=CloudUploadSettings(max_retries=None, backoff_factor=None, allow_failures=False))[source]#

This function is documented in encord.dataset.Dataset.upload_image().

Return type

Image

delete_image_group(data_hash)[source]#

This function is documented in encord.dataset.Dataset.delete_image_group().

delete_data(data_hashes)[source]#

This function is documented in encord.dataset.Dataset.delete_data().

add_private_data_to_dataset(integration_id, private_files, ignore_errors=False)[source]#

This function is documented in encord.dataset.Dataset.AddPrivateDataResponse().

Return type

AddPrivateDataResponse

update_data_item(data_hash, new_title)[source]#

This function is documented in encord.dataset.Dataset.update_data_item().

Return type

bool

re_encode_data(data_hashes)[source]#

This function is documented in encord.dataset.Dataset.re_encode_data().

re_encode_data_status(job_id)[source]#

This function is documented in encord.dataset.Dataset.re_encode_data_status().

run_ocr(image_group_id)[source]#

This function is documented in encord.dataset.Dataset.run_ocr().

Return type

List[ImageGroupOCR]

encord.client.CordClientDataset#

alias of encord.client.EncordClientDataset

class encord.client.EncordClientProject(querier, config)[source]#

DEPRECATED - prefer using the encord.project.Project instead

Expand for references to encord.client.EncordClientProject

Authentication / Resource authentication / Authenticate with Encord - resource authentication

get_project()[source]#

Retrieve project info (pointers to data, labels).

Parameters

self – Encord client object.

Returns

A project record instance.

Return type

OrmProject

Raises
  • AuthorisationError – If the project API key is invalid.

  • ResourceNotFoundError – If no project exists by the specified project EntityId.

  • UnknownError – If an error occurs while retrieving the project.

list_label_rows(edited_before=None, edited_after=None, label_statuses=None)[source]#
Return type

List[LabelRowMetadata]

set_label_status(label_hash, label_status)[source]#

This function is documented in encord.project.Project.set_label_status().

Return type

bool

add_users(user_emails, user_role)[source]#

This function is documented in encord.project.Project.add_users().

Return type

List[ProjectUser]

copy_project(copy_datasets=False, copy_collaborators=False, copy_models=False)[source]#

This function is documented in encord.project.Project.copy_project().

Return type

str

get_label_row(uid, get_signed_url=True, *, include_object_feature_hashes=None, include_classification_feature_hashes=None)[source]#

This function is documented in encord.project.Project.get_label_row().

Return type

LabelRow

get_label_rows(uids, get_signed_url=True, *, include_object_feature_hashes=None, include_classification_feature_hashes=None)[source]#

This function is documented in encord.project.Project.get_label_rows().

Return type

List[LabelRow]

save_label_row(uid, label)[source]#

This function is documented in encord.project.Project.save_label_row().

create_label_row(uid)[source]#

This function is documented in encord.project.Project.create_label_row().

submit_label_row_for_review(uid)[source]#

This function is documented in encord.project.Project.submit_label_row_for_review().

add_datasets(dataset_hashes)[source]#

This function is documented in encord.project.Project.add_datasets().

Return type

bool

remove_datasets(dataset_hashes)[source]#

This function is documented in encord.project.Project.remove_datasets().

Return type

bool

get_project_ontology()[source]#
Return type

Ontology

add_object(name, shape)[source]#

This function is documented in encord.project.Project.add_object().

Return type

bool

add_classification(name, classification_type, required, options=None)[source]#

This function is documented in encord.project.Project.add_classification().

list_models()[source]#

This function is documented in encord.project.Project.list_models().

Return type

List[ModelConfiguration]

get_training_metadata(model_iteration_uids, get_created_at=False, get_training_final_loss=False, get_model_training_labels=False)[source]#

This function is documented in encord.project.Project.get_training_metadata().

Return type

List[TrainingMetadata]

create_model_row(title, description, features, model)[source]#

This function is documented in encord.project.Project.create_model_row().

Return type

str

model_delete(uid)[source]#

This function is documented in encord.project.Project.model_delete().

Return type

bool

model_inference(uid, file_paths=None, base64_strings=None, conf_thresh=0.6, iou_thresh=0.3, device='cuda', detection_frame_range=None, allocation_enabled=False, data_hashes=None, rdp_thresh=0.005)[source]#

This function is documented in encord.project.Project.model_inference().

model_train(uid, label_rows=None, epochs=None, batch_size=24, weights=None, device='cuda')[source]#

This function is documented in encord.project.Project.model_train().

object_interpolation(key_frames, objects_to_interpolate)[source]#

This function is documented in encord.project.Project.object_interpolation().

fitted_bounding_boxes(frames, video)[source]#

This function is documented in encord.project.Project.fitted_bounding_boxes().

get_data(data_hash, get_signed_url=False)[source]#

This function is documented in encord.project.Project.get_data().

Return type

Tuple[Optional[Video], Optional[List[Image]]]

get_websocket_url()[source]#
Return type

str

get_label_logs(user_hash=None, data_hash=None, from_unix_seconds=None, to_unix_seconds=None)[source]#
Return type

List[LabelLog]

encord.client.CordClientProject#

alias of encord.client.EncordClientProject

Encord Objects#

class encord.objects.ontology_structure.OntologyStructure(objects=<factory>, classifications=<factory>)[source]#

This class is currently in BETA. Its API might change in future minor version releases.

objects: List[encord.objects.ontology_object.Object]#
classifications: List[encord.objects.classification.Classification]#
classmethod from_dict(d)[source]#
Parameters

d (dict) – a JSON blob of an “ontology structure” (e.g. from Encord web app)

Raises

KeyError – If the dict is missing a required field.

Return type

OntologyStructure

to_dict()[source]#
Return type

dict

Returns

The dict equivalent to the ontology.

Raises

KeyError – If the dict is missing a required field.

add_object(name, shape, uid=None, color=None, feature_node_hash=None)[source]#

Adds an object class definition to the structure.

structure = ontology_structure.OntologyStructure()

eye = structure.add_object(
    name="Eye",
)
nose = structure.add_object(
    name="Nose",
)
nose_detail = nose.add_attribute(
    encord.objects.common.ChecklistAttribute,
)
nose_detail.add_option(feature_node_hash="2bc17c88", label="Is it a cute nose?")
nose_detail.add_option(feature_node_hash="86eaa4f2", label="Is it a wet nose? ")
Parameters
  • name (str) – the user-visible name of the object

  • shape (Shape) – the kind of object (bounding box, polygon, etc). See encord.objects.common.Shape enum for possible values

  • uid (Optional[int]) – integer identifier of the object. Normally auto-generated; omit this unless the aim is to create an exact clone of existing structure

  • color (Optional[str]) – the color of the object in the label editor. Normally auto-assigned, should be in ‘#1A2B3F’ syntax.

  • feature_node_hash (Optional[str]) – global identifier of the object. Normally auto-generated; omit this unless the aim is to create an exact clone of existing structure

Return type

Object

Returns

the created object class that can be further customised with attributes.

add_classification(uid=None, feature_node_hash=None)[source]#

Adds an classification definition to the ontology.

structure = ontology_structure.OntologyStructure()

cls = structure.add_classification(feature_node_hash="a39d81c0")
cat_standing = cls.add_attribute(
    encord.objects.common.RadioAttribute,
    feature_node_hash="a6136d14",
    name="Is the cat standing?",
    required=True,
)
cat_standing.add_option(feature_node_hash="a3aeb48d", label="Yes")
cat_standing.add_option(feature_node_hash="d0a4b373", label="No")
Parameters
  • uid (Optional[int]) – integer identifier of the object. Normally auto-generated; omit this unless the aim is to create an exact clone of existing structure

  • feature_node_hash (Optional[str]) – global identifier of the object. Normally auto-generated; omit this unless the aim is to create an exact clone of existing structure

Return type

Classification

Returns

the created classification node. Note that classification attribute should be further specified by calling its add_attribute() method.

class encord.objects.ontology_object.Object(uid, name, color, shape, feature_node_hash, attributes=<factory>)[source]#

This class is currently in BETA. Its API might change in future minor version releases.

uid: int#
name: str#
color: str#
shape: encord.objects.common.Shape#
feature_node_hash: str#
attributes: List[Union[encord.objects.common.RadioAttribute, encord.objects.common.ChecklistAttribute, encord.objects.common.TextAttribute]]#
classmethod from_dict(d)[source]#
Return type

Object

to_dict()[source]#
Return type

dict

T#

alias of TypeVar(‘T’, bound=Union[encord.objects.common.RadioAttribute, encord.objects.common.ChecklistAttribute, encord.objects.common.TextAttribute])

add_attribute(cls, name, local_uid=None, feature_node_hash=None, required=False)[source]#

Adds an attribute to the object.

Parameters
  • cls (Type[T]) – attribute type, one of RadioAttribute, ChecklistAttribute, TextAttribute

  • name (str) – the user-visible name of the attribute

  • local_uid (Optional[int]) – integer identifier of the attribute. Normally auto-generated; omit this unless the aim is to create an exact clone of existing ontology

  • feature_node_hash (Optional[str]) – global identifier of the attribute. Normally auto-generated; omit this unless the aim is to create an exact clone of existing ontology

  • required (bool) – whether the label editor would mark this attribute as ‘required’

Return type

T

Returns

the created attribute that can be further specified with Options, where appropriate

Raises

ValueError – if specified local_uid or feature_node_hash violate uniqueness constraints

class encord.objects.classification.Classification(uid, feature_node_hash, attributes)[source]#

This class is currently in BETA. Its API might change in future minor version releases.

Represents a whole-image classification as part of Ontology structure. Wraps a single Attribute that describes the image in general rather then individual object.

uid: int#
feature_node_hash: str#
attributes: List[Union[encord.objects.common.RadioAttribute, encord.objects.common.ChecklistAttribute, encord.objects.common.TextAttribute]]#
classmethod from_dict(d)[source]#
Return type

Classification

to_dict()[source]#
Return type

dict

T#

alias of TypeVar(‘T’, bound=Union[encord.objects.common.RadioAttribute, encord.objects.common.ChecklistAttribute, encord.objects.common.TextAttribute])

add_attribute(cls, name, local_uid=None, feature_node_hash=None, required=False)[source]#

Adds an attribute to the classification.

Parameters
  • cls (Type[T]) – attribute type, one of RadioAttribute, ChecklistAttribute, TextAttribute

  • name (str) – the user-visible name of the attribute

  • local_uid (Optional[int]) – integer identifier of the attribute. Normally auto-generated; omit this unless the aim is to create an exact clone of existing ontology

  • feature_node_hash (Optional[str]) – global identifier of the attribute. Normally auto-generated; omit this unless the aim is to create an exact clone of existing ontology

  • required (bool) – whether the label editor would mark this attribute as ‘required’

Return type

T

Returns

the created attribute that can be further specified with Options, where appropriate

Raises

ValueError – if the classification already has an attribute assigned

class encord.objects.common.PropertyType(value)[source]#

An enumeration.

RADIO = 'radio'#
TEXT = 'text'#
CHECKLIST = 'checklist'#
class encord.objects.common.Shape(value)[source]#

An enumeration.

BOUNDING_BOX = 'bounding_box'#
POLYGON = 'polygon'#
POINT = 'point'#
SKELETON = 'skeleton'#
POLYLINE = 'polyline'#
ROTATABLE_BOUNDING_BOX = 'rotatable_bounding_box'#
class encord.objects.common.RadioAttribute(uid, feature_node_hash, name, required, options=<factory>)[source]#

This class is currently in BETA. Its API might change in future minor version releases.

options: List[encord.objects.common.NestableOption]#
get_property_type()[source]#
Return type

PropertyType

classmethod has_options_field()[source]#
Return type

bool

add_option(label, value=None, local_uid=None, feature_node_hash=None)[source]#
Parameters
  • label (str) – user-visible name of the option

  • value (Optional[str]) – internal unique value; optional; normally mechanically constructed from the label

  • local_uid (Optional[int]) – integer identifier of the option. Normally auto-generated; omit this unless the aim is to create an exact clone of existing ontology

  • feature_node_hash (Optional[str]) – global identifier of the option. Normally auto-generated; omit this unless the aim is to create an exact clone of existing ontology

Return type

NestableOption

Returns

a NestableOption instance attached to the attribute. This can be further specified by adding nested attributes.

class encord.objects.common.ChecklistAttribute(uid, feature_node_hash, name, required, options=<factory>)[source]#

This class is currently in BETA. Its API might change in future minor version releases.

options: List[encord.objects.common.FlatOption]#
get_property_type()[source]#
Return type

PropertyType

classmethod has_options_field()[source]#
Return type

bool

add_option(label, value=None, local_uid=None, feature_node_hash=None)[source]#
Parameters
  • label (str) – user-visible name of the option

  • value (Optional[str]) – internal unique value; optional; normally mechanically constructed from the label

  • local_uid (Optional[int]) – integer identifier of the option. Normally auto-generated; omit this unless the aim is to create an exact clone of existing ontology

  • feature_node_hash (Optional[str]) – global identifier of the option. Normally auto-generated; omit this unless the aim is to create an exact clone of existing ontology

Returns

a FlatOption instance attached to the attribute.

class encord.objects.common.TextAttribute(uid, feature_node_hash, name, required)[source]#

This class is currently in BETA. Its API might change in future minor version releases.

get_property_type()[source]#
Return type

PropertyType

classmethod has_options_field()[source]#
Return type

bool

uid: List[int]#
feature_node_hash: str#
name: str#
required: bool#
encord.objects.common.Attribute#

This class is currently in BETA. Its API might change in future minor version releases.

alias of Union[encord.objects.common.RadioAttribute, encord.objects.common.ChecklistAttribute, encord.objects.common.TextAttribute]

encord.objects.common.OptionAttribute#

This class is currently in BETA. Its API might change in future minor version releases.

alias of Union[encord.objects.common.RadioAttribute, encord.objects.common.ChecklistAttribute]

encord.objects.common.attribute_from_dict(d)[source]#

Convenience functions as you cannot call static member on union types.

Return type

Union[RadioAttribute, ChecklistAttribute, TextAttribute]

encord.objects.common.attributes_to_list_dict(attributes)[source]#
Return type

list

class encord.objects.common.OptionType(value)[source]#

An enumeration.

FLAT = 1#
NESTABLE = 2#
class encord.objects.common.FlatOption(uid, feature_node_hash, label, value)[source]#

This class is currently in BETA. Its API might change in future minor version releases.

get_option_type()[source]#
Return type

OptionType

classmethod from_dict(d)[source]#
Return type

FlatOption

uid: List[int]#
feature_node_hash: str#
label: str#
value: str#
class encord.objects.common.NestableOption(uid, feature_node_hash, label, value, nested_options=<factory>)[source]#

This class is currently in BETA. Its API might change in future minor version releases.

nested_options: List[Union[encord.objects.common.RadioAttribute, encord.objects.common.ChecklistAttribute, encord.objects.common.TextAttribute]]#
get_option_type()[source]#
Return type

OptionType

classmethod from_dict(d)[source]#
Return type

NestableOption

add_nested_option(cls, name, local_uid=None, feature_node_hash=None, required=False)[source]#

Adds a nested attribute to a RadioAttribute option.

Parameters
  • cls (Type[~T]) – attribute type, one of RadioAttribute, ChecklistAttribute, TextAttribute

  • name (str) – the user-visible name of the attribute

  • local_uid (Optional[int]) – integer identifier of the attribute. Normally auto-generated; omit this unless the aim is to create an exact clone of existing ontology

  • feature_node_hash (Optional[str]) – global identifier of the object. Normally auto-generated; omit this unless the aim is to create an exact clone of existing ontology

  • required (bool) – whether the label editor would mark this attribute as ‘required’

Return type

~T

Returns

the created attribute that can be further specified with Options, where appropriate

Raises

ValueError – if specified local_uid or feature_node_hash violate uniqueness constraints

encord.objects.common.Option#

This class is currently in BETA. Its API might change in future minor version releases.

alias of Union[encord.objects.common.FlatOption, encord.objects.common.NestableOption]

class encord.objects.project.ProjectDataset(dataset_hash, title, description)[source]#
dataset_hash: str#
title: str#
description: str#
static from_dict(d)[source]#
Return type

ProjectDataset

classmethod from_list(l)[source]#
Return type

List[ProjectDataset]

Project Ontology#

class encord.project_ontology.classification_attribute.ClassificationAttribute(id, name, classification_type, required, feature_node_hash, options=None)[source]#

A dataclass which holds classification attributes.

id: str#

A unique (to the ontology) identifier of the attribute.

name: str#

The descriptive name of the attribute.

classification_type: encord.project_ontology.classification_type.ClassificationType#

What type of attribute it is. E.g., Checkbox or radio button.

required: bool#

Whether annotating this attribute is required.

feature_node_hash: str#

An 8-character hex string uniquely defining the attribute.

options: Optional[Iterable[encord.project_ontology.classification_option.ClassificationOption]] = None#

Nested classification options.

class encord.project_ontology.classification_option.ClassificationOption(id, label, value, feature_node_hash)[source]#

A dataclass which holds nested options for the ClassificationAttribute.

id: str#

A unique (to the ontology) identifier of the option.

label: str#

A description of the option.

value: str#

A snake-case concatenated version of the label.

feature_node_hash: str#

An 8-character hex string uniquely defining the option.

Expand for references to encord.project_ontology.classification_type

Projects / Ontology / Adding components to a project ontology / Adding a classification to an ontology

class encord.project_ontology.classification_type.ClassificationType(value)[source]#

Enum used to define classification type in ontologies.

Expand for references to encord.project_ontology.classification_type.ClassificationType

Projects / Ontology / Adding components to a project ontology / Adding a classification to an ontology

RADIO = 'radio'#

Single select option

Expand for references to encord.project_ontology.classification_type.ClassificationType.RADIO

Projects / Ontology / Adding components to a project ontology / Adding a classification to an ontology

TEXT = 'text'#

Text option for free text input.

CHECKLIST = 'checklist'#

Multi select option

Expand for references to encord.project_ontology.object_type

Projects / Ontology / Adding components to a project ontology / Adding an object to an ontology

class encord.project_ontology.object_type.ObjectShape(value)[source]#

An enumeration.

Expand for references to encord.project_ontology.object_type.ObjectShape

Projects / Ontology / Adding components to a project ontology / Adding an object to an ontology

POLYGON = 'polygon'#
POLYLINE = 'polyline'#
BOUNDING_BOX = 'bounding_box'#
KEY_POINT = 'point'#
SKELETON = 'skeleton'#
ROTATABLE_BOUNDING_BOX = 'rotatable_bounding_box'#

Expand for references to encord.project_ontology.ontology

Projects / Ontology / Fetching a project’s ontology

encord.project_ontology.ontology.generate_feature_node_hash()[source]#

Utility function to generate an 8-character hex string.

Return type

str

class encord.project_ontology.ontology.Ontology[source]#

BETA: prefer using encord.objects.ontology_structure.OntologyStructure

Expand for references to encord.project_ontology.ontology.Ontology

Projects / Ontology / Fetching a project’s ontology

COLORS = ('#D33115', '#E27300', '#16406C', '#FE9200', '#FCDC00', '#DBDF00', '#A4DD00', '#68CCCA', '#73D8FF', '#AEA1FF', '#FCC400', '#B0BC00', '#68BC00', '#16A5A5', '#009CE0', '#7B64FF', '#FA28FF', '#B3B3B3', '#9F0500', '#C45100', '#FB9E00', '#808900', '#194D33', '#0C797D', '#0062B1', '#653294', '#AB149E')#
classmethod from_dict(ontology_dict)[source]#

Convert python dictionary too an Ontology object.

Parameters

ontology_dict (Dict) – The dictionary to convert.

add_object(name, shape)[source]#

Add an OntologyObject to the ontology.

Parameters
  • name (str) – A descriptive name of the object.

  • shape (ObjectShape) – The shape of the object.

Return type

None

add_classification(name, classification_type, required, options=None)[source]#

Add a classification to the ontology.

Parameters
  • name (str) – A descriptive name of the classification.

  • classification_type (ClassificationType) – The type of the classification.

  • required (bool) – Indicate whether annotating this classification is required.

  • options (Optional[Iterable[str]]) – Nested classification options.

Return type

None

to_dict()[source]#

Convert the ontology object to a python dictionary.

Return type

dict

Expand for references to encord.project_ontology.ontology.Ontology.to_dict

Projects / Ontology / Fetching a project’s ontology

ontology_object_to_dict(ontology_object)[source]#
Return type

Dict

ontology_classification_to_dict(ontology_classification)[source]#
Return type

Dict

class encord.project_ontology.ontology_classification.OntologyClassification(id, feature_node_hash, attributes)[source]#

A dataclass which holds classifications of the encord.project_ontology.Ontology.

id: str#

A unique (to the ontology) identifier of the classification.

feature_node_hash: str#

An 8-character hex string uniquely defining the option.

attributes: List[encord.project_ontology.classification_attribute.ClassificationAttribute]#

A List of attributes for the classification.

class encord.project_ontology.ontology_object.OntologyObject(id, color, name, shape, feature_node_hash)[source]#

A dataclass which holds an object for of the encord.project_ontology.Ontology.

id: str#

A unique (to the ontology) identifier of the classification.

color: str#

The color which is displayed in the web-app.

name: str#

The name of the object.

shape: encord.project_ontology.object_type.ObjectShape#

The shape of the object. E.g., polygon, polyline, and bounding_box.

feature_node_hash: str#

An 8-character hex string uniquely defining the option.

Utilities - Client#

Expand for references to encord.utilities.client_utilities

Projects / API keys / Creating a project API key / Creating a project API key with specific rights

Projects / Other Resources / CVAT Integration / Importing with the Encord SDK

encord.utilities.client_utilities.pretty_print(data)[source]#
class encord.utilities.client_utilities.APIKeyScopes(value)[source]#

The APIKeyScope is used to provide specific access rights to a project through EncordUserClient.create_project_api_key(). The options are a follows:

Expand for references to encord.utilities.client_utilities.APIKeyScopes

Projects / API keys / Creating a project API key / Creating a project API key with specific rights

LABEL_READ = 'label.read'#
LABEL_WRITE = 'label.write'#
MODEL_INFERENCE = 'model.inference'#
MODEL_TRAIN = 'model.train'#
LABEL_LOGS_READ = 'label_logs.read'#
ALGO_LIBRARY = 'algo.library'#
class encord.utilities.client_utilities.LocalImport(file_path)[source]#

file_path: Supply the path of the exported folder which contains the images and annotations.xml file. Make sure to select “Save images” when exporting your CVAT Task or Project.

Expand for references to encord.utilities.client_utilities.LocalImport

Projects / Other Resources / CVAT Integration / Importing with the Encord SDK

file_path: str#
encord.utilities.client_utilities.ImportMethod#

Using images/videos in cloud storage as an alternative import method will be supported in the future.

class encord.utilities.client_utilities.Issue(issue_type, instances)[source]#

For each issue_type there may be multiple occurrences which are documented in the instances. The instances list can provide additional information on how the issue was encountered. If there is no additional information available, the instances list will be empty.

issue_type: str#
instances: List[str]#
class encord.utilities.client_utilities.Issues(errors, warnings, infos)[source]#

Any issues that came up during importing a project. These usually come from incompatibilities between data saved on different platforms.

errors: List[encord.utilities.client_utilities.Issue]#
warnings: List[encord.utilities.client_utilities.Issue]#
infos: List[encord.utilities.client_utilities.Issue]#
static from_dict(d)[source]#
Return type

Issues

class encord.utilities.client_utilities.CvatImporterSuccess(project_hash, dataset_hash, issues)[source]#

Expand for references to encord.utilities.client_utilities.CvatImporterSuccess

Projects / Other Resources / CVAT Integration / Importing with the Encord SDK

project_hash: str#
dataset_hash: str#
issues: encord.utilities.client_utilities.Issues#
class encord.utilities.client_utilities.CvatImporterError(dataset_hash, issues)[source]#
dataset_hash: str#
issues: encord.utilities.client_utilities.Issues#
encord.utilities.client_utilities.parse_datetime(key, val)[source]#
encord.utilities.client_utilities.optional_set_to_list(s)[source]#
Return type

Optional[List[~T]]

Utilities - Project User#

Expand for references to encord.utilities.project_user

Projects / Adding users to projects

class encord.utilities.project_user.ProjectUserRole(value)[source]#

An enumeration.

Expand for references to encord.utilities.project_user.ProjectUserRole

Projects / Adding users to projects

ADMIN = 0#
ANNOTATOR = 1#
REVIEWER = 2#
ANNOTATOR_REVIEWER = 3#
TEAM_MANAGER = 4#
class encord.utilities.project_user.ProjectUser(user_email, user_role, project_hash)[source]#
user_email: str#
user_role: encord.utilities.project_user.ProjectUserRole#
project_hash: str#
classmethod from_dict(json_dict)[source]#

Utilities - Label#

Expand for references to encord.utilities.label_utilities

Projects / Labels / Saving label rows

encord.utilities.label_utilities.construct_answer_dictionaries(label_row)[source]#

Adds answer object and classification answer dictionaries from a label row if they do not exist. Integrity checks are conducted upon saving of labels.

Parameters

label_row – A label row.

Returns

A label row instance with updated answer dictionaries

Return type

LabelRow

Expand for references to encord.utilities.label_utilities.construct_answer_dictionaries

Projects / Labels / Saving label rows

encord.utilities.label_utilities.add_answers_to_items(items, classification_answers, object_answers)[source]#

If object_hash (uid) or classification_hash (uid) are not in answer dictionaries, add key entry with empty classification list.

Utilities - ORM classes#

class encord.orm.api_key.ApiKeyMeta(dic)[source]#

ApiKeyMeta contains key information.

ORM:

title, resource_type

DB_FIELDS: collections.OrderedDict = {'resource_type': <class 'str'>, 'title': <class 'str'>}#
NON_UPDATABLE_FIELDS: set = {'resource_type'}#
class encord.orm.base_orm.BaseORM(dic)[source]#

Base ORM for all database objects.

DB_FIELDS: collections.OrderedDict = {}#
NON_UPDATABLE_FIELDS: set = {}#
static from_db_row(row, db_field)[source]#

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

to_dic(time_str=True)[source]#

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

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.

updatable_fields()[source]#
class encord.orm.base_orm.BaseListORM(iter_)[source]#

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

BASE_ORM_TYPE#

alias of encord.orm.base_orm.BaseORM

Expand for references to encord.orm.cloud_integration

Datasets / Data / Adding data / Adding data from a private cloud

class encord.orm.cloud_integration.CloudIntegration(id, title)[source]#

Expand for references to encord.orm.cloud_integration.CloudIntegration

Datasets / Data / Adding data / Adding data from a private cloud

id: str#
title: str#

Expand for references to encord.orm.dataset

Datasets / Data / Adding data / Adding data from a private cloud

Datasets / Data / Re-encoding videos / Check the status of a re-encoding task

Datasets / Creating a dataset

Datasets / API keys / Creating a dataset API key with specific rights

Datasets / API keys / Creating a master API key with full rights

Datasets / API keys / Fetching dataset API keys

class encord.orm.dataset.DatasetUserRole(value)[source]#

An enumeration.

ADMIN = 0#
USER = 1#
class encord.orm.dataset.DataRow(uid, title, data_type, created_at)[source]#
property uid: str#
Return type

str

property title: str#
Return type

str

property data_type: encord.constants.enums.DataType#
Return type

DataType

property created_at: datetime.datetime#
Return type

datetime

classmethod from_dict(json_dict)[source]#
Return type

DataRow

classmethod from_dict_list(json_list)[source]#
Return type

List[DataRow]

class encord.orm.dataset.DatasetInfo(dataset_hash, user_hash, title, description, type, created_at, last_edited_at)[source]#

This class represents a dataset in the context of listing

Expand for references to encord.orm.dataset.DatasetInfo

Datasets / Listing existing datasets

dataset_hash: str#
user_hash: str#
title: str#
description: str#
type: int#
created_at: datetime.datetime#
last_edited_at: datetime.datetime#
class encord.orm.dataset.Dataset(title, storage_location, data_rows, dataset_hash, description=None)[source]#
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

List[DataRow]

classmethod from_dict(json_dict)[source]#
Return type

Dataset

class encord.orm.dataset.DatasetDataInfo(data_hash, title)[source]#
data_hash: str#
title: str#
classmethod from_dict(json_dict)[source]#
Return type

DatasetDataInfo

class encord.orm.dataset.AddPrivateDataResponse(dataset_data_list)[source]#

Response of add_private_data_to_dataset

Expand for references to encord.orm.dataset.AddPrivateDataResponse

Datasets / Data / Adding data / Adding data from a private cloud

dataset_data_list: List[encord.orm.dataset.DatasetDataInfo]#
classmethod from_dict(json_dict)[source]#
Return type

AddPrivateDataResponse

class encord.orm.dataset.DatasetAPIKey(dataset_hash, api_key, title, key_hash, scopes)[source]#

Expand for references to encord.orm.dataset.DatasetAPIKey

Datasets / API keys / Creating a dataset API key with specific rights

Datasets / API keys / Creating a master API key with full rights

Datasets / API keys / Fetching dataset API keys

dataset_hash: str#
api_key: str#
title: str#
key_hash: str#
scopes: List[encord.orm.dataset.DatasetScope]#
classmethod from_dict(json_dict)[source]#
Return type

DatasetAPIKey

class encord.orm.dataset.CreateDatasetResponse(title, storage_location, dataset_hash, user_hash)[source]#

Expand for references to encord.orm.dataset.CreateDatasetResponse

Datasets / Creating a dataset

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

classmethod from_dict(json_dict)[source]#
Return type

CreateDatasetResponse

class encord.orm.dataset.StorageLocation(value)[source]#

An enumeration.

Expand for references to encord.orm.dataset.StorageLocation

Datasets / Creating a dataset

CORD_STORAGE = 0#
AWS = 1#
GCP = 2#
AZURE = 3#
OTC = 4#
static from_str(string_location)[source]#
Return type

StorageLocation

get_str()[source]#
Return type

str

encord.orm.dataset.DatasetType#

For backwards compatibility

class encord.orm.dataset.DatasetScope(value)[source]#

An enumeration.

Expand for references to encord.orm.dataset.DatasetScope

Datasets / API keys / Creating a dataset API key with specific rights

READ = 'dataset.read'#
WRITE = 'dataset.write'#
class encord.orm.dataset.DatasetData(dic)[source]#

Video base ORM.

DB_FIELDS: collections.OrderedDict = {'data_hash': <class 'str'>, 'images': <class 'list'>, 'video': <class 'dict'>}#
class encord.orm.dataset.SignedVideoURL(dic)[source]#

A signed URL object with supporting information.

DB_FIELDS: collections.OrderedDict = {'data_hash': <class 'str'>, 'file_link': <class 'str'>, 'signed_url': <class 'str'>, 'title': <class 'str'>}#
class encord.orm.dataset.SignedImageURL(dic)[source]#

A signed URL object with supporting information.

DB_FIELDS: collections.OrderedDict = {'data_hash': <class 'str'>, 'file_link': <class 'str'>, 'signed_url': <class 'str'>, 'title': <class 'str'>}#
class encord.orm.dataset.SignedImagesURL(iter_)[source]#

A signed URL object with supporting information.

BASE_ORM_TYPE#

alias of encord.orm.dataset.SignedImageURL

class encord.orm.dataset.SignedDicomURL(dic)[source]#

A signed URL object with supporting information.

DB_FIELDS: collections.OrderedDict = {'data_hash': <class 'str'>, 'file_link': <class 'str'>, 'signed_url': <class 'str'>, 'title': <class 'str'>}#
class encord.orm.dataset.SignedDicomsURL(iter_)[source]#

A signed URL object with supporting information.

BASE_ORM_TYPE#

alias of encord.orm.dataset.SignedDicomURL

class encord.orm.dataset.Video(dic)[source]#

A video object with supporting information.

DB_FIELDS: collections.OrderedDict = {'data_hash': <class 'str'>, 'file_link': <class 'str'>, 'title': <class 'str'>}#
NON_UPDATABLE_FIELDS: set = {'data_hash'}#
class encord.orm.dataset.ImageGroup(dic)[source]#

An image group object with supporting information.

DB_FIELDS: collections.OrderedDict = {'data_hash': <class 'str'>, 'file_link': <class 'str'>, 'title': <class 'str'>}#
NON_UPDATABLE_FIELDS: set = {'data_hash'}#
class encord.orm.dataset.Image(dic)[source]#

An image object with supporting information.

DB_FIELDS: collections.OrderedDict = {'data_hash': <class 'str'>, 'file_link': <class 'str'>, 'title': <class 'str'>}#
NON_UPDATABLE_FIELDS: set = {'data_hash'}#
class encord.orm.dataset.SingleImage(dic)[source]#

For native single image upload.

success: bool#
class encord.orm.dataset.Images(success)[source]#

Uploading multiple images in a batch mode.

success: bool#
class encord.orm.dataset.DicomSeries(data_hash, title)[source]#
data_hash: str#
title: str#
class encord.orm.dataset.ImageGroupOCR(processed_texts)[source]#
processed_texts: Dict#
class encord.orm.dataset.ReEncodeVideoTaskResult(data_hash, signed_url, bucket_path)[source]#
data_hash: str#
signed_url: Optional[str]#
bucket_path: str#
class encord.orm.dataset.ReEncodeVideoTask(status, result=None)[source]#

A re encode video object with supporting information.

Expand for references to encord.orm.dataset.ReEncodeVideoTask

Datasets / Data / Re-encoding videos / Check the status of a re-encoding task

status: str#
result: List[encord.orm.dataset.ReEncodeVideoTaskResult] = None#
classmethod from_dict(json_dict)[source]#
class encord.orm.dataset_with_user_role.DatasetWithUserRole(user_role, dataset)[source]#

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

user_role: str#
dataset: dict#
class encord.orm.formatter.Formatter[source]#
abstract classmethod from_dict(json_dict)[source]#
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)[source]#
log_hash: str#
user_hash: str#
user_email: str#
annotation_hash: str#
identifier: str#
data_hash: str#
feature_hash: str#
action: Action#
label_name: str#
time_taken: int#
created_at: datetime.datetime#
frame: int#
class encord.orm.label_log.Action(value)[source]#

An enumeration.

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#
class encord.orm.label_row.LabelRow(dic)[source]#

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 that this does not reflect thes status shown in the Projects->Labels section on the web-app.

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: collections.OrderedDict = {'classification_answers': <class 'dict'>, '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'>, 'object_actions': <class 'dict'>, 'object_answers': <class 'dict'>}#
NON_UPDATABLE_FIELDS: set = {'label_hash'}#
class encord.orm.label_row.Review[source]#
class encord.orm.label_row.AnnotationTaskStatus(value)[source]#

An enumeration.

QUEUED = 'QUEUED'#
ASSIGNED = 'ASSIGNED'#
IN_REVIEW = 'IN_REVIEW'#
RETURNED = 'RETURNED'#
COMPLETED = 'COMPLETED'#
class encord.orm.label_row.LabelStatus(value)[source]#

An enumeration.

NOT_LABELLED = 'NOT_LABELLED'#
LABEL_IN_PROGRESS = 'LABEL_IN_PROGRESS'#
LABELLED = 'LABELLED'#
REVIEW_IN_PROGRESS = 'REVIEW_IN_PROGRESS'#
REVIEWED = 'REVIEWED'#
REVIEWED_TWICE = 'REVIEWED_TWICE'#
class encord.orm.label_row.LabelRowMetadata(label_hash, data_hash, dataset_hash, data_title, data_type, label_status, annotation_task_status)[source]#

Contains helpful information about a LabelRow.

label_hash: str#
data_hash: str#
dataset_hash: str#
data_title: str#
data_type: str#
label_status: encord.orm.label_row.LabelStatus#
annotation_task_status: encord.orm.label_row.AnnotationTaskStatus#
classmethod from_dict(json_dict)[source]#
Return type

LabelRowMetadata

classmethod from_list(json_list)[source]#
Return type

List[LabelRowMetadata]

class encord.orm.labeling_algorithm.LabelingAlgorithm(dic)[source]#

Labeling algorithm base ORM.

ORM:

algorithm_name, algorithm_params

DB_FIELDS: collections.OrderedDict = {'algorithm_name': <class 'str'>, 'algorithm_parameters': <class 'dict'>}#
class encord.orm.labeling_algorithm.ObjectInterpolationParams(dic)[source]#

Labeling algorithm parameters for interpolation algorithm

ORM:

key_frames, objects_to_interpolate

DB_FIELDS: collections.OrderedDict = {'key_frames': <class 'dict'>, 'objects_to_interpolate': <class 'list'>}#
class encord.orm.labeling_algorithm.BoundingBoxFittingParams(dic)[source]#

Labeling algorithm parameters for bounding box fitting algorithm

ORM:

labels, video

DB_FIELDS: collections.OrderedDict = {'labels': <class 'dict'>, 'video': <class 'dict'>}#
class encord.orm.model.ModelOperations(value)[source]#

An enumeration.

INFERENCE = 0#
TRAIN = 1#
CREATE = 2#
class encord.orm.model.Model(dic)[source]#

Model base ORM.

ORM:

model_operation, model_parameters,

DB_FIELDS: collections.OrderedDict = {'model_operation': <class 'int'>, 'model_parameters': <class 'dict'>}#
class encord.orm.model.ModelConfiguration(model_uid, title, description, feature_node_hashes, model, model_iteration_uids)[source]#
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

classmethod from_dict(json_dict)[source]#
class encord.orm.model.ModelTrainingLabelMetadata(label_uid, data_uid, data_link)[source]#
label_uid: str#
data_uid: str#
static from_dict(json_dict)[source]#
Return type

ModelTrainingLabelMetadata

classmethod from_list(json_list)[source]#
Return type

List[ModelTrainingLabelMetadata]

class encord.orm.model.ModelTrainingLabel(label_metadata_list, feature_uids)[source]#
label_metadata_list: List[encord.orm.model.ModelTrainingLabelMetadata]#
feature_uids: List[str]#
static from_dict(json_dict)[source]#
Return type

ModelTrainingLabel

class encord.orm.model.TrainingMetadata(model_iteration_uid, created_at=None, training_final_loss=None, model_training_labels=None)[source]#
model_iteration_uid: str#
created_at: Optional[datetime.datetime] = None#
training_final_loss: Optional[float] = None#
model_training_labels: Optional[List[encord.orm.model.ModelTrainingLabel]] = None#
classmethod from_dict(json_dict)[source]#
static get_created_at(json_dict)[source]#
Return type

Optional[datetime]

static get_model_training_labels(json_dict)[source]#
Return type

Optional[List[ModelTrainingLabel]]

class encord.orm.model.ModelRow(dic)[source]#

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

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 encord.orm.model.ModelInferenceParams(dic)[source]#

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: 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 encord.orm.model.ModelTrainingWeights(dic)[source]#

Model training weights.

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 encord.orm.model.ModelTrainingParams(dic)[source]#

Model training parameters.

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 encord.orm.project.Project(dic)[source]#

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: 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'>, 'title': <class 'str'>}#
NON_UPDATABLE_FIELDS: set = {'datasets', 'editor_ontology', 'label_rows'}#
get_labels_list()[source]#

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 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#
property title#
property description#
property editor_ontology#
property datasets#
property label_rows#
property ontology_hash#
class encord.orm.project.ProjectCopy[source]#
class encord.orm.project.ProjectUsers[source]#
class encord.orm.project.ProjectDataset[source]#
class encord.orm.project.ProjectCopyOptions(value)[source]#

An enumeration.

COLLABORATORS = 'collaborators'#
DATASETS = 'datasets'#
MODELS = 'models'#
class encord.orm.project.StringEnum(value)[source]#

Use this enum class if you need the helper that creates the enum instance from a string.

classmethod from_string(string)[source]#
Return type

Optional[StringEnum]

class encord.orm.project.ReviewMode(value)[source]#
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'#
class encord.orm.project.ProjectImporter(dic)[source]#
DB_FIELDS: collections.OrderedDict = {'errors': <class 'list'>, 'project_hash': typing.Union[str, NoneType]}#
class encord.orm.project.CvatExportType(value)[source]#

An enumeration.

PROJECT = 'project'#
TASK = 'task'#
class encord.orm.project.ProjectImporterCvatInfo(dic)[source]#
DB_FIELDS: collections.OrderedDict = {'export_type': <enum 'CvatExportType'>}#

Expand for references to encord.orm.project_api_key

Projects / API keys / Fetching project API keys

class encord.orm.project_api_key.ProjectAPIKey(api_key, title, scopes)[source]#

Expand for references to encord.orm.project_api_key.ProjectAPIKey

Projects / API keys / Fetching project API keys

api_key: str#
title: str#
scopes: List[encord.utilities.client_utilities.APIKeyScopes]#
classmethod from_dict(json_dict)[source]#
class encord.orm.project_with_user_role.ProjectWithUserRole(user_role, project)[source]#

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

user_role: int#
project: dict#

Utilities - Other#

class encord.http.utils.CloudUploadSettings(max_retries=None, backoff_factor=None, allow_failures=False)[source]#

The settings for uploading data into the GCP cloud storage. These apply for each individual upload. These settings will overwrite the encord.http.constants.RequestsSettings() which is set during encord.EncordUserClient creation.

max_retries: Optional[int] = None#

Number of allowed retries when uploading

backoff_factor: Optional[float] = None#

With each retry, there will be a sleep of backoff_factor * (2 ** retry_number)

allow_failures: bool = False#

If failures are allowed, the upload will continue even if some items were not successfully uploaded even after retries. For example, upon creation of a large image group, you might want to create the image group even if a few images were not successfully uploaded. The unsuccessfully uploaded images will then be logged.

Expand for references to encord.http.constants

Configurations / Network configurations

class encord.http.constants.RequestsSettings(max_retries=0, backoff_factor=0.1)[source]#

The settings for all outgoing network requests. These apply for each individual request.

Expand for references to encord.http.constants.RequestsSettings

Configurations / Network configurations

max_retries: int = 0#

Number of allowed retries when a request is sent.

backoff_factor: float = 0.1#

With each retry, there will be a sleep of backoff_factor * (2 ** retry_number)

encord.utilities.project_utilities.get_all_model_iteration_uids(model_configurations)[source]#

A convenience function that works well with encord.project.Project.list_models()

Return type

Set[str]

Configs#

class encord.configs.BaseConfig(endpoint, requests_settings=RequestsSettings(max_retries=0, backoff_factor=0.1))[source]#
abstract define_headers(data)[source]#
Return type

Dict

class encord.configs.UserConfig(private_key, domain='https://api.encord.com', requests_settings=RequestsSettings(max_retries=0, backoff_factor=0.1))[source]#
define_headers(data)[source]#
Return type

Dict

static from_ssh_private_key(ssh_private_key, password='', requests_settings=RequestsSettings(max_retries=0, backoff_factor=0.1), **kwargs)[source]#

Instantiate a UserConfig object by the content of a private ssh key.

Parameters
  • ssh_private_key (str) – The content of a private key file.

  • password (Optional[str]) – The password for the private key file.

  • requests_settings (RequestsSettings) – The requests settings for all outgoing network requests.

Returns

UserConfig.

Raises

ValueError – If the provided key content is not of the correct format.

class encord.configs.Config(resource_id=None, web_file_path='/public', domain=None, websocket_endpoint='wss://message-api.cord.tech/websocket', requests_settings=RequestsSettings(max_retries=0, backoff_factor=0.1))[source]#

Config defining endpoint, project id, API key, and timeouts.

abstract get_websocket_url()[source]#
encord.configs.get_env_resource_id()[source]#
Return type

str

encord.configs.get_env_api_key()[source]#
Return type

str

encord.configs.get_env_ssh_key()[source]#

Returns the raw ssh key by looking up the ENCORD_SSH_KEY_FILE and ENCORD_SSH_KEY environment variables in the mentioned order and returns the first successfully identified key.

Return type

str

class encord.configs.ApiKeyConfig(resource_id=None, api_key=None, domain=None, requests_settings=RequestsSettings(max_retries=0, backoff_factor=0.1))[source]#
define_headers(data)[source]#
Return type

Dict

get_websocket_url()[source]#
encord.configs.EncordConfig#

alias of encord.configs.ApiKeyConfig

encord.configs.CordConfig#

alias of encord.configs.ApiKeyConfig

class encord.configs.SshConfig(user_config, resource_type, resource_id=None)[source]#
define_headers(data)[source]#
Return type

Dict

get_websocket_url()[source]#
encord.configs.ENCORD_DOMAIN = 'https://api.encord.com'

str(object=’’) -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to ‘strict’.

Exceptions#

exception encord.exceptions.EncordException(message)[source]#

Base class for all exceptions.

encord.exceptions.CordException#

alias of encord.exceptions.EncordException

exception encord.exceptions.InitialisationError(message)[source]#

Exception thrown when API key fails to initialise.

exception encord.exceptions.AuthenticationError(message)[source]#

Exception thrown when API key fails authentication.

exception encord.exceptions.AuthorisationError(message)[source]#

Exception thrown when access is unauthorised. (E.g. access to a data asset or method).

exception encord.exceptions.ResourceNotFoundError(message)[source]#

Exception thrown when a requested resource is not found. (E.g. label, data asset).

exception encord.exceptions.TimeOutError(message)[source]#

Exception thrown when a request times out.

exception encord.exceptions.RequestException(message)[source]#

Ambiguous exception while handling request.

exception encord.exceptions.UnknownException(message)[source]#

Unknown error.

exception encord.exceptions.InvalidDateFormatError(message)[source]#

Invalid date format error

exception encord.exceptions.MethodNotAllowedError(message)[source]#

Exception thrown when HTTP method is not allowed.

exception encord.exceptions.OperationNotAllowed(message)[source]#

Exception thrown when a read/write operation is not allowed. The API key blocks the operation.

exception encord.exceptions.AnswerDictionaryError(message)[source]#

Exception thrown when answer dictionaries are incomplete. Occurs when an object or classification is missing.

exception encord.exceptions.CorruptedLabelError(message)[source]#

Exception thrown when a label is corrupted. (E.g. the frame labels have more frames than the video).

exception encord.exceptions.FileTypeNotSupportedError(message)[source]#

Exception thrown when a file type is not supported. Supported file types are: image/jpeg, image/png, video/webm, video/mp4.

exception encord.exceptions.FileSizeNotSupportedError(message)[source]#

Exception thrown when the combined size of the input files is larger than the supported limit.

exception encord.exceptions.FeatureDoesNotExistError(message)[source]#

If a feature uid does not exist in a given project ontology.

exception encord.exceptions.ModelWeightsInconsistentError(message)[source]#

Exception thrown when an attempted model training iteration has a different type of weights than what is recorded (i.e. if type of model_hash (uid) is faster_rcnn, but is attempted trained with yolov5 weights).

exception encord.exceptions.ModelFeaturesInconsistentError(message)[source]#

If a feature type is different than what is supported by the model (e.g. if creating a classification model using a bounding box).

exception encord.exceptions.UploadOperationNotSupportedError(message)[source]#

Exception thrown when trying to upload a video/image group to non-Encord storage dataset

exception encord.exceptions.DetectionRangeInvalidError(message)[source]#

Exception thrown when a detection range is invalid. (E.g. negative or higher than num frames in video).

exception encord.exceptions.InvalidAlgorithmError(message)[source]#

Exception thrown when invalid labeling algorithm name is sent.

exception encord.exceptions.ResourceExistsError(message)[source]#

Exception thrown when trying to re-create a resource. Avoids overriding existing work.

exception encord.exceptions.DuplicateSshKeyError(message)[source]#

Exception thrown when using an SSH key that was added twice to the platform.

exception encord.exceptions.SshKeyNotFound(message)[source]#

Exception thrown when using an SSH key that was not added to the platform.

exception encord.exceptions.InvalidArgumentsError(message)[source]#

Exception thrown when the arguments are invalid.

exception encord.exceptions.GenericServerError(message)[source]#

The server has reported an error which is not recognised by this SDK version. Try upgrading the SDK version to see the precise error that is reported.

exception encord.exceptions.CloudUploadError(message)[source]#

The upload to the cloud was not successful

exception encord.exceptions.MultiLabelLimitError(message, maximum_labels_allowed)[source]#

Too many labels were requested