An image data point value. More...

#include <xentara/data/Image.hpp>

Public Member Functions
	Image ()
	Constructor that creates an empty monochrome image.

template<std::ranges::contiguous_range Data> requires PixelCppType<std::remove_cv_t<std::ranges::range_value_t<Data>>>
	Image (const Data &data, std::size_t width, std::size_t height, ColorSpace colorSpace, ColorDepth colorDepth=defaultColorDepth< std::ranges::range_value_t< Data > >())
	Constructor that sets the image data.

template<std::contiguous_iterator Iterator, std::sized_sentinel_for< Iterator > Sentinel> requires PixelCppType<std::remove_cv_t<std::iter_value_t<Iterator>>>
	Image (Iterator first, Sentinel last, std::size_t width, std::size_t height, ColorSpace colorSpace, ColorDepth colorDepth=defaultColorDepth< std::iter_value_t< Iterator > >())
	Constructor that sets the image data using an iterator/sentinel pair.

auto	width () const noexcept -> std::size_t
	Gets the width of the image.

auto	height () const noexcept -> std::size_t
	Gets the height of the image.

auto	empty () const noexcept -> bool
	Checks whether the image is empty and contains no pixels.

auto	colorSpace () const noexcept -> ColorSpace
	Gets the colour space used by the image.

auto	colorDepth () const noexcept -> ColorDepth
	Gets the colour depth of the image.

auto	channelCount () const noexcept -> std::size_t
	Gets the number of channels in the image.

auto	pixelType () const noexcept -> PixelType
	Gets C++ type used for the individual pixels, as determined by the colour depth.

auto	combinedPlaneHeight () const noexcept -> std::size_t
	Gets the height of the image, plus any extra height to store necessary additional planes.

auto	data () const -> std::variant< std::span< const std::uint8_t >, std::span< const std::uint16_t >, std::span< const std::int8_t >, std::span< const std::int16_t >, std::span< const float >, std::span< const double > >
	Gets the image data as a variant.

template<PixelCppType PixelType>
auto	data () const -> std::span< const PixelType >
	Gets the image data if the C++ type is already known.

template<std::same_as< std::byte > >
auto	data () const -> std::span< const std::byte >
	Gets the image data as raw bytes.

template<utils::tools::CharType Char, typename CharTraits = std::char_traits<Char>>
auto	toBasicString () const -> std::basic_string< Char, CharTraits >
	Converts the image info to a string.

auto	toString () const -> std::string
	Converts the image info to a string of type char.

auto	toWString () const -> std::wstring
	Converts the image info to a string of type wchar_t.

auto	toU8String () const -> std::u8string
	Converts the image info to a string of type char8_t.

auto	toU16String () const -> std::u16string
	Converts the image info to a string of type char16_t.

auto	toU32String () const -> std::u32string
	Converts the image info to a string of type char32_t.

Static Public Member Functions
template<PixelCppType PixelType>
static auto	makeForOverwrite (std::size_t width, std::size_t height, ColorSpace colorSpace, ColorDepth colorDepth=defaultColorDepth< PixelType >()) -> std::pair< Image, std::span< PixelType > >
	Creates an image with uninitialized pixel data.

template<std::same_as< std::byte > >
static auto	makeForOverwrite (std::size_t width, std::size_t height, ColorSpace colorSpace, ColorDepth colorDepth) -> std::pair< Image, std::span< std::byte > >
	Creates an image with uninitialized pixel data, returning the data as raw bytes.

template<typename PixelType > requires PixelCppType<std::remove_cv_t<PixelType>>
static constexpr auto	defaultColorDepth () -> ColorDepth
	Gets the default color depth used for a certain CPP type.

OpenCV interoperability
Note Types and functions in this section are only available if the OpenCV header <opencv2/core.hpp> is available. This generally requires you to link against OpenCV, or put the OpenCV include directory into your include path.
enum class	OpenCvColorSpace { COLOR_BGR , COLOR_RGB , COLOR_BGRA , COLOR_RGBA , COLOR_GRAY , internal }
	Supported target colour spaces for conversion to OpenCV types. More...

auto	cvMat () const noexcept -> cv::Mat
	Gets the data as an OpenCV matrix.

auto	copyTo (cv::OutputArray data) const noexcept -> void
	Copies the data to an OpenCV matrix, or another type of OpenCV output array.

auto	cvSize () const noexcept -> cv::Size
	Gets the OpenCV size code of the image data.

auto	cvDepth () const noexcept -> int
	Gets the OpenCV depth code of the image data.

auto	cvType () const noexcept -> int
	Gets the OpenCV matrix type code of the image data.

auto	cvChannels () const noexcept -> int
	Gets the OpenCV channel count.

auto	cvColorConversionCode (OpenCvColorSpace targetColorSpace) const -> std::optional< int >
	Gets a color conversion code for use with cv::cvtColor().

template<std::same_as< cv::Mat > >
static auto	makeForOverwrite (std::size_t width, std::size_t height, ColorSpace colorSpace, ColorDepth colorDepth) -> std::pair< Image, cv::Mat >
	Creates an image with uninitialized pixel data, returning the data as a cv::Mat.

Detailed Description

An image data point value.

This class uses sharing for the actual image data, similar to std::shared_ptr. If you make a copy of an image object, the copy will share the image data with the original. This means that images can be copied in constant time, irrespective of their size.

Member Enumeration Documentation

◆ OpenCvColorSpace

enum class xentara::data::Image::OpenCvColorSpace

strong

Supported target colour spaces for conversion to OpenCV types.

Note: The Image class contains a using enum OpenCvColorSpace directive. This allows you to rever to these enum values by their unqualified names. You can write xentara::data::Image::COLOR_BGR instead of xentara::xentara::data::Image::OpenCvColorSpace::COLOR_BGR, for example.; This type is only available if the OpenCV header <opencv2/core.hpp> is available. This generally requires you to link against OpenCV, or put the OpenCV include directory into your include path.

Enumerator
COLOR_BGR	BGR (blue, green, red) image.
COLOR_RGB	RGB (red, green, blue) image.
COLOR_BGRA	BGR (blue, green, red) image with alpha channel.
COLOR_RGBA	RGB (red, green, blue) image with alpha channel.
COLOR_GRAY	Monochrome image.

Constructor & Destructor Documentation

◆ Image() [1/3]

xentara::data::Image::Image ( )

Constructor that creates an empty monochrome image.

This constructor creates a BRG image with a size of 0 × 0 pixels.

◆ Image() [2/3]

template<std::ranges::contiguous_range Data>
requires PixelCppType<std::remove_cv_t<std::ranges::range_value_t<Data>>>

xentara::data::Image::Image	(	const Data &	data,
		std::size_t	width,
		std::size_t	height,
		ColorSpace	colorSpace,
		ColorDepth	colorDepth = `defaultColorDepth<std::ranges::range_value_t<Data>>()`
	)

Constructor that sets the image data.

Parameters

data	The image data. This must be a range of pixels, like std::vector<PixelType>, std::array<PixelType>, or std::span<const PixelType>. The data type and size of the data must match the specified width, height, and colour settings.
width	The the width of the image.
height	The the height of the image.
colorSpace	The the colour space used by the image.
colorDepth	The the colour depth of the image.

Exceptions

std::invalid_argument data has the wrong element data type or wrong size for the specified width, height, and colour settings.

◆ Image() [3/3]

template<std::contiguous_iterator Iterator, std::sized_sentinel_for< Iterator > Sentinel>
requires PixelCppType<std::remove_cv_t<std::iter_value_t<Iterator>>>

xentara::data::Image::Image	(	Iterator	first,
		Sentinel	last,
		std::size_t	width,
		std::size_t	height,
		ColorSpace	colorSpace,
		ColorDepth	colorDepth = `defaultColorDepth<std::iter_value_t<Iterator>>()`
	)

Constructor that sets the image data using an iterator/sentinel pair.

Parameters

first	The beginning of the image data. The data type of the data must match the specified colour depth.
last	The sntinel object for the image data. The distance between first and last, must match the specified width, height, and colour space.
width	The the width of the image.
height	The the height of the image.
colorSpace	The the colour space used by the image.
colorDepth	The the colour depth of the image.

Exceptions

std::invalid_argument data has the wrong element data type or wrong size for the specified width, height, and colour settings.

Member Function Documentation

◆ channelCount()

auto xentara::data::Image::channelCount ( ) const -> std::size_t

noexcept

Gets the number of channels in the image.

Returns: The number of channels in the image’s color space

◆ colorDepth()

auto xentara::data::Image::colorDepth ( ) const -> ColorDepth

noexcept

Gets the colour depth of the image.

◆ colorSpace()

auto xentara::data::Image::colorSpace ( ) const -> ColorSpace

noexcept

Gets the colour space used by the image.

◆ combinedPlaneHeight()

auto xentara::data::Image::combinedPlaneHeight ( ) const -> std::size_t

noexcept

Gets the height of the image, plus any extra height to store necessary additional planes.

Gets the height of the image data. For most color spaces this is the same as the image height, but for Y′UV 4:2:0 images, the data height includes space of the extra half-plane used to store the U/V data.

See also: height()

◆ copyTo()

auto xentara::data::Image::copyTo ( cv::OutputArray data ) const -> void

noexcept

Copies the data to an OpenCV matrix, or another type of OpenCV output array.

Note: This function is only available if the OpenCV header <opencv2/core.hpp> is available. This generally requires you to link against OpenCV, or put the OpenCV include directory into your include path.

◆ cvChannels()

auto xentara::data::Image::cvChannels ( ) const -> int

noexcept

Gets the OpenCV channel count.

Note: This function is only available if the OpenCV header <opencv2/core.hpp> is available. This generally requires you to link against OpenCV, or put the OpenCV include directory into your include path.

Returns: The OpenCV channel count. This is the same as channelCount(), bit is of type int instead of std::size_t.

◆ cvColorConversionCode()

auto xentara::data::Image::cvColorConversionCode ( OpenCvColorSpace targetColorSpace ) const -> std::optional< int >

Gets a color conversion code for use with cv::cvtColor().

Note: This function is only available if the OpenCV header <opencv2/core.hpp> is available. This generally requires you to link against OpenCV, or put the OpenCV include directory into your include path.

Parameters

targetColorSpace The color space to convert to.

Returns: The correct code to pass to cv::cvtColor() to convert the image data to the desired format. If the image is already in the desired format, std::nullopt is returned.

Exceptions

std::runtime_error The conversion is not supported by OpenCV

◆ cvDepth()

auto xentara::data::Image::cvDepth ( ) const -> int

noexcept

Gets the OpenCV depth code of the image data.

Note: This function is only available if the OpenCV header <opencv2/core.hpp> is available. This generally requires you to link against OpenCV, or put the OpenCV include directory into your include path.

Returns: The depth code. This is an OpenCV type value like CV_8U or CV_16U, as also returned by cv::Mat::depth()

◆ cvMat()

auto xentara::data::Image::cvMat ( ) const -> cv::Mat

noexcept

Gets the data as an OpenCV matrix.

Attention: Do not modify the contents of the matrix, as that will destroy the original image. If you need a modifyable copy of the data, use copyTo() to get a private copy.

Note: This function is only available if the OpenCV header <opencv2/core.hpp> is available. This generally requires you to link against OpenCV, or put the OpenCV include directory into your

Returns: The data as a cv::Mat. The returned object only references the image data, so it will only be valid as long as this image object is valid.

◆ cvSize()

auto xentara::data::Image::cvSize ( ) const -> cv::Size

noexcept

Gets the OpenCV size code of the image data.

Note: This function is only available if the OpenCV header <opencv2/core.hpp> is available. This generally requires you to link against OpenCV, or put the OpenCV include directory into your include path.

Returns: The size of the OpenCV matrix required to hold the pixel data. The retured size is width() by combinedPlaneHeight().

◆ cvType()

auto xentara::data::Image::cvType ( ) const -> int

noexcept

Gets the OpenCV matrix type code of the image data.

Note: This function is only available if the OpenCV header <opencv2/core.hpp> is available. This generally requires you to link against OpenCV, or put the OpenCV include directory into your include path.

Returns: The matrix type code. This is an OpenCV type value like CV_8UC3 or CV_16UC1, as also returned by cv::Mat::type()

◆ data() [1/3]

template<PixelCppType PixelType>

auto xentara::data::Image::data ( ) const -> std::span< const PixelType >

Gets the image data if the C++ type is already known.

Returns: The image data

Exceptions

std::invalid_argument The data is not of type PixelType.

◆ data() [2/3]

template<std::same_as< std::byte > >

auto xentara::data::Image::data ( ) const -> std::span< const std::byte >

Gets the image data as raw bytes.

Calling this function is equivalent to calling data<PixelCppType PixelType>(), and passing the result through std::as_bytes().

Returns: The image data as a span of raw bytes.

◆ data() [3/3]

auto xentara::data::Image::data ( ) const -> std::variant< std::span< const std::uint8_t >, std::span< const std::uint16_t >, std::span< const std::int8_t >, std::span< const std::int16_t >, std::span< const float >, std::span< const double > >

Gets the image data as a variant.

Returns: The image data.

◆ defaultColorDepth()

template<typename PixelType >
requires PixelCppType<std::remove_cv_t<PixelType>>

constexpr auto xentara::data::Image::defaultColorDepth ( ) -> ColorDepth

staticconstexpr

Gets the default color depth used for a certain CPP type.

This function retrurns the following types:

Pixel Type	Colour Depth
std::uint8_t	PixelType::Unsigned8Bit
std::uint16_t	PixelType::Unsigned16Bit
std::int8_t	PixelType::Signed8Bit
std::int16_t	PixelType::Signed16Bit
float	PixelType::Float
double	PixelType::Double

Template Parameters

PixelType The C++ type used for the pixels. cv-qualifiers are ignored, so const std::uint8_t is treated the same as std::uint8_t

Returns: The default colour depth used.

◆ empty()

auto xentara::data::Image::empty ( ) const -> bool

noexcept

Checks whether the image is empty and contains no pixels.

Returns: Returns true if the width, the height, or both are zero.

◆ height()

auto xentara::data::Image::height ( ) const -> std::size_t

noexcept

Gets the height of the image.

See also: combinedPlaneHeight()

◆ makeForOverwrite() [1/3]

template<std::same_as< cv::Mat > >

static auto xentara::data::Image::makeForOverwrite	(	std::size_t	width,
		std::size_t	height,
		ColorSpace	colorSpace,
		ColorDepth	colorDepth
	)		-> std::pair< Image, cv::Mat >

static

Creates an image with uninitialized pixel data, returning the data as a cv::Mat.

Calling this function is equivalent to calling makeForOverwriteWithRawBytes<PixelCppType PixelType>(), and creating a cv::Mat object referencing the returned data span.

Parameters

width	The the width of the image.
height	The the height of the image.
colorSpace	The the colour space used by the image.
colorDepth	The the colour depth of the image.

Returns: Returns the image, together with a reference to the pixel data. The pixel data will be uninitialized memory and needs to be initialized by the caller.

Exceptions

std::invalid_argument PixelType does not match the specified colour depth.

◆ makeForOverwrite() [2/3]

template<std::same_as< std::byte > >

static auto xentara::data::Image::makeForOverwrite	(	std::size_t	width,
		std::size_t	height,
		ColorSpace	colorSpace,
		ColorDepth	colorDepth
	)		-> std::pair< Image, std::span< std::byte > >

static

Creates an image with uninitialized pixel data, returning the data as raw bytes.

Calling this function is equivalent to calling makeForOverwriteWithRawBytes<PixelCppType PixelType>(), and passing the resulting data span through std::as_writable_bytes().

Parameters

width	The the width of the image.
height	The the height of the image.
colorSpace	The the colour space used by the image.
colorDepth	The the colour depth of the image.

Returns: Returns the image, together with a reference to the pixel data. The pixel data will be uninitialized memory and needs to be initialized by the caller.

Exceptions

std::invalid_argument PixelType does not match the specified colour depth.

◆ makeForOverwrite() [3/3]

template<PixelCppType PixelType>

static auto xentara::data::Image::makeForOverwrite	(	std::size_t	width,
		std::size_t	height,
		ColorSpace	colorSpace,
		ColorDepth	colorDepth = `defaultColorDepth< PixelType >()`
	)		-> std::pair< Image, std::span< PixelType > >

static

Creates an image with uninitialized pixel data.

Template Parameters

PixelType The C++ type to be used for storing the pixels.

Parameters

width	The the width of the image.
height	The the height of the image.
colorSpace	The the colour space used by the image.
colorDepth	The the colour depth of the image.

Returns: Returns the image, together with a reference to the pixel data. The pixel data will be uninitialized memory and needs to be initialized by the caller.

Exceptions

std::invalid_argument PixelType does not match the specified colour depth.

◆ pixelType()

auto xentara::data::Image::pixelType ( ) const -> PixelType

noexcept

Gets C++ type used for the individual pixels, as determined by the colour depth.

Returns: The data type of the indiovidual pixels, as determined by the colour depth

◆ toBasicString()

template<utils::tools::CharType Char, typename CharTraits >

auto xentara::data::Image::toBasicString ( ) const -> std::basic_string<Char, CharTraits>

Converts the image info to a string.

◆ toString()

auto xentara::data::Image::toString ( ) const -> std::string

Converts the image info to a string of type char.

◆ toU16String()

auto xentara::data::Image::toU16String ( ) const -> std::u16string

Converts the image info to a string of type char16_t.

◆ toU32String()

auto xentara::data::Image::toU32String ( ) const -> std::u32string

Converts the image info to a string of type char32_t.

◆ toU8String()

auto xentara::data::Image::toU8String ( ) const -> std::u8string

Converts the image info to a string of type char8_t.

◆ toWString()

auto xentara::data::Image::toWString ( ) const -> std::wstring

Converts the image info to a string of type wchar_t.

◆ width()

auto xentara::data::Image::width ( ) const -> std::size_t

noexcept

Gets the width of the image.

Public Member Functions

Static Public Member Functions

OpenCV interoperability

Detailed Description

Member Enumeration Documentation

◆ OpenCvColorSpace

Constructor & Destructor Documentation

◆ Image() [1/3]

◆ Image() [2/3]

◆ Image() [3/3]

Member Function Documentation

◆ channelCount()

◆ colorDepth()

◆ colorSpace()

◆ combinedPlaneHeight()

◆ copyTo()

◆ cvChannels()

◆ cvColorConversionCode()

◆ cvDepth()

◆ cvMat()

◆ cvSize()

◆ cvType()

◆ data() [1/3]

◆ data() [2/3]

◆ data() [3/3]

◆ defaultColorDepth()

◆ empty()

◆ height()

◆ makeForOverwrite() [1/3]

◆ makeForOverwrite() [2/3]

◆ makeForOverwrite() [3/3]

◆ pixelType()

◆ toBasicString()

◆ toString()

◆ toU16String()

◆ toU32String()

◆ toU8String()

◆ toWString()

◆ width()