Shortcuts

BaseDataElement

class mmengine.structures.BaseDataElement(*, metainfo=None, **kwargs)[source]

A base data interface that supports Tensor-like and dict-like operations.

A typical data elements refer to predicted results or ground truth labels on a task, such as predicted bboxes, instance masks, semantic segmentation masks, etc. Because groundtruth labels and predicted results often have similar properties (for example, the predicted bboxes and the groundtruth bboxes), MMEngine uses the same abstract data interface to encapsulate predicted results and groundtruth labels, and it is recommended to use different name conventions to distinguish them, such as using gt_instances and pred_instances to distinguish between labels and predicted results. Additionally, we distinguish data elements at instance level, pixel level, and label level. Each of these types has its own characteristics. Therefore, MMEngine defines the base class BaseDataElement, and implement InstanceData, PixelData, and LabelData inheriting from BaseDataElement to represent different types of ground truth labels or predictions.

Another common data element is sample data. A sample data consists of input data (such as an image) and its annotations and predictions. In general, an image can have multiple types of annotations and/or predictions at the same time (for example, both pixel-level semantic segmentation annotations and instance-level detection bboxes annotations). All labels and predictions of a training sample are often passed between Dataset, Model, Visualizer, and Evaluator components. In order to simplify the interface between components, we can treat them as a large data element and encapsulate them. Such data elements are generally called XXDataSample in the OpenMMLab. Therefore, Similar to nn.Module, the BaseDataElement allows BaseDataElement as its attribute. Such a class generally encapsulates all the data of a sample in the algorithm library, and its attributes generally are various types of data elements. For example, MMDetection is assigned by the BaseDataElement to encapsulate all the data elements of the sample labeling and prediction of a sample in the algorithm library.

The attributes in BaseDataElement are divided into two parts, the metainfo and the data respectively.

  • metainfo: Usually contains the information about the image such as filename, image_shape, pad_shape, etc. The attributes can be accessed or modified by dict-like or object-like operations, such as . (for data access and modification), in, del, pop(str), get(str), metainfo_keys(), metainfo_values(), metainfo_items(), set_metainfo() (for set or change key-value pairs in metainfo).

  • data: Annotations or model predictions are stored. The attributes can be accessed or modified by dict-like or object-like operations, such as ., in, del, pop(str), get(str), keys(), values(), items(). Users can also apply tensor-like methods to all torch.Tensor in the data_fields, such as .cuda(), .cpu(), .numpy(), .to(), to_tensor(), .detach().

Parameters
  • metainfo (dict, optional) – A dict contains the meta information of single image, such as dict(img_shape=(512, 512, 3), scale_factor=(1, 1, 1, 1)). Defaults to None.

  • kwargs (dict, optional) – A dict contains annotations of single image or model predictions. Defaults to None.

Return type

None

Examples

>>> import torch
>>> from mmengine.structures import BaseDataElement
>>> gt_instances = BaseDataElement()
>>> bboxes = torch.rand((5, 4))
>>> scores = torch.rand((5,))
>>> img_id = 0
>>> img_shape = (800, 1333)
>>> gt_instances = BaseDataElement(
...     metainfo=dict(img_id=img_id, img_shape=img_shape),
...     bboxes=bboxes, scores=scores)
>>> gt_instances = BaseDataElement(
...     metainfo=dict(img_id=img_id, img_shape=(640, 640)))
>>> # new
>>> gt_instances1 = gt_instances.new(
...     metainfo=dict(img_id=1, img_shape=(640, 640)),
...                   bboxes=torch.rand((5, 4)),
...                   scores=torch.rand((5,)))
>>> gt_instances2 = gt_instances1.new()
>>> # add and process property
>>> gt_instances = BaseDataElement()
>>> gt_instances.set_metainfo(dict(img_id=9, img_shape=(100, 100)))
>>> assert 'img_shape' in gt_instances.metainfo_keys()
>>> assert 'img_shape' in gt_instances
>>> assert 'img_shape' not in gt_instances.keys()
>>> assert 'img_shape' in gt_instances.all_keys()
>>> print(gt_instances.img_shape)
(100, 100)
>>> gt_instances.scores = torch.rand((5,))
>>> assert 'scores' in gt_instances.keys()
>>> assert 'scores' in gt_instances
>>> assert 'scores' in gt_instances.all_keys()
>>> assert 'scores' not in gt_instances.metainfo_keys()
>>> print(gt_instances.scores)
tensor([0.5230, 0.7885, 0.2426, 0.3911, 0.4876])
>>> gt_instances.bboxes = torch.rand((5, 4))
>>> assert 'bboxes' in gt_instances.keys()
>>> assert 'bboxes' in gt_instances
>>> assert 'bboxes' in gt_instances.all_keys()
>>> assert 'bboxes' not in gt_instances.metainfo_keys()
>>> print(gt_instances.bboxes)
tensor([[0.0900, 0.0424, 0.1755, 0.4469],
        [0.8648, 0.0592, 0.3484, 0.0913],
        [0.5808, 0.1909, 0.6165, 0.7088],
        [0.5490, 0.4209, 0.9416, 0.2374],
        [0.3652, 0.1218, 0.8805, 0.7523]])
>>> # delete and change property
>>> gt_instances = BaseDataElement(
...     metainfo=dict(img_id=0, img_shape=(640, 640)),
...     bboxes=torch.rand((6, 4)), scores=torch.rand((6,)))
>>> gt_instances.set_metainfo(dict(img_shape=(1280, 1280)))
>>> gt_instances.img_shape  # (1280, 1280)
>>> gt_instances.bboxes = gt_instances.bboxes * 2
>>> gt_instances.get('img_shape', None)  # (1280, 1280)
>>> gt_instances.get('bboxes', None)  # 6x4 tensor
>>> del gt_instances.img_shape
>>> del gt_instances.bboxes
>>> assert 'img_shape' not in gt_instances
>>> assert 'bboxes' not in gt_instances
>>> gt_instances.pop('img_shape', None)  # None
>>> gt_instances.pop('bboxes', None)  # None
>>> # Tensor-like
>>> cuda_instances = gt_instances.cuda()
>>> cuda_instances = gt_instances.to('cuda:0')
>>> cpu_instances = cuda_instances.cpu()
>>> cpu_instances = cuda_instances.to('cpu')
>>> fp16_instances = cuda_instances.to(
...     device=None, dtype=torch.float16, non_blocking=False,
...     copy=False, memory_format=torch.preserve_format)
>>> cpu_instances = cuda_instances.detach()
>>> np_instances = cpu_instances.numpy()
>>> # print
>>> metainfo = dict(img_shape=(800, 1196, 3))
>>> gt_instances = BaseDataElement(
...     metainfo=metainfo, det_labels=torch.LongTensor([0, 1, 2, 3]))
>>> sample = BaseDataElement(metainfo=metainfo,
...                          gt_instances=gt_instances)
>>> print(sample)
<BaseDataElement(
    META INFORMATION
    img_shape: (800, 1196, 3)
    DATA FIELDS
    gt_instances: <BaseDataElement(
            META INFORMATION
            img_shape: (800, 1196, 3)
            DATA FIELDS
            det_labels: tensor([0, 1, 2, 3])
        ) at 0x7f0ec5eadc70>
) at 0x7f0fea49e130>
>>> # inheritance
>>> class DetDataSample(BaseDataElement):
...     @property
...     def proposals(self):
...         return self._proposals
...     @proposals.setter
...     def proposals(self, value):
...         self.set_field(value, '_proposals', dtype=BaseDataElement)
...     @proposals.deleter
...     def proposals(self):
...         del self._proposals
...     @property
...     def gt_instances(self):
...         return self._gt_instances
...     @gt_instances.setter
...     def gt_instances(self, value):
...         self.set_field(value, '_gt_instances',
...                        dtype=BaseDataElement)
...     @gt_instances.deleter
...     def gt_instances(self):
...         del self._gt_instances
...     @property
...     def pred_instances(self):
...         return self._pred_instances
...     @pred_instances.setter
...     def pred_instances(self, value):
...         self.set_field(value, '_pred_instances',
...                        dtype=BaseDataElement)
...     @pred_instances.deleter
...     def pred_instances(self):
...         del self._pred_instances
>>> det_sample = DetDataSample()
>>> proposals = BaseDataElement(bboxes=torch.rand((5, 4)))
>>> det_sample.proposals = proposals
>>> assert 'proposals' in det_sample
>>> assert det_sample.proposals == proposals
>>> del det_sample.proposals
>>> assert 'proposals' not in det_sample
>>> with self.assertRaises(AssertionError):
...     det_sample.proposals = torch.rand((5, 4))
all_items()[source]
Returns

An iterator object whose element is (key, value) tuple pairs for metainfo and data.

Return type

iterator

all_keys()[source]
Returns

Contains all keys in metainfo and data.

Return type

list

all_values()[source]
Returns

Contains all values in metainfo and data.

Return type

list

clone()[source]

Deep copy the current data element.

Returns

The copy of current data element.

Return type

BaseDataElement

cpu()[source]

Convert all tensors to CPU in data.

Return type

mmengine.structures.base_data_element.BaseDataElement

cuda()[source]

Convert all tensors to GPU in data.

Return type

mmengine.structures.base_data_element.BaseDataElement

detach()[source]

Detach all tensors in data.

Return type

mmengine.structures.base_data_element.BaseDataElement

get(key, default=None)[source]

Get property in data and metainfo as the same as python.

Return type

Any

items()[source]
Returns

An iterator object whose element is (key, value) tuple pairs for data.

Return type

iterator

keys()[source]
Returns

Contains all keys in data_fields.

Return type

list

property metainfo: dict

A dict contains metainfo of current data element.

Type

dict

metainfo_items()[source]
Returns

An iterator object whose element is (key, value) tuple pairs for metainfo.

Return type

iterator

metainfo_keys()[source]
Returns

Contains all keys in metainfo_fields.

Return type

list

metainfo_values()[source]
Returns

Contains all values in metainfo.

Return type

list

new(*, metainfo=None, **kwargs)[source]

Return a new data element with same type. If metainfo and data are None, the new data element will have same metainfo and data. If metainfo or data is not None, the new result will overwrite it with the input value.

Parameters
  • metainfo (dict, optional) – A dict contains the meta information of image, such as img_shape, scale_factor, etc. Defaults to None.

  • kwargs (dict) – A dict contains annotations of image or model predictions.

Returns

A new data element with same type.

Return type

BaseDataElement

npu()[source]

Convert all tensors to NPU in data.

Return type

mmengine.structures.base_data_element.BaseDataElement

numpy()[source]

Convert all tensors to np.ndarray in data.

Return type

mmengine.structures.base_data_element.BaseDataElement

pop(*args)[source]

Pop property in data and metainfo as the same as python.

Return type

Any

set_data(data)[source]

Set or change key-value pairs in data_field by parameter data.

Parameters

data (dict) – A dict contains annotations of image or model predictions.

Return type

None

set_field(value, name, dtype=None, field_type='data')[source]

Special method for set union field, used as property.setter functions.

Parameters
  • value (Any) –

  • name (str) –

  • dtype (Optional[Union[Type, Tuple[Type, ...]]]) –

  • field_type (str) –

Return type

None

set_metainfo(metainfo)[source]

Set or change key-value pairs in metainfo_field by parameter metainfo.

Parameters

metainfo (dict) – A dict contains the meta information of image, such as img_shape, scale_factor, etc.

Return type

None

to(*args, **kwargs)[source]

Apply same name function to all tensors in data_fields.

Return type

mmengine.structures.base_data_element.BaseDataElement

to_dict()[source]

Convert BaseDataElement to dict.

Return type

dict

to_tensor()[source]

Convert all np.ndarray to tensor in data.

Return type

mmengine.structures.base_data_element.BaseDataElement

update(instance)[source]

The update() method updates the BaseDataElement with the elements from another BaseDataElement object.

Parameters

instance (BaseDataElement) – Another BaseDataElement object for update the current object.

Return type

None

values()[source]
Returns

Contains all values in data.

Return type

list

Read the Docs v: v0.5.0
Versions
latest
stable
v0.5.0
v0.4.0
v0.3.0
v0.2.0
Downloads
On Read the Docs
Project Home
Builds

Free document hosting provided by Read the Docs.