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
andpred_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 classBaseDataElement
, and implementInstanceData
,PixelData
, andLabelData
inheriting fromBaseDataElement
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, themetainfo
and thedata
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 alltorch.Tensor
in thedata_fields
, such as.cuda()
,.cpu()
,.numpy()
,.to()
,to_tensor()
,.detach()
.
- Parameters
- Return type
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
anddata
.- Return type
iterator
- clone()[source]¶
Deep copy the current data element.
- Returns
The copy of current data element.
- Return type
- 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
- metainfo_items()[source]¶
- Returns
An iterator object whose element is (key, value) tuple pairs for
metainfo
.- Return type
iterator
- new(*, metainfo=None, **kwargs)[source]¶
Return a new data element with same type. If
metainfo
anddata
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
- Returns
A new data element with same type.
- Return type
- set_field(value, name, dtype=None, field_type='data')[source]¶
Special method for set union field, used as property.setter functions.
- set_metainfo(metainfo)[source]¶
Set or change key-value pairs in
metainfo_field
by parametermetainfo
.
- 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