Annotation Metadata¶

class dagshub.data_engine.annotation.MetadataAnnotations(datapoint: Datapoint, field: str, annotations: Sequence[IRAnnotationBase] | None = None, meta: Dict | None = None, original_value: bytes | None = None)¶

Class that holds metadata annotations for a datapoint.

This class is automatically created for every datapoint, as long as the field is a blob field and has been marked as annotation

Example of adding bounding boxes:

dp = ds.all()[0]
anns: MetadataAnnotations = dp["exported_annotations"]
anns.add_image_bbox("person", 0.1, 0.1, 0.1, 0.1)
anns.add_image_bbox("cat", 0.2, 0.2, 0.1, 0.1)
anns.meta["some_key"] = "some_value"
dp.save()

You can use the meta dictionary to add additional metadata to the task, as long as it is JSON-serializable.

All functions for adding annotations have additional arguments of image_width/image_height. They are required for new datapoints, but if there are already annotations existing, or if there is width/height in the metadata, they can be omitted.

to_ls_task() → bytes | None¶: Convert the annotations into a Label Studio task (this is what’s stored in the Data Engine backend).

property value: bytes | None¶

Returns the contents of annotation as a byte array. If it was loaded from the backend and not changed, it will return the original value.

If there were any changes, it will instead return the serialized version of the annotations (the username will be set to the current user).

add_image_bbox(category: str, top: float, left: float, width: float, height: float, image_width: int | None = None, image_height: int | None = None)¶

Adds a bounding box annotation. Values need to be normalized from 0 to 1

Parameters:

category – Annotation category
top – Top coordinate of the bounding box
left – Left coordinate of the bounding box
width – Width of the bounding box
height – Height of the bounding box
image_width – Width of the image. If not supplied, tries to get it from the width field in datapoint
image_height – Height of the image. If not supplied, tries to get it from the height field in datapoint

add_image_segmentation(category: str, points: Sequence[Tuple[float, float]], image_width: int | None = None, image_height: int | None = None)¶

Add a segmentation annotation. Points need to be a list of tuples of 2 (x, y) values, normalized from 0 to 1. Example of points: [(0.1, 0.1), (0.3, 0.3), (0.1, 0.6)]

Parameters:

category – Annotation category
points – List of points of the segmentation
image_width – Width of the image. If not supplied, tries to get it from the width field in datapoint
image_height – Height of the image. If not supplied, tries to get it from the height field in datapoint

Adds a new pose annotation

bbox_... arguments define the bounding box of the pose. If any of the parameters is not defined, the bounding box is instead created from the points.

Points need to be a list of tuples of (x, y) or (x, y, visible) values, normalized from 0 to 1.

Parameters:

category – Annotation category
points – List of points of the pose
bbox_left – Left coordinate of the bounding box
bbox_top – Top coordinate of the bounding box
bbox_width – Width of the bounding box
bbox_height – Height of the bounding box
image_width – Width of the image. If not supplied, tries to get it from the width field in datapoint
image_height – Height of the image. If not supplied, tries to get it from the height field in datapoint

add_yolo_annotation(annotation_type: Literal['bbox', 'segmentation', 'pose'], annotation: str | ultralytics.engine.results.Results, categories: Dict[int, str] | None = None, image_width: int | None = None, image_height: int | None = None, pose_keypoint_dim: int | None = None)¶

Add a YOLO annotation from string or from a result of prediction with a YOLO model.

This could be either a string of an annotations from a YOLO file, or a result of evaluating a YOLO model. Args: