Archetype: A dense 3D scalar field, rendered by ray marching. More...

#include <rerun/archetypes/volume3d.hpp>

Public Member Functions
RR_DISABLE_MAYBE_UNINITIALIZED_PUSH	Volume3D (Collection< uint64_t > shape, encodings::TensorBuffer buffer)
	New Volume3D from dimensions and tensor buffer.

	Volume3D (Volume3D &&other)=default

	Volume3D (const Volume3D &other)=default

Volume3D &	operator= (const Volume3D &other)=default

Volume3D &	operator= (Volume3D &&other)=default

	Volume3D (rerun::components::TensorData _values)

Volume3D	with_values (const rerun::components::TensorData &_values) &&
	The scalar value of each voxel, as a 3D tensor with dimensions ordered `[z, y, x]`.

Volume3D	with_many_values (const Collection< rerun::components::TensorData > &_values) &&
	This method makes it possible to pack multiple `values` in a single component batch.

Volume3D	with_voxel_size (const rerun::components::VoxelSize &_voxel_size) &&
	The scene-unit dimensions of a single voxel cell.

Volume3D	with_many_voxel_size (const Collection< rerun::components::VoxelSize > &_voxel_size) &&
	This method makes it possible to pack multiple `voxel_size` in a single component batch.

Volume3D	with_translation (const rerun::components::Translation3D &_translation) &&
	Translation of the minimum corner of voxel `[0, 0, 0]`.

Volume3D	with_many_translation (const Collection< rerun::components::Translation3D > &_translation) &&
	This method makes it possible to pack multiple `translation` in a single component batch.

Volume3D	with_quaternion (const rerun::components::RotationQuat &_quaternion) &&
	Rotation of the volume via quaternion.

Volume3D	with_many_quaternion (const Collection< rerun::components::RotationQuat > &_quaternion) &&
	This method makes it possible to pack multiple `quaternion` in a single component batch.

Volume3D	with_value_range (const rerun::components::ValueRange &_value_range) &&
	How to map `values` to opacity and color.

Volume3D	with_many_value_range (const Collection< rerun::components::ValueRange > &_value_range) &&
	This method makes it possible to pack multiple `value_range` in a single component batch.

Volume3D	with_colormap (const rerun::components::Colormap &_colormap) &&
	Colormap applied to the values after mapping them through `value_range`.

Volume3D	with_many_colormap (const Collection< rerun::components::Colormap > &_colormap) &&
	This method makes it possible to pack multiple `colormap` in a single component batch.

Volume3D	with_opacity (const rerun::components::Opacity &_opacity) &&
	Overall opacity of the volume.

Volume3D	with_many_opacity (const Collection< rerun::components::Opacity > &_opacity) &&
	This method makes it possible to pack multiple `opacity` in a single component batch.

Collection< ComponentColumn >	columns (const Collection< uint32_t > &lengths_)
	Partitions the component data into multiple sub-batches.

Collection< ComponentColumn >	columns ()
	Partitions the component data into unit-length sub-batches.

Static Public Member Functions
static Volume3D	update_fields ()
	Update only some specific fields of a `Volume3D`.

static Volume3D	clear_fields ()
	Clear all the fields of a `Volume3D`.

Public Attributes
std::optional< ComponentBatch >	values
	The scalar value of each voxel, as a 3D tensor with dimensions ordered `[z, y, x]`.

std::optional< ComponentBatch >	voxel_size
	The scene-unit dimensions of a single voxel cell.

std::optional< ComponentBatch >	translation
	Translation of the minimum corner of voxel `[0, 0, 0]`.

std::optional< ComponentBatch >	quaternion
	Rotation of the volume via quaternion.

std::optional< ComponentBatch >	value_range
	How to map `values` to opacity and color.

std::optional< ComponentBatch >	colormap
	Colormap applied to the values after mapping them through `value_range`.

std::optional< ComponentBatch >	opacity
	Overall opacity of the volume.

Static Public Attributes
static constexpr const char	ArchetypeName [] = "rerun.archetypes.Volume3D"
	The name of the archetype as used in `ComponentDescriptor`s.

static constexpr auto	Descriptor_values
	`ComponentDescriptor` for the `values` field.

static constexpr auto	Descriptor_voxel_size
	`ComponentDescriptor` for the `voxel_size` field.

static constexpr auto	Descriptor_translation
	`ComponentDescriptor` for the `translation` field.

static constexpr auto	Descriptor_quaternion
	`ComponentDescriptor` for the `quaternion` field.

static constexpr auto	Descriptor_value_range
	`ComponentDescriptor` for the `value_range` field.

static constexpr auto	Descriptor_colormap
	`ComponentDescriptor` for the `colormap` field.

static constexpr auto	Descriptor_opacity
	`ComponentDescriptor` for the `opacity` field.

Detailed Description

Archetype: 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].

Example

Simple volume

#include <rerun.hpp>
 
#include <algorithm> // std::max
#include <vector>
 
constexpr size_t SIZE = 32;
constexpr float RADIUS = 14.0f;
 
int main(int argc, char* argv[]) {
    const auto rec = rerun::RecordingStream("rerun_example_volume3d_simple");
    rec.spawn().exit_on_failure();
 
    // Dimensions are ordered `[z, y, x]`. Only `f16` values are supported for now.
    std::vector<rerun::half> values;
    values.reserve(SIZE * SIZE * SIZE);
    for (size_t z = 0; z <SIZE; ++z) {
        for (size_t y = 0; y <SIZE; ++y) {
            for (size_t x = 0; x <SIZE; ++x) {
                // Squared distance from the center of the grid, in voxel units.
                const float center = 0.5f * static_cast<float>(SIZE - 1);
                const float dx = static_cast<float>(x) - center;
                const float dy = static_cast<float>(y) - center;
                const float dz = static_cast<float>(z) - center;
                const float distance_sq = dx * dx + dy * dy + dz * dz;
 
                // A soft sphere: 1 at the center, falling off to 0 at `RADIUS`.
                values.push_back(rerun::half::from_float(
                    std::max(0.0f, 1.0f - distance_sq / (RADIUS * RADIUS))
                ));
            }
        }
    }
 
    rec.log(
        "volume",
        rerun::Volume3D({SIZE, SIZE, SIZE}, values)
            .with_voxel_size(rerun::Vec3D(0.1f, 0.1f, 0.1f))
    );
}

⚠ This type is unstable and may change significantly in a way that the data won't be backwards compatible.

Member Function Documentation

◆ with_values()

Volume3D rerun::archetypes::Volume3D::with_values ( const rerun::components::TensorData & _values ) &&

inline

The scalar value of each voxel, as a 3D tensor with dimensions ordered [z, y, x].

Currently only f16 are supported.

◆ with_many_values()

Volume3D rerun::archetypes::Volume3D::with_many_values ( const Collection< rerun::components::TensorData > & _values ) &&

inline

This method makes it possible to pack multiple values in a single component batch.

This only makes sense when used in conjunction with columns. with_values should be used when logging a single row's worth of data.

◆ with_voxel_size()

Volume3D rerun::archetypes::Volume3D::with_voxel_size ( const rerun::components::VoxelSize & _voxel_size ) &&

inline

The scene-unit dimensions of a single voxel cell.

This defines the voxel size along the local grid X/Y/Z axes, and thus the total extent of the volume: [width, height, depth] * voxel_size. Anisotropic spacing (as is common for medical scans) is expressed here. Each dimension must be finite and positive.

Defaults to [1.0, 1.0, 1.0].

◆ with_many_voxel_size()

Volume3D rerun::archetypes::Volume3D::with_many_voxel_size ( const Collection< rerun::components::VoxelSize > & _voxel_size ) &&

inline

This method makes it possible to pack multiple voxel_size in a single component batch.

This only makes sense when used in conjunction with columns. with_voxel_size should be used when logging a single row's worth of data.

◆ with_translation()

Volume3D rerun::archetypes::Volume3D::with_translation ( const rerun::components::Translation3D & _translation ) &&

inline

Translation of the minimum corner of voxel [0, 0, 0].

Together with components::RotationQuat, this defines the pose of the volume relative to the entity's coordinate frame.

If not set, the minimum corner is placed at the origin of the entity's coordinate frame.

◆ with_many_translation()

Volume3D rerun::archetypes::Volume3D::with_many_translation ( const Collection< rerun::components::Translation3D > & _translation ) &&

inline

This method makes it possible to pack multiple translation in a single component batch.

This only makes sense when used in conjunction with columns. with_translation should be used when logging a single row's worth of data.

◆ with_quaternion()

Volume3D rerun::archetypes::Volume3D::with_quaternion ( const rerun::components::RotationQuat & _quaternion ) &&

inline

Rotation of the volume via quaternion.

Together with components::Translation3D, this defines the pose of the volume relative to the entity's coordinate frame. The rotation is around the minimum corner of voxel [0, 0, 0], and is applied before the translation.

◆ with_many_quaternion()

Volume3D rerun::archetypes::Volume3D::with_many_quaternion ( const Collection< rerun::components::RotationQuat > & _quaternion ) &&

inline

This method makes it possible to pack multiple quaternion in a single component batch.

This only makes sense when used in conjunction with columns. with_quaternion should be used when logging a single row's worth of data.

◆ with_value_range()

Volume3D rerun::archetypes::Volume3D::with_value_range ( const rerun::components::ValueRange & _value_range ) &&

inline

How to map values to opacity and color.

If not specified, the range is estimated from the data.

◆ with_many_value_range()

Volume3D rerun::archetypes::Volume3D::with_many_value_range ( const Collection< rerun::components::ValueRange > & _value_range ) &&

inline

This method makes it possible to pack multiple value_range in a single component batch.

This only makes sense when used in conjunction with columns. with_value_range should be used when logging a single row's worth of data.

◆ with_colormap()

Volume3D rerun::archetypes::Volume3D::with_colormap ( const rerun::components::Colormap & _colormap ) &&

inline

Colormap applied to the values after mapping them through value_range.

Defaults to Turbo.

◆ with_many_colormap()

Volume3D rerun::archetypes::Volume3D::with_many_colormap ( const Collection< rerun::components::Colormap > & _colormap ) &&

inline

This method makes it possible to pack multiple colormap in a single component batch.

This only makes sense when used in conjunction with columns. with_colormap should be used when logging a single row's worth of data.

◆ with_opacity()

Volume3D rerun::archetypes::Volume3D::with_opacity ( const rerun::components::Opacity & _opacity ) &&

inline

Overall opacity of the volume.

The opacity of a single voxel is its value (normalized through value_range) scaled by this, i.e. a linear ramp: low values are transparent, high values are opaque. Lowering this makes the interior of the volume visible.

Defaults to 1.0.

◆ with_many_opacity()

Volume3D rerun::archetypes::Volume3D::with_many_opacity ( const Collection< rerun::components::Opacity > & _opacity ) &&

inline

This method makes it possible to pack multiple opacity in a single component batch.

This only makes sense when used in conjunction with columns. with_opacity should be used when logging a single row's worth of data.

◆ columns() [1/2]

Collection< ComponentColumn > rerun::archetypes::Volume3D::columns ( const Collection< uint32_t > & lengths_ )

Partitions the component data into multiple sub-batches.

Specifically, this transforms the existing ComponentBatch data into ComponentColumns instead, via ComponentBatch::partitioned.

This makes it possible to use RecordingStream::send_columns to send columnar data directly into Rerun.

The specified lengths must sum to the total length of the component batch.

◆ columns() [2/2]

Collection< ComponentColumn > rerun::archetypes::Volume3D::columns ( )

Partitions the component data into unit-length sub-batches.

This is semantically similar to calling columns with std::vector<uint32_t>(n, 1), where n is automatically guessed.

Member Data Documentation

◆ values

std::optional<ComponentBatch> rerun::archetypes::Volume3D::values

The scalar value of each voxel, as a 3D tensor with dimensions ordered [z, y, x].

Currently only f16 are supported.

◆ voxel_size

std::optional<ComponentBatch> rerun::archetypes::Volume3D::voxel_size

The scene-unit dimensions of a single voxel cell.

This defines the voxel size along the local grid X/Y/Z axes, and thus the total extent of the volume: [width, height, depth] * voxel_size. Anisotropic spacing (as is common for medical scans) is expressed here. Each dimension must be finite and positive.

Defaults to [1.0, 1.0, 1.0].

◆ translation

std::optional<ComponentBatch> rerun::archetypes::Volume3D::translation

Translation of the minimum corner of voxel [0, 0, 0].

Together with components::RotationQuat, this defines the pose of the volume relative to the entity's coordinate frame.

If not set, the minimum corner is placed at the origin of the entity's coordinate frame.

◆ quaternion

std::optional<ComponentBatch> rerun::archetypes::Volume3D::quaternion

Rotation of the volume via quaternion.

Together with components::Translation3D, this defines the pose of the volume relative to the entity's coordinate frame. The rotation is around the minimum corner of voxel [0, 0, 0], and is applied before the translation.

◆ value_range

std::optional<ComponentBatch> rerun::archetypes::Volume3D::value_range

How to map values to opacity and color.

If not specified, the range is estimated from the data.

◆ colormap

std::optional<ComponentBatch> rerun::archetypes::Volume3D::colormap

Colormap applied to the values after mapping them through value_range.

Defaults to Turbo.

◆ opacity

std::optional<ComponentBatch> rerun::archetypes::Volume3D::opacity

Overall opacity of the volume.

The opacity of a single voxel is its value (normalized through value_range) scaled by this, i.e. a linear ramp: low values are transparent, high values are opaque. Lowering this makes the interior of the volume visible.

Defaults to 1.0.

◆ Descriptor_values

constexpr auto rerun::archetypes::Volume3D::Descriptor_values

staticconstexpr

Initial value:

= ComponentDescriptor(
            ArchetypeName, "Volume3D:values", Loggable<rerun::components::TensorData>::ComponentType
        )

ComponentDescriptor for the values field.

◆ Descriptor_voxel_size

constexpr auto rerun::archetypes::Volume3D::Descriptor_voxel_size

staticconstexpr

Initial value:

= ComponentDescriptor(
            ArchetypeName, "Volume3D:voxel_size",
            Loggable<rerun::components::VoxelSize>::ComponentType
        )

ComponentDescriptor for the voxel_size field.

◆ Descriptor_translation

constexpr auto rerun::archetypes::Volume3D::Descriptor_translation

staticconstexpr

Initial value:

= ComponentDescriptor(
            ArchetypeName, "Volume3D:translation",
            Loggable<rerun::components::Translation3D>::ComponentType
        )

ComponentDescriptor for the translation field.

◆ Descriptor_quaternion

constexpr auto rerun::archetypes::Volume3D::Descriptor_quaternion

staticconstexpr

Initial value:

= ComponentDescriptor(
            ArchetypeName, "Volume3D:quaternion",
            Loggable<rerun::components::RotationQuat>::ComponentType
        )

ComponentDescriptor for the quaternion field.

◆ Descriptor_value_range

constexpr auto rerun::archetypes::Volume3D::Descriptor_value_range

staticconstexpr

Initial value:

= ComponentDescriptor(
            ArchetypeName, "Volume3D:value_range",
            Loggable<rerun::components::ValueRange>::ComponentType
        )

ComponentDescriptor for the value_range field.

◆ Descriptor_colormap

constexpr auto rerun::archetypes::Volume3D::Descriptor_colormap

staticconstexpr

Initial value:

= ComponentDescriptor(
            ArchetypeName, "Volume3D:colormap", Loggable<rerun::components::Colormap>::ComponentType
        )

ComponentDescriptor for the colormap field.

◆ Descriptor_opacity

constexpr auto rerun::archetypes::Volume3D::Descriptor_opacity

staticconstexpr

Initial value:

= ComponentDescriptor(
            ArchetypeName, "Volume3D:opacity", Loggable<rerun::components::Opacity>::ComponentType
        )

ComponentDescriptor for the opacity field.

The documentation for this struct was generated from the following file:

rerun/archetypes/volume3d.hpp

Public Member Functions

Static Public Member Functions

Public Attributes

Static Public Attributes

Detailed Description

Example

Simple volume

Member Function Documentation

◆ with_values()

◆ with_many_values()

◆ with_voxel_size()

◆ with_many_voxel_size()

◆ with_translation()

◆ with_many_translation()

◆ with_quaternion()

◆ with_many_quaternion()

◆ with_value_range()

◆ with_many_value_range()

◆ with_colormap()

◆ with_many_colormap()

◆ with_opacity()

◆ with_many_opacity()

◆ columns() [1/2]

◆ columns() [2/2]

Member Data Documentation

◆ values

◆ voxel_size

◆ translation

◆ quaternion

◆ value_range

◆ colormap

◆ opacity

◆ Descriptor_values

◆ Descriptor_voxel_size

◆ Descriptor_translation

◆ Descriptor_quaternion

◆ Descriptor_value_range

◆ Descriptor_colormap

◆ Descriptor_opacity