Image Handling Support#

Besides the Instant Camera classes used for grabbing images pylon offers additional classes that support handling the grabbed images. More…

Classes#

Types#

Functions#

Detailed Description#

Besides the Instant Camera classes used for grabbing images pylon offers additional classes that support handling the grabbed images.

You can find more information here:

• Image Handling Support

Types Documentation#

enum EKeyFrameSelection#

List the possibilities for selecting a key frame when using compression.

enum EImageOrientation#

Defines the vertical orientation of an image in memory.

enum EImageFileFormat#

Lists the available file formats.

enum EPixelType#

Lists the available pixel types.

These pixel types are returned by a grab result and are used by the Image Handling Support classes.

The camera parameter interface classes define additional pixel format enumerations. These pixel format enumerations are different from the enumeration EPixelType pylon uses, e.g. the pylon pixel type PixelType_Mono1packed corresponds to PixelFormat_Mono1packed or PixelFormat_Mono1p. See the documentation of the parameter interface classes for more information.

The camera User's Manual provides more information on pixel formats and the memory layout of the image data.

enum EPixelColorFilter#

Lists the Bayer color filter types.

Functions Documentation#

function IsMonoPacked#

inline bool IsMonoPacked(
    EPixelType pixelType
)

Returns true if the pixel type is Mono and the pixel values are not byte aligned.

function IsBayerPacked#

inline bool IsBayerPacked(
    EPixelType pixelType
)

Returns true if the pixel type is Bayer and the pixel values are not byte aligned.

function IsRGBPacked#

inline bool IsRGBPacked(
    EPixelType pixelType
)

Returns true if the pixel type is RGB and the pixel values are not byte aligned.

function IsBGRPacked#

inline bool IsBGRPacked(
    EPixelType pixelType
)

Returns true if the pixel type is BGR and the pixel values are not byte aligned.

function IsPacked#

inline bool IsPacked(
    EPixelType pixelType
)

Returns true if the pixels of the given pixel type are not byte aligned.

function IsPackedInLsbFormat#

inline bool IsPackedInLsbFormat(
    EPixelType pixelType
)

Returns true if the pixel type is packed in lsb packed format. For lsb packed format, the data is filled lsb first in the lowest address byte (byte 0) starting with the first pixel and continued in the lsb of byte 1 (and so on). See the camera User's Manual or the Pixel Format Naming Convention (PFNC) of the GenICam standard group for more information.

function PlaneCount#

inline uint32_t PlaneCount(
    EPixelType pixelType
)

Returns number of planes in the image composed of the pixel type.

function GetPlanePixelType#

inline EPixelType GetPlanePixelType(
    EPixelType pixelType
)

Returns the pixel type of a plane.

function IsPlanar#

inline bool IsPlanar(
    EPixelType pixelType
)

Returns true if images of the pixel type are divided into multiple planes.

function IsYUVSemiplanar#

inline bool IsYUVSemiplanar(
    EPixelType pixelType
)

Returns true if pixel type is YUV semiplanar.

function GetPixelColorFilter#

inline EPixelColorFilter GetPixelColorFilter(
    EPixelType pixelType
)

Returns the Bayer color filter type.

function BitPerPixel#

uint32_t BitPerPixel(
    EPixelType pixelType
)

Returns the bits needed to store a pixel.

Parameters:

• pixelType The pixel type.

Precondition: The pixel type must be defined.

Error Safety:

Throws an exception when the pixel type is undefined.

BitPerPixel(PixelType_Mono12) returns 16 and BitPerPixel(PixelType_Mono12packed) returns 12 for example.

function SamplesPerPixel#

uint32_t SamplesPerPixel(
    EPixelType pixelType
)

Returns the number of measured values per pixel.

Parameters:

• pixelType The pixel type.

Precondition: The pixel type must be defined. The pixel type is not PixelType_YUV411packed.

Error Safety:

Throws an exception when the pixel type is undefined.

SamplesPerPixel(PixelType_Mono8) returns 1 and SamplesPerPixel(PixelType_RGB8packed) returns 3 for example.

function IsYUV#

inline bool IsYUV(
    EPixelType pixelType
)

Returns true when the pixel type represents a YUV format.

function IsRGBA#

inline bool IsRGBA(
    EPixelType pixelType
)

Returns true when the pixel type represents an RGBA format.

function IsRGB#

inline bool IsRGB(
    EPixelType pixelType
)

Returns true when the pixel type represents an RGB or RGBA format.

function IsBGRA#

inline bool IsBGRA(
    EPixelType pixelType
)

Returns true when the pixel type represents a BGRA format.

function IsBGR#

inline bool IsBGR(
    EPixelType pixelType
)

Returns true when the pixel type represents a BGR or BGRA format.

function IsBayer#

inline bool IsBayer(
    EPixelType pixelType
)

Returns true when the pixel type represents a Bayer format.

function IsMono#

inline bool IsMono(
    EPixelType pixelType
)

Returns true when a given pixel is monochrome, e.g. PixelType_Mono8 or PixelType_BayerGR8.

function IsMonoImage#

inline bool IsMonoImage(
    EPixelType pixelType
)

Returns true when an image using the given pixel type is monochrome, e.g. PixelType_Mono8.

function IsColorImage#

inline bool IsColorImage(
    EPixelType pixelType
)

Returns true when an image using the given pixel type is a color image (RGB/BGR/RGBA/BGRA/ etc or Bayer.

function HasAlpha#

inline bool HasAlpha(
    EPixelType pixelType
)

Returns true when an the image using the given pixel type has an alpha channel.

function IsFloatingPoint#

inline bool IsFloatingPoint(
    EPixelType pixelType
)

Returns true if a given pixel type represents a floating point number.

function GetPixelIncrementX#

inline uint32_t GetPixelIncrementX(
    EPixelType pixelType
)

Returns the minimum step size expressed in pixels for extracting an AOI.

function GetPixelIncrementY#

inline uint32_t GetPixelIncrementY(
    EPixelType pixelType
)

Returns the minimum step size expressed in pixels for extracting an AOI.

function BitDepth#

uint32_t BitDepth(
    EPixelType pixelType
)

Returns the bit depth of a value of the pixel in bits.

Parameters:

• pixelType The pixel type.

Precondition: The pixel type must be valid.

Error Safety:

Throws an exception when the pixel type is undefined.

This may be less than the size needed to store the pixel. BitDepth(PixelType_Mono12) returns 12, BitDepth(PixelType_Mono12packed) returns 12, and BitDepth(PixelType_RGB8packed) returns 8 for example.

function ComputeStride#

bool ComputeStride(
    size_t & strideBytes,
    EPixelType pixelType,
    uint32_t width,
    size_t paddingX =0
)

Computes the stride in byte.

Parameters:

• strideBytes The stride in byte if it can be computed.
• pixelType The pixel type.
• width The number of pixels in a row.
• paddingX The number of additional bytes at the end of a row (byte aligned).

Return: Returns true if the stride can be computed.

Precondition: The width value must be >= 0 and <= _I32_MAX.

Error Safety:

Throws an exception when the preconditions are not met.

The stride indicates the number of bytes between the beginning of one row in an image and the beginning of the next row. For planar pixel types the returned value represents the stride of a plane.

The stride in bytes cannot be computed for packed image format when the stride is not byte aligned and paddingX == 0. If paddingX is larger than zero and the stride without padding is not byte aligned then the rest of the partially filled byte is considered as padding, e.g. pixelType = PixelType_Mono12packed, width = 5, paddingX = 10 results in a stride of 18 Bytes (stride without padding is 5 * BitPerPixel( PixelType_Mono12packed) = 5 * 12 = 60 Bits = 7.5 Bytes).

The stride can also be not computed for planar YUV422 and YUV420 image formats.

See also Pylon::IsPacked().

function ComputePaddingX#

size_t ComputePaddingX(
    size_t strideBytes,
    EPixelType pixelType,
    uint32_t width
)

Computes the padding value from row stride in byte.

Parameters:

• strideBytes The stride in byte.
• pixelType The pixel type.
• width The number of pixels in a row.

Return: Returns the paddingX value for the given stride value (byte aligned).

Precondition:

• The value of strideBytes must be large enough to contain a line described by pixelType and width.
• The pixel type must be valid.
• The width value must be >= 0 and <= _I32_MAX.

Error Safety:

Throws an exception when the preconditions are not met.

function ComputeBufferSize#

size_t ComputeBufferSize(
    EPixelType pixelType,
    uint32_t width,
    uint32_t height,
    size_t paddingX =0
)

Computes the buffer size in byte.

Parameters:

• pixelType The pixel type.
• width The number of pixels in a row.
• height The number of rows in an image.
• paddingX The number of extra data bytes at the end of each row (byte aligned).

Return: The buffer size in byte.

Precondition:

• The pixel type must be valid.
• The width value must be >= 0 and <= _I32_MAX.
• The height value must be >= 0 and <= _I32_MAX.

Error Safety:

Throws an exception when the preconditions are not met.

function GetPixelTypesForUnpacking#

inline bool GetPixelTypesForUnpacking(
    EPixelType pixelTypeSource,
    EPixelType & pixelTypeToImpose,
    EPixelType & pixelTypeTarget
)

Returns the pixel types needed for conversion from packed to unpacked image formats using the CImageFormatConverter class.

Parameters:

• pixelTypeSource The source pixel type.
• pixelTypeToImpose The pixel type that is used for conversion instead of the source pixel type. Returns pixelTypeSource if changing the source pixel type is not needed. Returns PixelType_Undefined if no unpacking is needed.
• pixelTypeTarget The pixel type to which the image pixel data are converted. Returns PixelType_Undefined if no unpacking is needed.

Return: Returns true if the source pixelTypeSource is in packed image format and a conversion is possible.

The following pixel types are supported:

• source: PixelType_Mono1packed target: PixelType_Mono8
• source: PixelType_Mono2packed target: PixelType_Mono8
• source: PixelType_Mono4packed target: PixelType_Mono8
• source: PixelType_Mono10packed target: PixelType_Mono16
• source: PixelType_Mono10p target: PixelType_Mono16
• source: PixelType_Mono12packed target: PixelType_Mono16
• source: PixelType_Mono12p target: PixelType_Mono16
• source: PixelType_BayerGB12Packed imposed: PixelType_Mono12packed target: PixelType_Mono16
• source: PixelType_BayerGR12Packed imposed: PixelType_Mono12packed target: PixelType_Mono16
• source: PixelType_BayerRG12Packed imposed: PixelType_Mono12packed target: PixelType_Mono16
• source: PixelType_BayerBG12Packed imposed: PixelType_Mono12packed target: PixelType_Mono16
• source: PixelType_BayerGB10p imposed: PixelType_Mono10p target: PixelType_Mono16
• source: PixelType_BayerGR10p imposed: PixelType_Mono10p target: PixelType_Mono16
• source: PixelType_BayerRG10p imposed: PixelType_Mono10p target: PixelType_Mono16
• source: PixelType_BayerBG10p imposed: PixelType_Mono10p target: PixelType_Mono16
• source: PixelType_BayerGB12p imposed: PixelType_Mono12p target: PixelType_Mono16
• source: PixelType_BayerGR12p imposed: PixelType_Mono12p target: PixelType_Mono16
• source: PixelType_BayerRG12p imposed: PixelType_Mono12p target: PixelType_Mono16
• source: PixelType_BayerBG12p imposed: PixelType_Mono12p target: PixelType_Mono16

function DisplayImage#

void DisplayImage(
    size_t winIndex,
    const Pylon::IImage & image
)

Convenience function to display an image on screen with one function call.

Parameters:

• winIndex The window used for displaying the image. Valid window indexes range from 0 to 31.
• image The image to display in the window, specified in winIndex. You can also pass a CGrabResultPtr.

Postcondition:

• The window specified by winIndex will be created and shown on the screen.
• If the passed image is valid, it is shown in the window specified by winIndex.
• If the passed image is invalid, the window specified by winIndex will be cleared.

Remark: To use this function, you must explicitly include pylon/PylonGUIIncludes.h in your code. Unlike other pylon headers, the GUI headers will not be included automatically when you include pylon/PylonIncludes.h.

Error Safety:

Can throw an exception if the passed winIndex is invalid or the window could not be created.

Thread Safety:

This function is thread-safe.

This convenience function displays the image or grab result passed in the image parameter in a window on the screen. Using this function is the easiest way to display an image on the screen.

You can pass any IImage based object or a GrabResultPtr. If the window hasn't been created before, it will be created with default positions and the image will be shown. When the function returns, you can free/delete the image. If you need more control over the window creation (e.g. to specify the position or size of the window), you can use the CPylonImageWindow class.

When you pass an empty/invalid (e.g. image.IsValid() returns false) image, the window will be cleared.

// This smart pointer will receive the grab result data.
CGrabResultPtr ptrGrabResult;
// Open the first device.
CInstantCamera Camera( CTlFactory::GetInstance().CreateFirstDevice());
// Grab one image.
Camera.GrabOne( 1000, ptrGrabResult);
// Display the image on the screen. If the grab result is invalid, the image window will be empty.
Pylon::DisplayImage(1, ptrGrabResult);