Archetype: A depth image, i.e. More...

#include <rerun/archetypes/depth_image.hpp>

Public Types
using	IndicatorComponent = rerun::components::IndicatorComponent< IndicatorComponentName >
	Indicator component, used to identify the archetype when converting to a list of components.

Public Member Functions
template<typename TElement >
	DepthImage (const TElement *pixels, WidthHeight resolution)
	Constructs image from pointer + resolution, inferring the datatype from the pointer type.

template<typename TElement >
	DepthImage (Collection< TElement > pixels, WidthHeight resolution)
	Constructs image from pixel data + resolution with datatype inferred from the passed collection.

	DepthImage (const void *bytes, WidthHeight resolution, datatypes::ChannelDatatype datatype)
	Constructs image from pixel data + resolution with explicit datatype.

	DepthImage (Collection< uint8_t > bytes, WidthHeight resolution, datatypes::ChannelDatatype datatype)
	Constructs image from pixel data + resolution + datatype.

	DepthImage (DepthImage &&other)=default

	DepthImage (const DepthImage &other)=default

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

DepthImage &	operator= (DepthImage &&other)=default

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

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

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

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

DepthImage	with_meter (const rerun::components::DepthMeter &_meter) &&
	An optional floating point value that specifies how long a meter is in the native depth units.

DepthImage	with_many_meter (const Collection< rerun::components::DepthMeter > &_meter) &&
	This method makes it possible to pack multiple `meter` in a single component batch.

DepthImage	with_colormap (const rerun::components::Colormap &_colormap) &&
	Colormap to use for rendering the depth image.

DepthImage	with_many_colormap (const Collection< rerun::components::Colormap > &_colormap) &&
	This method makes it possible to pack multiple `colormap` in a single component batch.

DepthImage	with_depth_range (const rerun::components::ValueRange &_depth_range) &&
	The expected range of depth values.

DepthImage	with_many_depth_range (const Collection< rerun::components::ValueRange > &_depth_range) &&
	This method makes it possible to pack multiple `depth_range` in a single component batch.

DepthImage	with_point_fill_ratio (const rerun::components::FillRatio &_point_fill_ratio) &&
	Scale the radii of the points in the point cloud generated from this image.

DepthImage	with_many_point_fill_ratio (const Collection< rerun::components::FillRatio > &_point_fill_ratio) &&
	This method makes it possible to pack multiple `point_fill_ratio` in a single component batch.

DepthImage	with_draw_order (const rerun::components::DrawOrder &_draw_order) &&
	An optional floating point value that specifies the 2D drawing order, used only if the depth image is shown as a 2D image.

DepthImage	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 DepthImage	update_fields ()
	Update only some specific fields of a `DepthImage`.

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

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

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

std::optional< ComponentBatch >	meter
	An optional floating point value that specifies how long a meter is in the native depth units.

std::optional< ComponentBatch >	colormap
	Colormap to use for rendering the depth image.

std::optional< ComponentBatch >	depth_range
	The expected range of depth values.

std::optional< ComponentBatch >	point_fill_ratio
	Scale the radii of the points in the point cloud generated from this image.

std::optional< ComponentBatch >	draw_order
	An optional floating point value that specifies the 2D drawing order, used only if the depth image is shown as a 2D image.

Static Public Attributes
static constexpr const char	IndicatorComponentName []

static constexpr const char	ArchetypeName [] = "rerun.archetypes.DepthImage"
	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_meter
	`ComponentDescriptor` for the `meter` field.

static constexpr auto	Descriptor_colormap
	`ComponentDescriptor` for the `colormap` field.

static constexpr auto	Descriptor_depth_range
	`ComponentDescriptor` for the `depth_range` field.

static constexpr auto	Descriptor_point_fill_ratio
	`ComponentDescriptor` for the `point_fill_ratio` field.

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

Detailed Description

Archetype: A depth image, i.e.

as captured by a depth camera.

Each pixel corresponds to a depth value in units specified by components::DepthMeter.

Since the underlying rerun::datatypes::ImageBuffer 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.

Example

Depth to 3D example

#include <rerun.hpp>
 
#include <algorithm> // fill_n
#include <vector>
 
int main() {
    const auto rec = rerun::RecordingStream("rerun_example_depth_image_3d");
    rec.spawn().exit_on_failure();
 
    // Create a synthetic depth image.
    const int HEIGHT = 200;
    const int WIDTH = 300;
    std::vector<uint16_t> data(WIDTH * HEIGHT, 65535);
    for (auto y = 50; y <150; ++y) {
        std::fill_n(data.begin() + y * WIDTH + 50, 100, static_cast<uint16_t>(20000));
    }
    for (auto y = 130; y <180; ++y) {
        std::fill_n(data.begin() + y * WIDTH + 100, 180, static_cast<uint16_t>(45000));
    }
 
    // If we log a pinhole camera model, the depth gets automatically back-projected to 3D
    rec.log(
        "world/camera",
        rerun::Pinhole::from_focal_length_and_resolution(
            200.0f,
            {static_cast<float>(WIDTH), static_cast<float>(HEIGHT)}
        )
    );
 
    rec.log(
        "world/camera/depth",
        rerun::DepthImage(data.data(), {WIDTH, HEIGHT})
            .with_meter(10000.0)
            .with_colormap(rerun::components::Colormap::Viridis)
    );
}

Constructor & Destructor Documentation

◆ DepthImage() [1/4]

template<typename TElement >

rerun::archetypes::DepthImage::DepthImage	(	const TElement *	pixels,
		WidthHeight	resolution
	)

inline

Constructs image from pointer + resolution, inferring the datatype from the pointer type.

Parameters

pixels	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`.
resolution	The resolution of the image as {width, height}.

◆ DepthImage() [2/4]

template<typename TElement >

rerun::archetypes::DepthImage::DepthImage	(	Collection< TElement >	pixels,
		WidthHeight	resolution
	)

inline

Constructs image from pixel data + resolution with datatype inferred from the passed collection.

Parameters

pixels	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`.
resolution	The resolution of the image as {width, height}.

◆ DepthImage() [3/4]

rerun::archetypes::DepthImage::DepthImage	(	const void *	bytes,
		WidthHeight	resolution,
		datatypes::ChannelDatatype	datatype
	)

inline

Constructs image from pixel data + resolution with explicit datatype.

Borrows data from a pointer (i.e. data must outlive the image!).

Parameters

bytes	The raw image data. ⚠️ Does not take ownership of the data, the caller must ensure the data outlives the image. The byte size of the data is assumed to be `W * H * datatype.size`
resolution	The resolution of the image as {width, height}.
datatype	How the data should be interpreted.

◆ DepthImage() [4/4]

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

inline

Constructs image from pixel data + resolution + datatype.

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`.
resolution	The resolution of the image as {width, height}.
datatype	How the data should be interpreted.

Member Function Documentation

◆ with_many_buffer()

DepthImage rerun::archetypes::DepthImage::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()

DepthImage rerun::archetypes::DepthImage::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_meter()

DepthImage rerun::archetypes::DepthImage::with_meter ( const rerun::components::DepthMeter & _meter ) &&

inline

An optional floating point value that specifies how long a meter is in the native depth units.

For instance: with uint16, perhaps meter=1000 which would mean you have millimeter precision and a range of up to ~65 meters (2^16 / 1000).

Note that the only effect on 2D views is the physical depth values shown when hovering the image. In 3D views on the other hand, this affects where the points of the point cloud are placed.

◆ with_many_meter()

DepthImage rerun::archetypes::DepthImage::with_many_meter ( const Collection< rerun::components::DepthMeter > & _meter ) &&

inline

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

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

◆ with_colormap()

DepthImage rerun::archetypes::DepthImage::with_colormap ( const rerun::components::Colormap & _colormap ) &&

inline

Colormap to use for rendering the depth image.

If not set, the depth image will be rendered using the Turbo colormap.

◆ with_many_colormap()

DepthImage rerun::archetypes::DepthImage::with_many_colormap ( const Collection< rerun::components::Colormap > & _colormap ) &&

inline

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.

◆ with_depth_range()

DepthImage rerun::archetypes::DepthImage::with_depth_range ( const rerun::components::ValueRange & _depth_range ) &&

inline

The expected range of depth values.

This is typically the expected range of valid values. Everything outside of the range is clamped to the range for the purpose of colormpaping. Note that point clouds generated from this image will still display all points, regardless of this range.

If not specified, the range will be automatically estimated from the data. Note that the Viewer may try to guess a wider range than the minimum/maximum of values in the contents of the depth image. E.g. if all values are positive, some bigger than 1.0 and all smaller than 255.0, the Viewer will guess that the data likely came from an 8bit image, thus assuming a range of 0-255.

◆ with_many_depth_range()

DepthImage rerun::archetypes::DepthImage::with_many_depth_range ( const Collection< rerun::components::ValueRange > & _depth_range ) &&

inline

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

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

◆ with_point_fill_ratio()

DepthImage rerun::archetypes::DepthImage::with_point_fill_ratio ( const rerun::components::FillRatio & _point_fill_ratio ) &&

inline

Scale the radii of the points in the point cloud generated from this image.

A fill ratio of 1.0 (the default) means that each point is as big as to touch the center of its neighbor if it is at the same depth, leaving no gaps. A fill ratio of 0.5 means that each point touches the edge of its neighbor if it has the same depth.

TODO(#6744): This applies only to 3D views!

◆ with_many_point_fill_ratio()

DepthImage rerun::archetypes::DepthImage::with_many_point_fill_ratio ( const Collection< rerun::components::FillRatio > & _point_fill_ratio ) &&

inline

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

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

◆ with_draw_order()

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

inline

An optional floating point value that specifies the 2D drawing order, used only if the depth image is shown as a 2D image.

Objects with higher values are drawn on top of those with lower values.

◆ with_many_draw_order()

DepthImage rerun::archetypes::DepthImage::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::DepthImage::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::DepthImage::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

◆ meter

std::optional<ComponentBatch> rerun::archetypes::DepthImage::meter

An optional floating point value that specifies how long a meter is in the native depth units.

For instance: with uint16, perhaps meter=1000 which would mean you have millimeter precision and a range of up to ~65 meters (2^16 / 1000).

Note that the only effect on 2D views is the physical depth values shown when hovering the image. In 3D views on the other hand, this affects where the points of the point cloud are placed.

◆ colormap

std::optional<ComponentBatch> rerun::archetypes::DepthImage::colormap

Colormap to use for rendering the depth image.

If not set, the depth image will be rendered using the Turbo colormap.

◆ depth_range

std::optional<ComponentBatch> rerun::archetypes::DepthImage::depth_range

The expected range of depth values.

This is typically the expected range of valid values. Everything outside of the range is clamped to the range for the purpose of colormpaping. Note that point clouds generated from this image will still display all points, regardless of this range.

If not specified, the range will be automatically estimated from the data. Note that the Viewer may try to guess a wider range than the minimum/maximum of values in the contents of the depth image. E.g. if all values are positive, some bigger than 1.0 and all smaller than 255.0, the Viewer will guess that the data likely came from an 8bit image, thus assuming a range of 0-255.

◆ point_fill_ratio

std::optional<ComponentBatch> rerun::archetypes::DepthImage::point_fill_ratio

Scale the radii of the points in the point cloud generated from this image.

A fill ratio of 1.0 (the default) means that each point is as big as to touch the center of its neighbor if it is at the same depth, leaving no gaps. A fill ratio of 0.5 means that each point touches the edge of its neighbor if it has the same depth.

TODO(#6744): This applies only to 3D views!

◆ draw_order

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

An optional floating point value that specifies the 2D drawing order, used only if the depth image is shown as a 2D image.

Objects with higher values are drawn on top of those with lower values.

◆ IndicatorComponentName

constexpr const char rerun::archetypes::DepthImage::IndicatorComponentName[]

staticconstexpr

Initial value:

=

"rerun.components.DepthImageIndicator"

◆ Descriptor_buffer

constexpr auto rerun::archetypes::DepthImage::Descriptor_buffer

staticconstexpr

Initial value:

= ComponentDescriptor(
            ArchetypeName, "buffer",
            Loggable<rerun::components::ImageBuffer>::Descriptor.component_name
        )

ComponentDescriptor for the buffer field.

◆ Descriptor_format

constexpr auto rerun::archetypes::DepthImage::Descriptor_format

staticconstexpr

Initial value:

= ComponentDescriptor(
            ArchetypeName, "format",
            Loggable<rerun::components::ImageFormat>::Descriptor.component_name
        )

ComponentDescriptor for the format field.

◆ Descriptor_meter

constexpr auto rerun::archetypes::DepthImage::Descriptor_meter

staticconstexpr

Initial value:

= ComponentDescriptor(
            ArchetypeName, "meter",
            Loggable<rerun::components::DepthMeter>::Descriptor.component_name
        )

ComponentDescriptor for the meter field.

◆ Descriptor_colormap

constexpr auto rerun::archetypes::DepthImage::Descriptor_colormap

staticconstexpr

Initial value:

= ComponentDescriptor(
            ArchetypeName, "colormap",
            Loggable<rerun::components::Colormap>::Descriptor.component_name
        )

ComponentDescriptor for the colormap field.

◆ Descriptor_depth_range

constexpr auto rerun::archetypes::DepthImage::Descriptor_depth_range

staticconstexpr

Initial value:

= ComponentDescriptor(
            ArchetypeName, "depth_range",
            Loggable<rerun::components::ValueRange>::Descriptor.component_name
        )

ComponentDescriptor for the depth_range field.

◆ Descriptor_point_fill_ratio

constexpr auto rerun::archetypes::DepthImage::Descriptor_point_fill_ratio

staticconstexpr

Initial value:

= ComponentDescriptor(
            ArchetypeName, "point_fill_ratio",
            Loggable<rerun::components::FillRatio>::Descriptor.component_name
        )

ComponentDescriptor for the point_fill_ratio field.

◆ Descriptor_draw_order

constexpr auto rerun::archetypes::DepthImage::Descriptor_draw_order

staticconstexpr

Initial value:

= ComponentDescriptor(
            ArchetypeName, "draw_order",
            Loggable<rerun::components::DrawOrder>::Descriptor.component_name
        )

ComponentDescriptor for the draw_order field.

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

rerun/archetypes/depth_image.hpp

Public Types

Public Member Functions

Static Public Member Functions

Public Attributes

Static Public Attributes

Detailed Description

Example

Depth to 3D example

Constructor & Destructor Documentation

◆ DepthImage() [1/4]

◆ DepthImage() [2/4]

◆ DepthImage() [3/4]

◆ DepthImage() [4/4]

Member Function Documentation

◆ with_many_buffer()

◆ with_many_format()

◆ with_meter()

◆ with_many_meter()

◆ with_colormap()

◆ with_many_colormap()

◆ with_depth_range()

◆ with_many_depth_range()

◆ with_point_fill_ratio()

◆ with_many_point_fill_ratio()

◆ with_draw_order()

◆ with_many_draw_order()

◆ columns() [1/2]

◆ columns() [2/2]

Member Data Documentation

◆ meter

◆ colormap

◆ depth_range

◆ point_fill_ratio

◆ draw_order

◆ IndicatorComponentName

◆ Descriptor_buffer

◆ Descriptor_format

◆ Descriptor_meter

◆ Descriptor_colormap

◆ Descriptor_depth_range

◆ Descriptor_point_fill_ratio

◆ Descriptor_draw_order