Detailed Description

Utility functions for reading and writing images, from/to either files or memory buffers.

The only file formats supported are JPEG, PNG, and TIFF.

The only format that supports floating-point scalars (e.g., ImageDepth32F) is TIFF. Trying to load or save a floating-point image from/to a PNG or JPEG file will throw an exception.

#include <drake/systems/sensors/image_io.h>

Classes
struct	ByteSpan
	When loading from memory, this struct denotes a span of raw bytes as input. More...

struct	Metadata
	Some characteristics of an image file. More...

Public Member Functions
	ImageIo ()=default
	Default constructor. More...

std::optional< Metadata >	LoadMetadata (const std::filesystem::path &path) const
	Returns the metadata of the given image file, or nullopt if the metadata cannot be determined or is unsupported. More...

std::optional< Metadata >	LoadMetadata (ByteSpan buffer) const
	Returns the metadata of the given image buffer, or nullopt if the metadata cannot be determined or is unsupported. More...

ImageAny	Load (const std::filesystem::path &path, std::optional< ImageFileFormat > format=std::nullopt) const
	Loads and returns an image from disk. More...

ImageAny	Load (ByteSpan buffer, std::optional< ImageFileFormat > format=std::nullopt) const
	Loads and returns an image from a memory buffer. More...

template<PixelType kPixelType>
void	Load (const std::filesystem::path &path, Image< kPixelType > *image) const
	Loads and outputs an image from disk. More...

template<PixelType kPixelType>
void	Load (const std::filesystem::path &path, ImageFileFormat format, Image< kPixelType > *image) const
	Loads and outputs an image from disk. More...

template<PixelType kPixelType>
void	Load (ByteSpan buffer, Image< kPixelType > *image) const
	Loads and outputs an image from a memory buffer. More...

template<PixelType kPixelType>
void	Load (ByteSpan buffer, ImageFileFormat format, Image< kPixelType > *image) const
	Loads and outputs an image from a memory buffer. More...

template<PixelType kPixelType>
void	Save (const Image< kPixelType > &image, const std::filesystem::path &path, std::optional< ImageFileFormat > format=std::nullopt) const
	Saves an image to disk. More...

template<PixelType kPixelType>
std::vector< uint8_t >	Save (const Image< kPixelType > &image, ImageFileFormat format) const
	Saves an image to a new memory buffer, returning the buffer. More...

template<PixelType kPixelType>
void	Save (const Image< kPixelType > &image, ImageFileFormat format, std::vector< uint8_t > *buffer) const
	Saves an image to an existing memory buffer. More...

Does not allow copy, move, or assignment
	ImageIo (const ImageIo &)=delete

ImageIo &	operator= (const ImageIo &)=delete

	ImageIo (ImageIo &&)=delete

ImageIo &	operator= (ImageIo &&)=delete

Constructor & Destructor Documentation

◆ ImageIo() [1/3]

ImageIo ( const ImageIo & )

delete

◆ ImageIo() [2/3]

ImageIo ( ImageIo && )

delete

◆ ImageIo() [3/3]

ImageIo ( )

default

Default constructor.

Member Function Documentation

◆ Load() [1/6]

ImageAny Load	(	const std::filesystem::path &	path,
		std::optional< ImageFileFormat >	format = `std::nullopt`
	)		const

Loads and returns an image from disk.

Parameters

format (Optionally) establishes the required image file format. When set, images that are a different file format will throw an exception. When not set, the filename extension has no bearing on the result; only the actual file contents determine the file format.

Exceptions

std::exception for any kind of error loading the image file.

◆ Load() [2/6]

ImageAny Load	(	ByteSpan	buffer,
		std::optional< ImageFileFormat >	format = `std::nullopt`
	)		const

Loads and returns an image from a memory buffer.

Parameters

format (Optionally) establishes the required image file format. When set, images that are a different file format will throw an exception.

Exceptions

std::exception for any kind of error loading the image data.

◆ Load() [3/6]

void Load	(	const std::filesystem::path &	path,
		Image< kPixelType > *	image
	)		const

Loads and outputs an image from disk.

The filename extension has no bearing on the result; only the actual file contents determine the file format.

Parameters

[out] image The output image (which will be overwritten).

Exceptions

std::exception	for any kind of error loading the image file.
std::exception	if the loaded image does not match the kPixelType.

◆ Load() [4/6]

void Load	(	const std::filesystem::path &	path,
		ImageFileFormat	format,
		Image< kPixelType > *	image
	)		const

Loads and outputs an image from disk.

Parameters

	format	Establishes the required image file format; images that are a different file format will throw an exception.
[out]	image	The output image (which will be overwritten).

Exceptions

std::exception	for any kind of error loading the image file.
std::exception	if the loaded image does not match the kPixelType.

◆ Load() [5/6]

void Load	(	ByteSpan	buffer,
		Image< kPixelType > *	image
	)		const

Loads and outputs an image from a memory buffer.

Parameters

[out] image The output image (which will be overwritten).

Exceptions

std::exception	for any kind of error loading the image data.
std::exception	if the loaded image does not match the kPixelType.

◆ Load() [6/6]

void Load	(	ByteSpan	buffer,
		ImageFileFormat	format,
		Image< kPixelType > *	image
	)		const

Loads and outputs an image from a memory buffer.

Parameters

	format	Establishes the required image file format; images that are a different file format will throw an exception.
[out]	image	The output image (which will be overwritten).

Exceptions

std::exception	for any kind of error loading the image data.
std::exception	if the loaded image does not match the kPixelType.

◆ LoadMetadata() [1/2]

std::optional<Metadata> LoadMetadata ( const std::filesystem::path & path ) const

Returns the metadata of the given image file, or nullopt if the metadata cannot be determined or is unsupported.

The filename extension has no bearing on the result; only the actual file contents determine the file format.

◆ LoadMetadata() [2/2]

std::optional<Metadata> LoadMetadata ( ByteSpan buffer ) const

Returns the metadata of the given image buffer, or nullopt if the metadata cannot be determined or is unsupported.

◆ operator=() [1/2]

ImageIo& operator= ( ImageIo && )

delete

◆ operator=() [2/2]

ImageIo& operator= ( const ImageIo & )

delete

◆ Save() [1/3]

void Save	(	const Image< kPixelType > &	image,
		const std::filesystem::path &	path,
		std::optional< ImageFileFormat >	format = `std::nullopt`
	)		const

Saves an image to disk.

Parameters

format (Optionally) chooses the image file format. When not set, the filename extension will determine the format and the extension must be a supported choice (i.e., .jpg, .jpeg, .png, .tif, or .tiff).

Exceptions

std::exception for any kind of error saving the image file.

◆ Save() [2/3]

std::vector<uint8_t> Save	(	const Image< kPixelType > &	image,
		ImageFileFormat	format
	)		const

Saves an image to a new memory buffer, returning the buffer.

Exceptions

std::exception for any kind of error saving the image data.

◆ Save() [3/3]

void Save	(	const Image< kPixelType > &	image,
		ImageFileFormat	format,
		std::vector< uint8_t > *	buffer
	)		const

Saves an image to an existing memory buffer.

Parameters

[out] buffer The output buffer (which will be overwritten).

Exceptions

std::exception for any kind of error saving the image data.

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

drake/systems/sensors/image_io.h

Detailed Description

Classes

Public Member Functions

Constructor & Destructor Documentation

◆ ImageIo() [1/3]

◆ ImageIo() [2/3]

◆ ImageIo() [3/3]

Member Function Documentation

◆ Load() [1/6]

◆ Load() [2/6]

◆ Load() [3/6]

◆ Load() [4/6]

◆ Load() [5/6]

◆ Load() [6/6]

◆ LoadMetadata() [1/2]

◆ LoadMetadata() [2/2]

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ Save() [1/3]

◆ Save() [2/3]

◆ Save() [3/3]