otx.api.entities.dataset_item#

This module implements the dataset item entity.

Classes

DatasetItemEntity(media, annotation_scene[, ...])

DatasetItemEntity represents an item in the DatasetEntity.

DatasetItemEntityWithID(media, annotation_scene)

class otx.api.entities.dataset_item.DatasetItemEntity(media: IMedia2DEntity, annotation_scene: AnnotationSceneEntity, roi: Annotation | None = None, metadata: List[MetadataItemEntity] | None = None, subset: Subset = Subset.NONE, ignored_labels: List[LabelEntity] | Tuple[LabelEntity, ...] | Set[LabelEntity] | None = None)[source]#

Bases: object

DatasetItemEntity represents an item in the DatasetEntity.

It holds a media item, annotation and an ROI. The ROI determines the region of interest for the dataset item, and is described by a shape entity.

The fundamental properties of a dataset item are:

  • A 2d media entity (e.g. Image)

  • A 2d annotation entity for the full resolution media entity

  • An ROI, describing the region of interest.

  • The subset it belongs to

  • Metadata for the media entity (e.g. saliency map or active score)

  • A list of labels to ignore

Getting data from dataset item

The first step is to fetch the input data for the network.

>>> dataset_item = DatasetItemEntity()
>>> media_numpy = dataset_item.numpy  # RGB media data (Height, Width, Channels)

This returns the numpy data for the assigned ROI. But it is possible to extract any arbitrary region.

>>> from otx.api.entities.shapes.rectangle import Rectangle
>>> top_left_quart_roi = Annotation(Rectangle(x1=0.0, y1=0.0, x2=0.5, y2=0.5), labels=[])
>>> top_left_quart_numpy = dataset_item.roi_numpy(roi=top_left_quart_roi)

Get the subset of labels for the item ROI:

>>> labels = dataset_item.get_roi_labels(labels=...)

Get the annotations __visible__ in the ROI:

>>> dataset_item.get_annotations()

Adding output data to dataset item

It is possible to add shapes or just labels for the ROI.

Add shapes to dataset item:

>>> box = Rectangle(x1=0.2, y1=0.3, x2=0.6, y2=0.5)
>>> dataset_item.append_annotations(annotations=[Annotation(box, labels=[...])])

Add labels to ROI:

>>> dataset_item.append_labels(labels=[...])
Parameters:

  • media (IMedia2DEntity) – Media item

  • annotation_scene (AnnotationSceneEntity) – Annotation scene

  • roi (Optional[Annotation]) – Region Of Interest

  • metadata (Optional[List[MetadataItemEntity]]) – Metadata attached to dataset item

  • subset (Subset) – Subset for item. E.g. Subset.VALIDATION

  • ignored_labels (Optional[Union[List[LabelEntity], Tuple[LabelEntity, ...], Set[LabelEntity]]]) – Collection of labels that should be ignored in this dataset item. For instance, in a training scenario, this parameter is used to ignore certain labels within the existing annotations because their status becomes uncertain following a label schema change.

append_annotations(annotations: Sequence[Annotation])[source]#

Adds a list of shapes to the annotation.

append_labels(labels: List[ScoredLabel])[source]#

Appends labels to the DatasetItem and adds it to the the annotation label as well if it’s not yet there.

Parameters:

labels (List[ScoredLabel]) – list of labels to be appended.

append_metadata_item(data: IMetadata, model: ModelEntity | None = None)[source]#

Appends metadata produced by some model to the dataset item.

Adding visualization heatmap (ResultMediaEntity) to DatasetItemEntity

>>> from otx.api.entities.image import Image
>>> from otx.api.entities.result_media import ResultMediaEntity
>>> media = Image(file_path='image.jpeg')
>>> annotation = NullAnnotationSceneEntity()
>>> dataset_item = DatasetItem(media=media, annotation_scene=annotation)
>>> data = np.ones((120, 120, 3)).astype(np.uint8) * 255 # Saliency numpy
>>> result_media = ResultMediaEntity(name="Gradcam++",
...                                  type="Gradcam++",
...                                  annotation_scene=annotation,
...                                  numpy=data)
>>> dataset_item.append_metadata_item(result_media)

Representation vector for active learning

>>> from otx.api.entities.tensor import TensorEntity
>>> tensor = TensorEntity(name="representation_vector", numpy=data)
>>> dataset_item.append_metadata_item(data=tensor, model=model)
Parameters:

  • data (IMetadata) – any object of a class inherited from IMetadata. (e.g., FloatMetadata, Tensor)

  • model (Optional[ModelEntity]) – model that was used to generated metadata

get_annotations(labels: List[LabelEntity] | None = None, include_empty: bool = False, include_ignored: bool = False, preserve_id: bool = False) → List[Annotation][source]#

Returns a list of annotations that exist in the dataset item (wrt. ROI).

This is done by checking that the center of the annotation is located in the ROI.

Parameters:

  • labels (Optional[LabelEntity]) – Subset of input labels to filter with; if None, all the shapes within the ROI are returned.

  • include_empty (bool) – if True, returns both empty and non-empty labels

  • include_ignored (bool) – if True, includes the labels in ignored_labels

  • preserve_id (bool) – if True, preserve the annotation id when copying

Returns:

The intersection of the input label set and those present within the ROI

Return type:

List[Annotation]

get_metadata() → List[MetadataItemEntity][source]#

Returns the metadata.

get_metadata_by_name_and_model(name: str, model: ModelEntity | None) → Sequence[MetadataItemEntity][source]#

Returns a metadata item with name and generated by model.

Parameters:

  • name (str) – the name of the metadata

  • model (Optional[ModelEntity]) – the model which was used to generate the metadata.

Returns:

a list of metadata items with name and generated by model.

Return type:

Sequence[MetadataItemEntity]

get_roi_labels(labels: List[LabelEntity] | None = None, include_empty: bool = False, include_ignored: bool = False) → List[LabelEntity][source]#

Return the subset of the input labels which exist in the dataset item (wrt. ROI).

Parameters:

  • labels (Optional[List[LabelEntity]]) – Subset of input labels to filter with; if None, all the labels within the ROI are returned.

  • include_empty (bool) – if True, returns both empty and non-empty labels

  • include_ignored (bool) – if True, includes the labels in ignored_labels

Returns:

The intersection of the input label set and those present within the ROI.

Return type:

List[LabelEntity]

get_shapes_labels(labels: List[LabelEntity] | None = None, include_empty: bool = False, include_ignored: bool = False) → List[LabelEntity][source]#

Get the labels of the shapes present in this dataset item.

if a label list is supplied, only labels present within that list are returned. if include_empty is True, present empty labels are returned as well.

Parameters:

  • labels (Optional[List[LabelEntity]]) – if supplied only labels present in this list are returned. Defaults to None.

  • include_empty (bool) – if True, returns both empty and non-empty labels. Defaults to False.

  • include_ignored (bool) – if True, includes the labels in ignored_labels. Defaults to False.

Returns:

a list of labels from the shapes within the roi of this dataset item

Return type:

List[LabelEntity]

roi_numpy(roi: Annotation | None = None) → ndarray[source]#

Gives the numpy data for the media, given an ROI.

This function allows to take a crop of any arbitrary region of the media in the Dataset entity. If the ROI is not given, the ROI assigned to the DatasetItem will be used as default.

Parameters:

roi (Optional[Annotation]) – Shape entity. The shape will be converted if needed, to extract the ROI numpy.

Returns:

Numpy array with media data

Return type:

np.ndarray

set_metadata(metadata: List[MetadataItemEntity])[source]#

Sets the metadata.

wrap(**kwargs) → T[source]#

Creates a new DatasetItemEntity, overriding only the given arguments to the existing ones for this instance.

property annotation_scene: AnnotationSceneEntity#

Access to annotation scene.

property height: int#

The height of the dataset item, taking into account the ROI.

property ignored_labels: Set[LabelEntity]#

Get the IDs of the labels to ignore in this dataset item.

property media: IMedia2DEntity#

Media.

property numpy: ndarray#

Returns the numpy data for the media, taking ROI into account.

Returns:

Numpy array. RGB array of shape (Height, Width, Channels)

Return type:

np.ndarrray

property roi: Annotation#

Region Of Interest.

property subset: Subset#

Returns the subset that the IDatasetItem belongs to. e.g. Subset.TRAINING.

property width: int#

The width of the dataset item, taking into account the ROI.

class otx.api.entities.dataset_item.DatasetItemEntityWithID(media: IMedia2DEntity, annotation_scene: AnnotationSceneEntity, roi: Annotation | None = None, metadata: List[MetadataItemEntity] | None = None, subset: Subset = Subset.NONE, ignored_labels: List[LabelEntity] | Tuple[LabelEntity, ...] | Set[LabelEntity] | None = None, id_: str | ObjectId | None = None)[source]#

Bases: DatasetItemEntity

property id_: ID#

Returns the id of this entity

Returns:

ID of this entity