LabelRowV2

​

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 :meth:.initialise_labels() first. To upload your added labels, call :meth:.save().

​

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.

​

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() -> str | None

Returns the file type of the data row.

Returns:

str | None: The file type or None if not set.

​

client_metadata

@property
def client_metadata() -> dict | None

Returns the client metadata associated with the label row.

Returns:

dict | None: The client metadata or None if not set.

​

label_status

@property
def label_status() -> LabelStatus

Returns the current labeling status for the label row.

Note: This method is not supported for workflow-based projects. Please see our :ref:workflow documentation <tutorials/workflows:Workflows> for more details.

Returns:

• LabelStatus - The current labeling status.

Raises:

• WrongProjectTypeError - If used with workflow-based projects.

​

annotation_task_status

@property
def annotation_task_status() -> AnnotationTaskStatus

Returns the current annotation task status for the label row.

Note: This method is not supported for workflow-based projects. Please see our :ref:workflow documentation <tutorials/workflows:Workflows> for more details.

Returns:

• AnnotationTaskStatus - The current annotation task status.

Raises:

• WrongProjectTypeError - If used with workflow-based projects.

​

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 if the label row is shadow data.

Returns:

• bool - True if the label row 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 optimisations, as there is no single underlying file for these data types.

This property will contain a signed URL if :meth:.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 optimisation, 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 optimisation, as there is no single underlying height for this data type.

Returns:

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

​

priority

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

Returns the workflow priority for the task associated with the data unit.

This property only works for workflow-based projects.

It is None for label rows in the “complete” state.

Returns:

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

Raises:

• WrongProjectTypeError - If used with non-workflow-based projects.

​

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

Get the corresponding ontology structure.

​

is_labelling_initialised

@property
def is_labelling_initialised() -> bool

Check if labelling is initialized.

Returns:

• bool - True if labelling is initialized, False otherwise.

  If this is False, call the :meth:.initialise_labels method to read or write specific ObjectInstances or ClassificationInstances.

​

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,
                      overwrite: bool = False,
                      bundle: Optional[Bundle] = None,
                      *,
                      include_signed_url: bool = False) -> None

Initialize labels from the Encord server.

This function downloads or exports labels stored on the Encord server and performs any other reading or writing operations. If you only want to inspect a subset of labels, you can filter them. Note that filtering and later uploading will delete all previously filtered labels.

If the label is not in progress, this sets the label status to LabelStatus.LABEL_IN_PROGRESS.

Arguments:

• include_object_feature_hashes - If None, all objects will be included. Otherwise, only objects with the specified feature hashes will be included.
• WARNING - Use this filter only for reading labels. Saving a filtered subset will delete all other object instances stored in the Encord platform.
• include_classification_feature_hashes - If None, all classifications will be included. Otherwise, only classifications with the specified feature hashes will be included.
• WARNING - Use this filter only for reading labels. Saving a filtered subset will delete all other classification instances stored in the Encord platform.
• include_reviews - Whether to request read-only information about the reviews of the label row.
• overwrite - If True, overwrite current labels with those stored in the Encord server. If False and the label row is already initialized, this function will raise an error.
• bundle - If not provided, initialization is performed independently. If provided, initialization is delayed and performed along with other objects in the same bundle.
• include_signed_url - If True, the :attr:.data_link property will contain a signed URL. See documentation for :attr:.data_link for more details.
• branch_name - Name of branch

​

from_labels_dict

def from_labels_dict(label_row_dict: dict) -> 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.

​

get_image_hash

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

Get the corresponding image hash for the 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 this function is used for non-image data types.

​

get_frame_number

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

Get the corresponding frame number for the image hash.

Arguments:

• image_hash - The image hash.

Returns:

• Optional[int] - The frame number if the image hash is found, None otherwise.

Raises:

• LabelRowError - If this function is used for non-image data types.

​

save

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

Upload the created labels to the Encord server.

This will overwrite any labels that someone else has created on the platform in the meantime.

Arguments:

• bundle - If not provided, save is executed immediately. If provided, save is executed as part of the bundle.
• validate_before_saving - Enable stricter server-side integrity checks. Default is False.

​

metadata

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

Get metadata for the given data type.

Returns:

• Optional[DICOMSeriesMetadata] - Metadata for the data type, or None if not supported.

  Currently only supported for DICOM. Returns None for other formats.

  Label row needs to be initialized before using this property.

​

get_frame_view

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

Get a view of the specified frame.

Arguments:

• frame - Either the frame number or the image hash if the data type is an image or image group. Defaults to the first frame.

Returns:

• FrameView - A view of the specified frame.

​

get_frame_metadata

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

Get metadata for a specific frame or image hash.

Arguments:

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

Returns:

• FrameViewMetadata - Metadata for the specified frame or image hash.

Raises:

• LabelRowError - If the specified frame or image hash is not found in the label row.

​

get_frames_metadata

def get_frames_metadata() -> List[FrameViewMetadata]

Get metadata for all frames in the image group.

Returns:

• List[FrameViewMetadata] - A list of metadata for each frame.

​

get_frame_views

def get_frame_views() -> List[FrameView]

Get views for all frames.

Returns:

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

​

get_object_instances

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

Get all object instances that match the given filters.

Arguments:

• filter_ontology_object - Optionally filter by a specific ontology object.
• filter_frames - Optionally filter by specific frames.

Returns:

• List[ObjectInstance] - A list of ObjectInstances that match the filters.

​

add_object_instance

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

Add an object instance to the label row. If the object instance already exists, it overwrites the current instance.

Arguments:

• object_instance - The object instance to add.
• force - If True, overwrites the current objects; otherwise, it will replace the current object.

Raises:

• LabelRowError - If the object instance is already part of another LabelRowV2.

​

add_classification_instance

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

Add a classification instance to the label row.

Arguments:

• classification_instance - The classification instance to add.
• force - If True, overwrites the current objects; otherwise, it will replace the current object.

Raises:

• LabelRowError - If the classification instance is already part of another LabelRowV2 or has overlapping frames.

​

remove_classification

def remove_classification(classification_instance: ClassificationInstance)

Remove a classification instance from a label row.

Arguments:

• classification_instance - The classification instance to remove.

​

get_classification_instances

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

Get all classification instances that match the given filters.

Arguments:

• filter_ontology_classification - Optionally filter by a specific ontology classification.
• filter_frames - Optionally filter by specific frames.

Returns:

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

​

remove_object

def remove_object(object_instance: ObjectInstance)

Remove an object instance from a label row.

Arguments:

• object_instance - The object instance to remove.

​

to_encord_dict

def to_encord_dict() -> Dict[str, Any]

Convert the label row to a dictionary in Encord format.

This is an internal helper function. Likely this should not be used by a user. To upload labels use the :meth:.save() function.

Returns:

Dict[str, Any]: A dictionary representing the label row in Encord format.

​

workflow_reopen

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

Return a label row to the first annotation stage for re-labeling.

No data will be lost during this call. This method is only relevant for the projects that use the :ref:Workflow <tutorials/workflows:Workflows> feature, and will raise an error for pre-workflow projects.

Arguments:

• bundle - Optional parameter. If passed, the method will be executed in a deferred way as part of the bundle.

​

workflow_complete

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

Move a label row to the final workflow node, marking it as ‘Complete’.

This method can be called only for labels for which :meth:.initialise_labels() was called at least once, and consequentially the “label_hash” field is not None. Labels need not be initialised every time the workflow_complete() method is called.

This method is only relevant for the projects that use the :ref:Workflow <tutorials/workflows:Workflows> feature, and will raise an error for projects that don’t use Workflows.

Arguments:

• bundle - Optional parameter. If passed, the method will be executed in a deferred way as part of the bundle.

Raises:

• LabelRowError - If the label hash is None.

​

set_priority

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

Set priority for a task in a workflow project.

Arguments:

• priority - Float value from 0.0 to 1.0, where 1.0 is the highest priority.
• bundle - Optional parameter. If passed, the method will be executed in a deferred way as part of the bundle.

Raises:

• WrongProjectTypeError - If the project is not a workflow-based project.

​

get_validation_errors

def get_validation_errors() -> List[str] | None

Get validation errors for the label row.

Returns:

List[str] | None: A list of error messages if the label row is invalid, otherwise None.

​

FrameViewMetadata Objects

class FrameViewMetadata()

Class to inspect metadata for a frame view.

​

image_hash

@property
def image_hash() -> str

Get the hash of the image.

Returns:

• str - The image hash.

​

frame_number

@property
def frame_number() -> int

Get the frame number.

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

Get the width of the image or image group.

Returns:

• int - The width of the image or image group.

Raises:

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

​

height

@property
def height() -> int

Get the height of the image or image group.

Returns:

• int - The height of the image or image group.

Raises:

• LabelRowError - If the height is not set for the 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]

Get annotation metadata for the current frame.

Returns:

• Optional[DICOMSliceMetadata] - The metadata for the frame, or None if not applicable.

Notes:

Currently only supported for DICOM, and will return None for other formats.

​

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 object instance is already assigned 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 (default is DEFAULT_CONFIDENCE).
• manual_annotation - Flag indicating manual annotation (default is DEFAULT_MANUAL_ANNOTATION).
• 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 - Type of the file (e.g., JPEG, PNG).
• frame_number - The number of the frame in the sequence.
• width - Width of the image.
• height - Height of the image.
• data_link - Optional link to additional data related to 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 - Type of the file (e.g., JPEG, PNG).
• 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.
• 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 shadow data.
• 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.
• width - Optional width of the data.
• height - Optional height of the data.
• data_link - Optional link to additional data.
• priority - Optional priority of the data.
• file_type - Optional file type of the data.
• 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.