volume3d.hpp

// DO NOT EDIT! This file was auto-generated by crates/build/re_types_builder/src/codegen/cpp/mod.rs
// Based on "crates/build/re_type_definitions/rerun/archetypes/volume_3d.def.rs".
 
#pragma once
 
#include "../collection.hpp"
#include "../component_batch.hpp"
#include "../component_column.hpp"
#include "../components/colormap.hpp"
#include "../components/gamma_correction.hpp"
#include "../components/optical_density.hpp"
#include "../components/rotation_quat.hpp"
#include "../components/tensor_data.hpp"
#include "../components/translation3d.hpp"
#include "../components/value_range.hpp"
#include "../components/voxel_size.hpp"
#include "../result.hpp"
 
#include <cstdint>
#include <optional>
#include <utility>
#include <vector>
 
namespace rerun::archetypes {
    /// **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]`.
    ///
    /// **WebGL limitation:** The viewer is not able to clip volumes against opaque scene geometry.
    /// Parts of a volume can therefore appear in front of objects that should hide them.
    ///
    /// ## Example
    ///
    /// ### Simple volume
    /// ```cpp
    /// #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.**
    ///
    struct Volume3D {
        /// The scalar value of each voxel, as a 3D tensor with dimensions ordered `[z, y, x]`.
        ///
        /// Currently only `f16` are supported.
        std::optional<ComponentBatch> values;
 
        /// 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]`.
        std::optional<ComponentBatch> voxel_size;
 
        /// 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.
        std::optional<ComponentBatch> translation;
 
        /// 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.
        std::optional<ComponentBatch> quaternion;
 
        /// The inclusive range of voxel values to render.
        ///
        /// Values outside the range are ignored.
        ///
        /// If not specified, the range is automatically estimated from the data.
        std::optional<ComponentBatch> value_range;
 
        /// Gamma correction applied to normalized voxel values before colormapping and opacity calculation.
        ///
        /// The corrected density is `normalized_value ^ gamma`.
        /// Must be finite and positive.
        /// Defaults to 3.0, suppressing low-density material and emphasizing dense structures.
        std::optional<ComponentBatch> gamma;
 
        /// Colormap applied to the values after mapping them through `value_range` and gamma correction.
        ///
        /// Defaults to Turbo.
        std::optional<ComponentBatch> colormap;
 
        /// Dimensionless optical depth for the volume.
        ///
        /// For a uniform volume at the upper bound of `value_range`, this is the optical depth across one full volume-local axis.
        /// Zero is transparent, one is about 63% opaque, and larger values are denser.
        ///
        /// Defaults to 1.0.
        std::optional<ComponentBatch> optical_density;
 
      public:
        /// The name of the archetype as used in `ComponentDescriptor`s.
        static constexpr const char ArchetypeName[] = "rerun.archetypes.Volume3D";
 
        /// `ComponentDescriptor` for the `values` field.
        static constexpr auto Descriptor_values = ComponentDescriptor(
            ArchetypeName, "Volume3D:values", Loggable<rerun::components::TensorData>::ComponentType
        );
        /// `ComponentDescriptor` for the `voxel_size` field.
        static constexpr auto Descriptor_voxel_size = ComponentDescriptor(
            ArchetypeName, "Volume3D:voxel_size",
            Loggable<rerun::components::VoxelSize>::ComponentType
        );
        /// `ComponentDescriptor` for the `translation` field.
        static constexpr auto Descriptor_translation = ComponentDescriptor(
            ArchetypeName, "Volume3D:translation",
            Loggable<rerun::components::Translation3D>::ComponentType
        );
        /// `ComponentDescriptor` for the `quaternion` field.
        static constexpr auto Descriptor_quaternion = ComponentDescriptor(
            ArchetypeName, "Volume3D:quaternion",
            Loggable<rerun::components::RotationQuat>::ComponentType
        );
        /// `ComponentDescriptor` for the `value_range` field.
        static constexpr auto Descriptor_value_range = ComponentDescriptor(
            ArchetypeName, "Volume3D:value_range",
            Loggable<rerun::components::ValueRange>::ComponentType
        );
        /// `ComponentDescriptor` for the `gamma` field.
        static constexpr auto Descriptor_gamma = ComponentDescriptor(
            ArchetypeName, "Volume3D:gamma",
            Loggable<rerun::components::GammaCorrection>::ComponentType
        );
        /// `ComponentDescriptor` for the `colormap` field.
        static constexpr auto Descriptor_colormap = ComponentDescriptor(
            ArchetypeName, "Volume3D:colormap", Loggable<rerun::components::Colormap>::ComponentType
        );
        /// `ComponentDescriptor` for the `optical_density` field.
        static constexpr auto Descriptor_optical_density = ComponentDescriptor(
            ArchetypeName, "Volume3D:optical_density",
            Loggable<rerun::components::OpticalDensity>::ComponentType
        );
 
      public: // START of extensions from volume3d_ext.cpp:
        RR_DISABLE_MAYBE_UNINITIALIZED_PUSH
 
        /// New Volume3D from dimensions and tensor buffer.
        Volume3D(Collection<uint64_t> shape, encodings::TensorBuffer buffer)
            : Volume3D(encodings::TensorData(std::move(shape), std::move(buffer))) {}
 
        RR_DISABLE_MAYBE_UNINITIALIZED_POP
 
        // END of extensions from volume3d_ext.cpp, start of generated code:
 
      public:
        Volume3D() = default;
        Volume3D(Volume3D&& other) = default;
        Volume3D(const Volume3D& other) = default;
        Volume3D& operator=(const Volume3D& other) = default;
        Volume3D& operator=(Volume3D&& other) = default;
 
        explicit Volume3D(rerun::components::TensorData _values)
            : values(ComponentBatch::from_loggable(std::move(_values), Descriptor_values)
                         .value_or_throw()) {}
 
        /// Update only some specific fields of a `Volume3D`.
        static Volume3D update_fields() {
            return Volume3D();
        }
 
        /// Clear all the fields of a `Volume3D`.
        static Volume3D clear_fields();
 
        /// The scalar value of each voxel, as a 3D tensor with dimensions ordered `[z, y, x]`.
        ///
        /// Currently only `f16` are supported.
        Volume3D with_values(const rerun::components::TensorData& _values) && {
            values = ComponentBatch::from_loggable(_values, Descriptor_values).value_or_throw();
            return std::move(*this);
        }
 
        /// 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.
        Volume3D with_many_values(const Collection<rerun::components::TensorData>& _values) && {
            values = ComponentBatch::from_loggable(_values, Descriptor_values).value_or_throw();
            return std::move(*this);
        }
 
        /// 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]`.
        Volume3D with_voxel_size(const rerun::components::VoxelSize& _voxel_size) && {
            voxel_size =
                ComponentBatch::from_loggable(_voxel_size, Descriptor_voxel_size).value_or_throw();
            return std::move(*this);
        }
 
        /// 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.
        Volume3D with_many_voxel_size(const Collection<rerun::components::VoxelSize>& _voxel_size
        ) && {
            voxel_size =
                ComponentBatch::from_loggable(_voxel_size, Descriptor_voxel_size).value_or_throw();
            return std::move(*this);
        }
 
        /// 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.
        Volume3D with_translation(const rerun::components::Translation3D& _translation) && {
            translation = ComponentBatch::from_loggable(_translation, Descriptor_translation)
                              .value_or_throw();
            return std::move(*this);
        }
 
        /// 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.
        Volume3D with_many_translation(
            const Collection<rerun::components::Translation3D>& _translation
        ) && {
            translation = ComponentBatch::from_loggable(_translation, Descriptor_translation)
                              .value_or_throw();
            return std::move(*this);
        }
 
        /// 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.
        Volume3D with_quaternion(const rerun::components::RotationQuat& _quaternion) && {
            quaternion =
                ComponentBatch::from_loggable(_quaternion, Descriptor_quaternion).value_or_throw();
            return std::move(*this);
        }
 
        /// 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.
        Volume3D with_many_quaternion(const Collection<rerun::components::RotationQuat>& _quaternion
        ) && {
            quaternion =
                ComponentBatch::from_loggable(_quaternion, Descriptor_quaternion).value_or_throw();
            return std::move(*this);
        }
 
        /// The inclusive range of voxel values to render.
        ///
        /// Values outside the range are ignored.
        ///
        /// If not specified, the range is automatically estimated from the data.
        Volume3D with_value_range(const rerun::components::ValueRange& _value_range) && {
            value_range = ComponentBatch::from_loggable(_value_range, Descriptor_value_range)
                              .value_or_throw();
            return std::move(*this);
        }
 
        /// 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.
        Volume3D with_many_value_range(const Collection<rerun::components::ValueRange>& _value_range
        ) && {
            value_range = ComponentBatch::from_loggable(_value_range, Descriptor_value_range)
                              .value_or_throw();
            return std::move(*this);
        }
 
        /// Gamma correction applied to normalized voxel values before colormapping and opacity calculation.
        ///
        /// The corrected density is `normalized_value ^ gamma`.
        /// Must be finite and positive.
        /// Defaults to 3.0, suppressing low-density material and emphasizing dense structures.
        Volume3D with_gamma(const rerun::components::GammaCorrection& _gamma) && {
            gamma = ComponentBatch::from_loggable(_gamma, Descriptor_gamma).value_or_throw();
            return std::move(*this);
        }
 
        /// This method makes it possible to pack multiple `gamma` in a single component batch.
        ///
        /// This only makes sense when used in conjunction with `columns`. `with_gamma` should
        /// be used when logging a single row's worth of data.
        Volume3D with_many_gamma(const Collection<rerun::components::GammaCorrection>& _gamma) && {
            gamma = ComponentBatch::from_loggable(_gamma, Descriptor_gamma).value_or_throw();
            return std::move(*this);
        }
 
        /// Colormap applied to the values after mapping them through `value_range` and gamma correction.
        ///
        /// Defaults to Turbo.
        Volume3D with_colormap(const rerun::components::Colormap& _colormap) && {
            colormap =
                ComponentBatch::from_loggable(_colormap, Descriptor_colormap).value_or_throw();
            return std::move(*this);
        }
 
        /// 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.
        Volume3D with_many_colormap(const Collection<rerun::components::Colormap>& _colormap) && {
            colormap =
                ComponentBatch::from_loggable(_colormap, Descriptor_colormap).value_or_throw();
            return std::move(*this);
        }
 
        /// Dimensionless optical depth for the volume.
        ///
        /// For a uniform volume at the upper bound of `value_range`, this is the optical depth across one full volume-local axis.
        /// Zero is transparent, one is about 63% opaque, and larger values are denser.
        ///
        /// Defaults to 1.0.
        Volume3D with_optical_density(const rerun::components::OpticalDensity& _optical_density
        ) && {
            optical_density =
                ComponentBatch::from_loggable(_optical_density, Descriptor_optical_density)
                    .value_or_throw();
            return std::move(*this);
        }
 
        /// This method makes it possible to pack multiple `optical_density` in a single component batch.
        ///
        /// This only makes sense when used in conjunction with `columns`. `with_optical_density` should
        /// be used when logging a single row's worth of data.
        Volume3D with_many_optical_density(
            const Collection<rerun::components::OpticalDensity>& _optical_density
        ) && {
            optical_density =
                ComponentBatch::from_loggable(_optical_density, Descriptor_optical_density)
                    .value_or_throw();
            return std::move(*this);
        }
 
        /// Partitions the component data into multiple sub-batches.
        ///
        /// Specifically, this transforms the existing `ComponentBatch` data into `ComponentColumn`s
        /// 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.
        Collection<ComponentColumn> columns(const Collection<uint32_t>& lengths_);
 
        /// 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.
        Collection<ComponentColumn> columns();
    };
 
} // namespace rerun::archetypes
 
namespace rerun {
    /// \private
    template <typename T>
    struct AsComponents;
 
    /// \private
    template <>
    struct AsComponents<archetypes::Volume3D> {
        /// Serialize all set component batches.
        static Result<Collection<ComponentBatch>> as_batches(const archetypes::Volume3D& archetype);
    };
} // namespace rerun