BaseDataElement — mmengine 0.10.7 documentation (original) (raw)
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 usinggt_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 classBaseDataElement, and implement InstanceData, PixelData, andLabelData 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 BaseDataElementallows 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 thedata_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.
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()
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))
Returns:
An iterator object whose element is (key, value) tuple pairs for metainfo and data.
Return type:
iterator
Returns:
Contains all keys in metainfo and data.
Return type:
Returns:
Contains all values in metainfo and data.
Return type:
Deep copy the current data element.
Returns:
The copy of current data element.
Return type:
Convert all tensors to CPU in data.
Return type:
Convert all tensors to GPU in data.
Return type:
Detach all tensors in data.
Return type:
get(key, default=None)[source]¶
Get property in data and metainfo as the same as python.
Return type:
Returns:
An iterator object whose element is (key, value) tuple pairs for data.
Return type:
iterator
Returns:
Contains all keys in data_fields.
Return type:
A dict contains metainfo of current data element.
Type:
Returns:
An iterator object whose element is (key, value) tuple pairs for metainfo.
Return type:
iterator
Returns:
Contains all keys in metainfo_fields.
Return type:
Returns:
Contains all values in metainfo.
Return type:
Convert all tensors to MLU in data.
Return type:
Convert all tensors to musa in data.
Return type:
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:
- 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:
Convert all tensors to NPU in data.
Return type:
Convert all tensors to np.ndarray in data.
Return type:
Pop property in data and metainfo as the same as python.
Return type:
Set or change key-value pairs in data_field by parameterdata.
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:
Return type:
None
set_metainfo(metainfo)[source]¶
Set or change key-value pairs in metainfo_field by parametermetainfo.
Parameters:
metainfo (dict) – A dict contains the meta information of image, such as img_shape, scale_factor, etc.
Return type:
None
Apply same name function to all tensors in data_fields.
Return type:
Convert BaseDataElement to dict.
Return type:
Convert all np.ndarray to tensor in data.
Return type:
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
Returns:
Contains all values in data.
Return type: