Stores the pixel format, width and height of an image and the pointer to the image buffer. More...

#include <peak_ipl/types/peak_ipl_image.hpp>

Public Member Functions
	Image ()
	Creates an empty image. In other words, size is 0x0 and an invalid pixel format.

	Image (const peak::ipl::PixelFormat &pixelFormat, size_t width, size_t height)
	Creates an image with the given pixel format and size.

	Image (const peak::ipl::PixelFormat &pixelFormat, uint8_t *buffer, size_t bufferSize, size_t width, size_t height)
	Creates an image with the given pixel format and size from the given buffer.

	Image (const peak::ipl::PixelFormat &pixelFormat, size_t width, size_t height, uint64_t timestamp_ns)
	Creates an image with the given pixel format, size and timestamp.

	Image (const peak::ipl::PixelFormat &pixelFormat, uint8_t *buffer, size_t bufferSize, size_t width, size_t height, uint64_t timestamp_ns)
	Creates an image with the given pixel format, size and timestamp from the given buffer.

	~Image ()
	Destructor for the Image instance.

	Image (const Image &other)
	Copy Constructor for a new Image instance.

Image &	operator= (const Image &other)
	Copy assigment for Image instance.

	Image (Image &&other) noexcept
	Move constructor for Image instance.

Image &	operator= (Image &&other) noexcept
	Move assignment for Image instance.

size_t	Width () const
	Returns the width.

size_t	Height () const
	Returns the height.

peak::ipl::Size2D	Size () const
	Returns the Size.

uint8_t *	PixelPointer (size_t xPos, size_t yPos) const
	Returns the pixel pointer to the given pixel position in relation to the size of the pixel format.

template<typename T , typename = std::enable_if_t<std::is_arithmetic<T>::value>>
T *	PixelPointer (size_t xPos, size_t yPos) const
	Returns the pixel pointer to the given pixel position in relation to the size of the pixel format.

size_t	ByteCount () const
	Returns the size of the given image in number of bytes.

peak::ipl::PixelFormat	PixelFormat () const
	Returns the pixel format.

uint8_t *	Data () const
	Returns the pointer to the first pixel position in dependency on the size of the pixel format.

template<typename T , typename = std::enable_if_t<std::is_arithmetic<T>::value>>
T *	Data () const
	Returns the pointer to the first pixel position in dependency on the size of the pixel format.

Image	ConvertTo (const peak::ipl::PixelFormat &outputPixelFormat, peak::ipl::ConversionMode conversionMode=peak::ipl::ConversionMode::Fast) const
	Returns a new created image containing the data of the current image converted to the given pixel format.

Image	ConvertTo (const peak::ipl::PixelFormat &outputPixelFormat, uint8_t *outputImageBuffer, size_t outputImageBufferSize, peak::ipl::ConversionMode conversionMode=peak::ipl::ConversionMode::Fast) const
	Saves the data of the current image converted to the given pixel format into a destination buffer and creates an image from that buffer.

Image	ConvertToWithFactor (const peak::ipl::PixelFormat &outputPixelFormat, double factor, peak::ipl::ConversionMode conversionMode=peak::ipl::ConversionMode::Fast) const
	Returns a new created image containing the data of the current image converted to the given pixel format with the factor multiplied to each output pixel.

template<typename Integer1 , typename Integer2 , typename std::enable_if_t< std::is_integral< Integer1 >::value, int > = 0, typename std::enable_if_t< std::is_integral< Integer2 >::value, int > = 0>
Image	Scale (Integer1 width, Integer2 height, peak::ipl::InterpolationAlgorithm algorithm=InterpolationAlgorithm::linear) const
	Scale the image to the supplied width and height using the supplied `algorithm`.

Image	Scale (const peak::ipl::Size2D &size, peak::ipl::InterpolationAlgorithm algorithm=InterpolationAlgorithm::linear) const
	Scale the image to the supplied width and height using the supplied `algorithm`.

Image	Scale (const peak::ipl::ScaleFactor &factor, peak::ipl::InterpolationAlgorithm algorithm=InterpolationAlgorithm::linear) const
	Scale the image to the supplied scale factors `factor` using the supplied `algorithm`.

template<typename FloatingPoint1 , typename FloatingPoint2 , typename std::enable_if_t< std::is_floating_point< FloatingPoint1 >::value, int > = 0, typename std::enable_if_t< std::is_floating_point< FloatingPoint2 >::value, int > = 0>
Image	Scale (FloatingPoint1 scaleFactorX, FloatingPoint2 scaleFactorY, peak::ipl::InterpolationAlgorithm algorithm=InterpolationAlgorithm::linear) const
	Scale the image to the supplied scale factors `scaleFactorX` and `scaleFactorY` using the supplied `algorithm`.

void	ScaleInto (const peak::ipl::Size2D &size, uint8_t *buffer, std::size_t bufferSize, peak::ipl::InterpolationAlgorithm algorithm=InterpolationAlgorithm::linear) const
	Scale the image to the supplied width and height using the supplied `algorithm` and save it into the supplied buffer.

Image	Crop (const peak::ipl::Point2D &pos, const peak::ipl::Size2D &size) const
	Crop the image to the `size` starting at `pos`.

Image	Crop (const peak::ipl::Size2D &size) const
	Crop the image to the supplied size. Position is set to (0, 0)

Image	Clone () const
	Returns a new created image containing the data of the current image as `deep copy`.

bool	Empty () const
	Checks whether the image is empty.

uint64_t	Timestamp () const
	The timestamp in nanoseconds.

bool	operator== (const Image &img) const
	Checks whether the image is data-wise the same.

bool	operator!= (const Image &img) const
	Checks whether the image is data-wise different.

Detailed Description

Stores the pixel format, width and height of an image and the pointer to the image buffer.

Constructor & Destructor Documentation

◆ Image() [1/7]

peak::ipl::Image::Image ( )

inline

Creates an empty image. In other words, size is 0x0 and an invalid pixel format.

Exceptions

Exception An internal error has occurred.

Since: 1.1

◆ Image() [2/7]

peak::ipl::Image::Image	(	const peak::ipl::PixelFormat &	pixelFormat,
		size_t	width,
		size_t	height
	)

inline

Creates an image with the given pixel format and size.

Parameters

[in]	pixelFormat	The pixel format.
[in]	width	The width.
[in]	height	The height.

Exceptions

OutOfRangeException	pixelFormat is valid but width or height is 0.
Exception	An internal error has occurred.

Since: 1.0

◆ Image() [3/7]

peak::ipl::Image::Image	(	const peak::ipl::PixelFormat &	pixelFormat,
		uint8_t *	buffer,
		size_t	bufferSize,
		size_t	width,
		size_t	height
	)

inline

Creates an image with the given pixel format and size from the given buffer.

Parameters

[in]	pixelFormat	The pixel format.
[in]	buffer	The buffer.
[in]	bufferSize	The size of the buffer.
[in]	width	The width.
[in]	height	The height.

Note: The given buffer doesn't get copied. This is why the buffer mustn't be freed before the image gets freed.

Exceptions

InvalidArgumentException	bufferSize is too small for the specified pixel format and image dimension.
OutOfRangeException	pixelFormat is valid but width or height is 0.
Exception	An internal error has occurred.

Since: 1.0

◆ Image() [4/7]

peak::ipl::Image::Image	(	const peak::ipl::PixelFormat &	pixelFormat,
		size_t	width,
		size_t	height,
		uint64_t	timestamp_ns
	)

inline

Creates an image with the given pixel format, size and timestamp.

Parameters

[in]	pixelFormat	The pixel format.
[in]	width	The width.
[in]	height	The height.
[in]	timestamp_ns	The timestamp in ns.

Exceptions

OutOfRangeException	pixelFormat is valid but width or height is 0.
Exception	An internal error has occurred.

Since: 1.5

◆ Image() [5/7]

peak::ipl::Image::Image	(	const peak::ipl::PixelFormat &	pixelFormat,
		uint8_t *	buffer,
		size_t	bufferSize,
		size_t	width,
		size_t	height,
		uint64_t	timestamp_ns
	)

inline

Creates an image with the given pixel format, size and timestamp from the given buffer.

Parameters

[in]	pixelFormat	The pixel format.
[in]	buffer	The buffer.
[in]	bufferSize	The size of the buffer.
[in]	width	The width.
[in]	height	The height.
[in]	timestamp_ns	The timestamp in ns.

Note: The given buffer doesn't get copied. This is why the buffer mustn't be freed before the image gets freed.

Exceptions

InvalidArgumentException	bufferSize is too small for the specified pixel format and image dimension.
OutOfRangeException	pixelFormat is valid but width or height is 0.
Exception	An internal error has occurred.

Since: 1.5

◆ ~Image()

peak::ipl::Image::~Image ( )

inline

Destructor for the Image instance.

Destroys an Image instance.

Since: 1.0

◆ Image() [6/7]

peak::ipl::Image::Image ( const Image & other )

inline

Copy Constructor for a new Image instance.

Creates a new Image instance.

Note: This only creates a shallow copy. To create a deepcopy, see Image::Clone. See Shallow copy (since 1.8) for a detailed explanation.

Parameters

[in] other The other instance to acquire a reference for.

Since: 1.0 Deleted; 1.8 Implemented as shallow copy

◆ Image() [7/7]

peak::ipl::Image::Image ( Image && other )

inlinenoexcept

Move constructor for Image instance.

Moves the instance from other to this. Afterwards other is invalid.

Parameters

[in] other The other instance to move.

Since: 1.0

Member Function Documentation

◆ ByteCount()

size_t peak::ipl::Image::ByteCount ( ) const

inline

Returns the size of the given image in number of bytes.

Returns: ByteCount

Exceptions

Exception An internal error has occurred.

Since: 1.0

◆ Clone()

Image peak::ipl::Image::Clone ( ) const

inline

Returns a new created image containing the data of the current image as deep copy.

Returns: The copied image

Exceptions

Exception An internal error has occurred.

Since: 1.0

◆ ConvertTo() [1/2]

Image peak::ipl::Image::ConvertTo	(	const peak::ipl::PixelFormat &	outputPixelFormat,
		peak::ipl::ConversionMode	conversionMode = `peak::ipl::ConversionMode::Fast`
	)		const

inline

Returns a new created image containing the data of the current image converted to the given pixel format.

Parameters

[in]	outputPixelFormat	The output pixel format.
[in]	conversionMode	The conversion mode.

Returns: Converted image

Note: This function allocates memory on every use. For faster processing, consider using ImageConverter::Convert instead.

Exceptions

Exception An internal error has occurred.

Since: 1.0

◆ ConvertTo() [2/2]

Image peak::ipl::Image::ConvertTo	(	const peak::ipl::PixelFormat &	outputPixelFormat,
		uint8_t *	outputImageBuffer,
		size_t	outputImageBufferSize,
		peak::ipl::ConversionMode	conversionMode = `peak::ipl::ConversionMode::Fast`
	)		const

inline

Saves the data of the current image converted to the given pixel format into a destination buffer and creates an image from that buffer.

Parameters

[in]	outputPixelFormat	The output pixel format.
[out]	outputImageBuffer	Pointer to destination buffer.
[in]	outputImageBufferSize	Size of destination buffer.
[in]	conversionMode	The conversion mode.

Returns: Converted image

Note: This function allocates memory on every use. For faster processing, consider using ImageConverter::Convert instead.

Exceptions

BufferTooSmallException	The provided buffer is too small for the output image.
Exception	An internal error has occurred.

Since: 1.1

◆ ConvertToWithFactor()

Image peak::ipl::Image::ConvertToWithFactor	(	const peak::ipl::PixelFormat &	outputPixelFormat,
		double	factor,
		peak::ipl::ConversionMode	conversionMode = `peak::ipl::ConversionMode::Fast`
	)		const

inline

Returns a new created image containing the data of the current image converted to the given pixel format with the factor multiplied to each output pixel.

Parameters

[in]	outputPixelFormat	The output pixel format.
[in]	factor	The factor multiplied to each output pixel.
[in]	conversionMode	The conversion mode.

Returns: Converted image with the factor applied

Exceptions

Exception An internal error has occurred.

Since: 1.12

◆ Crop() [1/2]

Image peak::ipl::Image::Crop	(	const peak::ipl::Point2D &	pos,
		const peak::ipl::Size2D &	size
	)		const

inline

Crop the image to the size starting at pos.

Parameters

[in]	pos	The starting position of the cropped image
[in]	size	The image size used for the cropped image

Returns

The cropped image

Exceptions

Exception An internal error has occurred.

Since: 1.7

◆ Crop() [2/2]

Image peak::ipl::Image::Crop ( const peak::ipl::Size2D & size ) const

inline

Crop the image to the supplied size. Position is set to (0, 0)

Parameters

[in] size The output size.

Returns

The cropped image

Exceptions

Exception An internal error has occurred.

Since: 1.7

◆ Data() [1/2]

uint8_t * peak::ipl::Image::Data ( ) const

inline

Returns the pointer to the first pixel position in dependency on the size of the pixel format.

Note: Accessing the raw data pointer isn't thread safe. Ensure data is read/written only by one thread concurrently. Also note that the buffer may be freed in the meantime.

Returns: Buffer data.

Exceptions

Exception An internal error has occurred.

Since: 1.0

◆ Data() [2/2]

template<typename T , typename = std::enable_if_t<std::is_arithmetic<T>::value>>

T * peak::ipl::Image::Data ( ) const

inline

Returns the pointer to the first pixel position in dependency on the size of the pixel format.

Note: Accessing the raw data pointer isn't thread safe. Ensure data is read/written only by one thread concurrently. Also note that the buffer may be freed in the meantime.

Template Parameters

T	Type of the underlying pixel format

Returns: Buffer data as T.

Exceptions

Exception An internal error has occurred.

Since: 1.10

◆ Empty()

bool peak::ipl::Image::Empty ( ) const

inline

Checks whether the image is empty.

An image can be empty if its data have been moved.

Returns: True if the image is empty

Since: 1.0

◆ Height()

size_t peak::ipl::Image::Height ( ) const

inline

Returns the height.

Returns: Height

Exceptions

Exception An internal error has occurred.

Since: 1.0

◆ operator!=()

bool peak::ipl::Image::operator!= ( const Image & img ) const

inline

Checks whether the image is data-wise different.

Returns: True if image is data-wise different, false if not.

◆ operator=() [1/2]

Image & peak::ipl::Image::operator= ( const Image & other )

inline

Copy assigment for Image instance.

Acquires a reference from other to this instance. If this instance already has a reference, it will be destroyed.

Note: See Shallow copy (since 1.8) for a detailed explanation.

Parameters

[in] other The other instance to acquire a reference for.

Since: 1.0 Deleted; 1.8 Implemented as shallow copy

◆ operator=() [2/2]

Image & peak::ipl::Image::operator= ( Image && other )

inlinenoexcept

Move assignment for Image instance.

Moves the instance from other to this. Afterwards other is invalid.

Parameters

[in] other The other instance to move.

Since: 1.0

◆ operator==()

bool peak::ipl::Image::operator== ( const Image & img ) const

inline

Checks whether the image is data-wise the same.

Returns: True if image is data-wise the same, false if not.

◆ PixelFormat()

peak::ipl::PixelFormat peak::ipl::Image::PixelFormat ( ) const

inline

Returns the pixel format.

Returns: Pixel format

Exceptions

Exception An internal error has occurred.

Since: 1.0

◆ PixelPointer() [1/2]

uint8_t * peak::ipl::Image::PixelPointer	(	size_t	xPos,
		size_t	yPos
	)		const

inline

Returns the pixel pointer to the given pixel position in relation to the size of the pixel format.

Note: Accessing the raw data pointer isn't thread safe. Ensure data is read/written only by one thread concurrently. Also note that the buffer may be freed in the meantime.

Parameters

[in]	xPos	The x position.
[in]	yPos	The y position.

Returns: PixelPointer

Exceptions

OutOfRangeException	The pixel position is outside the image.
Exception	An internal error has occurred.

Since: 1.0

◆ PixelPointer() [2/2]

template<typename T , typename = std::enable_if_t<std::is_arithmetic<T>::value>>

T * peak::ipl::Image::PixelPointer	(	size_t	xPos,
		size_t	yPos
	)		const

inline

Returns the pixel pointer to the given pixel position in relation to the size of the pixel format.

Note: Accessing the raw data pointer isn't thread safe. Ensure data is read/written only by one thread concurrently. Also note that the buffer may be freed in the meantime.

Parameters

[in]	xPos	The x position.
[in]	yPos	The y position.

Template Parameters

T	Type of the underlying pixel format

Returns: PixelPointer of type T

Exceptions

OutOfRangeException	The pixel position is outside the image.
Exception	An internal error has occurred.

Since: 1.10

◆ Scale() [1/4]

Image peak::ipl::Image::Scale	(	const peak::ipl::ScaleFactor &	factor,
		peak::ipl::InterpolationAlgorithm	algorithm = `InterpolationAlgorithm::linear`
	)		const

inline

Scale the image to the supplied scale factors factor using the supplied algorithm.

Parameters

[in]	factor	output image scale factors
[in]	algorithm	the used interpolation algorithm

Returns: The scaled image

Note: the image size is { input_image.width * factor.X, input_image.height * factor.Y }

Exceptions

Exception An internal error has occurred.

Since: 1.7

◆ Scale() [2/4]

Image peak::ipl::Image::Scale	(	const peak::ipl::Size2D &	size,
		peak::ipl::InterpolationAlgorithm	algorithm = `InterpolationAlgorithm::linear`
	)		const

inline

Scale the image to the supplied width and height using the supplied algorithm.

Parameters

[in]	size	output size of the image
[in]	algorithm	the used interpolation algorithm

Returns: The scaled image

Exceptions

Exception An internal error has occurred.

Since: 1.7

◆ Scale() [3/4]

template<typename FloatingPoint1 , typename FloatingPoint2 , typename std::enable_if_t< std::is_floating_point< FloatingPoint1 >::value, int > = 0, typename std::enable_if_t< std::is_floating_point< FloatingPoint2 >::value, int > = 0>

Image peak::ipl::Image::Scale	(	FloatingPoint1	scaleFactorX,
		FloatingPoint2	scaleFactorY,
		peak::ipl::InterpolationAlgorithm	algorithm = `InterpolationAlgorithm::linear`
	)		const

inline

Scale the image to the supplied scale factors scaleFactorX and scaleFactorY using the supplied algorithm.

Parameters

[in]	scaleFactorX	output image scale factor for width
[in]	scaleFactorY	output image scale factor for height
[in]	algorithm	the used interpolation algorithm

Returns: The scaled image

Note: the image size is { input_image.width * scaleFactorX, input_image.height * scaleFactorY }

Exceptions

Exception An internal error has occurred.

Since: 1.7

◆ Scale() [4/4]

template<typename Integer1 , typename Integer2 , typename std::enable_if_t< std::is_integral< Integer1 >::value, int > = 0, typename std::enable_if_t< std::is_integral< Integer2 >::value, int > = 0>

Image peak::ipl::Image::Scale	(	Integer1	width,
		Integer2	height,
		peak::ipl::InterpolationAlgorithm	algorithm = `InterpolationAlgorithm::linear`
	)		const

inline

Scale the image to the supplied width and height using the supplied algorithm.

Parameters

[in]	width	output image width
[in]	height	output image height
[in]	algorithm	the used interpolation algorithm

Returns: The scaled image

Exceptions

Exception An internal error has occurred.

Since: 1.7

◆ ScaleInto()

void peak::ipl::Image::ScaleInto	(	const peak::ipl::Size2D &	size,
		uint8_t *	buffer,
		std::size_t	bufferSize,
		peak::ipl::InterpolationAlgorithm	algorithm = `InterpolationAlgorithm::linear`
	)		const

inline

Scale the image to the supplied width and height using the supplied algorithm and save it into the supplied buffer.

Parameters

[in]	size	output size of the image
[in]	buffer	the used interpolation algorithm
[in]	bufferSize	the used interpolation algorithm
[in]	algorithm	the used interpolation algorithm

Exceptions

Exception An internal error has occurred.

Since: 1.7

◆ Size()

peak::ipl::Size2D peak::ipl::Image::Size ( ) const

inline

Returns the Size.

Returns: Size

Exceptions

Exception An internal error has occurred.

Since: 1.7

◆ Timestamp()

uint64_t peak::ipl::Image::Timestamp ( ) const

inline

The timestamp in nanoseconds.

The point in camera time at which the image was exposed.

Returns: Timestamp in nanoseconds

Since: 1.6

◆ Width()

size_t peak::ipl::Image::Width ( ) const

inline

Returns the width.

Returns: Width

Exceptions

Exception An internal error has occurred.

Since: 1.0

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

peak_ipl/types/peak_ipl_image.hpp

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ Image() [1/7]

◆ Image() [2/7]

◆ Image() [3/7]

◆ Image() [4/7]

◆ Image() [5/7]

◆ ~Image()

◆ Image() [6/7]

◆ Image() [7/7]

Member Function Documentation

◆ ByteCount()

◆ Clone()

◆ ConvertTo() [1/2]

◆ ConvertTo() [2/2]

◆ ConvertToWithFactor()

◆ Crop() [1/2]

◆ Crop() [2/2]

◆ Data() [1/2]

◆ Data() [2/2]

◆ Empty()

◆ Height()

◆ operator!=()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ operator==()

◆ PixelFormat()

◆ PixelPointer() [1/2]

◆ PixelPointer() [2/2]

◆ Scale() [1/4]

◆ Scale() [2/4]

◆ Scale() [3/4]

◆ Scale() [4/4]

◆ ScaleInto()

◆ Size()

◆ Timestamp()

◆ Width()