Rerun C++ SDK
Loading...
Searching...
No Matches
volume3d.hpp
1// DO NOT EDIT! This file was auto-generated by crates/build/re_types_builder/src/codegen/cpp/mod.rs
2// Based on "crates/build/re_type_definitions/rerun/archetypes/volume_3d.def.rs".
3
4#pragma once
5
6#include "../archetype_utils.hpp"
7#include "../collection.hpp"
8#include "../component_batch.hpp"
9#include "../component_column.hpp"
10#include "../components/colormap.hpp"
11#include "../components/gamma_correction.hpp"
12#include "../components/optical_density.hpp"
13#include "../components/rotation_quat.hpp"
14#include "../components/tensor_data.hpp"
15#include "../components/translation3d.hpp"
16#include "../components/value_range.hpp"
17#include "../components/voxel_size.hpp"
18#include "../result.hpp"
19
20#include <cstdint>
21#include <optional>
22#include <utility>
23#include <vector>
24
25namespace rerun::archetypes {
26 /// **Archetype**: A dense 3D scalar field, rendered by ray marching.
27 ///
28 /// This archetype is intended for volumetric scans and simulations, e.g. CT/MRI scans,
29 /// signed distance fields, or occupancy probabilities sampled on a regular grid.
30 ///
31 /// The values are a 3D tensor with dimensions ordered `[z, y, x]`, i.e. the last dimension varies
32 /// fastest and runs along the local X axis. This matches the row-major layout of
33 /// `archetypes::Image`, with slices stacked along the local Z axis.
34 /// The tensor element at `[k, j, i]` is thus the voxel with grid index `[i, j, k]`.
35 ///
36 /// Voxels are positioned exactly like those of `archetypes::VoxelGridMap`:
37 /// the minimum corner of the voxel with `[0, 0, 0]` index is located at the origin of the entity's
38 /// coordinate frame and can have an additional offset from there through the optional translation
39 /// and rotation fields, and a voxel center is at `(index + 0.5) * voxel_size` in local grid
40 /// coordinates (i.e. relative to the minimum corner).
41 /// This archetype and a `archetypes::VoxelGridMap` with the same `voxel_size` and pose
42 /// therefore agree voxel for voxel, the dense volume covering indices `[0, 0, 0]` up to
43 /// `[width - 1, height - 1, depth - 1]`.
44 ///
45 /// **WebGL limitation:** The viewer is not able to clip volumes against opaque scene geometry.
46 /// Parts of a volume can therefore appear in front of objects that should hide them.
47 ///
48 /// ## Example
49 ///
50 /// ### Simple volume
51 /// ```cpp
52 /// #include <rerun.hpp>
53 ///
54 /// #include <algorithm> // std::max
55 /// #include <vector>
56 ///
57 /// constexpr size_t SIZE = 32;
58 /// constexpr float RADIUS = 14.0f;
59 ///
60 /// int main(int argc, char* argv[]) {
61 /// const auto rec = rerun::RecordingStream("rerun_example_volume3d_simple");
62 /// rec.spawn().exit_on_failure();
63 ///
64 /// // Dimensions are ordered `[z, y, x]`. Only `f16` values are supported for now.
65 /// std::vector<rerun::half> values;
66 /// values.reserve(SIZE * SIZE * SIZE);
67 /// for (size_t z = 0; z <SIZE; ++z) {
68 /// for (size_t y = 0; y <SIZE; ++y) {
69 /// for (size_t x = 0; x <SIZE; ++x) {
70 /// // Squared distance from the center of the grid, in voxel units.
71 /// const float center = 0.5f * static_cast<float>(SIZE - 1);
72 /// const float dx = static_cast<float>(x) - center;
73 /// const float dy = static_cast<float>(y) - center;
74 /// const float dz = static_cast<float>(z) - center;
75 /// const float distance_sq = dx * dx + dy * dy + dz * dz;
76 ///
77 /// // A soft sphere: 1 at the center, falling off to 0 at `RADIUS`.
78 /// values.push_back(rerun::half::from_float(
79 /// std::max(0.0f, 1.0f - distance_sq / (RADIUS * RADIUS))
80 /// ));
81 /// }
82 /// }
83 /// }
84 ///
85 /// rec.log(
86 /// "volume",
87 /// rerun::Volume3D({SIZE, SIZE, SIZE}, values)
88 /// .with_voxel_size(rerun::Vec3D(0.1f, 0.1f, 0.1f))
89 /// );
90 /// }
91 /// ```
92 ///
93 /// ⚠ **This type is _unstable_ and may change significantly in a way that the data won't be backwards compatible.**
94 ///
95 struct Volume3D {
96 /// The scalar value of each voxel, as a 3D tensor with dimensions ordered `[z, y, x]`.
97 ///
98 /// Currently only `f16` are supported.
99 std::optional<ComponentBatch> values;
100
101 /// The scene-unit dimensions of a single voxel cell.
102 ///
103 /// This defines the voxel size along the local grid X/Y/Z axes, and thus the total extent of the
104 /// volume: `[width, height, depth] * voxel_size`.
105 /// Anisotropic spacing (as is common for medical scans) is expressed here.
106 /// Each dimension must be finite and positive.
107 ///
108 /// Defaults to `[1.0, 1.0, 1.0]`.
109 std::optional<ComponentBatch> voxel_size;
110
111 /// Translation of the minimum corner of voxel `[0, 0, 0]`.
112 ///
113 /// Together with `components::RotationQuat`, this defines the pose of the volume
114 /// relative to the entity's coordinate frame.
115 ///
116 /// If not set, the minimum corner is placed at the origin of the entity's coordinate frame.
117 std::optional<ComponentBatch> translation;
118
119 /// Rotation of the volume via quaternion.
120 ///
121 /// Together with `components::Translation3D`, this defines the pose of the volume
122 /// relative to the entity's coordinate frame.
123 /// The rotation is around the minimum corner of voxel `[0, 0, 0]`, and is applied before the
124 /// translation.
125 std::optional<ComponentBatch> quaternion;
126
127 /// The inclusive range of voxel values to render.
128 ///
129 /// Values outside the range are ignored.
130 ///
131 /// If not specified, the range is automatically estimated from the data.
132 std::optional<ComponentBatch> value_range;
133
134 /// Gamma correction applied to normalized voxel values before colormapping and opacity calculation.
135 ///
136 /// The corrected density is `normalized_value ^ gamma`.
137 /// Must be finite and positive.
138 /// Defaults to 3.0, suppressing low-density material and emphasizing dense structures.
139 std::optional<ComponentBatch> gamma;
140
141 /// Colormap applied to the values after mapping them through `value_range` and gamma correction.
142 ///
143 /// Defaults to Turbo.
144 std::optional<ComponentBatch> colormap;
145
146 /// Dimensionless optical depth for the volume.
147 ///
148 /// For a uniform volume at the upper bound of `value_range`, this is the optical depth across one full volume-local axis.
149 /// Zero is transparent, one is about 63% opaque, and larger values are denser.
150 ///
151 /// Defaults to 1.0.
152 std::optional<ComponentBatch> optical_density;
153
154 public:
155 /// The name of the archetype as used in `ComponentDescriptor`s.
156 static constexpr const char ArchetypeName[] = "rerun.archetypes.Volume3D";
157
158 /// `ComponentDescriptor` for the `values` field.
159 static constexpr auto Descriptor_values = ComponentDescriptor(
161 );
162 /// `ComponentDescriptor` for the `voxel_size` field.
164 ArchetypeName, "Volume3D:voxel_size",
166 );
167 /// `ComponentDescriptor` for the `translation` field.
169 ArchetypeName, "Volume3D:translation",
171 );
172 /// `ComponentDescriptor` for the `quaternion` field.
174 ArchetypeName, "Volume3D:quaternion",
176 );
177 /// `ComponentDescriptor` for the `value_range` field.
179 ArchetypeName, "Volume3D:value_range",
181 );
182 /// `ComponentDescriptor` for the `gamma` field.
183 static constexpr auto Descriptor_gamma = ComponentDescriptor(
184 ArchetypeName, "Volume3D:gamma",
186 );
187 /// `ComponentDescriptor` for the `colormap` field.
190 );
191 /// `ComponentDescriptor` for the `optical_density` field.
193 ArchetypeName, "Volume3D:optical_density",
195 );
196
197 public: // START of extensions from volume3d_ext.cpp:
198 RR_DISABLE_MAYBE_UNINITIALIZED_PUSH
199
200 /// New Volume3D from dimensions and tensor buffer.
202 : Volume3D(encodings::TensorData(std::move(shape), std::move(buffer))) {}
203
204 RR_DISABLE_MAYBE_UNINITIALIZED_POP
205
206 // END of extensions from volume3d_ext.cpp, start of generated code:
207
208 public:
209 Volume3D() = default;
210 Volume3D(Volume3D&& other) = default;
211 Volume3D(const Volume3D& other) = default;
212 Volume3D& operator=(const Volume3D& other) = default;
213 Volume3D& operator=(Volume3D&& other) = default;
214
216 : values(ComponentBatch::from_loggable(std::move(_values), Descriptor_values)
217 .value_or_throw()) {}
218
219 /// Update only some specific fields of a `Volume3D`.
221 return Volume3D();
222 }
223
224 /// Clear all the fields of a `Volume3D`.
226
227 /// The scalar value of each voxel, as a 3D tensor with dimensions ordered `[z, y, x]`.
228 ///
229 /// Currently only `f16` are supported.
231 values = ComponentBatch::from_loggable(_values, Descriptor_values).value_or_throw();
232 return std::move(*this);
233 }
234
235 /// This method makes it possible to pack multiple `values` in a single component batch.
236 ///
237 /// This only makes sense when used in conjunction with `columns`. `with_values` should
238 /// be used when logging a single row's worth of data.
240 values = ComponentBatch::from_loggable(_values, Descriptor_values).value_or_throw();
241 return std::move(*this);
242 }
243
244 /// The scene-unit dimensions of a single voxel cell.
245 ///
246 /// This defines the voxel size along the local grid X/Y/Z axes, and thus the total extent of the
247 /// volume: `[width, height, depth] * voxel_size`.
248 /// Anisotropic spacing (as is common for medical scans) is expressed here.
249 /// Each dimension must be finite and positive.
250 ///
251 /// Defaults to `[1.0, 1.0, 1.0]`.
253 voxel_size =
254 ComponentBatch::from_loggable(_voxel_size, Descriptor_voxel_size).value_or_throw();
255 return std::move(*this);
256 }
257
258 /// This method makes it possible to pack multiple `voxel_size` in a single component batch.
259 ///
260 /// This only makes sense when used in conjunction with `columns`. `with_voxel_size` should
261 /// be used when logging a single row's worth of data.
263 ) && {
264 voxel_size =
265 ComponentBatch::from_loggable(_voxel_size, Descriptor_voxel_size).value_or_throw();
266 return std::move(*this);
267 }
268
269 /// Translation of the minimum corner of voxel `[0, 0, 0]`.
270 ///
271 /// Together with `components::RotationQuat`, this defines the pose of the volume
272 /// relative to the entity's coordinate frame.
273 ///
274 /// If not set, the minimum corner is placed at the origin of the entity's coordinate frame.
277 .value_or_throw();
278 return std::move(*this);
279 }
280
281 /// This method makes it possible to pack multiple `translation` in a single component batch.
282 ///
283 /// This only makes sense when used in conjunction with `columns`. `with_translation` should
284 /// be used when logging a single row's worth of data.
287 ) && {
289 .value_or_throw();
290 return std::move(*this);
291 }
292
293 /// Rotation of the volume via quaternion.
294 ///
295 /// Together with `components::Translation3D`, this defines the pose of the volume
296 /// relative to the entity's coordinate frame.
297 /// The rotation is around the minimum corner of voxel `[0, 0, 0]`, and is applied before the
298 /// translation.
300 quaternion =
301 ComponentBatch::from_loggable(_quaternion, Descriptor_quaternion).value_or_throw();
302 return std::move(*this);
303 }
304
305 /// This method makes it possible to pack multiple `quaternion` in a single component batch.
306 ///
307 /// This only makes sense when used in conjunction with `columns`. `with_quaternion` should
308 /// be used when logging a single row's worth of data.
310 ) && {
311 quaternion =
312 ComponentBatch::from_loggable(_quaternion, Descriptor_quaternion).value_or_throw();
313 return std::move(*this);
314 }
315
316 /// The inclusive range of voxel values to render.
317 ///
318 /// Values outside the range are ignored.
319 ///
320 /// If not specified, the range is automatically estimated from the data.
323 .value_or_throw();
324 return std::move(*this);
325 }
326
327 /// This method makes it possible to pack multiple `value_range` in a single component batch.
328 ///
329 /// This only makes sense when used in conjunction with `columns`. `with_value_range` should
330 /// be used when logging a single row's worth of data.
332 ) && {
334 .value_or_throw();
335 return std::move(*this);
336 }
337
338 /// Gamma correction applied to normalized voxel values before colormapping and opacity calculation.
339 ///
340 /// The corrected density is `normalized_value ^ gamma`.
341 /// Must be finite and positive.
342 /// Defaults to 3.0, suppressing low-density material and emphasizing dense structures.
344 gamma = ComponentBatch::from_loggable(_gamma, Descriptor_gamma).value_or_throw();
345 return std::move(*this);
346 }
347
348 /// This method makes it possible to pack multiple `gamma` in a single component batch.
349 ///
350 /// This only makes sense when used in conjunction with `columns`. `with_gamma` should
351 /// be used when logging a single row's worth of data.
353 gamma = ComponentBatch::from_loggable(_gamma, Descriptor_gamma).value_or_throw();
354 return std::move(*this);
355 }
356
357 /// Colormap applied to the values after mapping them through `value_range` and gamma correction.
358 ///
359 /// Defaults to Turbo.
361 colormap =
362 ComponentBatch::from_loggable(_colormap, Descriptor_colormap).value_or_throw();
363 return std::move(*this);
364 }
365
366 /// This method makes it possible to pack multiple `colormap` in a single component batch.
367 ///
368 /// This only makes sense when used in conjunction with `columns`. `with_colormap` should
369 /// be used when logging a single row's worth of data.
371 colormap =
372 ComponentBatch::from_loggable(_colormap, Descriptor_colormap).value_or_throw();
373 return std::move(*this);
374 }
375
376 /// Dimensionless optical depth for the volume.
377 ///
378 /// For a uniform volume at the upper bound of `value_range`, this is the optical depth across one full volume-local axis.
379 /// Zero is transparent, one is about 63% opaque, and larger values are denser.
380 ///
381 /// Defaults to 1.0.
383 ) && {
386 .value_or_throw();
387 return std::move(*this);
388 }
389
390 /// This method makes it possible to pack multiple `optical_density` in a single component batch.
391 ///
392 /// This only makes sense when used in conjunction with `columns`. `with_optical_density` should
393 /// be used when logging a single row's worth of data.
396 ) && {
399 .value_or_throw();
400 return std::move(*this);
401 }
402
403 /// Partitions the component data into multiple sub-batches.
404 ///
405 /// Specifically, this transforms the existing `ComponentBatch` data into `ComponentColumn`s
406 /// instead, via `ComponentBatch::partitioned`.
407 ///
408 /// This makes it possible to use `RecordingStream::send_columns` to send columnar data directly into Rerun.
409 ///
410 /// The specified `lengths` must sum to the total length of the component batch.
412 return detail::partition_batches(
413 {&values,
414 &voxel_size,
416 &quaternion,
418 &gamma,
419 &colormap,
421 lengths_
422 )
423 .value_or_throw();
424 }
425
426 /// Partitions the component data into unit-length sub-batches.
427 ///
428 /// This is semantically similar to calling `columns` with `std::vector<uint32_t>(n, 1)`,
429 /// where `n` is automatically guessed.
431 return detail::partition_batches_of_unit_length({&values,
432 &voxel_size,
434 &quaternion,
436 &gamma,
437 &colormap,
439 .value_or_throw();
440 }
441 };
442
443} // namespace rerun::archetypes
444
445namespace rerun {
446 /// \private
447 template <typename T>
448 struct AsComponents;
449
450 /// \private
451 template <>
452 struct AsComponents<archetypes::Volume3D> {
453 /// Serialize all set component batches.
454 static Result<Collection<ComponentBatch>> as_batches(const archetypes::Volume3D& archetype
455 ) {
456 return detail::collect_batches(
457 {&archetype.values,
458 &archetype.voxel_size,
459 &archetype.translation,
460 &archetype.quaternion,
461 &archetype.value_range,
462 &archetype.gamma,
463 &archetype.colormap,
464 &archetype.optical_density}
465 );
466 }
467 };
468} // namespace rerun
Generic collection of elements that are roughly contiguous in memory.
Definition collection.hpp:49
All built-in archetypes. See Types in the Rerun manual.
Definition rerun.hpp:90
Colormap
Component: Colormap for mapping scalar values within a given range to a color.
Definition colormap.hpp:28
All Rerun C++ types and functions are in the rerun namespace or one of its nested namespaces.
Definition rerun.hpp:26
Arrow-encoded data of a single batch of components together with a component descriptor.
Definition component_batch.hpp:28
static Result< ComponentBatch > from_loggable(const rerun::Collection< T > &components, const ComponentDescriptor &descriptor)
Creates a new component batch from a collection of component instances.
Definition component_batch.hpp:46
A ComponentDescriptor fully describes the semantics of a column of data.
Definition component_descriptor.hpp:16
The Loggable trait is used by all built-in implementation of rerun::AsComponents to serialize a colle...
Definition loggable.hpp:11
Archetype: A dense 3D scalar field, rendered by ray marching.
Definition volume3d.hpp:95
static Volume3D update_fields()
Update only some specific fields of a Volume3D.
Definition volume3d.hpp:220
Collection< ComponentColumn > columns(const Collection< uint32_t > &lengths_)
Partitions the component data into multiple sub-batches.
Definition volume3d.hpp:411
static constexpr auto Descriptor_gamma
ComponentDescriptor for the gamma field.
Definition volume3d.hpp:183
static constexpr auto Descriptor_translation
ComponentDescriptor for the translation field.
Definition volume3d.hpp:168
Volume3D with_many_gamma(const Collection< rerun::components::GammaCorrection > &_gamma) &&
This method makes it possible to pack multiple gamma in a single component batch.
Definition volume3d.hpp:352
Collection< ComponentColumn > columns()
Partitions the component data into unit-length sub-batches.
Definition volume3d.hpp:430
Volume3D with_optical_density(const rerun::components::OpticalDensity &_optical_density) &&
Dimensionless optical depth for the volume.
Definition volume3d.hpp:382
static constexpr const char ArchetypeName[]
The name of the archetype as used in ComponentDescriptors.
Definition volume3d.hpp:156
Volume3D with_voxel_size(const rerun::components::VoxelSize &_voxel_size) &&
The scene-unit dimensions of a single voxel cell.
Definition volume3d.hpp:252
Volume3D with_colormap(const rerun::components::Colormap &_colormap) &&
Colormap applied to the values after mapping them through value_range and gamma correction.
Definition volume3d.hpp:360
static constexpr auto Descriptor_colormap
ComponentDescriptor for the colormap field.
Definition volume3d.hpp:188
std::optional< ComponentBatch > quaternion
Rotation of the volume via quaternion.
Definition volume3d.hpp:125
Volume3D with_many_translation(const Collection< rerun::components::Translation3D > &_translation) &&
This method makes it possible to pack multiple translation in a single component batch.
Definition volume3d.hpp:285
Volume3D with_quaternion(const rerun::components::RotationQuat &_quaternion) &&
Rotation of the volume via quaternion.
Definition volume3d.hpp:299
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.
Definition volume3d.hpp:262
Volume3D with_translation(const rerun::components::Translation3D &_translation) &&
Translation of the minimum corner of voxel [0, 0, 0].
Definition volume3d.hpp:275
static Volume3D clear_fields()
Clear all the fields of a Volume3D.
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.
Definition volume3d.hpp:331
Volume3D with_many_quaternion(const Collection< rerun::components::RotationQuat > &_quaternion) &&
This method makes it possible to pack multiple quaternion in a single component batch.
Definition volume3d.hpp:309
std::optional< ComponentBatch > voxel_size
The scene-unit dimensions of a single voxel cell.
Definition volume3d.hpp:109
std::optional< ComponentBatch > values
The scalar value of each voxel, as a 3D tensor with dimensions ordered [z, y, x].
Definition volume3d.hpp:99
static constexpr auto Descriptor_value_range
ComponentDescriptor for the value_range field.
Definition volume3d.hpp:178
std::optional< ComponentBatch > colormap
Colormap applied to the values after mapping them through value_range and gamma correction.
Definition volume3d.hpp:144
Volume3D with_many_colormap(const Collection< rerun::components::Colormap > &_colormap) &&
This method makes it possible to pack multiple colormap in a single component batch.
Definition volume3d.hpp:370
std::optional< ComponentBatch > optical_density
Dimensionless optical depth for the volume.
Definition volume3d.hpp:152
std::optional< ComponentBatch > value_range
The inclusive range of voxel values to render.
Definition volume3d.hpp:132
static constexpr auto Descriptor_values
ComponentDescriptor for the values field.
Definition volume3d.hpp:159
Volume3D with_many_values(const Collection< rerun::components::TensorData > &_values) &&
This method makes it possible to pack multiple values in a single component batch.
Definition volume3d.hpp:239
Volume3D with_gamma(const rerun::components::GammaCorrection &_gamma) &&
Gamma correction applied to normalized voxel values before colormapping and opacity calculation.
Definition volume3d.hpp:343
RR_DISABLE_MAYBE_UNINITIALIZED_PUSH Volume3D(Collection< uint64_t > shape, encodings::TensorBuffer buffer)
New Volume3D from dimensions and tensor buffer.
Definition volume3d.hpp:201
Volume3D with_values(const rerun::components::TensorData &_values) &&
The scalar value of each voxel, as a 3D tensor with dimensions ordered [z, y, x].
Definition volume3d.hpp:230
static constexpr auto Descriptor_optical_density
ComponentDescriptor for the optical_density field.
Definition volume3d.hpp:192
Volume3D with_many_optical_density(const Collection< rerun::components::OpticalDensity > &_optical_density) &&
This method makes it possible to pack multiple optical_density in a single component batch.
Definition volume3d.hpp:394
std::optional< ComponentBatch > translation
Translation of the minimum corner of voxel [0, 0, 0].
Definition volume3d.hpp:117
std::optional< ComponentBatch > gamma
Gamma correction applied to normalized voxel values before colormapping and opacity calculation.
Definition volume3d.hpp:139
static constexpr auto Descriptor_quaternion
ComponentDescriptor for the quaternion field.
Definition volume3d.hpp:173
Volume3D with_value_range(const rerun::components::ValueRange &_value_range) &&
The inclusive range of voxel values to render.
Definition volume3d.hpp:321
static constexpr auto Descriptor_voxel_size
ComponentDescriptor for the voxel_size field.
Definition volume3d.hpp:163
Component: A gamma correction value to be used with a scalar value or color.
Definition gamma_correction.hpp:20
Component: Dimensionless natural-log optical depth.
Definition optical_density.hpp:17
Component: A 3D rotation expressed as a quaternion.
Definition rotation_quat.hpp:18
Component: An N-dimensional array of numbers.
Definition tensor_data.hpp:22
Component: A translation vector in 3D space.
Definition translation3d.hpp:15
Component: Range of expected or valid values, specifying a lower and upper bound.
Definition value_range.hpp:18
Component: The scene-unit dimensions of one voxel in a sparse 3D voxel grid.
Definition voxel_size.hpp:18
Encoding: The underlying storage for archetypes::Tensor.
Definition tensor_buffer.hpp:98
Encoding: An N-dimensional array of numbers.
Definition tensor_data.hpp:30