Archetype: A monochrome or color image. More...

#include <rerun/archetypes/image.hpp>

Public Member Functions
	Image (Collection< uint8_t > bytes, components::ImageFormat format_)
	Construct an image from bytes and image format.

	Image (Collection< uint8_t > bytes, WidthHeight resolution, datatypes::PixelFormat pixel_format)
	Construct an image from resolution, pixel format and bytes.

	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.

template<typename T >
	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 element type.

template<typename T >
	Image (const T *elements, WidthHeight resolution, datatypes::ColorModel color_model)
	Construct an image from resolution, color model and element pointer, inferring the channel datatype from the element type.

	Image (Image &&other)=default

	Image (const Image &other)=default

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

Image &	operator= (Image &&other)=default

Image	with_buffer (const rerun::components::ImageBuffer &_buffer) &&
	The raw image data.

Image	with_many_buffer (const Collection< rerun::components::ImageBuffer > &_buffer) &&
	This method makes it possible to pack multiple `buffer` in a single component batch.

Image	with_format (const rerun::components::ImageFormat &_format) &&
	The format of the image.

Image	with_many_format (const Collection< rerun::components::ImageFormat > &_format) &&
	This method makes it possible to pack multiple `format` in a single component batch.

Image	with_opacity (const rerun::components::Opacity &_opacity) &&
	Opacity of the image, useful for layering several media.

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

Image	with_draw_order (const rerun::components::DrawOrder &_draw_order) &&
	An optional floating point value that specifies the 2D drawing order.

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.

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 Image	from_grayscale8 (Collection< uint8_t > bytes, WidthHeight resolution)
	Assumes single channel grayscale/luminance with 8-bit per value.

static Image	from_greyscale8 (Collection< uint8_t > bytes, WidthHeight resolution)
	Assumes single channel grayscale/luminance with 8-bit per value.

static Image	from_rgb24 (Collection< uint8_t > bytes, WidthHeight resolution)
	Assumes RGB, 8-bit per channel, packed as `RGBRGBRGB…`.

static Image	from_rgba32 (Collection< uint8_t > bytes, WidthHeight resolution)
	Assumes RGBA, 8-bit per channel, with separate alpha.

static Image	update_fields ()
	Update only some specific fields of a `Image`.

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

Public Attributes
std::optional< ComponentBatch >	buffer
	The raw image data.

std::optional< ComponentBatch >	format
	The format of the image.

std::optional< ComponentBatch >	opacity
	Opacity of the image, useful for layering several media.

std::optional< ComponentBatch >	draw_order
	An optional floating point value that specifies the 2D drawing order.

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

static constexpr auto	Descriptor_buffer
	`ComponentDescriptor` for the `buffer` field.

static constexpr auto	Descriptor_format
	`ComponentDescriptor` for the `format` field.

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

static constexpr auto	Descriptor_draw_order
	`ComponentDescriptor` for the `draw_order` field.

Detailed Description

Archetype: A monochrome or color image.

Rerun also supports compressed images (JPEG, PNG, …), using archetypes::EncodedImage. For images that refer to video frames see archetypes::VideoFrameReference. Compressing images or using video data instead can save a lot of bandwidth and memory.

The raw image data is stored as a single buffer of bytes in a components::Blob. The meaning of these bytes is determined by the components::ImageFormat which specifies the resolution and the pixel format (e.g. RGB, RGBA, …).

The order of dimensions in the underlying components::Blob follows the typical row-major, interleaved-pixel image format.

Since the underlying [rerun::components::Blob] uses rerun::Collection internally, data can be passed in without a copy from raw pointers or by reference from std::vector/std::array/c-arrays. If needed, this "borrow-behavior" can be extended by defining your own rerun::CollectionAdapter.

Examples

image_simple:

#include <rerun.hpp>
 
#include <vector>
 
int main() {
    const auto rec = rerun::RecordingStream("rerun_example_image");
    rec.spawn().exit_on_failure();
 
    // Create a synthetic image.
    const int HEIGHT = 200;
    const int WIDTH = 300;
    std::vector<uint8_t> data(WIDTH * HEIGHT * 3, 0);
    for (size_t i = 0; i <data.size(); i += 3) {
        data[i] = 255;
    }
    for (size_t y = 50; y <150; ++y) {
        for (size_t x = 50; x <150; ++x) {
            data[(y * WIDTH + x) * 3 + 0] = 0;
            data[(y * WIDTH + x) * 3 + 1] = 255;
            data[(y * WIDTH + x) * 3 + 2] = 0;
        }
    }
 
    rec.log("image", rerun::Image::from_rgb24(data, {WIDTH, HEIGHT}));
}

Logging images with various formats

#include <algorithm>
#include <cstdint>
#include <vector>
 
#include <rerun.hpp>
 
int main() {
    const auto rec = rerun::RecordingStream("rerun_example_image_formats");
    rec.spawn().exit_on_failure();
 
    // Simple gradient image
    std::vector<uint8_t> image(256 * 256 * 3);
    for (size_t y = 0; y <256; ++y) {
        for (size_t x = 0; x <256; ++x) {
            image[(y * 256 + x) * 3 + 0] = static_cast<uint8_t>(x);
            image[(y * 256 + x) * 3 + 1] = static_cast<uint8_t>(std::min<size_t>(255, x + y));
            image[(y * 256 + x) * 3 + 2] = static_cast<uint8_t>(y);
        }
    }
 
    // RGB image
    rec.log("image_rgb", rerun::Image::from_rgb24(image, {256, 256}));
 
    // Green channel only (Luminance)
    std::vector<uint8_t> green_channel(256 * 256);
    for (size_t i = 0; i <256 * 256; ++i) {
        green_channel[i] = image[i * 3 + 1];
    }
    rec.log(
        "image_green_only",
        rerun::Image(rerun::borrow(green_channel), {256, 256}, rerun::ColorModel::L)
    );
 
    // BGR image
    std::vector<uint8_t> bgr_image(256 * 256 * 3);
    for (size_t i = 0; i <256 * 256; ++i) {
        bgr_image[i * 3 + 0] = image[i * 3 + 2];
        bgr_image[i * 3 + 1] = image[i * 3 + 1];
        bgr_image[i * 3 + 2] = image[i * 3 + 0];
    }
    rec.log(
        "image_bgr",
        rerun::Image(rerun::borrow(bgr_image), {256, 256}, rerun::ColorModel::BGR)
    );
 
    // New image with Separate Y/U/V planes with 4:2:2 chroma downsampling
    std::vector<uint8_t> yuv_bytes(256 * 256 + 128 * 256 * 2);
    std::fill_n(yuv_bytes.begin(), 256 * 256, static_cast<uint8_t>(128)); // Fixed value for Y
    size_t u_plane_offset = 256 * 256;
    size_t v_plane_offset = u_plane_offset + 128 * 256;
    for (size_t y = 0; y <256; ++y) {
        for (size_t x = 0; x <128; ++x) {
            auto coord = y * 128 + x;
            yuv_bytes[u_plane_offset + coord] = static_cast<uint8_t>(x * 2); // Gradient for U
            yuv_bytes[v_plane_offset + coord] = static_cast<uint8_t>(y);     // Gradient for V
        }
    }
    rec.log(
        "image_yuv422",
        rerun::Image(rerun::borrow(yuv_bytes), {256, 256}, rerun::PixelFormat::Y_U_V16_FullRange)
    );
 
    return 0;
}

Constructor & Destructor Documentation

◆ Image() [1/5]

rerun::archetypes::Image::Image	(	Collection< uint8_t >	bytes,
		components::ImageFormat	format_
	)

inline

Construct an image from bytes and image format.

Parameters

bytes	The raw image data as bytes. If the data does not outlive the image, use `std::move` or create the `rerun::Collection` explicitly ahead of time with `rerun::Collection::take_ownership`. The length of the data should be `W * H * image_format.bytes_per_pixel`.
format_	How the data should be interpreted.

◆ Image() [2/5]

rerun::archetypes::Image::Image	(	Collection< uint8_t >	bytes,
		WidthHeight	resolution,
		datatypes::PixelFormat	pixel_format
	)

inline

Construct an image from resolution, pixel format and bytes.

Parameters

bytes	The raw image data as bytes. If the data does not outlive the image, use `std::move` or create the `rerun::Collection` explicitly ahead of time with `rerun::Collection::take_ownership`. The length of the data should be `W * H * pixel_format.bytes_per_pixel`.
resolution	The resolution of the image as {width, height}.
pixel_format	How the data should be interpreted.

◆ Image() [3/5]

rerun::archetypes::Image::Image	(	Collection< uint8_t >	bytes,
		WidthHeight	resolution,
		datatypes::ColorModel	color_model,
		datatypes::ChannelDatatype	datatype
	)

inline

Construct an image from resolution, color model, channel datatype and bytes.

Parameters

bytes	The raw image data. If the data does not outlive the image, use `std::move` or create the `rerun::Collection` explicitly ahead of time with `rerun::Collection::take_ownership`. The length of the data should be `W * H * datatype.bytes * color_model.num_channels`.
resolution	The resolution of the image as {width, height}.
color_model	The color model of the pixel data.
datatype	Datatype of the individual channels of the color model.

◆ Image() [4/5]

template<typename T >

rerun::archetypes::Image::Image	(	Collection< T >	elements,
		WidthHeight	resolution,
		datatypes::ColorModel	color_model
	)

inline

Construct an image from resolution, color model and elements, inferring the channel datatype from the element type.

Parameters

elements	Pixel data as a `rerun::Collection`. If the data does not outlive the image, use `std::move` or create the `rerun::Collection` explicitly ahead of time with `rerun::Collection::take_ownership`. The length of the data should be `W * H * color_model.num_channels`.
resolution	The resolution of the image as {width, height}.
color_model	The color model of the pixel data. Each element in elements is interpreted as a single channel of the color model.

◆ Image() [5/5]

template<typename T >

rerun::archetypes::Image::Image	(	const T *	elements,
		WidthHeight	resolution,
		datatypes::ColorModel	color_model
	)

inline

Construct an image from resolution, color model and element pointer, inferring the channel datatype from the element type.

Parameters

elements	The raw image data. ⚠️ Does not take ownership of the data, the caller must ensure the data outlives the image. The number of elements is assumed to be `W * H * color_model.num_channels`.
resolution	The resolution of the image as {width, height}.
color_model	The color model of the pixel data. Each element in elements is interpreted as a single channel of the color model.

Member Function Documentation

◆ from_grayscale8()

static Image rerun::archetypes::Image::from_grayscale8	(	Collection< uint8_t >	bytes,
		WidthHeight	resolution
	)

inlinestatic

Assumes single channel grayscale/luminance with 8-bit per value.

Parameters

bytes	Pixel data as a `rerun::Collection`. If the data does not outlive the image, use `std::move` or create the `rerun::Collection` explicitly ahead of time with `rerun::Collection::take_ownership`. The length of the data should be `W * H`.
resolution	The resolution of the image as {width, height}.

◆ from_greyscale8()

static Image rerun::archetypes::Image::from_greyscale8	(	Collection< uint8_t >	bytes,
		WidthHeight	resolution
	)

inlinestatic

Assumes single channel grayscale/luminance with 8-bit per value.

Parameters

bytes	Pixel data as a `rerun::Collection`. If the data does not outlive the image, use `std::move` or create the `rerun::Collection` explicitly ahead of time with `rerun::Collection::take_ownership`. The length of the data should be `W * H`.
resolution	The resolution of the image as {width, height}.

◆ from_rgb24()

static Image rerun::archetypes::Image::from_rgb24	(	Collection< uint8_t >	bytes,
		WidthHeight	resolution
	)

inlinestatic

Assumes RGB, 8-bit per channel, packed as RGBRGBRGB….

Parameters

bytes	Pixel data as a `rerun::Collection`. If the data does not outlive the image, use `std::move` or create the `rerun::Collection` explicitly ahead of time with `rerun::Collection::take_ownership`. The length of the data should be `W * H * 3`.
resolution	The resolution of the image as {width, height}.

◆ from_rgba32()

static Image rerun::archetypes::Image::from_rgba32	(	Collection< uint8_t >	bytes,
		WidthHeight	resolution
	)

inlinestatic

Assumes RGBA, 8-bit per channel, with separate alpha.

Parameters

bytes	Pixel data as a `rerun::Collection`. If the data does not outlive the image, use `std::move` or create the `rerun::Collection` explicitly ahead of time with `rerun::Collection::take_ownership`. The length of the data should be `W * H * 4`.
resolution	The resolution of the image as {width, height}.

◆ with_many_buffer()

Image rerun::archetypes::Image::with_many_buffer ( const Collection< rerun::components::ImageBuffer > & _buffer ) &&

inline

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

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

◆ with_many_format()

Image rerun::archetypes::Image::with_many_format ( const Collection< rerun::components::ImageFormat > & _format ) &&

inline

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

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

◆ with_opacity()

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

inline

Opacity of the image, useful for layering several media.

Defaults to 1.0 (fully opaque).

◆ with_many_opacity()

Image rerun::archetypes::Image::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.

◆ with_draw_order()

Image rerun::archetypes::Image::with_draw_order ( const rerun::components::DrawOrder & _draw_order ) &&

inline

An optional floating point value that specifies the 2D drawing order.

Objects with higher values are drawn on top of those with lower values. Defaults to -10.0.

◆ with_many_draw_order()

Image rerun::archetypes::Image::with_many_draw_order ( const Collection< rerun::components::DrawOrder > & _draw_order ) &&

inline

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

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

◆ columns() [1/2]

Collection< ComponentColumn > rerun::archetypes::Image::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::Image::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

◆ opacity

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

Opacity of the image, useful for layering several media.

Defaults to 1.0 (fully opaque).

◆ draw_order

std::optional<ComponentBatch> rerun::archetypes::Image::draw_order

An optional floating point value that specifies the 2D drawing order.

Objects with higher values are drawn on top of those with lower values. Defaults to -10.0.

◆ Descriptor_buffer

constexpr auto rerun::archetypes::Image::Descriptor_buffer

staticconstexpr

Initial value:

= ComponentDescriptor(
            ArchetypeName, "Image:buffer", Loggable<rerun::components::ImageBuffer>::ComponentType
        )

ComponentDescriptor for the buffer field.

◆ Descriptor_format

constexpr auto rerun::archetypes::Image::Descriptor_format

staticconstexpr

Initial value:

= ComponentDescriptor(
            ArchetypeName, "Image:format", Loggable<rerun::components::ImageFormat>::ComponentType
        )

ComponentDescriptor for the format field.

◆ Descriptor_opacity

constexpr auto rerun::archetypes::Image::Descriptor_opacity

staticconstexpr

Initial value:

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

ComponentDescriptor for the opacity field.

◆ Descriptor_draw_order

constexpr auto rerun::archetypes::Image::Descriptor_draw_order

staticconstexpr

Initial value:

= ComponentDescriptor(
            ArchetypeName, "Image:draw_order", Loggable<rerun::components::DrawOrder>::ComponentType
        )

ComponentDescriptor for the draw_order field.

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

rerun/archetypes/image.hpp

Public Member Functions

Static Public Member Functions

Public Attributes

Static Public Attributes

Detailed Description

Examples

image_simple:

Logging images with various formats

Constructor & Destructor Documentation

◆ Image() [1/5]

◆ Image() [2/5]

◆ Image() [3/5]

◆ Image() [4/5]

◆ Image() [5/5]

Member Function Documentation

◆ from_grayscale8()

◆ from_greyscale8()

◆ from_rgb24()

◆ from_rgba32()

◆ with_many_buffer()

◆ with_many_format()

◆ with_opacity()

◆ with_many_opacity()

◆ with_draw_order()

◆ with_many_draw_order()

◆ columns() [1/2]

◆ columns() [2/2]

Member Data Documentation

◆ opacity

◆ draw_order

◆ Descriptor_buffer

◆ Descriptor_format

◆ Descriptor_opacity

◆ Descriptor_draw_order