All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
Public Member Functions | Static Public Member Functions | Public Attributes | List of all members
Pylon::CImageFormatConverter Class Reference

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

#include <pylon/ImageFormatConverter.h>

Inheritance diagram for Pylon::CImageFormatConverter:
Inheritance graph
[legend]

Public Member Functions

 CImageFormatConverter ()
 Creates an image format converter. More...
 
virtual ~CImageFormatConverter ()
 Destroys the image format converter. More...
 
virtual void Initialize (EPixelType sourcePixelType)
 Optionally initializes the image format converter before conversion. More...
 
virtual bool IsInitialized (EPixelType sourcePixelType) const
 Returns information about the converter being initialized. More...
 
virtual void Uninitialize ()
 Destroys data structures required for conversion. More...
 
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. More...
 
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. More...
 
virtual size_t GetBufferSizeForConversion (const IImage &sourceImage) const
 Computes the size of the destination image buffer in byte. More...
 
virtual size_t GetBufferSizeForConversion (EPixelType sourcePixelType, uint32_t sourceWidth, uint32_t sourceHeight) const
 Computes the size of the destination image buffer in byte. More...
 
virtual void Convert (IReusableImage &destinationImage, const IImage &sourceImage)
 Creates a new image by converting an image to a different format. More...
 
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. More...
 
virtual void Convert (void *pDestinationBuffer, size_t destinationBufferSizeBytes, const IImage &sourceImage)
 Creates a new image by converting an image to a different format. More...
 
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. More...
 
virtual GenApi::INodeMap & GetNodeMap ()
 Provides access to the node map of the format converter. More...
 

Static Public Member Functions

static bool IsSupportedInputFormat (EPixelType sourcePixelType)
 Returns true if the image format defined by the given pixel type is a supported input format. More...
 
static bool IsSupportedOutputFormat (EPixelType destinationPixelType)
 Returns true if the image format defined by the given pixel type is a supported output format. More...
 

Public Attributes

IOutputPixelFormatEnum & OutputPixelFormat
 The pixel data format of the output image. More...
 
MonoConversion - Parameters for converting monochrome images.
GenApi::IEnumerationT
< MonoConversionMethodEnums > & 
MonoConversionMethod
 Sets the conversion method for monochrome images. More...
 
GenApi::IFloat & Gamma
 Sets the gamma value for converting monochrome images. More...
 
GenApi::IInteger & AdditionalLeftShift
 Sets the value for additional shifting when converting monochrome images in Truncate mode. More...
 
Root - Image Format Converter parameters.
GenApi::IInteger & OutputPaddingX
 The number of additional data bytes at the end of each line. More...
 
GenApi::IEnumerationT
< OutputOrientationEnums > & 
OutputOrientation
 Defines the vertical orientation of the output image in memory. More...
 
GenApi::IEnumerationT
< InconvertibleEdgeHandlingEnums > & 
InconvertibleEdgeHandling
 Sets the handling for rows and columns that cannot be converted. More...
 
GenApi::IEnumerationT
< OutputBitAlignmentEnums > & 
OutputBitAlignment
 Controls the alignment of the bits in the target pixel type. More...
 

Detailed Description

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

Supported input image formats defined by the pixel type:

<ul>
<li> PixelType_Mono1packed
<li> PixelType_Mono2packed
<li> PixelType_Mono4packed
<li> PixelType_Mono8
<li> PixelType_Mono10
<li> PixelType_Mono10packed
<li> PixelType_Mono10p
<li> PixelType_Mono12
<li> PixelType_Mono12packed
<li> PixelType_Mono12p
<li> PixelType_Mono16
</ul>
<ul>
<li> PixelType_BayerGR8
<li> PixelType_BayerRG8
<li> PixelType_BayerGB8
<li> PixelType_BayerBG8
<li> PixelType_BayerGR10
<li> PixelType_BayerRG10
<li> PixelType_BayerGB10
<li> PixelType_BayerBG10
<li> PixelType_BayerGR12
<li> PixelType_BayerRG12
<li> PixelType_BayerGB12
<li> PixelType_BayerBG12
<li> PixelType_BayerGR12Packed
<li> PixelType_BayerRG12Packed
<li> PixelType_BayerGB12Packed
<li> PixelType_BayerBG12Packed
<li> PixelType_BayerGR10p
<li> PixelType_BayerRG10p
<li> PixelType_BayerGB10p
<li> PixelType_BayerBG10p
<li> PixelType_BayerGR12p
<li> PixelType_BayerRG12p
<li> PixelType_BayerGB12p
<li> PixelType_BayerBG12p
<li> PixelType_BayerGR16
<li> PixelType_BayerRG16
<li> PixelType_BayerGB16
<li> PixelType_BayerBG16
</ul>
<ul>
<li> PixelType_RGB8packed
<li> PixelType_BGR8packed
<li> PixelType_RGBA8packed
<li> PixelType_BGRA8packed
<li> PixelType_RGB10packed
<li> PixelType_BGR10packed
<li> PixelType_RGB12packed
<li> PixelType_BGR12packed
<li> PixelType_RGB12V1packed
<li> PixelType_RGB16packed
<li> PixelType_RGB8planar
<li> PixelType_RGB16planar
</ul>
<ul>
<li> PixelType_YUV422packed
<li> PixelType_YUV422_YUYV_Packed
</ul>

Supported output image formats defined by the pixel type:

<ul>
<li> PixelType_BGRA8packed - This pixel type can be used in Windows bitmaps. See Pylon::SBGRA8Pixel.
<li> PixelType_BGR8packed - This pixel type can be used in Windows bitmaps. See Pylon::SBGR8Pixel.
<li> PixelType_RGB8packed - See Pylon::SRGB8Pixel.
<li> PixelType_RGB16packed - See Pylon::SRGB16Pixel.
<li> PixelType_RGB8planar
<li> PixelType_RGB16planar
<li> PixelType_Mono8
<li> PixelType_Mono16
</ul>

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.

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.

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.

Thread Safety:
The CImageFormatConverter class is not thread-safe.

Constructor & Destructor Documentation

Pylon::CImageFormatConverter::CImageFormatConverter ( )

Creates an image format converter.

Error Safety:
Does not throw C++ exceptions.
virtual Pylon::CImageFormatConverter::~CImageFormatConverter ( )
virtual

Destroys the image format converter.

Error Safety:
Does not throw C++ exceptions.

Member Function Documentation

virtual void Pylon::CImageFormatConverter::Convert ( IReusableImage destinationImage,
const IImage sourceImage 
)
virtual

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

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().

Parameters
[out]destinationImageThe destination image, e.g. a CPylonImage or CPylonBitmapImage object. When passing a CPylonBitmapImage object the target format must be supported by the CPylonBitmapImage class.
[in]sourceImageThe 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.
virtual void Pylon::CImageFormatConverter::Convert ( IReusableImage destinationImage,
const void *  pSourceBuffer,
size_t  sourceBufferSizeBytes,
EPixelType  sourcePixelType,
uint32_t  sourceWidth,
uint32_t  sourceHeight,
size_t  sourcePaddingX,
EImageOrientation  sourceOrientation 
)
virtual

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

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().

Parameters
[out]destinationImageThe destination image.
[in]pSourceBufferThe pointer to the buffer of the source image.
[in]sourceBufferSizeBytesThe size of the buffer of the source image.
[in]sourcePixelTypeThe pixel type of the source image.
[in]sourceWidthThe number of pixels in a row in the source image.
[in]sourceHeightThe number of rows in the source image.
[in]sourcePaddingXThe number of extra data bytes at the end of each row. The default value is usually 0.
[in]sourceOrientationThe 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.
virtual void Pylon::CImageFormatConverter::Convert ( void *  pDestinationBuffer,
size_t  destinationBufferSizeBytes,
const IImage sourceImage 
)
virtual

Creates a new image by converting an image to a different 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.

Parameters
[out]pDestinationBufferThe pointer to the buffer of the destination image.
[in]destinationBufferSizeBytesThe size of the buffer of the destination image.
[in]sourceImageThe 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.
virtual void Pylon::CImageFormatConverter::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 
)
virtual

Creates a new image by converting an image to a different 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.

Parameters
[out]pDestinationBufferThe pointer to the buffer of the destination image.
[in]destinationBufferSizeBytesThe size of the buffer of the destination image.
[in]pSourceBufferThe pointer to the buffer of the source image.
[in]sourceBufferSizeBytesThe size of the buffer of the source image.
[in]sourcePixelTypeThe pixel type of the source image.
[in]sourceWidthThe number of pixels in a row in the source image.
[in]sourceHeightThe number of rows in the source image.
[in]sourcePaddingXThe number of extra data bytes at the end of each row. The default value is usually 0.
[in]sourceOrientationThe 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.
virtual size_t Pylon::CImageFormatConverter::GetBufferSizeForConversion ( const IImage sourceImage) const
virtual

Computes the size of the destination image buffer in byte.

Parameters
[in]sourceImageThe source image, e.g. a CPylonImage, CPylonBitmapImage, or Grab Result Smart Pointer object.
Returns
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.
virtual size_t Pylon::CImageFormatConverter::GetBufferSizeForConversion ( EPixelType  sourcePixelType,
uint32_t  sourceWidth,
uint32_t  sourceHeight 
) const
virtual

Computes the size of the destination image buffer in byte.

Parameters
[in]sourceWidthThe number of pixels in a row in the source image.
[in]sourceHeightThe number of rows in the source image.
[in]sourcePixelTypeThe pixel type of the source image.
Returns
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.
virtual GenApi::INodeMap& Pylon::CImageFormatConverter::GetNodeMap ( )
virtual

Provides access to the node map of the format converter.

Returns
Reference to the node map of the format converter.
Error Safety:
Does not throw C++ exceptions.
virtual bool Pylon::CImageFormatConverter::ImageHasDestinationFormat ( const IImage sourceImage) const
virtual

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

Parameters
[in]sourceImageThe source image, e.g. a CPylonImage, CPylonBitmapImage, or Grab Result Smart Pointer object.
Returns
Returns true if the source image already has the desired format.

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.

Error Safety:
Does not throw C++ exceptions.
virtual bool Pylon::CImageFormatConverter::ImageHasDestinationFormat ( EPixelType  sourcePixelType,
size_t  sourcePaddingX,
EImageOrientation  sourceOrientation 
) const
virtual

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

Parameters
[in]sourcePixelTypeThe pixel type of the source image.
[in]sourcePaddingXThe number of extra data bytes at the end of each row. The default value is usually 0.
[in]sourceOrientationThe vertical orientation of the image in the image buffer. The default value is usually ImageOrientation_TopDown.
Returns
Returns true if the source image already has the desired format. This is done according to the current converter settings.

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.

Error Safety:
Does not throw C++ exceptions.
virtual void Pylon::CImageFormatConverter::Initialize ( EPixelType  sourcePixelType)
virtual

Optionally initializes the image format converter before conversion.

Parameters
[in]sourcePixelTypeThe pixel type of the source image.
  • 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.
Precondition
  • The converter parameters are set up.
  • The pixelTypeSource must be supported by the converter.

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.

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.
virtual bool Pylon::CImageFormatConverter::IsInitialized ( EPixelType  sourcePixelType) const
virtual

Returns information about the converter being initialized.

Parameters
[in]sourcePixelTypeThe pixel type of the source image.

The result depends on the converter settings.

Returns
True if initialized.
Error Safety:
Does not throw C++ exceptions.
static bool Pylon::CImageFormatConverter::IsSupportedInputFormat ( EPixelType  sourcePixelType)
static

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

Parameters
[in]sourcePixelTypeThe pixel type of the source image.
Error Safety:
Does not throw C++ exceptions.
static bool Pylon::CImageFormatConverter::IsSupportedOutputFormat ( EPixelType  destinationPixelType)
static

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

Parameters
[in]destinationPixelTypeThe pixel type of the destination image.
Error Safety:
Does not throw C++ exceptions.
virtual void Pylon::CImageFormatConverter::Uninitialize ( )
virtual

Destroys data structures required for conversion.

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

Error Safety:
Does not throw C++ exceptions.

Member Data Documentation

GenApi::IInteger& Basler_ImageFormatConverterParams::CImageFormatConverterParams_Params::AdditionalLeftShift
inherited

Sets the value for additional shifting when converting monochrome images in Truncate mode.

Sets the value for additional shifting when converting monochrome images in Truncate mode. The image data is converted using a lookup table if the parameter value differs from zero. 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

GenApi::IFloat& Basler_ImageFormatConverterParams::CImageFormatConverterParams_Params::Gamma
inherited

Sets the gamma value for converting monochrome images.

Sets the gamma value for converting monochrome images. The image data is converted using a lookup table. The values of the lookup table are computed using the following formula: valueOut = min((((valueIn ^ Gamma) / (valueInMax ^ Gamma)) * valueOutMax), valueOutMax).

Visibility = Beginner

GenApi::IEnumerationT<InconvertibleEdgeHandlingEnums >& Basler_ImageFormatConverterParams::CImageFormatConverterParams_Params::InconvertibleEdgeHandling
inherited

Sets the handling for rows and columns that cannot be converted.

Sets the handling for rows and columns that cannot be converted.

Visibility = Beginner

GenApi::IEnumerationT<MonoConversionMethodEnums >& Basler_ImageFormatConverterParams::CImageFormatConverterParams_Params::MonoConversionMethod
inherited

Sets the conversion method for monochrome images.

Sets the conversion method for monochrome images.

Visibility = Beginner

GenApi::IEnumerationT<OutputBitAlignmentEnums >& Basler_ImageFormatConverterParams::CImageFormatConverterParams_Params::OutputBitAlignment
inherited

Controls the alignment of the bits in the target pixel type.

Controls the alignment of the bits in the target pixel type if the target value has more bits than the source value.

Visibility = Beginner

GenApi::IEnumerationT<OutputOrientationEnums >& Basler_ImageFormatConverterParams::CImageFormatConverterParams_Params::OutputOrientation
inherited

Defines the vertical orientation of the output image in memory.

Defines the vertical orientation of the output image in memory.

Visibility = Beginner

GenApi::IInteger& Basler_ImageFormatConverterParams::CImageFormatConverterParams_Params::OutputPaddingX
inherited

The number of additional data bytes at the end of each line.

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

Visibility = Beginner

IOutputPixelFormatEnum& Pylon::CImageFormatConverter::OutputPixelFormat

The pixel data format of the output image.

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.

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.

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

pylon 5.0.5
Copyright © 2006-2016 Basler AG (Thu Aug 11 2016 18:01:28)