Pylon::CImageFormatConverter#

Module: Image Handling Support

Creates new images by converting a source image to another format. More…

#include <pylon/ImageFormatConverter.h>

Inherits from Basler_ImageFormatConverterParams::CImageFormatConverterParams_Params, Basler_ImageFormatConverterParams::CImageFormatConverterParams_Params_v10_0_0

Public Classes#

Public Functions#

Public Attributes#

Detailed Description#

class Pylon::CImageFormatConverter;

Creates new images by converting a source image to another format.

Limitations:

The last column of a YUV input image with odd width cannot be converted. The last column and the last row of a Bayer input image cannot be converted.

Thread Safety:

The CImageFormatConverter class is not thread-safe.

Supported input image formats defined by the pixel type:

• PixelType_Mono1packed
• PixelType_Mono2packed
• PixelType_Mono4packed
• PixelType_Mono8
• PixelType_Mono10
• PixelType_Mono10packed
• PixelType_Mono10p
• PixelType_Mono12
• PixelType_Mono12packed
• PixelType_Mono12p

• PixelType_Mono16

• PixelType_BayerGR8

• PixelType_BayerRG8
• PixelType_BayerGB8
• PixelType_BayerBG8
• PixelType_BayerGR10
• PixelType_BayerRG10
• PixelType_BayerGB10
• PixelType_BayerBG10
• PixelType_BayerGR12
• PixelType_BayerRG12
• PixelType_BayerGB12
• PixelType_BayerBG12
• PixelType_BayerGR12Packed
• PixelType_BayerRG12Packed
• PixelType_BayerGB12Packed
• PixelType_BayerBG12Packed
• PixelType_BayerGR10p
• PixelType_BayerRG10p
• PixelType_BayerGB10p
• PixelType_BayerBG10p
• PixelType_BayerGR12p
• PixelType_BayerRG12p
• PixelType_BayerGB12p
• PixelType_BayerBG12p
• PixelType_BayerGR16
• PixelType_BayerRG16
• PixelType_BayerGB16

• PixelType_BayerBG16

• PixelType_RGB8packed

• PixelType_BGR8packed
• PixelType_RGBA8packed
• PixelType_BGRA8packed
• PixelType_RGB10packed
• PixelType_BGR10packed
• PixelType_RGB12packed
• PixelType_BGR12packed
• PixelType_RGB12V1packed
• PixelType_RGB16packed
• PixelType_RGB8planar

• PixelType_RGB16planar

• PixelType_YUV422packed

• PixelType_YUV422_YUYV_Packed
• PixelType_YCbCr422_8_YY_CbCr_Semiplanar
• PixelType_YCbCr420_8_YY_CbCr_Semiplanar

Supported output image formats defined by the pixel type:

• PixelType_BGRA8packed - This pixel type can be used in Windows bitmaps. See Pylon::SBGRA8Pixel.
• PixelType_BGR8packed - This pixel type can be used in Windows bitmaps. See Pylon::SBGR8Pixel.
• PixelType_RGB8packed - See Pylon::SRGB8Pixel.
• PixelType_RGB16packed - See Pylon::SRGB16Pixel.
• PixelType_RGB8planar
• PixelType_RGB16planar
• PixelType_Mono8
• PixelType_Mono16
• PixelType_YUV444planar
• PixelType_YUV422planar
• PixelType_YUV420planar

All input image formats can be converted to all output image formats.

RGB, BGR and Bayer image formats are converted to monochrome formats by using the following formula:

mono = (0.25 * red) + (0.625 * green) + (0.125 * blue);

YUV formats are converted to 16 bit bit depth in an intermediate conversion step. This is why the output is always aligned at the most significant bit when converting to 16 bit color output formats like PixelType_RGB16packed.

The default treatment of rows and columns that cannot be converted due to their location on edges, can be controlled using the CImageFormatConverter::InconvertibleEdgeHandling parameter. See also the Convert() method description.

Public Functions Documentation#

function CImageFormatConverter#

CImageFormatConverter()

Creates an image format converter.

Error Safety:

Does not throw C++ exceptions.

function ~CImageFormatConverter#

virtual ~CImageFormatConverter()

Destroys the image format converter.

Error Safety:

Does not throw C++ exceptions.

function Initialize#

virtual void Initialize(
    EPixelType sourcePixelType
)

Optionally initializes the image format converter before conversion.

Parameters:

• sourcePixelType The pixel type of the source image.

Precondition:

• The converter parameters are set up.
• The pixelTypeSource must be supported by the converter.

Error Safety:

Throws an exception if the passed pixel type does not represent a valid input format. The converter object is still valid after error and can be initialized again.

• Depending on parameter settings and the input format, data structures required for conversion are created, e.g. lookup tables.
• Initialization is done automatically when calling Convert() if needed. This may add a delay when converting the first image.

Lookup tables are created when using monochrome images as input and when the gamma conversion method is selected or when the shift conversion method is selected and the value of AdditionalLeftShift is not zero. The converter can be reinitialized with other settings if required.

function IsInitialized#

virtual bool IsInitialized(
    EPixelType sourcePixelType
) const

Returns information about the converter being initialized.

Parameters:

• sourcePixelType The pixel type of the source image.

Return: True if initialized.

Error Safety:

Does not throw C++ exceptions.

The result depends on the converter settings.

function Uninitialize#

virtual void Uninitialize()

Destroys data structures required for conversion.

Error Safety:

Does not throw C++ exceptions.

This function can be called to free resources held by the format converter.

function ImageHasDestinationFormat#

virtual bool ImageHasDestinationFormat(
    const IImage & sourceImage
) const

Checks to see if a conversion is required or if the source image already has the desired format.

Parameters:

• sourceImage The source image, e.g. a CPylonImage, CPylonBitmapImage, or Grab Result Smart Pointer object.

Return: Returns true if the source image already has the desired format.

Error Safety:

Does not throw C++ exceptions.

A conversion may even be required image format does not change e.g. if the gamma conversion method is selected and the format describes a monochrome image.

function ImageHasDestinationFormat#

virtual bool ImageHasDestinationFormat(
    EPixelType sourcePixelType,
    size_t sourcePaddingX,
    EImageOrientation sourceOrientation
) const

Checks to see if a conversion is required or if the source image already has the desired format.

Parameters:

• sourcePixelType The pixel type of the source image.
• sourcePaddingX The number of extra data bytes at the end of each row. The default value is usually 0.
• sourceOrientation The vertical orientation of the image in the image buffer. The default value is usually ImageOrientation_TopDown.

Return: Returns true if the source image already has the desired format. This is done according to the current converter settings.

Error Safety:

Does not throw C++ exceptions.

A conversion may even be required image format does not change e.g. if the gamma conversion method is selected and the format describes a monochrome image.

function GetBufferSizeForConversion#

virtual size_t GetBufferSizeForConversion(
    const IImage & sourceImage
) const

Computes the size of the destination image buffer in byte.

Parameters:

• sourceImage The source image, e.g. a CPylonImage, CPylonBitmapImage, or Grab Result Smart Pointer object.

Return: The size of the destination image when converting the given source image using current converter settings.

Error Safety:

Throws an exception if the destination image size for the passed input cannot be computed. The converter object is still valid after error.

function GetBufferSizeForConversion#

virtual size_t GetBufferSizeForConversion(
    EPixelType sourcePixelType,
    uint32_t sourceWidth,
    uint32_t sourceHeight
) const

Computes the size of the destination image buffer in byte.

Parameters:

• sourceWidth The number of pixels in a row in the source image.
• sourceHeight The number of rows in the source image.
• sourcePixelType The pixel type of the source image.

Return: The size of the destination image when converting the source image using current converter settings.

Precondition:

• The sourceWidth value must be >= 0 and < _I32_MAX.
• The sourceHeight value must be >= 0 and < _I32_MAX.

Error Safety:

Throws an exception if the destination image size for the passed input cannot be computed. The converter object is still valid after error.

function Convert#

virtual void Convert(
    IReusableImage & destinationImage,
    const IImage & sourceImage
)

Creates a new image by converting an image to a different format.

Parameters:

• destinationImage The destination image, e.g. a CPylonImage or CPylonBitmapImage object. When passing a CPylonBitmapImage object the target format must be supported by the CPylonBitmapImage class.
• sourceImage The source image, e.g. a CPylonImage, CPylonBitmapImage, or Grab Result Smart Pointer object.

Precondition:

• The source and destination images must be different images.
• The source image must be valid.
• The format of the source image must be supported by the converter.
• The destination image must support the destination format.
• The destination image must be able to provide a large enough buffer to hold the image.

Error Safety:

Throws an exception if the passed parameters are not valid. The converter object is still valid after error.

The IReusableImage::Reset() method of the destination image is called to set the destination format. The image is converted to the destination image according to the current converter settings. The padding area of a row in the destination image is set to zero.

The OutputPaddingX setting is ignored for images that do not support user defined padding, e.g. CPylonBitmapImage. See also IReusableImage::IsAdditionalPaddingSupported().

function Convert#

virtual void Convert(
    IReusableImage & destinationImage,
    const void * pSourceBuffer,
    size_t sourceBufferSizeBytes,
    EPixelType sourcePixelType,
    uint32_t sourceWidth,
    uint32_t sourceHeight,
    size_t sourcePaddingX,
    EImageOrientation sourceOrientation
)

Creates a new image by converting an image to a different format.

Parameters:

• destinationImage The destination image.
• pSourceBuffer The pointer to the buffer of the source image.
• sourceBufferSizeBytes The size of the buffer of the source image.
• sourcePixelType The pixel type of the source image.
• sourceWidth The number of pixels in a row in the source image.
• sourceHeight The number of rows in the source image.
• sourcePaddingX The number of extra data bytes at the end of each row. The default value is usually 0.
• sourceOrientation The vertical orientation of the source image in the image buffer. The default value is usually ImageOrientation_TopDown.

Precondition:

• The pixel type must be valid.
• The sourceWidth value must be >= 0 and < _I32_MAX.
• The sourceHeight value must be >= 0 and < _I32_MAX.
• The pointer to the source buffer must not be NULL.
• The source buffer must be large enough to hold the image described by the parameters.
• The format of the input image represented by the given parameter must be supported by the converter.
• The destination image must support the destination format.
• The destination image must be able to provide a large enough buffer to hold the image.
• The source image buffer and the destination image buffer must not be identical.

Error Safety:

Throws an exception if the passed parameters are not valid. The converter object is still valid after error.

The IReusableImage::Reset() method of the destination image is called to set the destination format. The image is converted to the destination image according to the current converter settings. The padding area of a row in the destination image is set to zero.

The OutputPaddingX setting is ignored for images that do not support user defined padding, e.g. CPylonBitmapImage. See also IReusableImage::IsAdditionalPaddingSupported().

function Convert#

virtual void Convert(
    void * pDestinationBuffer,
    size_t destinationBufferSizeBytes,
    const IImage & sourceImage
)

Creates a new image by converting an image to a different format.

Parameters:

• pDestinationBuffer The pointer to the buffer of the destination image.
• destinationBufferSizeBytes The size of the buffer of the destination image.
• sourceImage The source image, e.g. a CPylonImage, CPylonBitmapImage, or Grab Result Smart Pointer object.

Precondition:

• The format of the source image must be supported by the converter.
• The destination image buffer must be large enough to hold the destination image.
• The source image buffer and the destination image buffer must not be identical.

Error Safety:

Throws an exception if the passed parameters are not valid. The converter object is still valid after error.

The image is converted to the destination image according to the current converter settings. The padding area of a row in the destination image is set to zero.

function Convert#

virtual void Convert(
    void * pDestinationBuffer,
    size_t destinationBufferSizeBytes,
    const void * pSourceBuffer,
    size_t sourceBufferSizeBytes,
    EPixelType sourcePixelType,
    uint32_t sourceWidth,
    uint32_t sourceHeight,
    size_t sourcePaddingX,
    EImageOrientation sourceOrientation
)

Creates a new image by converting an image to a different format.

Parameters:

• pDestinationBuffer The pointer to the buffer of the destination image.
• destinationBufferSizeBytes The size of the buffer of the destination image.
• pSourceBuffer The pointer to the buffer of the source image.
• sourceBufferSizeBytes The size of the buffer of the source image.
• sourcePixelType The pixel type of the source image.
• sourceWidth The number of pixels in a row in the source image.
• sourceHeight The number of rows in the source image.
• sourcePaddingX The number of extra data bytes at the end of each row. The default value is usually 0.
• sourceOrientation The vertical orientation of the source image in the image buffer. The default value is usually ImageOrientation_TopDown.

Precondition:

• The parameters regarding the source buffer must describe a valid image.
• The format of the input image represented by the given parameter must be supported by the converter.
• If the destination image buffer must be large enough to hold the destination image.
• The the source buffer can not be equal the destination buffer.

Error Safety:

Throws an exception if the passed parameters are not valid. The converter object is still valid after error.

The image is converted to the destination image according to the current converter settings. The padding area of a row in the destination image is set to zero.

function GetNodeMap#

virtual GenApi::INodeMap & GetNodeMap()

Provides access to the node map of the format converter.

Return: Reference to the node map of the format converter.

Error Safety:

Does not throw C++ exceptions.

function IsSupportedInputFormat#

static bool IsSupportedInputFormat(
    EPixelType sourcePixelType
)

Returns true if the image format defined by the given pixel type is a supported input format.

Parameters:

• sourcePixelType The pixel type of the source image.

Error Safety:

Does not throw C++ exceptions.

function IsSupportedOutputFormat#

static bool IsSupportedOutputFormat(
    EPixelType destinationPixelType
)

Returns true if the image format defined by the given pixel type is a supported output format.

Parameters:

• destinationPixelType The pixel type of the destination image.

Error Safety:

Does not throw C++ exceptions.

Public Attributes Documentation#

variable AdditionalLeftShift#

Pylon::IIntegerEx & AdditionalLeftShift;

Additional shifting value used for converting monochrome images - Applies to: ImageFormatConverter.

Additional shifting value used for converting monochrome images. Only effective if the Mono Conversion Method parameter is set to Truncate. If the parameter value isn't zero, the image data is converted using a lookup table. Shifted values exceeding the maximum output value boundary are set to the maximum allowed value. Negative values are treated as right-shifted values.

Visibility: Beginner

variable Gamma#

Pylon::IFloatEx & Gamma;

Gamma value for converting monochrome images - Applies to: ImageFormatConverter.

Gamma value for converting monochrome images. The image data is converted using a lookup table.

Visibility: Beginner

variable MonoConversionMethod#

Pylon::IEnumParameterT< MonoConversionMethodEnums > & MonoConversionMethod;

Sets the conversion method for monochrome images - Applies to: ImageFormatConverter.

Visibility: Beginner

variable InconvertibleEdgeHandling#

Pylon::IEnumParameterT< InconvertibleEdgeHandlingEnums > & InconvertibleEdgeHandling;

Sets how to handle rows and columns that can't be converted - Applies to: ImageFormatConverter.

Visibility: Beginner

variable MaxNumThreads#

Pylon::IIntegerEx & MaxNumThreads;

Maximum number of threads used for format conversion - Applies to: ImageFormatConverter.

Maximum number of threads used for format conversion. Depending on the image size fewer than the specified number of threads will be used.

Visibility: Beginner

variable OutputBitAlignment#

Pylon::IEnumParameterT< OutputBitAlignmentEnums > & OutputBitAlignment;

Sets the alignment of the bits in the target pixel type - Applies to: ImageFormatConverter.

Sets the alignment of the bits in the target pixel type if the target bit depth is greater than the source bit depth, e.g., if you are converting from a 10-bit to a 16-bit format.

Visibility: Beginner

variable OutputOrientation#

Pylon::IEnumParameterT< OutputOrientationEnums > & OutputOrientation;

Sets the vertical orientation of the output image in the buffer - Applies to: ImageFormatConverter.

Visibility: Beginner

variable OutputPaddingX#

Pylon::IIntegerEx & OutputPaddingX;

Number of additional data bytes at the end of each line - Applies to: ImageFormatConverter.

Number of additional data bytes at the end of each line. These bytes are set to zero during the conversion.

Visibility: Beginner

variable OutputPixelFormat#

IOutputPixelFormatEnum & OutputPixelFormat;

The pixel data format of the output image.

Precondition: The pixel format set must be a supported output pixel format. See IsSupportedOutputFormat().

Error Safety:

Throws an exception if the set output pixel format is not supported.

This member can be used to get and set the output pixel format using the EPixelType enumeration. It emulates the behavior of native parameter access.