Objects.ontology labels impl

LabelRowV2 Objects

class LabelRowV2()

This class represents a single label row. It corresponds to exactly one data row within a project and holds all the labels for that data row.

You can access many metadata fields with this class directly. To read or write labels, you need to call initialise_labels() first. To upload your added labels, call save().

is_event_based

@property
def is_event_based() -> bool

Whether this label row is on a continuous timeline instead of a frame grid.

This is True for scenes from self-contained (MCAP) recordings, and False for all other label rows. On an event-based label row, frame numbers are nanosecond offsets from the start of the recording, and classifications are stored as ranges instead of one entry per frame.

Geometric objects on an event-based label row are stored as keyframe events. Per-frame reads on an ObjectInstance return read-only views, and per-frame writes raise an error. Use ObjectInstance.upsert_event and ObjectInstance.delete_event to write them instead.

Returns:

• bool - True if the label row is event-based, False otherwise.

Raises:

• LabelRowError - If labels have not been initialized.

from_media_metadata

@classmethod
def from_media_metadata(cls,
                        ontology: Ontology,
                        media_metadata: Union[
                            orm_storage.CustomerProvidedImageMetadata,
                            orm_storage.CustomerProvidedVideoMetadata,
                            orm_storage.CustomerProvidedAudioMetadata,
                            orm_storage.CustomerProvidedTextMetadata,
                            orm_storage.CustomerProvidedPdfMetadata,
                            List[orm_storage.CustomerProvidedImageMetadata],
                        ],
                        *,
                        branch_name: str = "main") -> "LabelRowV2"

Create a detached label row from media metadata, without connecting to the Encord platform.

Detached label rows can be used to generate labels programmatically for media files before they’re uploaded. Labels can be serialized via to_encord_dict() for later bulk ingestion.

Server-dependent operations (save(), initialise_labels(), workflow_reopen(), workflow_complete(), etc.) will raise LabelRowError on a detached label row. Use attach_to_project() to connect to a real project.

The serialized dict from to_encord_dict() contains placeholder (zero) UUIDs for identity fields (label_hash, data_hash, dataset_hash). These are replaced with real server-side values when attached to a project.

Arguments:

• ontology - The ontology to use for label creation.

• media_metadata - Metadata describing the media file. The data type is inferred from the metadata class:

  • CustomerProvidedImageMetadata -> IMAGE
  • CustomerProvidedVideoMetadata -> VIDEO
  • CustomerProvidedAudioMetadata -> AUDIO
  • CustomerProvidedTextMetadata -> PLAIN_TEXT
  • CustomerProvidedPdfMetadata -> PDF
  • List[CustomerProvidedImageMetadata] -> IMG_GROUP

• branch_name - Branch name for the label row. Defaults to "main".

Returns:

A detached LabelRowV2 instance with labels initialized.

label_hash

@property
def label_hash() -> Optional[str]

Returns the hash of the label row.

Returns:

• Optional[str] - The label row hash or None if not set.

branch_name

@property
def branch_name() -> str

Returns the branch name of the label row.

Returns:

• str - The branch name.

data_hash

@property
def data_hash() -> str

Returns the hash of the data row.

Returns:

• str - The data row hash.

group_hash

@property
def group_hash() -> Optional[str]

Returns the hash of the data group that this data unit belongs to.

Only set if this label row is a child of a data group.

Returns:

• Optional[str] - The data group hash, or None if the data unit is not part of a data group.

dataset_hash

@property
def dataset_hash() -> str

Returns the hash of the dataset.

Returns:

• str - The dataset hash.

dataset_title

@property
def dataset_title() -> str

Returns the title of the dataset.

Returns:

• str - The dataset title.

data_title

@property
def data_title() -> str

Returns the title of the data row.

Returns:

• str - The data row title.

data_type

@property
def data_type() -> DataType

Returns the data type of the label row.

Returns:

• DataType - The data type.

file_type

@property
def file_type() -> Optional[str]

Returns the MIME type of the file, for example image/jpeg, video/mp4, or text/html.

This is None for image groups once labels are initialized, because an image group has no single underlying file. Use get_frames_metadata() to get the file type of each image.

Returns:

• Optional[str] - The MIME type, or None if not set.

client_metadata

@property
def client_metadata() -> Optional[dict]

Returns the client metadata of the data unit.

This is only populated if the label row was listed with include_client_metadata=True, for example project.list_label_rows_v2(include_client_metadata=True). Otherwise, it is None.

Returns:

• Optional[dict] - The client metadata, or None if it was not requested or is not set.

label_status

@property
def label_status() -> LabelStatus

Returns the current labeling status of the label row.

Only supported for projects that don’t use workflows. For workflow projects, use workflow_graph_node instead.

For more details, see the workflow documentation.

Returns:

• LabelStatus - The current labeling status.

Raises:

• WrongProjectTypeError - If used with a workflow project.

annotation_task_status

@property
def annotation_task_status() -> AnnotationTaskStatus

Returns the current annotation task status of the label row.

Only supported for projects that don’t use workflows. For workflow projects, use workflow_graph_node instead.

For more details, see the workflow documentation.

Returns:

• AnnotationTaskStatus - The current annotation task status.

Raises:

• WrongProjectTypeError - If used with a workflow project.

workflow_graph_node

@property
def workflow_graph_node() -> Optional[WorkflowGraphNode]

Returns the workflow graph node associated with the label row.

Returns:

• Optional[WorkflowGraphNode] - The workflow graph node or None if not set.

is_shadow_data

@property
def is_shadow_data() -> bool

Indicates whether the data unit is shadow data.

Shadow data is a per-user copy of a data unit. Encord creates shadow data when a project is linked to a source project for Benchmark QA or annotator training.

Returns:

• bool - True if the data unit is shadow data, False otherwise.

created_at

@property
def created_at() -> Optional[datetime]

Returns the creation date of the label row.

Returns:

• Optional[datetime] - The creation date or None if not yet created.

last_edited_at

@property
def last_edited_at() -> Optional[datetime]

Returns the last edited date of the label row.

Returns:

• Optional[datetime] - The last edited date or None if not yet edited.

number_of_frames

@property
def number_of_frames() -> int

Returns the number of frames in the label row.

Returns:

• int - The number of frames.

duration

@property
def duration() -> Optional[float]

Returns the duration of the video data type.

Returns:

• Optional[float] - The duration or None if not applicable.

fps

@property
def fps() -> Optional[float]

Returns the frames per second (fps) of the video data type.

Returns:

• Optional[float] - The fps or None if not applicable.

data_link

@property
def data_link() -> Optional[str]

Returns the data link to the underlying object in either cloud storage or Encord storage. This will be None for DICOM series or image groups created without performance optimizations, as there is no single underlying file for these data types.

This property will contain a signed URL if initialise_labels() was called with include_signed_url=True.

Returns:

• Optional[str] - The data link or None if not applicable.

width

@property
def width() -> Optional[int]

Returns the width of the image data type.

This is None for image groups without performance optimization, as there is no single underlying width for this data type.

Returns:

• Optional[int] - The width or None if not applicable.

height

@property
def height() -> Optional[int]

Returns the height of the image data type.

This is None for image groups without performance optimization, as there is no single underlying height for this data type.

Returns:

• Optional[int] - The height or None if not applicable.

audio_codec

@property
def audio_codec() -> Optional[str]

Returns the codec of the audio data type.

This only applies to audio data types, and returns None for all other data types.

Returns:

• Optional[str] - The codec or None if not applicable.

audio_sample_rate

@property
def audio_sample_rate() -> Optional[int]

Returns the sample rate of the audio data type.

This only applies to audio data types, and returns None for all other data types.

Returns:

• Optional[int] - The sample rate or None if not applicable.

audio_bit_depth

@property
def audio_bit_depth() -> Optional[int]

Returns the bit depth of the audio data type.

This only applies to audio data types, and returns None for all other data types.

Returns:

• Optional[int] - The bit depth or None if not applicable.

audio_num_channels

@property
def audio_num_channels() -> Optional[int]

Returns the number of channels of the audio data type.

This only applies to audio data types, and returns None for all other data types.

Returns:

• Optional[int] - The number of channels or None if not applicable.

backing_item_uuid

@property
def backing_item_uuid() -> Optional[UUID]

Returns the unique identifier (UUID) for the backing storage item associated with this label row.

While it is always included in server responses, it is marked as optional for backward compatibility with earlier versions.

Returns:

• Optional[UUID] - The backing storage item id or None if not found.

task_uuid

@property
def task_uuid() -> Optional[UUID]

Returns the UUID of the workflow task for this data unit.

Only works for workflow projects.

Returns:

• Optional[UUID] - The workflow task UUID, or None if not applicable.

Raises:

• WrongProjectTypeError - If used with a project that doesn’t use workflows.

priority

@property
def priority() -> Optional[float]

Returns the priority of the workflow task for this data unit.

Only works for workflow projects. This is None for label rows in the Complete stage.

Returns:

• Optional[float] - The task priority, from 0.0 to 1.0, or None if not applicable.

Raises:

• WrongProjectTypeError - If used with a project that doesn’t use workflows.

is_valid

@property
def is_valid() -> bool

Indicates if the labels are valid.

For labels uploaded via the SDK, a check is run to ensure that the labels are valid. This property returns True if the labels have correct structure and match the project ontology.

If it is False, then loading the labels via LabelRowV2 will raise an error, and the label editor will not be able to load the labels.

You can call get_validation_errors() to get the validation error messages.

Returns:

• bool - True if the labels are valid, False otherwise.

ontology_structure

@property
def ontology_structure() -> OntologyStructure

Returns the ontology structure of the project that this label row belongs to.

Use it to find the ontology objects and classifications that you need to create object and classification instances, for example with label_row.ontology_structure.get_child_by_title("Car", type_=Object).

Returns:

• OntologyStructure - The ontology structure.

is_labelling_initialised

@property
def is_labelling_initialised() -> bool

Checks whether labels have been initialized.

If this is False, call initialise_labels() before you read or write object or classification instances.

Returns:

• bool - True if labels are initialized, False otherwise.

is_detached

@property
def is_detached() -> bool

Checks whether this label row is detached (not connected to Encord).

Detached label rows are created with from_media_metadata() and can’t perform server operations until you attach them to a project with attach_to_project().

Returns:

• bool - True if the label row is detached, False otherwise.

assigned_user_email

@property
def assigned_user_email() -> Optional[str]

Returns the email of the user assigned to the current annotation or review task.

Only applies to workflow projects. This is None when the task is complete or nobody is assigned.

Returns:

• Optional[str] - The email of the assigned user, or None.

last_actioned_by_user_email

@property
def last_actioned_by_user_email() -> Optional[str]

Returns the email of the user who last acted on the task for this data unit.

Returns:

• Optional[str] - The email of the user who last acted on the task, or None.

get_storage_item

def get_storage_item(get_signed_urls: bool = False) -> StorageItem

Returns the storage item that backs this label row.

Use the storage item to get details such as the storage folder, signed URL, creation date, item type, and client metadata.

The storage item is fetched on the first call (or by initialise_storage_item()) and then cached, so get_signed_urls only takes effect if the item has not been fetched yet. StorageItem.get_signed_url() fetches a signed URL on demand if the cached item doesn’t have one.

Arguments:

• get_signed_urls - If True, request a signed URL when fetching the storage item.

Returns:

• StorageItem - The storage item.

Raises:

• LabelRowError - If the label row is detached or has no backing storage item.

initialise_storage_item

def initialise_storage_item(get_signed_url: bool = False,
                            bundle: Optional[Bundle] = None) -> None

Fetches the storage item that backs this label row from Encord and caches it.

After this call, get_storage_item() returns the cached item without making another request. Pass a bundle to fetch the storage items of many label rows in fewer requests.

Arguments:

• get_signed_url - If True, request a signed URL for the item. You can then read it with label_row.get_storage_item().get_signed_url().
• bundle - If not provided, the storage item is fetched immediately. If provided, the fetch is deferred and performed together with the other operations in the bundle.

Raises:

• LabelRowError - If the label row is detached or has no backing storage item.

initialise_labels

def initialise_labels(include_object_feature_hashes: Optional[Set[str]] = None,
                      include_classification_feature_hashes: Optional[
                          Set[str]] = None,
                      include_reviews: bool = False,
                      include_archived: bool = False,
                      overwrite: bool = False,
                      bundle: Optional[Bundle] = None,
                      *,
                      include_signed_url: bool = False) -> None

Downloads the labels for this label row from Encord so that you can read and edit them.

Call this method (or from_labels_dict()) before you read or write object and classification instances. If the label row doesn’t exist on Encord yet (label_hash is None), this method creates it.

To download only some labels, filter by feature hash. Only use filters to read labels. If you save a label row that was initialized with a filter, the labels that were filtered out are deleted from Encord.

Pass a bundle to initialize many label rows in fewer requests.

Arguments:

• include_object_feature_hashes - If None, all objects are included. Otherwise, only objects with these feature hashes are included. Saving a label row initialized with this filter deletes all other objects from Encord.
• include_classification_feature_hashes - If None, all classifications are included. Otherwise, only classifications with these feature hashes are included. Saving a label row initialized with this filter deletes all other classifications from Encord.
• include_reviews - If True, also download read-only information about the reviews of the label row.
• include_archived - If True, also include labels whose ontology features are archived.
• overwrite - If True, replace any labels already held in this object with the labels stored on Encord. If False and labels are already initialized, an error is raised.
• bundle - If not provided, labels are downloaded immediately. If provided, the download is deferred and performed together with the other operations in the bundle.
• include_signed_url - If True, data_link contains a signed URL.

Raises:

• LabelRowError - If labels are already initialized and overwrite is False, or if the label row is detached.

Example:

label_row = project.list_label_rows_v2(data_title_eq="my_image.jpg")[0]
label_row.initialise_labels()
for object_instance in label_row.get_object_instances():
    print(object_instance.object_name)

from_labels_dict

def from_labels_dict(label_row_dict: dict,
                     *,
                     preserve_identity: bool = False) -> None

Initialize the LabelRow from a label row dictionary.

This function also initializes the label row. It resets all the labels currently stored within this class.

Arguments:

• label_row_dict - The dictionary of all labels in the Encord format.
• preserve_identity - If True, the current row’s identity fields (label_hash, data_hash, dataset_hash, branch_name, and IMG_GROUP frame hashes) are preserved instead of being overwritten from the dict.

get_image_hash

def get_image_hash(frame_number: int) -> Optional[str]

Returns the image hash for a frame number.

Arguments:

• frame_number - The frame number.

Returns:

• Optional[str] - The image hash if the frame number is within bounds, None otherwise.

Raises:

• LabelRowError - If labels have not been initialized, or if the data type is not an image or image group.

get_frame_number

def get_frame_number(image_hash: str) -> Optional[int]

Returns the frame number for an image hash.

Arguments:

• image_hash - The image hash.

Returns:

• Optional[int] - The frame number of the image.

Raises:

• LabelRowError - If labels have not been initialized, or if the data type is not an image or image group.
• KeyError - If the image hash is not in the label row.

get_spaces

def get_spaces() -> list[Space]

Returns all spaces in the label row.

Use this to see which spaces are available. To work with a specific space, use get_space().

On a scene from a self-contained (MCAP) recording, the label row has no space metadata, so this method only lists the spaces it can infer. These are point clouds that have labels stored under a stream@timestamp_ns key, time series channels referenced by labels, and spaces that you already requested by ID. The list can be empty and is not a full inventory of the recording. Use get_space(id=..., type_=...) to get the space you want.

Returns:

• list[Space] - All spaces in the label row.

get_space

def get_space(*,
              id: Optional[str] = None,
              layout_key: Optional[str] = None,
              type_: SpaceLiteral,
              stream_id: Optional[str] = None,
              event_index: int = 0,
              start_frame: Optional[int] = None,
              file_name: Optional[str] = None) -> Space

Returns the space that matches the given identifier and type.

Identify the space with one of id, layout_key, stream_id, or file_name. You can’t pass both id and layout_key.

On a scene from a self-contained (MCAP) recording, requesting type_="point_cloud" with an id of the form stream@timestamp_ns that has no labels yet creates an empty space, so that you can add segmentations to it. Requesting type_="time_series" with a non-empty channel ID does the same for time range labels. The label row has no metadata for these spaces, so the ID and type that you pass are used as given.

Arguments:

• id - The ID of the space.
• layout_key - The layout key of the data unit within its data group layout.
• type_ - The expected space type, for example "image", "video", or "point_cloud". The space that is found must be of this type.
• stream_id - For scenes, the name of the stream.
• event_index - For scenes, the event index within stream_id. Defaults to 0.
• start_frame - For scene images, the frame where the image event starts. Used instead of event_index if set.
• file_name - The name of the file associated with the space.

Returns:

• Space - The matching space, as the space class that matches type_.

Raises:

• LabelRowError - If both id and layout_key are passed, if no matching space is found, or if the matching space is not of the type given in type_.

save

def save(bundle: Optional[Bundle] = None,
         validate_before_saving: bool = False,
         renumber_objects: bool = False) -> None

Uploads the labels in this label row to Encord.

This overwrites the labels stored on Encord, including any changes that someone else made after you called initialise_labels().

Arguments:

• bundle - If not provided, labels are saved immediately. If provided, the save is deferred and performed together with the other operations in the bundle.
• validate_before_saving - If True, Encord validates the labels against the project ontology and rejects the save if they are invalid. If False (default), the labels are saved without this check. You can check them afterwards with is_valid and get_validation_errors().
• renumber_objects - If True, recompute the number of every object when saving, ignoring any object_number values that are set, including values read from Encord. If False (default), existing numbers are kept.

Raises:

• LabelRowError - If labels have not been initialized, if the label row is detached, or if two objects of the same ontology object have the same object_number. Object numbers are only checked when renumber_objects is False.
• CorruptedLabelError - If validate_before_saving is True and the labels are invalid.

Example:

label_row.initialise_labels()
# Add, change, or remove labels here.
label_row.save()

metadata

@property
def metadata() -> Optional[Union[DICOMSeriesMetadata, DataGroupMetadata]]

Returns the metadata of DICOM series and data groups.

Returns:

Optional[Union[DICOMSeriesMetadata, DataGroupMetadata]]: DICOMSeriesMetadata for DICOM data, DataGroupMetadata for data groups, or None for other data types.

Raises:

• LabelRowError - If labels have not been initialized.

get_frame_view

def get_frame_view(frame: Union[int, str] = 0) -> FrameView

Returns a view of a single frame, which you can use to read and write the labels on that frame.

On an event-based label row, frame is a nanosecond offset. Object reads on the view return every object whose range covers that offset, not only the objects with a keyframe at that offset. Adding objects through the view raises an error.

Arguments:

• frame - The frame number, or the image hash for image and image group data. Defaults to the first frame.

Returns:

• FrameView - A view of the frame.

Raises:

• LabelRowError - If labels have not been initialized, or if the data type is audio or time series.
• KeyError - If frame is an image hash that is not in the label row.

get_frame_metadata

def get_frame_metadata(frame: Union[int, str] = 0) -> FrameViewMetadata

Returns metadata for a single frame, such as its title, file type, and dimensions.

Works for images, videos, and image groups, and doesn’t require labels to be initialized. For image groups, the label row must have been listed with include_images_data=True.

Arguments:

• frame - The frame number or the image hash. Defaults to the first frame.

Returns:

• FrameViewMetadata - Metadata for the frame.

Raises:

• LabelRowError - If the frame or image hash is not found, if the data type is not supported, or if image data is missing for an image group.

get_frames_metadata

def get_frames_metadata() -> List[FrameViewMetadata]

Returns metadata for all frames, such as their titles, file types, and dimensions.

Works for images, videos, and image groups, and doesn’t require labels to be initialized. For images and videos, the list has one entry. For image groups, the label row must have been listed with include_images_data=True.

Returns:

• List[FrameViewMetadata] - Metadata for each frame.

Raises:

• LabelRowError - If the data type is not supported, or if image data is missing for an image group.

get_frame_views

def get_frame_views() -> List[FrameView]

Returns views of all frames.

Returns:

• List[FrameView] - A list of frame views, in frame order.

Raises:

• LabelRowError - If labels have not been initialized, or if the label row is event-based.

get_object_instances

def get_object_instances(
        filter_ontology_object: Optional[Object] = None,
        filter_frames: Optional[Frames] = None) -> List[ObjectInstance]

Returns all object instances on the label row that match the given filters.

Only objects on the label row itself are returned. Objects placed on a space, for example in a data group, are not included. To get those, use get_space() and the space’s get_object_instances() method.

Arguments:

• filter_ontology_object - Optionally, only return instances of this ontology object.
• filter_frames - Optionally, only return objects that appear on these frames.

Returns:

• List[ObjectInstance] - The object instances that match the filters.

Raises:

• LabelRowError - If labels have not been initialized.

Example:

from encord.objects import Object
label_row.initialise_labels()
car = label_row.ontology_structure.get_child_by_title("Car", type_=Object)
cars = label_row.get_object_instances(filter_ontology_object=car)

add_object_instance

def add_object_instance(object_instance: ObjectInstance,
                        force: bool = True) -> None

Adds an object instance to the label row.

Create the object instance from an ontology object, set its coordinates on one or more frames, and then add it to the label row. Call save() to upload it.

On an event-based label row, you can add an empty geometric object and then write its keyframes with ObjectInstance.upsert_event. Saving the label row raises an error until the object has at least one event, or until you remove the object.

Arguments:

• object_instance - The object instance to add.
• force - If True (default), an object instance with the same object hash that is already on the label row is replaced. If False, an error is raised instead.

Raises:

• LabelRowError - If labels have not been initialized, if the object instance is already on a label row or a space, if an object instance with the same object hash exists and force is False, if the object instance is not on any frames, or if the object instance doesn’t fit the data type. For example, audio and time series data need range-only objects, and HTML files need objects with HTML coordinates.

Example:

from encord.objects import Object
from encord.objects.coordinates import BoundingBoxCoordinates
label_row.initialise_labels()
car = label_row.ontology_structure.get_child_by_title("Car", type_=Object)
car_instance = car.create_instance()
car_instance.set_for_frames(
    coordinates=BoundingBoxCoordinates(height=0.2, width=0.3, top_left_x=0.1, top_left_y=0.1),
    frames=0,
)
label_row.add_object_instance(car_instance)
label_row.save()

add_classification_instance

def add_classification_instance(
        classification_instance: ClassificationInstance,
        force: bool = False) -> None

Adds a classification instance to the label row.

For images, videos, image groups, DICOM, NIfTI, PDF, and data groups, set the frames of the classification instance with ClassificationInstance.set_for_frames before you add it. For audio, text, and time series data, and for event-based label rows, create the classification instance with range_only=True.

Arguments:

• classification_instance - The classification instance to add.
• force - If False (default), an error is raised if the label row already has a classification instance with the same classification hash, or an instance of the same classification on any of the same frames. If True, the instance is added anyway. An instance with the same classification hash is replaced, and for a global classification, all other instances of the same classification are removed.

Raises:

• LabelRowError - If labels have not been initialized, if the classification instance is already on a label row or a space, if it conflicts with an existing instance and force is False, if it is not on any frames, or if it was not created with range_only=True on data that requires it.

Example:

from encord.objects import Classification
label_row.initialise_labels()
notes = label_row.ontology_structure.get_child_by_title("Notes", type_=Classification)
notes_instance = notes.create_instance()
notes_instance.set_answer("Taken at night")
notes_instance.set_for_frames(frames=0)
label_row.add_classification_instance(notes_instance)
label_row.save()

remove_classification

def remove_classification(classification_instance: ClassificationInstance)

Removes a classification instance from the label row.

Arguments:

• classification_instance - The classification instance to remove.

Raises:

• LabelRowError - If labels have not been initialized, or if the classification instance is on a space. Use the space’s own methods to remove it.
• KeyError - If the classification instance is not on the label row.

get_classification_instances

def get_classification_instances(
        filter_ontology_classification: Optional[Classification] = None,
        filter_frames: Optional[Frames] = None
) -> List[ClassificationInstance]

Returns all classification instances on the label row that match the given filters.

Only classifications on the label row itself are returned. Classifications placed on a space, for example in a data group, are not included. To get those, use get_space() and the space’s get_classification_instances() method.

Arguments:

• filter_ontology_classification - Optionally, only return instances of this ontology classification.
• filter_frames - Optionally, only return classifications that appear on these frames.

Returns:

• List[ClassificationInstance] - The classification instances that match the filters.

Raises:

• LabelRowError - If labels have not been initialized.

remove_object

def remove_object(object_instance: ObjectInstance)

Removes an object instance from the label row.

Does nothing if the object instance is not on the label row.

Arguments:

• object_instance - The object instance to remove.

Raises:

• LabelRowError - If labels have not been initialized, or if the object instance is on a space. Use the space’s own methods to remove it.

to_encord_dict

def to_encord_dict(renumber_objects: bool = False) -> Dict[str, Any]

Returns the labels in this label row as a dictionary in the Encord label format.

Use this to export labels, for example to write them to a JSON file. To upload labels to Encord, use save() instead.

Classifications are written only to classification_answers, with their ranges and metadata.

Arguments:

• renumber_objects - If True, leave out the objectNumber of every object so that Encord recomputes the numbers when the labels are uploaded. Defaults to False.

Returns:

Dict[str, Any]: The label row in the Encord label format.

Raises:

• LabelRowError - If labels have not been initialized.

workflow_reopen

def workflow_reopen(bundle: Optional[Bundle] = None) -> None

Returns the task for this label row to the first annotation stage of the workflow.

No labels are lost. Only works for workflow projects. If the label row has no label_hash yet, this method does nothing.

This method acts on the main branch and doesn’t update this object. To see the new workflow stage, list the label row again with project.list_label_rows_v2().

For more details, see the workflow documentation.

Arguments:

• bundle - If not provided, the task is moved immediately. If provided, the operation is deferred and performed together with the other operations in the bundle.

Raises:

• LabelRowError - If the label row is detached.
• WrongProjectTypeError - If the project doesn’t use workflows.
• InvalidArgumentsError - If the first annotation stage of the workflow is a consensus stage.

workflow_complete

def workflow_complete(bundle: Optional[Bundle] = None) -> None

Moves the task for this label row to the Complete stage of the workflow.

The task skips any remaining annotation and review stages. Only works for workflow projects.

Labels must have been initialized at least once, so that label_hash is set. You don’t need to initialize them each time you call this method.

This method acts on the main branch and doesn’t update this object. To see the new workflow stage, list the label row again with project.list_label_rows_v2().

For more details, see the workflow documentation.

Arguments:

• bundle - If not provided, the task is moved immediately. If provided, the operation is deferred and performed together with the other operations in the bundle.

Raises:

• LabelRowError - If label_hash is None, or if the label row is detached.
• WrongProjectTypeError - If the project doesn’t use workflows.

set_priority

def set_priority(priority: float, bundle: Optional[Bundle] = None) -> None

Sets the priority of the task for this label row in a workflow project.

You need the Admin or Team Manager role on the project.

Arguments:

• priority - A value from 0.0 to 1.0, where 1.0 is the highest priority. Encord rejects values outside this range.
• bundle - If not provided, the priority is set immediately. If provided, the operation is deferred and performed together with the other operations in the bundle.

Raises:

• LabelRowError - If the label row is detached.
• WrongProjectTypeError - If the project doesn’t use workflows.

get_validation_errors

def get_validation_errors() -> Optional[List[str]]

Returns the validation errors for the label row.

Returns:

• Optional[List[str]] - The error messages if the labels are invalid, or None if the labels are valid or the label row has no label_hash yet.

Raises:

• LabelRowError - If the label row is detached.

attach_to_project

def attach_to_project(project: "Project", data_hash: str) -> None

Attach a detached label row to a data unit in a project.

Fetches the identity of the data unit’s label row (such as label_hash, data_hash, and dataset_hash) from the project and applies it to this label row, keeping its labels. If the label row doesn’t exist on Encord yet, it is created. After this call, you can upload the labels with save().

The ontology used to create the detached label row must match the project’s ontology (the same feature hashes), or Encord rejects the save. Labels on frames beyond the data unit’s frame count may also be rejected.

Arguments:

• project - The project to attach to.
• data_hash - The data hash of the data unit in the project.

Raises:

• LabelRowError - If the project has no label row for data_hash.

FrameViewMetadata Objects

class FrameViewMetadata()

Class to inspect metadata for a frame view.

title

@property
def title() -> str

Returns the title of the image or data unit.

Returns:

• str - The title.

file_type

@property
def file_type() -> str

Returns the MIME type of the image, for example image/jpeg.

Returns:

• str - The MIME type, or an empty string if it is not known.

width

@property
def width() -> int

Returns the width of the image in pixels.

Returns:

• int - The width, or 0 if it is not known.

height

@property
def height() -> int

Returns the height of the image in pixels.

Returns:

• int - The height, or 0 if it is not known.

image_hash

@property
def image_hash() -> str

Returns the image hash. For images and videos, this is the data hash.

Returns:

• str - The image hash.

frame_number

@property
def frame_number() -> int

Returns the position of the image in the image group. This is 0 for images and videos.

Returns:

• int - The frame number.

FrameView Objects

class FrameView()

This class can be used to inspect object or classification instances on a given frame, or metadata such as image file size for a given frame.

image_hash

@property
def image_hash() -> str

Get the image hash for the current frame.

Returns:

• str - The image hash.

Raises:

• LabelRowError - If the data type is not IMAGE or IMG_GROUP.

image_title

@property
def image_title() -> str

Get the image title for the current frame.

Returns:

• str - The image title.

Raises:

• LabelRowError - If the data type is not IMAGE or IMG_GROUP.

file_type

@property
def file_type() -> str

Get the file type for the current frame.

Returns:

• str - The file type.

Raises:

• LabelRowError - If the data type is not IMAGE or IMG_GROUP.

frame

@property
def frame() -> int

Get the frame number.

Returns:

• int - The frame number.

width

@property
def width() -> int

Returns the width of the frame in pixels.

Returns:

• int - The width.

Raises:

• LabelRowError - If the width is not set for this data type.

height

@property
def height() -> int

Returns the height of the frame in pixels.

Returns:

• int - The height.

Raises:

• LabelRowError - If the height is not set for this data type.

data_link

@property
def data_link() -> Optional[str]

Get the data link for the current frame.

Returns:

• Optional[str] - The data link, or None if not available.

Raises:

• LabelRowError - If the data type is not IMAGE or IMG_GROUP.

metadata

@property
def metadata() -> Optional[DICOMSliceMetadata]

Returns the DICOM metadata of the current slice.

Returns:

• Optional[DICOMSliceMetadata] - The slice metadata, or None for data types other than DICOM.

add_object_instance

def add_object_instance(object_instance: ObjectInstance,
                        coordinates: Coordinates,
                        *,
                        overwrite: bool = False,
                        created_at: Optional[datetime] = None,
                        created_by: Optional[str] = None,
                        last_edited_at: Optional[datetime] = None,
                        last_edited_by: Optional[str] = None,
                        confidence: Optional[float] = None,
                        manual_annotation: Optional[bool] = None) -> None

Add an object instance to the current frame.

Arguments:

• object_instance - The object instance to add.
• coordinates - The coordinates for the object instance.
• overwrite - Whether to overwrite existing instance data (default is False).
• created_at - Optional creation timestamp.
• created_by - Optional creator identifier.
• last_edited_at - Optional last edited timestamp.
• last_edited_by - Optional last editor identifier.
• confidence - Optional confidence score.
• manual_annotation - Optional flag indicating manual annotation.

Raises:

• LabelRowError - If the row is event-based or the object belongs to a different label row.

add_classification_instance

def add_classification_instance(
        classification_instance: ClassificationInstance,
        *,
        overwrite: bool = False,
        created_at: Optional[datetime] = None,
        created_by: Optional[str] = None,
        confidence: float = DEFAULT_CONFIDENCE,
        manual_annotation: bool = DEFAULT_MANUAL_ANNOTATION,
        last_edited_at: Optional[datetime] = None,
        last_edited_by: Optional[str] = None) -> None

Add a classification instance to the current frame.

Arguments:

• classification_instance - The classification instance to add.
• overwrite - Whether to overwrite existing instance data (default is False).
• created_at - Optional creation timestamp.
• created_by - Optional creator identifier.
• confidence - Confidence score. Defaults to 1.0.
• manual_annotation - Whether the classification was created manually. Defaults to True.
• last_edited_at - Optional last edited timestamp.
• last_edited_by - Optional last editor identifier.

Raises:

• LabelRowError - If the classification instance is already assigned to a different label row.

get_object_instances

def get_object_instances(
        filter_ontology_object: Optional[Object] = None
) -> List[ObjectInstance]

Get object instances for the current frame.

Arguments:

• filter_ontology_object - Optionally filter by a specific ontology object.

Returns:

• List[ObjectInstance] - All ObjectInstances that match the filter.

get_classification_instances

def get_classification_instances(
    filter_ontology_classification: Optional[Classification] = None
) -> List[ClassificationInstance]

Get classification instances for the current frame.

Arguments:

• filter_ontology_classification - Optionally filter by a specific ontology classification.

Returns:

• List[ClassificationInstance] - All ClassificationInstances that match the filter.

FrameLevelImageGroupData Objects

@dataclass(frozen=True)
class FrameLevelImageGroupData()

Data related to a specific frame in an image group.

Attributes:

• image_hash - Hash of the image.
• image_title - Title of the image.
• file_type - MIME type of the image, for example image/jpeg.
• frame_number - The number of the frame in the sequence.
• width - Width of the image.
• height - Height of the image.
• data_link - Optional URL of the image.

LabelRowReadOnlyDataImagesDataEntry Objects

@dataclass(frozen=True)
class LabelRowReadOnlyDataImagesDataEntry()

Read-only data entry for image data in a label row.

Attributes:

• index - Index of the image.
• title - Title of the image.
• file_type - MIME type of the image, for example image/jpeg.
• height - Height of the image.
• width - Width of the image.
• image_hash - Hash of the image.

LabelRowReadOnlyData Objects

@dataclass(frozen=True)
class LabelRowReadOnlyData()

Read-only data for a label row.

Attributes:

• label_hash - Optional hash for the label. None if not initialized for labeling.
• created_at - Optional creation timestamp. None if not initialized for labeling.
• last_edited_at - Optional last edited timestamp. None if not initialized for labeling.
• data_hash - Hash of the data.
• group_hash - Optional hash of the data group that the data belongs to.
• data_type - Type of the data (e.g., IMAGE, VIDEO).
• label_status - Status of the label.
• annotation_task_status - Optional status of the annotation task.
• workflow_graph_node - Optional workflow graph node related to the data.
• is_shadow_data - Boolean indicating if the data is a per-user shadow copy for Benchmark QA or training.
• number_of_frames - Number of frames in the data.
• duration - Optional duration of the video or sequence.
• fps - Optional frames per second for video.
• dataset_hash - Hash of the dataset.
• dataset_title - Title of the dataset.
• data_title - Title of the data.
• backing_item_uuid - Optional UUID of the storage item that backs the data.
• audio_codec - Codec for audio data.
• audio_bit_depth - Bit depth for audio data.
• audio_sample_rate - Sample Rate for audio data.
• audio_num_channels - Number of channels for audio data.
• width - Optional width of the data.
• height - Optional height of the data.
• data_link - Optional URL of the underlying file.
• task_uuid - Optional task uuid of the data.
• priority - Optional priority of the data.
• file_type - Optional MIME type of the file.
• client_metadata - Optional metadata provided by the client.
• images_data - Optional list of image data entries.
• branch_name - Name of the branch associated with the data.
• frame_level_data - Mapping from frame number to frame level data.
• image_hash_to_frame - Mapping from image hash to frame number.
• frame_to_image_hash - Mapping from frame number to image hash.
• is_valid - Boolean indicating if the data is valid.
• assigned_user_email - Optional email of the user assigned to the data.
• last_actioned_by_user_email - Optional email of the user who last actioned the data.