Shortcuts

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.

返回类型

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.

返回类型

mmengine.structures.base_data_element.BaseDataElement

cuda()[源代码]

Convert all tensors to GPU in data.

返回类型

mmengine.structures.base_data_element.BaseDataElement

detach()[源代码]

Detach all tensors in data.

返回类型

mmengine.structures.base_data_element.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

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.

返回类型

mmengine.structures.base_data_element.BaseDataElement

numpy()[源代码]

Convert all tensors to np.ndarray in data.

返回类型

mmengine.structures.base_data_element.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 (Optional[Union[Type, Tuple[Type, ...]]]) –

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

返回类型

mmengine.structures.base_data_element.BaseDataElement

to_dict()[源代码]

Convert BaseDataElement to dict.

返回类型

dict

to_tensor()[源代码]

Convert all np.ndarray to tensor in data.

返回类型

mmengine.structures.base_data_element.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

Read the Docs v: latest
Versions
latest
stable
Downloads
pdf
html
epub
On Read the Docs
Project Home
Builds

Free document hosting provided by Read the Docs.