data module

Armory data types

class data.BBoxFormat(value)

Bases: Enum

The format of bounding box coordinates.

CXCYWH = 3: Coordinates are the center X and Y and the widht and height

XYWH = 2: Coordinates are the upper left X and Y and the width and height

XYXY = 1: Coordinates are the upper left X and Y and lower right X and Y

class data.Batch(*args, **kwargs)

Bases: Protocol

A collated sequence of samples to be processed simultaneously.

clone()

property initial_inputs: DataWithSpecification

property inputs: DataWithSpecification

property metadata: Metadata

property predictions: DataWithSpecification

property targets: DataWithSpecification

class data.BoundingBoxSpec(format: data.BBoxFormat)

Bases: DataSpecification

format: BBoxFormat: Bounding box coordinate format

class data.BoundingBoxes(boxes: Sequence[BoxesNumpy] | Sequence[BoxesTorch], spec: BoundingBoxSpec)

Bases: DataWithSpecification

Object detection targets or predictions

class BoxesNumpy(*args, **kwargs)

Bases: dict

NumPy representation of bounding boxes

boxes: ndarray

labels: ndarray

scores: ndarray | None

class BoxesTorch(*args, **kwargs)

Bases: dict

PyTorch tensor representation of bounding boxes

boxes: Tensor

labels: Tensor

scores: Tensor | None

clone()

get(spec: NumpySpec) → Sequence[BoxesNumpy]

get(spec: TorchSpec) → Sequence[BoxesTorch]

get(spec: BoundingBoxSpec) → _RawDataTypes

Retrieves a copy of the raw bounding boxes data with the given bounding box data specification.

Example:

from armory.data import BBoxFormat, NumpyBoundingBoxSpec, TorchBoundingBoxSpec

# assuming `boxes` has been defined elsewhere
boxes_pt = boxes.get(TorchBoundingBoxSpec(
    format=BBoxFormat.XYWH,
))

boxes_np = boxes.get(NumpyBoundingBoxSpec(
    format=BBoxFormat.CXCYWH,
))

Parameters:: spec (Union[BoundingBoxSpec, NumpySpec, TorchSpec]) – Specification for the structure, format, and values of the raw bounding boxes data to be returned
Returns:: Raw bounding boxes data matching the requested specification
Return type:: _RawDataTypes

set(boxes: Sequence[BoxesNumpy] | Sequence[BoxesTorch], spec: BoundingBoxSpec) → None

Replaces the bounding boxes data.

Parameters:

boxes (_RawDataTypes) – New raw bounding boxes data
spec (BoundingBoxSpec) – New bounding box data specification

class data.DataSpecification

Bases: object

A specification for the structure, format, and values of raw data.

class data.DataType(value)

Bases: Enum

Data type for image data values.

FLOAT = 2: Floating point.

UINT8 = 1: Unsigned 8-bit integer.

class data.DataWithSpecification(*args, **kwargs)

Bases: Protocol

Data with an accompanying specification, which may be converted to raw data of a different specification.

clone() → Self

get(specification: DataSpecification) → object: Retrieves a copy of the data with the given data specification. Specific subtypes will support different specifications according to the nature of the data.

set(data: object, specification: DataSpecification) → None: Replaces the data with the given data specification.

class data.ImageClassificationBatch(inputs: Images, targets: NDimArray, metadata: Metadata | None = None, predictions: NDimArray | None = None)

Bases: Batch

A batch of images and classified label/category predictions

clone() → ImageClassificationBatch

property initial_inputs: Images

property inputs: Images

property metadata: Metadata

property predictions: NDimArray

property targets: NDimArray

class data.ImageDimensions(value)

Bases: Enum

The format of a 3-dimensional data array containing image data.

CHW = 1: Images whose n-dim array shape is (C, H, W) with the first dimension being the channels and the last two are the height and width.

HWC = 2: Images whose n-dim array shape is (H, W, C) with the last dimension being the channels and the first two are the height and width.

class data.ImageSpec(dim: data.ImageDimensions, scale: data.Scale)

Bases: DataSpecification

dim: ImageDimensions: Image dimension format

scale: Scale: Image data scale

class data.Images(images: ndarray | Tensor, spec: ImageSpec)

Bases: DataWithSpecification

Computer vision model inputs

clone()

get(spec: NumpySpec) → ndarray

get(spec: TorchSpec) → Tensor

get(spec: ImageSpec) → _RawDataTypes

Retrieves a copy of the raw images data with the given image data specification.

Example:

from armory.data import DataType, ImageDimensions, NumpyImageSpec, Scale, TorchImageSpec

# assuming `images` has been defined elsewhere
images_pt = images.get(TorchImageSpec(
    dim=ImageDimensions.CHW,
    scale=Scale(
        dtype=DataType.FLOAT,
        max=1.0,
    ),
))

images_np = images.get(NumpyImageSpec(
    dim=ImageDimensions.HWC,
    scale=Scale(
        dtype=DataType.UINT8,
        max=255,
    ),
))

Parameters:: spec (Union[ImageSpec, NumpySpec, TorchSpec]) – Specification for the structure, format, and values of the raw images data to be returned
Returns:: Raw images data matching the requested specification
Return type:: _RawDataTypes

set(images: ndarray | Tensor, spec: ImageSpec) → None

Replaces the image data.

Parameters:

images (_RawDataTypes) – New raw images data
spec (ImageSpec) – New image data specification

class data.Metadata(*args, **kwargs)

Bases: dict

Metadata about the source data or perturbations that have been applied to a batch.

data: Dict[str, Any]

perturbations: Dict[str, Any]

class data.NDimArray(contents: ndarray | Tensor)

Bases: DataWithSpecification

Variable-dimension data array

clone()

get(spec: NumpySpec) → ndarray

get(spec: TorchSpec) → Tensor

Retrieves a copy of the raw data array with the given data specification.

Example:

from armory.data import NumpySpec, TorchSpec

# assuming `data` has been defined elsewhere
data_pt = data.get(TorchSpec())

data_np = data.get(NumpySpec())

Parameters:: spec (Union[NumpySpec, TorchSpec]) – Specification for the data type of the raw data array to be returned
Returns:: Raw data array matching the requested specification
Return type:: _RawDataTypes

set(contents: ndarray | Tensor) → None

Replaces the data array.

Parameters:: contents (_RawDataTypes) – New raw data array

Bases: NumpySpec, BoundingBoxSpec

Bounding box data specification using NumPy arrays

box_dtype: dtype[Any] | None | Type[Any] | _SupportsDType[dtype[Any]] | str | Tuple[Any, int] | Tuple[Any, SupportsIndex | Sequence[SupportsIndex]] | List[Any] | _DTypeDict | Tuple[Any, Any] = None: Optional, the NumPy dtype in which to represent bounding box coordinates. If none specified, the dtype will be unchanged.

label_dtype: dtype[Any] | None | Type[Any] | _SupportsDType[dtype[Any]] | str | Tuple[Any, int] | Tuple[Any, SupportsIndex | Sequence[SupportsIndex]] | List[Any] | _DTypeDict | Tuple[Any, Any] = None: Optional, the NumPy dtype in which to represent object labels. If none specified, the dtype will be unchanged.

score_dtype: dtype[Any] | None | Type[Any] | _SupportsDType[dtype[Any]] | str | Tuple[Any, int] | Tuple[Any, SupportsIndex | Sequence[SupportsIndex]] | List[Any] | _DTypeDict | Tuple[Any, Any] = None: Optional, the NumPy dtype in which to represent prediction scores. If none specified, the dtype will be unchanged.

Bases: NumpySpec, ImageSpec

Image data specification using NumPy arrays

Bases: DataSpecification

A data specification for data types based on NumPy arrays.

dtype: dtype[Any] | None | Type[Any] | _SupportsDType[dtype[Any]] | str | Tuple[Any, int] | Tuple[Any, SupportsIndex | Sequence[SupportsIndex]] | List[Any] | _DTypeDict | Tuple[Any, Any] = None: Optional, the NumPy dtype in which to represent data based on NumPy arrays. If none specified, the dtype will be unchanged.

class data.ObjectDetectionBatch(inputs: Images, targets: BoundingBoxes, metadata: Metadata | None = None, predictions: BoundingBoxes | None = None)

Bases: Batch

A batch of images and detected object bounding box predictions

clone() → ObjectDetectionBatch

property initial_inputs: Images

property inputs: Images

property metadata: Metadata

property predictions: BoundingBoxes

property targets: BoundingBoxes

class data.Scale(dtype: DataType, max: int | float, mean: Tuple[float, ...] | None = None, std: Tuple[float, ...] | None = None)

Bases: object

Image data scaling parameters.

dtype: DataType: The data type of the image data values.

property is_normalized: bool: Whether the image data has been normalized.

max: int | float: The maximum value of the (unnormalized) image data values.

mean: Tuple[float, ...] | None = None: If normalized, the mean used for normalization.

std: Tuple[float, ...] | None = None: If normalized, the standard deviation used for normalization.

Bases: TorchSpec, BoundingBoxSpec

Bounding box data specification using PyTorch Tensors

box_dtype: dtype | None = None: Optional, the PyTorch dtype in which to represent bounding box coordinates. If none specified, the dtype will be unchanged.

label_dtype: dtype | None = None: Optional, the PyTorch dtype in which to represent object labels. If none specified, the dtype will be unchanged.

score_dtype: dtype | None = None: Optional, the PyTorch dtype in which to represent prediction scores. If none specified, the dtype will be unchanged.

class data.TorchImageSpec(dim: ImageDimensions, scale: Scale, dtype: dtype | None = None, device: device | None = None)

Bases: TorchSpec, ImageSpec

Image data specification using PyTorch Tensors

class data.TorchSpec(dtype: dtype | None = None, device: device | None = None)

Bases: DataSpecification

A data specification for data types based on PyTorch Tensors.

device: device | None = None: Optional, the PyTorch device on which to store the data. If none specified, the data will be unmoved from the originating device.

dtype: dtype | None = None: Optional, the PyTorch dtype in which to represent data based on PyTorch Tensors. If none specified, the dtype will be unchanged.

to(device: device) → None: Moves the target device of this spec to the given device, but only if the spec was not originally created with an explicit device.

data.convert_dim(data, from_dim: ImageDimensions, to_dim: ImageDimensions | None = None): Converts image data from the original dimension format to the new dimension format, if one is specified and does not already match the image data’s current dimension format.

data.convert_scale(data, from_scale: Scale, to_scale: Scale | None = None): Converts image data from the original scale to the new scale, if one is specified and does not already match the image data’s current scale.

data.debug(arg) → str: Creates a string message describing the argument, useful for debug logging.

data.normalize(data, mean, std): Normalizes the given image data using the given mean and standard deviation.

data.to_bbox_format(data, from_format: BBoxFormat, to_format: BBoxFormat | None = None): Converts bounding boxes from the original coordinate format to the new format, if one is specified and does not already match the bounding box’s current coordinate format.

data.to_device(arg: Tensor, device: device | None): Moves the given PyTorch tensor to the given device, if one is specified and does not already match the tensor’s current device.

data.to_dtype(arg: T, dtype) → T: Converts the dtype of the argument to the given dtype

data.to_float_dtype(arg: T) → T: Converts the dtype of the argument to float.

data.to_numpy(arg) → ndarray: Converts the argument to a NumPy array.

data.to_torch(arg) → Tensor: Converts the argument to a PyTorch tensor.

data.unnormalize(data, mean, std): Unnormalizes the given normalized image data using the given mean and standard deviation.