Class image#

Nested Relationships#

Nested Types#

Class Documentation#

class image#

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.

Constructors

image()#

Default/copy/move constructors/operators.

~image()#

Default/copy/move constructors/operators.

image(const image &img)#

Default/copy/move constructors/operators.

image &operator=(const image &img) noexcept#

Default/copy/move constructors/operators.

image(image &&img) noexcept#

Default/copy/move constructors/operators.

image &operator=(image &&img) noexcept#

Default/copy/move constructors/operators.

Operators

bool operator==(const image &reference) const#

Comparison operators, uses image::compare with a threshold of 0.

bool operator!=(const image &reference) const#

Comparison operators, uses image::compare with a threshold of 0.

Resolution

unsigned int getWidth() const#

Set/Get image resolution.

Deprecated:

{ setResolution is deprecated, use the appropriate constructor }

unsigned int getHeight() const#

Set/Get image resolution.

Deprecated:

{ setResolution is deprecated, use the appropriate constructor }

F3D_DEPRECATED image & setResolution (unsigned int width, unsigned int height)

Set/Get image resolution.

Deprecated:

{ setResolution is deprecated, use the appropriate constructor }

Channel Count

unsigned int getChannelCount() const#

Set/Get image channel count.

Deprecated:

{ setChannelCount is deprecated, use the appropriate constructor }

F3D_DEPRECATED image & setChannelCount (unsigned int dim)

Set/Get image channel count.

Deprecated:

{ setChannelCount is deprecated, use the appropriate constructor }

Buffer Data

image &setContent(void *buffer)#

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

Deprecated:

{ setData and getData are deprecated, use setContent and getContent instead }

void *getContent() const#

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

Deprecated:

{ setData and getData are deprecated, use setContent and getContent instead }

F3D_DEPRECATED image & setData (unsigned char *buffer)

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

Deprecated:

{ setData and getData are deprecated, use setContent and getContent instead }

F3D_DEPRECATED unsigned char * getData () const

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

Deprecated:

{ setData and getData are deprecated, use setContent and getContent instead }

Public Types

enum class SaveFormat : unsigned char#

Enumeration of supported export formats#

PNG: Supports channel size up to 2 bytes JPG: Supports channel size of 1 byte TIF: Supports channel size up to 4 bytes BMP: Supports channel size of 1 byte

Values:

enumerator PNG#
enumerator JPG#
enumerator TIF#
enumerator BMP#
enum class ChannelType : unsigned char#

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]

Values:

enumerator BYTE#
enumerator SHORT#
enumerator FLOAT#

Public Functions

explicit image(const std::string &path)#

Create an image from file, 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 retrieve at runtime by calling getSupportedFormats. Throw an image::read_exception in case of failure.

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.

std::vector<double> 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.

Warning

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

ChannelType getChannelType() const#

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

unsigned int getChannelTypeSize() const#

Get image channel type size in bytes.

bool compare(const image &reference, double threshold, image &diff, double &error) const#

Compare current image to a reference using the provided threshold. If the comparison fails, ie. error is higher than the threshold, this outputs the resulting diff and error and return false, return true otherwise. The error is based on the pixel value and accumulated over neighbors pixels. 0: Pixel perfect comparison. 50: Visually indistinguishable. 100: Small visible difference. 300: Comparable images.

void save(const std::string &path, SaveFormat format = SaveFormat::PNG) const#

Save an image to a file in the specified format. Default format is PNG if not specified.

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

Save an image to a memory buffer in the specified format. Default format is PNG if not specified. TIF format is not supported yet. Throw an image::write_exception if the type is TIF.

const 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) Throw an exception if the type is not byte RGB or RGBA.

std::string toTerminalText() const#

Convert to colored text using ANSI escape sequences for printing in a terminal. See toTerminalText(std::ostream& stream). Throw an exception if the type is not byte RGB or RGBA.

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

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

std::string getMetadata(const std::string &key) const#

Get the value for a metadata key. Throw std::invalid_argument exception if key does not exist.

std::vector<std::string> allMetadata() const#

List all the metadata keys which have a value set.

Public Static Functions

static std::vector<std::string> getSupportedFormats()#

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

struct read_exception : public f3d::exception#

An exception that can be thrown by the image. when there is an error on read.

Public Functions

explicit read_exception(const std::string &what = "")#
struct write_exception : public f3d::exception#

An exception that can be thrown by the image when there. is an error on write.

Public Functions

explicit write_exception(const std::string &what = "")#