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