BaseDataElement

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

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().

参数:

• 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.

示例

>>> 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()

返回:

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

返回类型:

iterator

all_keys()

返回:

Contains all keys in metainfo and data.

返回类型:

list

all_values()

返回:

Contains all values in metainfo and data.

返回类型:

list

clone()

Deep copy the current data element.

返回:

The copy of current data element.

返回类型:

BaseDataElement

cpu()

Convert all tensors to CPU in data.

返回类型:

BaseDataElement

cuda()

Convert all tensors to GPU in data.

返回类型:

BaseDataElement

detach()

Detach all tensors in data.

返回类型:

BaseDataElement

get(key, default=None)

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

返回类型:

Any

items()

返回:

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

返回类型:

iterator

keys()

返回:

Contains all keys in data_fields.

返回类型:

list

property metainfo: dict

A dict contains metainfo of current data element.

Type:

dict

metainfo_items()

返回:

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

返回类型:

iterator

metainfo_keys()

返回:

Contains all keys in metainfo_fields.

返回类型:

list

metainfo_values()

返回:

Contains all values in metainfo.

返回类型:

list

mlu()

Convert all tensors to MLU in data.

返回类型:

BaseDataElement

musa()

Convert all tensors to musa in data.

返回类型:

BaseDataElement

new(*, metainfo=None, **kwargs)

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.

参数:

• 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.

返回:

A new data element with same type.

返回类型:

BaseDataElement

npu()

Convert all tensors to NPU in data.

返回类型:

BaseDataElement

numpy()

Convert all tensors to np.ndarray in data.

返回类型:

BaseDataElement

pop(*args)

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

返回类型:

Any

set_data(data)

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

参数:

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

返回类型:

None

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

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

参数:

• value (Any) –

• name (str) –

• dtype (Type | Tuple[Type, ...] | None) –

• field_type (str) –

返回类型:

None

set_metainfo(metainfo)

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

参数:

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

返回类型:

None

to(*args, **kwargs)

Apply same name function to all tensors in data_fields.

返回类型:

BaseDataElement

to_dict()

Convert BaseDataElement to dict.

返回类型:

dict

to_tensor()

Convert all np.ndarray to tensor in data.

返回类型:

BaseDataElement

update(instance)

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

参数:

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

返回类型:

None

values()

返回:

Contains all values in data.

返回类型:

list