Converts images from one PixelFormat to another. More...

#include <peak_ipl/algorithm/peak_ipl_image_converter.hpp>

Public Member Functions
	ImageConverter ()
	Constructor for a new ImageConverter instance.

	~ImageConverter ()
	Destructor for the ImageConverter instance.

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

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

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

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

	ImageConverter (const peak::ipl::PixelFormat &inputPixelFormat, const peak::ipl::PixelFormat &outputPixelFormat, size_t width, size_t height, size_t imageCount=5)
	Convenience constructor to directly pre-allocate an internal buffer pool. This calls PreAllocateConversion internally.

void	PreAllocateConversion (const peak::ipl::PixelFormat &inputPixelFormat, const peak::ipl::PixelFormat &outputPixelFormat, size_t width, size_t height, size_t imageCount=5)
	Pre-allocate buffer pools needed for the specified conversion.

peak::ipl::ConversionMode	ConversionMode () const
	Returns the current conversion mode.

void	SetConversionMode (peak::ipl::ConversionMode conversionMode)
	Set conversion mode.

std::vector< peak::ipl::PixelFormatName >	SupportedOutputPixelFormatNames (const peak::ipl::PixelFormat &inputPixelFormat) const
	Returns the supported output pixel formats for a given input pixel format.

Image	Convert (const Image &inputImage, const peak::ipl::PixelFormat &outputPixelFormat) const
	Converts the given `inputImage` to the specified `outputPixelFormat`.

Image	Convert (const Image &inputImage, const peak::ipl::PixelFormat &outputPixelFormat, uint8_t *outputImageBuffer, size_t outputImageBufferSize) const
	Converts the given `inputImage` to the specified `outputPixelFormat` into an existing `outputImageBuffer`.

Image	Convert (const Image &inputImage, const peak::ipl::PixelFormat &outputPixelFormat, double factor, double offset=0.0) const
	Converts the given `inputImage` to the specified `outputPixelFormat` and scales the pixel values by the `factor`.

Image	Convert (const Image &inputImage, const peak::ipl::PixelFormat &outputPixelFormat, uint8_t *outputImageBuffer, size_t outputImageBufferSize, double factor, double offset=0.0) const
	Converts the given `inputImage` to the specified `outputPixelFormat` into an existing `outputImageBuffer` and scales the pixel values by the `factor`.

Image	Convert (const Image &inputImage, const peak::ipl::PixelFormat &outputPixelFormat, peak::ipl::Interval< double > interval) const
	Converts the given `inputImage` to the specified `outputPixelFormat`. The pixel values are mapped from `interval` to the value range of the `outputPixelFormat`. All pixel values outside the interval will be clamped.

Image	Convert (const Image &inputImage, const peak::ipl::PixelFormat &outputPixelFormat, uint8_t *outputImageBuffer, size_t outputImageBufferSize, peak::ipl::Interval< double > interval) const
	Converts the given `inputImage` to the specified `outputPixelFormat` into an existing `outputImageBuffer`. The pixel values are mapped from `interval` to the value range of the `outputPixelFormat`. All pixel values outside the interval will be clamped.

Detailed Description

Converts images from one PixelFormat to another.

Note: In order to speed up processing, instances of this class maintain internal memory pools, which allows reuse of memory instead of allocating new memory on each conversion.
The memory is freed when the instance is destroyed. There is one pool for every needed byte count, therefore, a new pool will be allocated if an image with a new size or format needs to be processed.
One may select to create a new instance of this class when changing image settings in order to free old pools. If a new pool or buffer is needed, they will get allocated automatically during the conversion, which results in the first conversion taking more time.
This can be prevented by using the function ImageConverter::PreAllocateConversion before the conversion. Buffers can be reused once a converted image gets freed.

Constructor & Destructor Documentation

◆ ImageConverter() [1/4]

peak::ipl::ImageConverter::ImageConverter ( )

inline

Constructor for a new ImageConverter instance.

Creates a new ImageConverter instance.

Since: 1.0

◆ ~ImageConverter()

peak::ipl::ImageConverter::~ImageConverter ( )

inline

Destructor for the ImageConverter instance.

Destroys an ImageConverter instance.

Since: 1.0

◆ ImageConverter() [2/4]

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

inline

Copy Constructor for a new ImageConverter instance.

Creates a new ImageConverter instance.

Note: This only creates a shallow copy. 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

◆ ImageConverter() [3/4]

peak::ipl::ImageConverter::ImageConverter ( ImageConverter && other )

inlinenoexcept

Move constructor for ImageConverter instance.

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

Parameters

[in] other The other instance to move.

Since: 1.0

◆ ImageConverter() [4/4]

peak::ipl::ImageConverter::ImageConverter	(	const peak::ipl::PixelFormat &	inputPixelFormat,
		const peak::ipl::PixelFormat &	outputPixelFormat,
		size_t	width,
		size_t	height,
		size_t	imageCount = 5 )

inline

Convenience constructor to directly pre-allocate an internal buffer pool. This calls PreAllocateConversion internally.

Parameters

[in]	inputPixelFormat	The pixelformat of the source image
[in]	outputPixelFormat	The pixelformat of the converted image
[in]	width	Width of the source image
[in]	height	Height of the source image
[in]	imageCount	Maximum number of converted images held at one time

Exceptions

Exception An internal error has occurred.

Since: 1.4

Member Function Documentation

◆ ConversionMode()

peak::ipl::ConversionMode peak::ipl::ImageConverter::ConversionMode ( ) const

inline

Returns the current conversion mode.

Returns: The current conversion mode

Exceptions

Exception An internal error has occurred.

Since: 1.0

◆ Convert() [1/6]

Image peak::ipl::ImageConverter::Convert	(	const Image &	inputImage,
		const peak::ipl::PixelFormat &	outputPixelFormat ) const

inline

Converts the given inputImage to the specified outputPixelFormat.

Parameters

[in]	inputImage	The source image to be converted.
[in]	outputPixelFormat	The desired pixel format for the output image.

Returns: A new peak::ipl::Image containing the content of inputImage in the specified outputPixelFormat.

Exceptions

Exception An internal error has occurred.

Since: 1.0

◆ Convert() [2/6]

Image peak::ipl::ImageConverter::Convert	(	const Image &	inputImage,
		const peak::ipl::PixelFormat &	outputPixelFormat,
		double	factor,
		double	offset = 0.0 ) const

inline

Converts the given inputImage to the specified outputPixelFormat and scales the pixel values by the factor.

Note: The outputPixelFormat must be a float pixel format.

Parameters

[in]	inputImage	The source image to be converted.
[in]	outputPixelFormat	The desired pixel format for the output image.
[in]	factor	Scale factor that is applied to each pixel value.
[in]	offset	The offset to apply to all output pixels.

Returns: A new peak::ipl::Image containing the content of inputImage in the specified outputPixelFormat with pixel values scaled by factor (m) and offset (c) added according to y = m · x + c.

Exceptions

ImageFormatNotSupportedException	The given input or output pixel format is not supported.
Exception	An internal error has occurred.

Since: 1.15

◆ Convert() [3/6]

Image peak::ipl::ImageConverter::Convert	(	const Image &	inputImage,
		const peak::ipl::PixelFormat &	outputPixelFormat,
		peak::ipl::Interval< double >	interval ) const

inline

Converts the given inputImage to the specified outputPixelFormat. The pixel values are mapped from interval to the value range of the outputPixelFormat. All pixel values outside the interval will be clamped.

Note: The pixel format of the inputImage must be a float pixel format.

Parameters

[in]	inputImage	The source image to be converted.
[in]	outputPixelFormat	The desired pixel format for the output image.
[in]	interval	The interval of the input range.

Returns: A new peak::ipl::Image containing the content of inputImage in the specified outputPixelFormat with mapped pixel values.

Exceptions

ImageFormatNotSupportedException	The given input or output pixel format is not supported.
Exception	An internal error has occurred.

Since: 1.15

◆ Convert() [4/6]

Image peak::ipl::ImageConverter::Convert	(	const Image &	inputImage,
		const peak::ipl::PixelFormat &	outputPixelFormat,
		uint8_t *	outputImageBuffer,
		size_t	outputImageBufferSize ) const

inline

Converts the given inputImage to the specified outputPixelFormat into an existing outputImageBuffer.

Parameters

[in]	inputImage	The source image to be converted.
[in]	outputPixelFormat	The desired pixel format for the output image.
[in]	outputImageBuffer	Pointer to the output buffer.
[in]	outputImageBufferSize	Size of the output buffer.

Returns: A peak::ipl::Image object representing the converted image. The returned Image object encapsulates the outputImageBuffer. Note that the memory is not owned by the image object. Ensure the buffer is not deleted until you have finished working with the image.

Exceptions

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

Since: 1.1

◆ Convert() [5/6]

Image peak::ipl::ImageConverter::Convert	(	const Image &	inputImage,
		const peak::ipl::PixelFormat &	outputPixelFormat,
		uint8_t *	outputImageBuffer,
		size_t	outputImageBufferSize,
		double	factor,
		double	offset = 0.0 ) const

inline

Converts the given inputImage to the specified outputPixelFormat into an existing outputImageBuffer and scales the pixel values by the factor.

Parameters

[in]	inputImage	The source image to be converted.
[in]	outputPixelFormat	The desired pixel format for the output image.
[in]	outputImageBuffer	Pointer to the output buffer.
[in]	outputImageBufferSize	Size of the output buffer.
[in]	factor	Scale factor that is applied to each pixel value.
[in]	offset	The offset to apply to all output pixels.

Returns: A peak::ipl::Image object representing the converted image. The returned Image object encapsulates the outputImageBuffer with pixel values scaled by factor (m) and offset (c) added according to y = m · x + c. Note that the memory is not owned by the image object. Ensure the buffer is not deleted until you have finished working with the image.

Exceptions

ImageFormatNotSupportedException	The given input or output pixel format is not supported.
BufferTooSmallException	The provided buffer is too small for the output image.
InvalidArgumentException	The given output buffer pointer is invalid.
Exception	An internal error has occurred.

Since: 1.15

◆ Convert() [6/6]

Image peak::ipl::ImageConverter::Convert	(	const Image &	inputImage,
		const peak::ipl::PixelFormat &	outputPixelFormat,
		uint8_t *	outputImageBuffer,
		size_t	outputImageBufferSize,
		peak::ipl::Interval< double >	interval ) const

inline

Converts the given inputImage to the specified outputPixelFormat into an existing outputImageBuffer. The pixel values are mapped from interval to the value range of the outputPixelFormat. All pixel values outside the interval will be clamped.

Note: The pixel format of the inputImage must be a float pixel format.

Parameters

[in]	inputImage	The source image to be converted.
[in]	outputPixelFormat	The desired pixel format for the output image.
[in]	outputImageBuffer	Pointer to the output buffer.
[in]	outputImageBufferSize	Size of the output buffer.
[in]	interval	The interval of the input range.

Returns: A peak::ipl::Image object representing the converted image. The returned Image object encapsulates the outputImageBuffer with mapped pixel values. Note that the memory is not owned by the image object. Ensure the buffer is not deleted until you have finished working with the image.

Exceptions

ImageFormatNotSupportedException	The given input or output pixel format is not supported.
BufferTooSmallException	The provided buffer is too small for the output image.
InvalidArgumentException	The given output buffer pointer is invalid.
Exception	An internal error has occurred.

Since: 1.15

◆ operator=() [1/2]

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

inline

Copy assigment for ImageConverter 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]

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

inlinenoexcept

Move assignment for ImageConverter instance.

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

Parameters

[in] other The other instance to move.

Since: 1.0

◆ PreAllocateConversion()

void peak::ipl::ImageConverter::PreAllocateConversion	(	const peak::ipl::PixelFormat &	inputPixelFormat,
		const peak::ipl::PixelFormat &	outputPixelFormat,
		size_t	width,
		size_t	height,
		size_t	imageCount = 5 )

inline

Pre-allocate buffer pools needed for the specified conversion.

Parameters

[in]	inputPixelFormat	The pixelformat of the source image
[in]	outputPixelFormat	The pixelformat of the converted image
[in]	width	Width of the source image
[in]	height	Height of the source image
[in]	imageCount	Maximum number of converted images held at one time

Exceptions

Exception An internal error has occurred.

Since: 1.4

◆ SetConversionMode()

void peak::ipl::ImageConverter::SetConversionMode ( peak::ipl::ConversionMode conversionMode )

inline

Set conversion mode.

Parameters

[in] conversionMode The conversion mode to set.

Exceptions

Exception An internal error has occurred.

Since: 1.0

◆ SupportedOutputPixelFormatNames()

std::vector< PixelFormatName > peak::ipl::ImageConverter::SupportedOutputPixelFormatNames ( const peak::ipl::PixelFormat & inputPixelFormat ) const

inline

Returns the supported output pixel formats for a given input pixel format.

Parameters

[in] inputPixelFormat The input pixel format.

Returns: A vector of supported pixel formats for the given input pixel format

Exceptions

Exception An internal error has occurred.

Since: 1.0

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

peak_ipl/algorithm/peak_ipl_image_converter.hpp

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ ImageConverter() [1/4]

◆ ~ImageConverter()

◆ ImageConverter() [2/4]

◆ ImageConverter() [3/4]

◆ ImageConverter() [4/4]

Member Function Documentation

◆ ConversionMode()

◆ Convert() [1/6]

◆ Convert() [2/6]

◆ Convert() [3/6]

◆ Convert() [4/6]

◆ Convert() [5/6]

◆ Convert() [6/6]

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ PreAllocateConversion()

◆ SetConversionMode()

◆ SupportedOutputPixelFormatNames()