Rerun C++ SDK
Loading...
Searching...
No Matches
image.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/store/re_types/definitions/rerun/archetypes/image.fbs".
3
4#pragma once
5
6#include "../collection.hpp"
7#include "../component_batch.hpp"
8#include "../component_column.hpp"
9#include "../components/draw_order.hpp"
10#include "../components/image_buffer.hpp"
11#include "../components/image_format.hpp"
12#include "../components/opacity.hpp"
13#include "../image_utils.hpp"
14#include "../result.hpp"
15
16#include <cstdint>
17#include <optional>
18#include <utility>
19#include <vector>
20
21namespace rerun::archetypes {
22 /// **Archetype**: A monochrome or color image.
23 ///
24 /// See also `archetypes::DepthImage` and `archetypes::SegmentationImage`.
25 ///
26 /// Rerun also supports compressed images (JPEG, PNG, …), using `archetypes::EncodedImage`.
27 /// For images that refer to video frames see `archetypes::VideoFrameReference`.
28 /// Compressing images or using video data instead can save a lot of bandwidth and memory.
29 ///
30 /// The raw image data is stored as a single buffer of bytes in a `components::Blob`.
31 /// The meaning of these bytes is determined by the `components::ImageFormat` which specifies the resolution
32 /// and the pixel format (e.g. RGB, RGBA, …).
33 ///
34 /// The order of dimensions in the underlying `components::Blob` follows the typical
35 /// row-major, interleaved-pixel image format.
36 ///
37 /// Since the underlying [rerun::components::Blob] uses `rerun::Collection` internally,
38 /// data can be passed in without a copy from raw pointers or by reference from `std::vector`/`std::array`/c-arrays.
39 /// If needed, this "borrow-behavior" can be extended by defining your own `rerun::CollectionAdapter`.
40 ///
41 /// ## Examples
42 ///
43 /// ### image_simple:
44 /// ![image](https://static.rerun.io/image_simple/06ba7f8582acc1ffb42a7fd0006fad7816f3e4e4/full.png)
45 ///
46 /// ```cpp
47 /// #include <rerun.hpp>
48 ///
49 /// #include <vector>
50 ///
51 /// int main() {
52 /// const auto rec = rerun::RecordingStream("rerun_example_image");
53 /// rec.spawn().exit_on_failure();
54 ///
55 /// // Create a synthetic image.
56 /// const int HEIGHT = 200;
57 /// const int WIDTH = 300;
58 /// std::vector<uint8_t> data(WIDTH * HEIGHT * 3, 0);
59 /// for (size_t i = 0; i <data.size(); i += 3) {
60 /// data[i] = 255;
61 /// }
62 /// for (size_t y = 50; y <150; ++y) {
63 /// for (size_t x = 50; x <150; ++x) {
64 /// data[(y * WIDTH + x) * 3 + 0] = 0;
65 /// data[(y * WIDTH + x) * 3 + 1] = 255;
66 /// data[(y * WIDTH + x) * 3 + 2] = 0;
67 /// }
68 /// }
69 ///
70 /// rec.log("image", rerun::Image::from_rgb24(data, {WIDTH, HEIGHT}));
71 /// }
72 /// ```
73 ///
74 /// ### Logging images with various formats
75 /// ![image](https://static.rerun.io/image_formats/182a233fb4d0680eb31912a82f328ddaaa66324e/full.png)
76 ///
77 /// ```cpp
78 /// #include <algorithm>
79 /// #include <cstdint>
80 /// #include <vector>
81 ///
82 /// #include <rerun.hpp>
83 ///
84 /// int main() {
85 /// const auto rec = rerun::RecordingStream("rerun_example_image_formats");
86 /// rec.spawn().exit_on_failure();
87 ///
88 /// // Simple gradient image
89 /// std::vector<uint8_t> image(256 * 256 * 3);
90 /// for (size_t y = 0; y <256; ++y) {
91 /// for (size_t x = 0; x <256; ++x) {
92 /// image[(y * 256 + x) * 3 + 0] = static_cast<uint8_t>(x);
93 /// image[(y * 256 + x) * 3 + 1] = static_cast<uint8_t>(std::min<size_t>(255, x + y));
94 /// image[(y * 256 + x) * 3 + 2] = static_cast<uint8_t>(y);
95 /// }
96 /// }
97 ///
98 /// // RGB image
99 /// rec.log("image_rgb", rerun::Image::from_rgb24(image, {256, 256}));
100 ///
101 /// // Green channel only (Luminance)
102 /// std::vector<uint8_t> green_channel(256 * 256);
103 /// for (size_t i = 0; i <256 * 256; ++i) {
104 /// green_channel[i] = image[i * 3 + 1];
105 /// }
106 /// rec.log(
107 /// "image_green_only",
108 /// rerun::Image(rerun::borrow(green_channel), {256, 256}, rerun::ColorModel::L)
109 /// );
110 ///
111 /// // BGR image
112 /// std::vector<uint8_t> bgr_image(256 * 256 * 3);
113 /// for (size_t i = 0; i <256 * 256; ++i) {
114 /// bgr_image[i * 3 + 0] = image[i * 3 + 2];
115 /// bgr_image[i * 3 + 1] = image[i * 3 + 1];
116 /// bgr_image[i * 3 + 2] = image[i * 3 + 0];
117 /// }
118 /// rec.log(
119 /// "image_bgr",
120 /// rerun::Image(rerun::borrow(bgr_image), {256, 256}, rerun::ColorModel::BGR)
121 /// );
122 ///
123 /// // New image with Separate Y/U/V planes with 4:2:2 chroma downsampling
124 /// std::vector<uint8_t> yuv_bytes(256 * 256 + 128 * 256 * 2);
125 /// std::fill_n(yuv_bytes.begin(), 256 * 256, static_cast<uint8_t>(128)); // Fixed value for Y
126 /// size_t u_plane_offset = 256 * 256;
127 /// size_t v_plane_offset = u_plane_offset + 128 * 256;
128 /// for (size_t y = 0; y <256; ++y) {
129 /// for (size_t x = 0; x <128; ++x) {
130 /// auto coord = y * 128 + x;
131 /// yuv_bytes[u_plane_offset + coord] = static_cast<uint8_t>(x * 2); // Gradient for U
132 /// yuv_bytes[v_plane_offset + coord] = static_cast<uint8_t>(y); // Gradient for V
133 /// }
134 /// }
135 /// rec.log(
136 /// "image_yuv422",
137 /// rerun::Image(rerun::borrow(yuv_bytes), {256, 256}, rerun::PixelFormat::Y_U_V16_FullRange)
138 /// );
139 ///
140 /// return 0;
141 /// }
142 /// ```
143 struct Image {
144 /// The raw image data.
145 std::optional<ComponentBatch> buffer;
146
147 /// The format of the image.
148 std::optional<ComponentBatch> format;
149
150 /// Opacity of the image, useful for layering several images.
151 ///
152 /// Defaults to 1.0 (fully opaque).
153 std::optional<ComponentBatch> opacity;
154
155 /// An optional floating point value that specifies the 2D drawing order.
156 ///
157 /// Objects with higher values are drawn on top of those with lower values.
158 /// Defaults to `-10.0`.
159 std::optional<ComponentBatch> draw_order;
160
161 public:
162 /// The name of the archetype as used in `ComponentDescriptor`s.
163 static constexpr const char ArchetypeName[] = "rerun.archetypes.Image";
164
165 /// `ComponentDescriptor` for the `buffer` field.
166 static constexpr auto Descriptor_buffer = ComponentDescriptor(
168 );
169 /// `ComponentDescriptor` for the `format` field.
170 static constexpr auto Descriptor_format = ComponentDescriptor(
172 );
173 /// `ComponentDescriptor` for the `opacity` field.
176 );
177 /// `ComponentDescriptor` for the `draw_order` field.
180 );
181
182 public: // START of extensions from image_ext.cpp:
183 /// Construct an image from bytes and image format.
184 ///
185 /// @param bytes The raw image data as bytes.
186 /// If the data does not outlive the image, use `std::move` or create the `rerun::Collection`
187 /// explicitly ahead of time with `rerun::Collection::take_ownership`.
188 /// The length of the data should be `W * H * image_format.bytes_per_pixel`.
189 /// @param format_ How the data should be interpreted.
191 if (bytes.size() != format_.image_format.num_bytes()) {
192 Error(
193 ErrorCode::InvalidTensorDimension,
194 "Image buffer has the wrong size. Got " + std::to_string(bytes.size()) +
195 " bytes, expected " + std::to_string(format_.image_format.num_bytes())
196 )
197 .handle();
198 }
199 *this = std::move(*this).with_buffer(bytes).with_format(format_);
200 }
201
202 /// Construct an image from resolution, pixel format and bytes.
203 ///
204 /// @param bytes The raw image data as bytes.
205 /// If the data does not outlive the image, use `std::move` or create the `rerun::Collection`
206 /// explicitly ahead of time with `rerun::Collection::take_ownership`.
207 /// The length of the data should be `W * H * pixel_format.bytes_per_pixel`.
208 /// @param resolution The resolution of the image as {width, height}.
209 /// @param pixel_format How the data should be interpreted.
211 Collection<uint8_t> bytes, WidthHeight resolution, datatypes::PixelFormat pixel_format
212 )
213 : Image{std::move(bytes), datatypes::ImageFormat{resolution, pixel_format}} {}
214
215 /// Construct an image from resolution, color model, channel datatype and bytes.
216 ///
217 /// @param bytes The raw image data.
218 /// If the data does not outlive the image, use `std::move` or create the `rerun::Collection`
219 /// explicitly ahead of time with `rerun::Collection::take_ownership`.
220 /// The length of the data should be `W * H * datatype.bytes * color_model.num_channels`.
221 /// @param resolution The resolution of the image as {width, height}.
222 /// @param color_model The color model of the pixel data.
223 /// @param datatype Datatype of the individual channels of the color model.
225 Collection<uint8_t> bytes, WidthHeight resolution, datatypes::ColorModel color_model,
227 )
228 : Image(std::move(bytes), datatypes::ImageFormat(resolution, color_model, datatype)) {}
229
230 /// Construct an image from resolution, color model and elements,
231 /// inferring the channel datatype from the element type.
232 ///
233 /// @param elements Pixel data as a `rerun::Collection`.
234 /// If the data does not outlive the image, use `std::move` or create the `rerun::Collection`
235 /// explicitly ahead of time with `rerun::Collection::take_ownership`.
236 /// The length of the data should be `W * H * color_model.num_channels`.
237 /// @param resolution The resolution of the image as {width, height}.
238 /// @param color_model The color model of the pixel data.
239 /// Each element in elements is interpreted as a single channel of the color model.
240 template <typename T>
241 Image(Collection<T> elements, WidthHeight resolution, datatypes::ColorModel color_model)
242 : Image(elements.to_uint8(), resolution, color_model, get_datatype(elements.data())) {}
243
244 /// Construct an image from resolution, color model and element pointer,
245 /// inferring the channel datatype from the element type.
246 ///
247 /// @param elements The raw image data.
248 /// ⚠️ Does not take ownership of the data, the caller must ensure the data outlives the image.
249 /// The number of elements is assumed to be `W * H * color_model.num_channels`.
250 /// @param resolution The resolution of the image as {width, height}.
251 /// @param color_model The color model of the pixel data.
252 /// Each element in elements is interpreted as a single channel of the color model.
253 template <typename T>
254 Image(const T* elements, WidthHeight resolution, datatypes::ColorModel color_model)
255 : Image(
256 rerun::Collection<uint8_t>::borrow(
257 reinterpret_cast<const uint8_t*>(elements),
258 resolution.width * resolution.height * color_model_channel_count(color_model)
259 ),
260 resolution, color_model, get_datatype(elements)
261 ) {}
262
263 /// Assumes single channel grayscale/luminance with 8-bit per value.
264 ///
265 /// @param bytes Pixel data as a `rerun::Collection`.
266 /// If the data does not outlive the image, use `std::move` or create the `rerun::Collection`
267 /// explicitly ahead of time with `rerun::Collection::take_ownership`.
268 /// The length of the data should be `W * H`.
269 /// @param resolution The resolution of the image as {width, height}.
271 return Image(
272 bytes,
273 resolution,
276 );
277 }
278
279 /// Assumes single channel grayscale/luminance with 8-bit per value.
280 ///
281 /// @param bytes Pixel data as a `rerun::Collection`.
282 /// If the data does not outlive the image, use `std::move` or create the `rerun::Collection`
283 /// explicitly ahead of time with `rerun::Collection::take_ownership`.
284 /// The length of the data should be `W * H`.
285 /// @param resolution The resolution of the image as {width, height}.
286 [[deprecated("Renamed `from_grayscale8`")]] static Image from_greyscale8(
287 Collection<uint8_t> bytes, WidthHeight resolution
288 ) {
289 return Image(
290 bytes,
291 resolution,
294 );
295 }
296
297 /// Assumes RGB, 8-bit per channel, packed as `RGBRGBRGB…`.
298 ///
299 /// @param bytes Pixel data as a `rerun::Collection`.
300 /// If the data does not outlive the image, use `std::move` or create the `rerun::Collection`
301 /// explicitly ahead of time with `rerun::Collection::take_ownership`.
302 /// The length of the data should be `W * H * 3`.
303 /// @param resolution The resolution of the image as {width, height}.
305 return Image(
306 bytes,
307 resolution,
310 );
311 }
312
313 /// Assumes RGBA, 8-bit per channel, with separate alpha.
314 ///
315 /// @param bytes Pixel data as a `rerun::Collection`.
316 /// If the data does not outlive the image, use `std::move` or create the `rerun::Collection`
317 /// explicitly ahead of time with `rerun::Collection::take_ownership`.
318 /// The length of the data should be `W * H * 4`.
319 /// @param resolution The resolution of the image as {width, height}.
321 return Image(
322 bytes,
323 resolution,
326 );
327 }
328
329 // END of extensions from image_ext.cpp, start of generated code:
330
331 public:
332 Image() = default;
333 Image(Image&& other) = default;
334 Image(const Image& other) = default;
335 Image& operator=(const Image& other) = default;
336 Image& operator=(Image&& other) = default;
337
338 /// Update only some specific fields of a `Image`.
340 return Image();
341 }
342
343 /// Clear all the fields of a `Image`.
345
346 /// The raw image data.
348 buffer = ComponentBatch::from_loggable(_buffer, Descriptor_buffer).value_or_throw();
349 return std::move(*this);
350 }
351
352 /// This method makes it possible to pack multiple `buffer` in a single component batch.
353 ///
354 /// This only makes sense when used in conjunction with `columns`. `with_buffer` should
355 /// be used when logging a single row's worth of data.
357 buffer = ComponentBatch::from_loggable(_buffer, Descriptor_buffer).value_or_throw();
358 return std::move(*this);
359 }
360
361 /// The format of the image.
363 format = ComponentBatch::from_loggable(_format, Descriptor_format).value_or_throw();
364 return std::move(*this);
365 }
366
367 /// This method makes it possible to pack multiple `format` in a single component batch.
368 ///
369 /// This only makes sense when used in conjunction with `columns`. `with_format` should
370 /// be used when logging a single row's worth of data.
372 format = ComponentBatch::from_loggable(_format, Descriptor_format).value_or_throw();
373 return std::move(*this);
374 }
375
376 /// Opacity of the image, useful for layering several images.
377 ///
378 /// Defaults to 1.0 (fully opaque).
380 opacity = ComponentBatch::from_loggable(_opacity, Descriptor_opacity).value_or_throw();
381 return std::move(*this);
382 }
383
384 /// This method makes it possible to pack multiple `opacity` in a single component batch.
385 ///
386 /// This only makes sense when used in conjunction with `columns`. `with_opacity` should
387 /// be used when logging a single row's worth of data.
389 opacity = ComponentBatch::from_loggable(_opacity, Descriptor_opacity).value_or_throw();
390 return std::move(*this);
391 }
392
393 /// An optional floating point value that specifies the 2D drawing order.
394 ///
395 /// Objects with higher values are drawn on top of those with lower values.
396 /// Defaults to `-10.0`.
398 draw_order =
399 ComponentBatch::from_loggable(_draw_order, Descriptor_draw_order).value_or_throw();
400 return std::move(*this);
401 }
402
403 /// This method makes it possible to pack multiple `draw_order` in a single component batch.
404 ///
405 /// This only makes sense when used in conjunction with `columns`. `with_draw_order` should
406 /// be used when logging a single row's worth of data.
408 draw_order =
409 ComponentBatch::from_loggable(_draw_order, Descriptor_draw_order).value_or_throw();
410 return std::move(*this);
411 }
412
413 /// Partitions the component data into multiple sub-batches.
414 ///
415 /// Specifically, this transforms the existing `ComponentBatch` data into `ComponentColumn`s
416 /// instead, via `ComponentBatch::partitioned`.
417 ///
418 /// This makes it possible to use `RecordingStream::send_columns` to send columnar data directly into Rerun.
419 ///
420 /// The specified `lengths` must sum to the total length of the component batch.
422
423 /// Partitions the component data into unit-length sub-batches.
424 ///
425 /// This is semantically similar to calling `columns` with `std::vector<uint32_t>(n, 1)`,
426 /// where `n` is automatically guessed.
428 };
429
430} // namespace rerun::archetypes
431
432namespace rerun {
433 /// \private
434 template <typename T>
435 struct AsComponents;
436
437 /// \private
438 template <>
439 struct AsComponents<archetypes::Image> {
440 /// Serialize all set component batches.
441 static Result<Collection<ComponentBatch>> as_batches(const archetypes::Image& archetype);
442 };
443} // namespace rerun
Generic collection of elements that are roughly contiguous in memory.
Definition collection.hpp:49
size_t size() const
Returns the number of instances in this collection.
Definition collection.hpp:291
Status outcome object (success or error) returned for fallible operations.
Definition error.hpp:99
void handle() const
Handle this error based on the set log handler.
A class for representing either a usable value, or an error.
Definition result.hpp:14
All built-in archetypes. See Types in the Rerun manual.
Definition rerun.hpp:76
PixelFormat
Datatype: Specifieds a particular format of an archetypes::Image.
Definition pixel_format.hpp:34
ColorModel
Datatype: Specified what color components are present in an archetypes::Image.
Definition color_model.hpp:26
@ RGB
Red, Green, Blue.
@ L
Grayscale luminance intencity/brightness/value, sometimes called Y
@ RGBA
Red, Green, Blue, Alpha.
ChannelDatatype
Datatype: The innermost datatype of an image.
Definition channel_datatype.hpp:26
@ U8
8-bit unsigned integer.
All Rerun C++ types and functions are in the rerun namespace or one of its nested namespaces.
Definition rerun.hpp:23
size_t color_model_channel_count(datatypes::ColorModel color_model)
Returns the number of channels for a given color model.
Definition image_utils.hpp:139
Collection< TElement > borrow(const TElement *data, size_t num_instances=1)
Borrows binary data into a Collection from a pointer.
Definition collection.hpp:462
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
The width and height of an image.
Definition image_utils.hpp:13
Archetype: A monochrome or color image.
Definition image.hpp:143
Collection< ComponentColumn > columns(const Collection< uint32_t > &lengths_)
Partitions the component data into multiple sub-batches.
Image with_draw_order(const rerun::components::DrawOrder &_draw_order) &&
An optional floating point value that specifies the 2D drawing order.
Definition image.hpp:397
static constexpr auto Descriptor_opacity
ComponentDescriptor for the opacity field.
Definition image.hpp:174
Image with_many_format(const Collection< rerun::components::ImageFormat > &_format) &&
This method makes it possible to pack multiple format in a single component batch.
Definition image.hpp:371
Image with_format(const rerun::components::ImageFormat &_format) &&
The format of the image.
Definition image.hpp:362
Image with_buffer(const rerun::components::ImageBuffer &_buffer) &&
The raw image data.
Definition image.hpp:347
static constexpr auto Descriptor_buffer
ComponentDescriptor for the buffer field.
Definition image.hpp:166
static Image from_greyscale8(Collection< uint8_t > bytes, WidthHeight resolution)
Assumes single channel grayscale/luminance with 8-bit per value.
Definition image.hpp:286
Image(Collection< uint8_t > bytes, components::ImageFormat format_)
Construct an image from bytes and image format.
Definition image.hpp:190
Image with_many_opacity(const Collection< rerun::components::Opacity > &_opacity) &&
This method makes it possible to pack multiple opacity in a single component batch.
Definition image.hpp:388
static constexpr auto Descriptor_draw_order
ComponentDescriptor for the draw_order field.
Definition image.hpp:178
Collection< ComponentColumn > columns()
Partitions the component data into unit-length sub-batches.
static constexpr auto Descriptor_format
ComponentDescriptor for the format field.
Definition image.hpp:170
Image(Collection< T > elements, WidthHeight resolution, datatypes::ColorModel color_model)
Construct an image from resolution, color model and elements, inferring the channel datatype from the...
Definition image.hpp:241
static Image clear_fields()
Clear all the fields of a Image.
Image(Collection< uint8_t > bytes, WidthHeight resolution, datatypes::PixelFormat pixel_format)
Construct an image from resolution, pixel format and bytes.
Definition image.hpp:210
Image(const T *elements, WidthHeight resolution, datatypes::ColorModel color_model)
Construct an image from resolution, color model and element pointer, inferring the channel datatype f...
Definition image.hpp:254
std::optional< ComponentBatch > format
The format of the image.
Definition image.hpp:148
Image with_opacity(const rerun::components::Opacity &_opacity) &&
Opacity of the image, useful for layering several images.
Definition image.hpp:379
Image(Collection< uint8_t > bytes, WidthHeight resolution, datatypes::ColorModel color_model, datatypes::ChannelDatatype datatype)
Construct an image from resolution, color model, channel datatype and bytes.
Definition image.hpp:224
Image with_many_draw_order(const Collection< rerun::components::DrawOrder > &_draw_order) &&
This method makes it possible to pack multiple draw_order in a single component batch.
Definition image.hpp:407
static Image update_fields()
Update only some specific fields of a Image.
Definition image.hpp:339
std::optional< ComponentBatch > draw_order
An optional floating point value that specifies the 2D drawing order.
Definition image.hpp:159
std::optional< ComponentBatch > buffer
The raw image data.
Definition image.hpp:145
static constexpr const char ArchetypeName[]
The name of the archetype as used in ComponentDescriptors.
Definition image.hpp:163
static Image from_grayscale8(Collection< uint8_t > bytes, WidthHeight resolution)
Assumes single channel grayscale/luminance with 8-bit per value.
Definition image.hpp:270
std::optional< ComponentBatch > opacity
Opacity of the image, useful for layering several images.
Definition image.hpp:153
static Image from_rgba32(Collection< uint8_t > bytes, WidthHeight resolution)
Assumes RGBA, 8-bit per channel, with separate alpha.
Definition image.hpp:320
static Image from_rgb24(Collection< uint8_t > bytes, WidthHeight resolution)
Assumes RGB, 8-bit per channel, packed as RGBRGBRGB….
Definition image.hpp:304
Image with_many_buffer(const Collection< rerun::components::ImageBuffer > &_buffer) &&
This method makes it possible to pack multiple buffer in a single component batch.
Definition image.hpp:356
Component: Draw order of 2D elements.
Definition draw_order.hpp:19
Component: A buffer that is known to store image data.
Definition image_buffer.hpp:18
Component: The metadata describing the contents of a components::ImageBuffer.
Definition image_format.hpp:14
Component: Degree of transparency ranging from 0.0 (fully transparent) to 1.0 (fully opaque).
Definition opacity.hpp:17
size_t num_bytes() const
How many bytes will this image occupy?
Definition image_format.hpp:65