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
- IfNone
, 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
- IfNone
, 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
- IfTrue
, overwrite current labels with those stored in the Encord server. IfFalse
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
- IfTrue
, the :attr:.data_link
property will contain a signed URL. See documentation for :attr:.data_link
for more details.
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 isFalse
.
metadata
@property
def metadata() -> Optional[DICOMSeriesMetadata]
Get metadata for the given data type.
Returns:
-
Optional[DICOMSeriesMetadata]
- Metadata for the data type, orNone
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 ofObjectInstance
s 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
- IfTrue
, 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
- IfTrue
, 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.
add_to_single_frame_to_hashes_map
def add_to_single_frame_to_hashes_map(label_item: Union[
ObjectInstance, ClassificationInstance], frame: int) -> None
This is an internal function, it is not meant to be called by the SDK user.
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 theClassificationInstance
s 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, orNone
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, orNone
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]
- AllObjectInstance
s 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]
- AllClassificationInstance
s 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.
Was this page helpful?