LabelRowV2
LabelRowV2 Objects
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
Returns the hash of the label row.
Returns:
Optional[str]
- The label row hash or None if not set.
branch_name
Returns the branch name of the label row.
Returns:
str
- The branch name.
data_hash
Returns the hash of the data row.
Returns:
str
- The data row hash.
dataset_hash
Returns the hash of the dataset.
Returns:
str
- The dataset hash.
dataset_title
Returns the title of the dataset.
Returns:
str
- The dataset title.
data_title
Returns the title of the data row.
Returns:
str
- The data row title.
data_type
Returns the data type of the label row.
Returns:
DataType
- The data type.
file_type
Returns the file type of the data row.
Returns:
str | None: The file type or None if not set.
client_metadata
Returns the client metadata associated with the label row.
Returns:
dict | None: The client metadata or None if not set.
label_status
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
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
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
Indicates if the label row is shadow data.
Returns:
bool
- True if the label row is shadow data, False otherwise.
created_at
Returns the creation date of the label row.
Returns:
Optional[datetime]
- The creation date or None if not yet created.
last_edited_at
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
Returns the number of frames in the label row.
Returns:
int
- The number of frames.
duration
Returns the duration of the video data type.
Returns:
Optional[float]
- The duration or None if not applicable.
fps
Returns the frames per second (fps) of the video data type.
Returns:
Optional[float]
- The fps or None if not applicable.
data_link
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
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
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.
audio_codec
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
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
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
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.
priority
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
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
Get the corresponding ontology structure.
is_labelling_initialised
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
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.branch_name
- Name of branch
from_labels_dict
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
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
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
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
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
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
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
Get metadata for all frames in the image group.
Returns:
List[FrameViewMetadata]
- A list of metadata for each frame.
get_frame_views
Get views for all frames.
Returns:
List[FrameView]
- A list of frame views in order of available frames.
get_object_instances
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
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
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
Remove a classification instance from a label row.
Arguments:
classification_instance
- The classification instance to remove.
get_classification_instances
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
Remove an object instance from a label row.
Arguments:
object_instance
- The object instance to remove.
to_encord_dict
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
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
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
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
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 to inspect metadata for a frame view.
image_hash
Get the hash of the image.
Returns:
str
- The image hash.
frame_number
Get the frame number.
Returns:
int
- The frame number.
FrameView Objects
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
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
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
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
Get the frame number.
Returns:
int
- The frame number.
width
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
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
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
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
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
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
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
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
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
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
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.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 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?