1 utils.tensor_payloads

utils.tensor_payloads

Shared typed-payload helpers for cache and offline-store serialization.

This module centralizes the project-wide logic for converting dataclass-based runtime objects to CPU-only, msgspec-compatible payloads and reconstructing them later. It supports the tensor-wrapper types commonly used across Aria-NBV, including PoseTW, CameraTW, ObbTW, generic TensorWrapper subclasses, and PyTorch3D PerspectiveCameras.

The helpers here are intentionally shared across both aria_nbv.data and aria_nbv.data_handling so the project does not maintain duplicate custom serialization code in multiple data packages.

1.1 Classes

Name Description
PerspectiveCameraPayload Msgspec payload for a PyTorch3D PerspectiveCameras batch.
TensorPayload Msgspec payload for a CPU tensor.

1.1.1 PerspectiveCameraPayload

utils.tensor_payloads.PerspectiveCameraPayload()

Msgspec payload for a PyTorch3D PerspectiveCameras batch.

1.1.1.1 Attributes

Name Description
kind Stable type tag used during untyped restoration.
R Rotation matrices.
T Translation vectors.
focal_length Focal lengths.
principal_point Principal points.
image_size Image sizes.
in_ndc Whether the batch is in NDC coordinates.
znear Optional near-plane value.
zfar Optional far-plane value.

1.1.1.2 Methods

Name Description
from_cameras Build a payload from a PyTorch3D camera batch.
to_cameras Reconstruct the camera batch represented by this payload.
1.1.1.2.1 from_cameras
utils.tensor_payloads.PerspectiveCameraPayload.from_cameras(cameras)

Build a payload from a PyTorch3D camera batch.

1.1.1.2.1.1 Parameters
Name Type Description Default
cameras PerspectiveCameras Camera batch to serialize. required
1.1.1.2.1.2 Returns
Name Type Description
'PerspectiveCameraPayload' CPU payload describing the camera batch.
1.1.1.2.2 to_cameras
utils.tensor_payloads.PerspectiveCameraPayload.to_cameras(device)

Reconstruct the camera batch represented by this payload.

1.1.1.2.2.1 Parameters
Name Type Description Default
device torch.device Destination device. required
1.1.1.2.2.2 Returns
Name Type Description
PerspectiveCameras Reconstructed PerspectiveCameras batch.

1.1.2 TensorPayload

utils.tensor_payloads.TensorPayload()

Msgspec payload for a CPU tensor.

1.1.2.1 Attributes

Name Type Description
kind str Stable type tag used when decoding untyped payloads.
dtype str NumPy dtype string for the stored array.
shape tuple[int, …] Full tensor shape.
data bytes Contiguous raw bytes for the CPU tensor.

1.1.2.2 Methods

Name Description
from_tensor Build a payload from a tensor.
to_tensor Reconstruct the tensor represented by this payload.
1.1.2.2.1 from_tensor
utils.tensor_payloads.TensorPayload.from_tensor(tensor)

Build a payload from a tensor.

1.1.2.2.1.1 Parameters
Name Type Description Default
tensor Tensor Tensor to serialize. required
1.1.2.2.1.2 Returns
Name Type Description
'TensorPayload' CPU payload describing the tensor.
1.1.2.2.2 to_tensor
utils.tensor_payloads.TensorPayload.to_tensor(device=None)

Reconstruct the tensor represented by this payload.

1.1.2.2.2.1 Parameters
Name Type Description Default
device torch.device | None Optional destination device. None
1.1.2.2.2.2 Returns
Name Type Description
Tensor Reconstructed tensor.

1.2 Functions

Name Description
from_serializable Reconstruct a typed runtime object from a serialized payload.
to_serializable Convert a runtime value into a msgspec-compatible CPU payload.

1.2.1 from_serializable

utils.tensor_payloads.from_serializable(
    cls,
    payload,
    *,
    device,
    include_fields=None,
)

Reconstruct a typed runtime object from a serialized payload.

1.2.1.1 Parameters

Name Type Description Default
cls type[SerializableType] Target runtime type. required
payload Any Serialized payload. required
device torch.device | None Optional destination device for tensors and wrappers. required
include_fields set[str] | None Optional subset of dataclass fields to decode. None

1.2.1.2 Returns

Name Type Description
SerializableType Reconstructed runtime object.

1.2.2 to_serializable

utils.tensor_payloads.to_serializable(value, *, exclude=None)

Convert a runtime value into a msgspec-compatible CPU payload.

1.2.2.1 Parameters

Name Type Description Default
value Any Runtime value to serialize. required
exclude set[str] | None Optional dataclass field names to omit. None

1.2.2.2 Returns

Name Type Description
Any Serializable builtins composed of scalars, lists, dicts, bytes, and
Any tagged msgspec payloads.
Back to top