Volume3D

⚠️ This type is unstable and may change significantly in a way that the data won't be backwards compatible. A dense 3D scalar field, rendered by ray marching.

This archetype is intended for volumetric scans and simulations, e.g. CT/MRI scans, signed distance fields, or occupancy probabilities sampled on a regular grid.

The values are a 3D tensor with dimensions ordered [z, y, x], i.e. the last dimension varies fastest and runs along the local X axis. This matches the row-major layout of archetypes.Image, with slices stacked along the local Z axis. The tensor element at [k, j, i] is thus the voxel with grid index [i, j, k].

Voxels are positioned exactly like those of archetypes.VoxelGridMap: the minimum corner of the voxel with [0, 0, 0] index is located at the origin of the entity's coordinate frame and can have an additional offset from there through the optional translation and rotation fields, and a voxel center is at (index + 0.5) * voxel_size in local grid coordinates (i.e. relative to the minimum corner). This archetype and a archetypes.VoxelGridMap with the same voxel_size and pose therefore agree voxel for voxel, the dense volume covering indices [0, 0, 0] up to [width - 1, height - 1, depth - 1].

Fields

Required

• values: TensorData

Recommended

• voxel_size: VoxelSize

Optional

• translation: Translation3D
• quaternion: RotationQuat
• value_range: ValueRange
• colormap: Colormap
• opacity: Opacity

Can be shown in

• Spatial3DView
• DataframeView

API reference links

• 🌊 C++ API docs for Volume3D
• 🐍 Python API docs for Volume3D
• 🦀 Rust API docs for Volume3D

Example

Simple volume

"""Log a small volume: a soft sphere sampled on a 32³ grid."""

import numpy as np

import rerun as rr

SIZE = 32
RADIUS = np.float32(14.0)

rr.init("rerun_example_volume3d_simple", spawn=True)

# Squared distance from the center of the grid, per voxel, in voxel units.
axis = np.arange(SIZE, dtype=np.float32) - np.float32(0.5 * (SIZE - 1))
z, y, x = np.meshgrid(axis, axis, axis, indexing="ij")
distance_sq = x * x + y * y + z * z

# A soft sphere: 1 at the center, falling off to 0 at `RADIUS`.
values = np.maximum(
    np.float32(0.0), np.float32(1.0) - distance_sq / (RADIUS * RADIUS)
)

# Dimensions are ordered `[z, y, x]`. Only `f16` values are supported for now.
rr.log(
    "volume",
    rr.Volume3D(values.astype(np.float16), voxel_size=[0.1, 0.1, 0.1]),
)