Class f3d::image

Definition: image.h (line 22)

Class used to represent an image.

A class to represent an image, which can be created from a file, a buffer and provided by a window. It provides tools to save and compare images.

Inner classes

• f3d::image::write_exception
• f3d::image::read_exception
• f3d::image::metadata_exception

Members

• allMetadata
• ChannelType
• compare
• getChannelCount
• getChannelType
• getChannelTypeSize
• getContent
• getHeight
• getMetadata
• getNormalizedPixel
• getSupportedFormats
• getWidth
• image
• image
• image
• image
• image
• Internals
• operator!=
• operator=
• operator=
• operator==
• save
• saveBuffer
• SaveFormat
• setContent
• setMetadata
• toTerminalText
• toTerminalText
• ~image

Constructors

Function image

f3d::image::image()

Default/copy/move constructors/operators.

Return type:

Function ~image

f3d::image::~image()

Default/copy/move constructors/operators.

Return type:

Function image

f3d::image::image(const image &img)

Default/copy/move constructors/operators.

Parameters:

• const image & img

Return type:

Function operator=

image & f3d::image::operator=(const image &img) noexcept

Default/copy/move constructors/operators.

Parameters:

• const image & img

Return type: image &

Function image

f3d::image::image(image &&img) noexcept

Default/copy/move constructors/operators.

Parameters:

• image && img

Return type:

Function operator=

image & f3d::image::operator=(image &&img) noexcept

Default/copy/move constructors/operators.

Parameters:

• image && img

Return type: image &

Operators

Function operator==

bool f3d::image::operator==(const image &reference) const

Comparison operators, uses image::compare with a threshold of 1e-14.

Parameters:

• const image & reference

Return type: bool

Function operator!=

bool f3d::image::operator!=(const image &reference) const

Comparison operators, uses image::compare with a threshold of 1e-14.

Parameters:

• const image & reference

Return type: bool

Resolution

Function getWidth

unsigned int f3d::image::getWidth() const

Set/Get image resolution.

Return type: unsigned int

Function getHeight

unsigned int f3d::image::getHeight() const

Set/Get image resolution.

Return type: unsigned int

Channel Count

Function getChannelCount

unsigned int f3d::image::getChannelCount() const

Set/Get image channel count.

Return type: unsigned int

Buffer Data

Function setContent

image & f3d::image::setContent(void *buffer)

Set/Get image buffer data. Its size is expected to be width * height * channelCount * typeSize.

Parameters:

• void * buffer

Return type: image &

Function getContent

void * f3d::image::getContent() const

Set/Get image buffer data. Its size is expected to be width * height * channelCount * typeSize.

Return type: void *

Public types

Enumeration type SaveFormat

Definition: image.h (line 28)

enum SaveFormat {
  PNG,
  JPG,
  TIF,
  BMP
}

Enumeration of supported export formats

Enumerator PNG

Enumerator JPG

Enumerator TIF

Enumerator BMP

Enumeration type ChannelType

Definition: image.h (line 42)

enum ChannelType {
  BYTE,
  SHORT,
  FLOAT
}

Enumeration of supported channel types

• BYTE: 8-bit integer in range [0,255]

• SHORT: 16-bit integer in range [0,65535]

• FLOAT: 32-bit floating point in range [-inf,+inf]

Enumerator BYTE

Enumerator SHORT

Enumerator FLOAT

Private attributes

Variable Internals

Definition: image.h (line 245)

internals* f3d::image::Internals

Type: internals *

Public functions

Function image

f3d::image::image(const std::filesystem::path &filePath)

Read provided file path (used as is) into a new image instance, the following formats are supported: PNG, PNM, TIFF, BMP, HDR, JPEG, GESigna, MetaImage, TGA. EXR files are also supported if the associated module is built. The complete list can be retrieved at runtime by calling getSupportedFormats().

Throws an image::read_exception in case of failure.

Parameters:

• const std::filesystem::path & filePath

Return type:

Function image

f3d::image::image(unsigned int width, unsigned int height, unsigned int channelCount, ChannelType type=ChannelType::BYTE)

Create an image from a given width, height, and channel count. A channel type can also be given. Default is BYTE.

Parameters:

• unsigned int width
• unsigned int height
• unsigned int channelCount
• ChannelType type = ChannelType::BYTE

Return type:

Function getNormalizedPixel

std::vector< double > f3d::image::getNormalizedPixel(const std::pair< int, int > &xy) const

Read one specific pixel and return all channel normalized values. If the channel type is BYTE or SHORT, the values are normalized to [0, 1] range.

Because of the normalization, this function can be slow, prefer getContent() when reading several pixels and normalization is not needed.

Parameters:

• const std::pair< int, int > & xy

Return type: std::vector< double >

Function getChannelType

ChannelType f3d::image::getChannelType() const

Get image channel type. Throws an image::read_exception if the type is unknown.

Return type: ChannelType

Function getChannelTypeSize

unsigned int f3d::image::getChannelTypeSize() const

Get image channel type size in bytes.

Return type: unsigned int

Function compare

double f3d::image::compare(const image &reference) const

Compare current image to a reference. The error is minimum between Minkownski and Wasserstein distance on a SSIM computation, as specified in VTK. Please note, due to possible arithmetic imprecision in the SSIM computation a non-zero value can be returned with identical images. Depending on the VTK version, another comparison algorithm may be used. Error value meaning is described below:

• 1e-14: Pixel perfect comparison.

• 0.04: Visually indistinguishable.

• 0.1: Small visible difference.

• 0.5: Comparable images.

• 1.0: Different type, size or number of components

Parameters:

• const image & reference

Return type: double

Function save

const image & f3d::image::save(const std::filesystem::path &filePath, SaveFormat format=SaveFormat::PNG) const

Save an image to the provided file path, used as is, in the specified format. Default format is PNG if not specified.

• PNG: Supports channel type BYTE and SHORT with channel count of 1 to 4

• JPG: Supports channel type BYTE with channel count of 1 or 3

• TIF: Supports channel type BYTE, SHORT and FLOAT with channel count of 1 to 4

• BMP: Supports channel type BYTE with channel count of 1 to 4

Throws an image::write_exception if the format is incompatible with with image channel type or channel count or if the image cannot be written for any other reason.

Parameters:

• const std::filesystem::path & filePath
• SaveFormat format = SaveFormat::PNG

Return type: const image &

Function saveBuffer

std::vector< unsigned char > f3d::image::saveBuffer(SaveFormat format=SaveFormat::PNG) const

Save an image to a memory buffer in the specified format and returns it. Default format is PNG if not specified.

• PNG: Supports channel type BYTE and SHORT with channel count of 1 to 4

• JPG: Supports channel type BYTE with channel count of 1 or 3

• BMP: Supports channel type BYTE with channel count of 1 to 4

• TIF format is not supported yet.

Throws an image::write_exception if the type is TIF or if the format is incompatible with with image channel type or channel count.

Parameters:

• SaveFormat format = SaveFormat::PNG

Return type: std::vector< unsigned char >

Function toTerminalText

const image & f3d::image::toTerminalText(std::ostream &stream) const

Convert to colored text using ANSI escape sequences for printing in a terminal. Block and half-block characters are used to represent two pixels per character (vertically) meaning that each text line represent two rows of pixels. Byte encoded RGB and RGBA images are supported (alpha channel values are binarized). Assumes terminal support for:

• unicode block characters (U+2580, U+2584, U+2588)

• SGR escape codes (ESC[0m, ESC[49m)

• 24-bit escape codes (ESC[38;2;{r};{g};{b}m, ESC[48;2;{r};{g};{b}m)

Throws a image::write_exception if the type is not byte RGB or RGBA.

Parameters:

• std::ostream & stream

Return type: const image &

Function toTerminalText

std::string f3d::image::toTerminalText() const

Convert to colored text using ANSI escape sequences for printing in a terminal. See toTerminalText(std::ostream& stream).

Throws a image::write_exception if the type is not byte RGB or RGBA.

Return type: std::string

Function setMetadata

f3d::image & f3d::image::setMetadata(std::string key, std::string value)

Set the value for a metadata key. Setting an empty value ("") removes the key.

Parameters:

• std::string key
• std::string value

Return type: f3d::image &

Function getMetadata

std::string f3d::image::getMetadata(const std::string &key) const

Get the value for a metadata key. Throws a image::read_exception if key does not exist.

Parameters:

• const std::string & key

Return type: std::string

Function allMetadata

std::vector< std::string > f3d::image::allMetadata() const

List all the metadata keys which have a value set.

Return type: std::vector< std::string >

Public static functions

Function getSupportedFormats

static std::vector< std::string > f3d::image::getSupportedFormats()

Get the list of supported image format extensions when opening a file.

Return type: std::vector< std::string >