Struct rerun::Image

pub struct Image {
    pub buffer: ImageBuffer,
    pub format: ImageFormat,
    pub opacity: Option<Opacity>,
    pub draw_order: Option<DrawOrder>,
}

Archetype: A monochrome or color image.

See also archetypes::DepthImage and archetypes::SegmentationImage.

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.

Examples

image_simple:

use ndarray::{s, Array, ShapeBuilder};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let rec = rerun::RecordingStreamBuilder::new("rerun_example_image").spawn()?;

    let mut image = Array::<u8, _>::zeros((200, 300, 3).f());
    image.slice_mut(s![.., .., 0]).fill(255);
    image.slice_mut(s![50..150, 50..150, 0]).fill(0);
    image.slice_mut(s![50..150, 50..150, 1]).fill(255);

    rec.log(
        "image",
        &rerun::Image::from_color_model_and_tensor(rerun::ColorModel::RGB, image)?,
    )?;

    Ok(())
}

Logging images with various formats

use rerun::external::ndarray;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let rec = rerun::RecordingStreamBuilder::new("rerun_example_image_formats").spawn()?;

    // Simple gradient image
    let image = ndarray::Array3::from_shape_fn((256, 256, 3), |(y, x, c)| match c {
        0 => x as u8,
        1 => (x + y).min(255) as u8,
        2 => y as u8,
        _ => unreachable!(),
    });

    // RGB image
    rec.log(
        "image_rgb",
        &rerun::Image::from_color_model_and_tensor(rerun::ColorModel::RGB, image.clone())?,
    )?;

    // Green channel only (Luminance)
    rec.log(
        "image_green_only",
        &rerun::Image::from_color_model_and_tensor(
            rerun::ColorModel::L,
            image.slice(ndarray::s![.., .., 1]).to_owned(),
        )?,
    )?;

    // BGR image
    rec.log(
        "image_bgr",
        &rerun::Image::from_color_model_and_tensor(
            rerun::ColorModel::BGR,
            image.slice(ndarray::s![.., .., ..;-1]).to_owned(),
        )?,
    )?;

    // New image with Separate Y/U/V planes with 4:2:2 chroma downsampling
    let mut yuv_bytes = Vec::with_capacity(256 * 256 + 128 * 256 * 2);
    yuv_bytes.extend(std::iter::repeat(128).take(256 * 256)); // Fixed value for Y.
    yuv_bytes.extend((0..256).flat_map(|_y| (0..128).map(|x| x * 2))); // Gradient for U.
    yuv_bytes.extend((0..256).flat_map(|y| std::iter::repeat(y as u8).take(128))); // Gradient for V.
    rec.log(
        "image_yuv422",
        &rerun::Image::from_pixel_format(
            [256, 256],
            rerun::PixelFormat::Y_U_V16_FullRange,
            yuv_bytes,
        ),
    )?;

    Ok(())
}

Fields

buffer: ImageBuffer

The raw image data.

format: ImageFormat

The format of the image.

opacity: Option<Opacity>

Opacity of the image, useful for layering several images.

Defaults to 1.0 (fully opaque).

draw_order: Option<DrawOrder>

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

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

Implementations

impl Image

pub const NUM_COMPONENTS: usize = 5usize

The total number of components in the archetype: 2 required, 1 recommended, 2 optional

impl Image

pub fn new( buffer: impl Into<ImageBuffer>, format: impl Into<ImageFormat> ) -> Image

Create a new Image.

pub fn with_opacity(self, opacity: impl Into<Opacity>) -> Image

Opacity of the image, useful for layering several images.

Defaults to 1.0 (fully opaque).

pub fn with_draw_order(self, draw_order: impl Into<DrawOrder>) -> Image

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

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

impl Image

pub fn from_color_model_and_tensor<T>( color_model: ColorModel, data: T ) -> Result<Image, ImageConstructionError<T>>

where T: TryInto<TensorData>, <T as TryInto<TensorData>>::Error: Error,

Try to construct an Image from a color model (L, RGB, RGBA, …) and anything that can be converted into TensorData.

Will return an ImageConstructionError if the shape of the tensor data does not match the given color model.

This is useful for constructing an Image from an ndarray.

See also Self::from_pixel_format.

pub fn from_pixel_format( _: [u32; 2], pixel_format: PixelFormat, bytes: impl Into<ImageBuffer> ) -> Image

Construct an image from a byte buffer given its resolution and pixel format.

See also Self::from_color_model_and_tensor.

pub fn from_color_model_and_bytes( bytes: impl Into<ImageBuffer>, _: [u32; 2], color_model: ColorModel, datatype: ChannelDatatype ) -> Image

Construct an image from a byte buffer given its resolution, color model, and data type.

See also Self::from_color_model_and_tensor.

pub fn from_elements<T>( elements: &[T], _: [u32; 2], color_model: ColorModel ) -> Image

where T: ImageChannelType,

Construct an image from a byte buffer given its resolution, color model, and using the data type of the given vector.

pub fn from_l8(bytes: impl Into<ImageBuffer>, resolution: [u32; 2]) -> Image

From an 8-bit grayscale image.

pub fn from_rgb24(bytes: impl Into<ImageBuffer>, resolution: [u32; 2]) -> Image

Assumes RGB, 8-bit per channel, interleaved as RGBRGBRGB.

pub fn from_rgba32(bytes: impl Into<ImageBuffer>, resolution: [u32; 2]) -> Image

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

pub fn from_file_path(filepath: impl AsRef<Path>) -> Result<EncodedImage, Error>

👎Deprecated: Use EncodedImage::from_file instead

Creates a new Image from a file.

The image format will be inferred from the path (extension), or the contents if that fails.

pub fn from_file_contents( contents: Vec<u8>, _format: Option<ImageFormat> ) -> EncodedImage

👎Deprecated: Use EncodedImage::from_file_contents instead

Creates a new Image from the contents of a file.

If unspecified, the image format will be inferred from the contents.

impl Image

pub fn from_image_bytes( format: ImageFormat, file_contents: &[u8] ) -> Result<Image, ImageLoadError>

Construct a tensor from the contents of an image file.

This will spend CPU cycles decoding the image. To save CPU time and storage, we recommend you instead use EncodedImage::from_file_contents.

Requires the image feature.

pub fn from_image( image: impl Into<DynamicImage> ) -> Result<Image, ImageConversionError>

Construct a tensor from something that can be turned into a image::DynamicImage.

Requires the image feature.

pub fn from_dynamic_image( image: DynamicImage ) -> Result<Image, ImageConversionError>

Construct a tensor from image::DynamicImage.

Requires the image feature.

Trait Implementations

impl Archetype for Image

type Indicator = GenericIndicatorComponent<Image>

The associated indicator component, whose presence indicates that the high-level archetype-based APIs were used to log the data.

fn name() -> ArchetypeName

The fully-qualified name of this archetype, e.g. rerun.archetypes.Points2D.

fn display_name() -> &'static str

Readable name for displaying in ui.

fn indicator() -> MaybeOwnedComponentBatch<'static>

Creates a ComponentBatch out of the associated Self::Indicator component.

fn required_components() -> Cow<'static, [ComponentName]>

Returns the names of all components that must be provided by the user when constructing this archetype.

fn recommended_components() -> Cow<'static, [ComponentName]>

Returns the names of all components that should be provided by the user when constructing this archetype.

fn optional_components() -> Cow<'static, [ComponentName]>

Returns the names of all components that may be provided by the user when constructing this archetype.

fn all_components() -> Cow<'static, [ComponentName]>

Returns the names of all components that must, should and may be provided by the user when constructing this archetype.

fn from_arrow_components( arrow_data: impl IntoIterator<Item = (ComponentName, Box<dyn Array>)> ) -> Result<Image, DeserializationError>

Given an iterator of Arrow arrays and their respective ComponentNames, deserializes them into this archetype.

fn from_arrow( data: impl IntoIterator<Item = (Field, Box<dyn Array>)> ) -> Result<Self, DeserializationError>

where Self: Sized,

Given an iterator of Arrow arrays and their respective field metadata, deserializes them into this archetype.

impl AsComponents for Image

fn as_component_batches(&self) -> Vec<MaybeOwnedComponentBatch<'_>>

Exposes the object’s contents as a set of ComponentBatchs.

fn to_arrow(&self) -> Result<Vec<(Field, Box<dyn Array>)>, SerializationError>

Serializes all non-null Components of this bundle into Arrow arrays.

impl Clone for Image

fn clone(&self) -> Image

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Image

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl PartialEq for Image

fn eq(&self, other: &Image) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl SizeBytes for Image

fn heap_size_bytes(&self) -> u64

Returns the total size of self on the heap, in bytes.

fn is_pod() -> bool

Is Self just plain old data?

fn total_size_bytes(&self) -> u64

Returns the total size of self in bytes, accounting for both stack and heap space.

fn stack_size_bytes(&self) -> u64

Returns the total size of self on the stack, in bytes.

impl ArchetypeReflectionMarker for Image

impl StructuralPartialEq for Image