Pylon::CImageDecompressor#

Provides convenient access to cameras that support image compression and helps with decompressing these images. More…

#include <pylon/ImageDecompressor.h>

Public Functions#

Detailed Description#

class Pylon::CImageDecompressor;

Provides convenient access to cameras that support image compression and helps with decompressing these images.

A decompressor requires a compression descriptor in order to be able to decompress images. You can set a compression descriptor via the constructor or the SetCompressionDescriptor methods (in both cases, either using the node map or manually).

A compression descriptor can be identified via a hash. This hash can be used to identify the matching compression descriptor for a particular compressed image. It can be computed using the ComputeCompressionDescriptorHash method or retrieved from the camera, decompressor, or a grab buffer/result using one of the GetCompressionDescriptorHash methods.

Grab buffers/results may contain different kinds of data. You can use the decompressor's GetCompressionInfo methods to distinguish between them. For that to work, a grab buffer/result must have been received successfully and it must contain the payload type chunk (for grab results you can get the payload type using the GetPayloadType method).

If compression info for the grab buffer/result provided is available, GetCompressionInfo returns true and you will receive the compression info via the CompressionInfo_t struct. If the field hasCompressedImage in the struct is true, the grab buffer/result contains a compressed image. In this case, you should check the compressionStatus field in the struct to check whether the camera was able to compress the image properly. The camera can't compress an image if the amount of data required for compressing the image exceeds the desired compression ratio. The image can be decompressed if compressionStatus is CompressionStatus_Ok. If the field hasCompressedImage in the struct is false, the grab buffer/result contains an already decompressed image. In this case, the decompressedImageSize and decompressedPayloadSize fields will not be used. All other fields contain information about the decompressed data.

Public Functions Documentation#

function CImageDecompressor#

CImageDecompressor()

Creates an empty decompressor without compression descriptor.

Error Safety:

Throws an exception if no memory can be allocated.

This constructor does not initialize the decompressor with a compression descriptor. You will have to initialize the decompressor first by using one of the SetCompressionDescriptor methods in order to be able to decompress images. You will get an exception if you access methods that require the decompressor to be initialized (see method descriptions for which methods are affected by that precondition).

function CImageDecompressor#

explicit CImageDecompressor(
    const CImageDecompressor & imageDecompressor
)

Creates a decompressor by copying from another decompressor.

Parameters:

• imageDecompressor Decompressor to copy from during initialization.

Error Safety:

Throws an exception if no memory can be allocated.

function CImageDecompressor#

CImageDecompressor(
    const void * pCompressionDescriptor,
    size_t sizeCompressionDescriptor
)

Creates a decompressor and initializes it with the compression descriptor provided.

Parameters:

• pCompressionDescriptor Pointer to the compression descriptor. This parameter must not be NULL.
• sizeCompressionDescriptor Size of the data (in bytes) of the compression descriptor.

Error Safety:

Throws an exception if no memory can be allocated or the compression descriptor provided is invalid (e.g., because it is corrupt) or incompatible (e.g., because a compression descriptor of a newer compression implementation is passed).

function CImageDecompressor#

explicit CImageDecompressor(
    GenApi::INodeMap & nodeMap
)

Creates a decompressor and initializes it with a compression descriptor that is retrieved from the camera's node map.

Parameters:

• nodeMap Node map of the camera to be used for retrieving the compression descriptor.

Error Safety:

Throws an exception if no memory can be allocated or no proper compression descriptor can be retrieved from the camera.

function ~CImageDecompressor#

~CImageDecompressor()

Destroys the decompressor instance.

Error Safety:

Does not throw C++ exceptions.

Thread Safety:

This method is thread-safe.

function HasCompressionDescriptor#

bool HasCompressionDescriptor() const

Determines whether the decompressor already has a compression descriptor.

Return: Returns true if the decompressor is already initialized with a compression descriptor or false otherwise.

Error Safety:

Does not throw C++ exceptions.

Thread Safety:

This method is thread-safe.

function ResetCompressionDescriptor#

void ResetCompressionDescriptor()

Resets the compression descriptor in the decompressor.

Note After calling this method, no images can be decompressed by the decompressor because it is back in uninitialized state.

Error Safety:

Does not throw C++ exceptions.

Thread Safety:

This method is thread-safe.

function SetCompressionDescriptor#

void SetCompressionDescriptor(
    const void * pCompressionDescriptor,
    size_t sizeCompressionDescriptor
)

Initializes a decompressor with the compression descriptor provided.

Parameters:

• pCompressionDescriptor Pointer to the compression descriptor. This parameter must not be NULL.
• sizeCompressionDescriptor Size of the data (in bytes) of the compression descriptor.

Error Safety:

Throws an exception if no memory can be allocated or the compression descriptor provided is invalid (e.g., because it is corrupt) or incompatible (e.g., because a compression descriptor of a newer compression implementation is passed).

Thread Safety:

This method is thread-safe.

function SetCompressionDescriptor#

void SetCompressionDescriptor(
    GenApi::INodeMap & nodeMap
)

Initializes a decompressor with a compression descriptor that is retrieved from the camera's node map.

Parameters:

• nodeMap Node map of the camera to be used for retrieving the compression descriptor.

Error Safety:

Throws an exception if no memory can be allocated or no proper compression descriptor can be retrieved from the camera.

Thread Safety:

This method is thread-safe.

function GetCompressionDescriptor#

void GetCompressionDescriptor(
    void * pCompressionDescriptor,
    size_t * pSizeCompressionDescriptor
) const

Gets the currently set compression descriptor.

Parameters:

• pCompressionDescriptor Pointer to the buffer that will receive the compression descriptor or NULL if you only want to get the size of the buffer for buffer allocation.
• pSizeCompressionDescriptor On input, the variable specifies the size of the buffer (in bytes) for the compression descriptor (if pCompressionDescriptor is not NULL). On output, the variable will receive the actual buffer size required for the current compression descriptor. This parameter must not be NULL.

Error Safety:

Throws an exception if the decompressor has no compression descriptor set or the input parameters are invalid (e.g., if the size provided is not sufficient to hold the compression descriptor).

Thread Safety:

This method is thread-safe.

This method requires that a compression descriptor has been set previously via the constructor or the SetCompressionDescriptor methods. You can determine this via the HasCompressionDescriptor method.

function GetCompressionDescriptorHash#

void GetCompressionDescriptorHash(
    void * pHash,
    size_t * pSizeHash
) const

Gets the hash of the currently set compression descriptor.

Parameters:

• pHash Pointer to the buffer that will receive the compression descriptor hash or NULL if you only want to get the size of the buffer for buffer allocation.
• pSizeHash On input, the variable specifies the size of the buffer (in bytes) for the compression descriptor hash (if pHash is not NULL). On output, the variable will receive the actual buffer size required for the current compression descriptor hash. This parameter must not be NULL.

Error Safety:

Throws an exception if the decompressor has no compression descriptor set or the input parameters are invalid (e.g., if the size provided is not sufficient to hold the compression descriptor hash).

Thread Safety:

This method is thread-safe.

This method requires that a compression descriptor has been set previously via the constructor or the SetCompressionDescriptor methods. You can determine this via the HasCompressionDescriptor method.

function DecompressImage#

CompressionInfo_t DecompressImage(
    void * pOutputBuffer,
    size_t * pSizeOutputBuffer,
    const void * pGrabBuffer,
    size_t payloadSize
) const

Decompresses the image of the grab buffer provided.

Parameters:

• pOutputBuffer Pointer to the buffer that will receive the decompressed image. This parameter must not be NULL.
• pSizeOutputBuffer On input, the variable specifies the size of the buffer (in bytes) for the decompressed image (must be larger or equal to the value in the decompressedImageSize field in the CompressionInfo_t struct received via the GetCompressionInfo methods; alternatively, the GetImageSizeForDecompression method can be used to get the image size required for decompression). On output, the variable will receive the actual buffer size required for the decompressed image. This parameter must not be NULL.
• pGrabBuffer Pointer to the grab buffer that holds the compressed data. This parameter must not be NULL.
• payloadSize Payload size (in bytes) of the data received (must be less or equal to the size of the grab buffer).

Return: Returns the struct with the compression information of the compressed image.

Error Safety:

Throws an exception if the grab buffer does not contain compressed data, the data is corrupt, the image cannot be decompressed, or the input parameters are invalid (e.g., if the size provided is not sufficient to hold the decompressed image).

Thread Safety:

This method is thread-safe.

This method requires that a compression descriptor has been set previously via the constructor or the SetCompressionDescriptor methods. You can determine this via the HasCompressionDescriptor method.

The grab buffer provided must contain a compressed image that has been received without errors.

function DecompressImage#

CompressionInfo_t DecompressImage(
    void * pOutputBuffer,
    size_t * pSizeOutputBuffer,
    const Pylon::GrabResult & grabResult
) const

Decompresses the image of the grab result provided.

Parameters:

• pOutputBuffer Pointer to the buffer that will receive the decompressed image. This parameter must not be NULL.
• pSizeOutputBuffer On input, the variable specifies the size of the buffer (in bytes) for the decompressed image (must be larger or equal to the value in the decompressedImageSize field in the CompressionInfo_t struct received via the GetCompressionInfo methods; alternatively, the GetImageSizeForDecompression method can be used to get the image size required for decompression). On output, the variable will receive the actual buffer size required for the decompressed image. This parameter must not be NULL.
• grabResult Grab result that holds the compressed data.

Return: Returns the struct with the compression information about the compressed image.

Error Safety:

Throws an exception if the grab result does not contain compressed data, the data is corrupt, the image cannot be decompressed or the input parameters are invalid (e.g., if the size provided is not sufficient to hold the decompressed image).

Thread Safety:

This method is thread-safe.

This method requires that a compression descriptor has been set previously via the constructor or the SetCompressionDescriptor methods. You can determine this via the HasCompressionDescriptor method.

The grab result provided must contain a compressed image that has been received without errors.

function DecompressImage#

CompressionInfo_t DecompressImage(
    void * pOutputBuffer,
    size_t * pSizeOutputBuffer,
    const Pylon::CGrabResultPtr grabResultPtr
) const

Decompresses the image of the grab result provided.

Parameters:

• pOutputBuffer Pointer to the buffer that will receive the decompressed image. This parameter must not be NULL.
• pSizeOutputBuffer On input, the variable specifies the size of the buffer (in bytes) for the decompressed image (must be larger or equal to the value in the decompressedImageSize field in the CompressionInfo_t struct received via the GetCompressionInfo methods; alternatively, the GetImageSizeForDecompression method can be used to get the image size required for decompression). On output, the variable will receive the actual buffer size required for the decompressed image. This parameter must not be NULL.
• grabResultPtr Pointer to grab result that holds the compressed data.

Return: Returns the struct with the compression information about the compressed image.

Error Safety:

Throws an exception if the grab result does not contain compressed data, the data is corrupt, the image cannot be decompressed or the input parameters are invalid (e.g., if the size provided is not sufficient to hold the decompressed image).

Thread Safety:

This method is thread-safe.

This method requires that a compression descriptor has been set previously via the constructor or the SetCompressionDescriptor methods. You can determine this via the HasCompressionDescriptor method.

The grab result provided must contain a compressed image that has been received without errors.

function DecompressImage#

CompressionInfo_t DecompressImage(
    IReusableImage & destinationImage,
    const void * pGrabBuffer,
    size_t payloadSize
) const

Decompresses the image of the grab buffer provided.

Parameters:

• destinationImage Image object (e.g., instance of CPylonImage) that will be filled with the decompressed image (will be resized if required).
• pGrabBuffer Pointer to the grab buffer that holds the compressed data. This parameter must not be NULL.
• payloadSize Payload size (in bytes) of the data received (must be less or equal to the size of the grab buffer).

Return: Returns the struct with the compression information about the compressed image.

Error Safety:

Throws an exception if the grab buffer does not contain compressed data, the data is corrupt, the image cannot be decompressed or the input parameters are invalid.

Thread Safety:

This method is thread-safe.

This method requires that a compression descriptor has been set previously via the constructor or the SetCompressionDescriptor methods. You can determine this via the HasCompressionDescriptor method.

The grab buffer provided must contain a compressed image that has been received without errors.

function DecompressImage#

CompressionInfo_t DecompressImage(
    IReusableImage & destinationImage,
    const Pylon::GrabResult & grabResult
) const

Decompresses the image of the grab result provided.

Parameters:

• destinationImage Image object (e.g., instance of CPylonImage) that will be filled with the decompressed image (will be resized if required).
• grabResult Grab result that holds the compressed data.

Return: Returns the struct with the compression information about the compressed image.

Error Safety:

Throws an exception if the grab result does not contain compressed data, the data is corrupt, the image cannot be decompressed, or the input parameters are invalid.

Thread Safety:

This method is thread-safe.

This method requires that a compression descriptor has been set previously via the constructor or the SetCompressionDescriptor methods. You can determine this via the HasCompressionDescriptor method.

The grab result provided must contain a compressed image that has been received without errors.

function DecompressImage#

CompressionInfo_t DecompressImage(
    IReusableImage & destinationImage,
    const Pylon::CGrabResultPtr grabResultPtr
) const

Decompresses the image of the grab result provided.

Parameters:

• destinationImage Image object (e.g., instance of CPylonImage) that will be filled with the decompressed image (will be resized if required).
• grabResultPtr Pointer to grab result that holds the compressed data.

Return: Returns the struct with the compression information about the compressed image.

Error Safety:

Throws an exception if the grab result does not contain compressed data, the data is corrupt, the image cannot be decompressed, or the input parameters are invalid.

Thread Safety:

This method is thread-safe.

This method requires that a compression descriptor has been set previously via the constructor or the SetCompressionDescriptor methods. You can determine this via the HasCompressionDescriptor method.

The grab result provided must contain a compressed image that has been received without errors.

function operator=#

CImageDecompressor & operator=(
    const CImageDecompressor & imageDecompressor
)

Copies the decompressor.

Parameters:

• imageDecompressor The source decompressor.

Return: Returns a reference to the destination decompressor.

Error Safety:

Does not throw C++ exceptions.

Thread Safety:

This method is thread-safe.

function operator==#

bool operator==(
    const CImageDecompressor & imageDecompressor
)

Compares this instance with another decompressor.

Parameters:

• imageDecompressor The decompressor on the right-hand side of the comparison.

Return: True if both decompressors are equal or false otherwise.

Error Safety:

Does not throw C++ exceptions.

Thread Safety:

This method is thread-safe.

function GetCompressionMode#

static ECompressionMode GetCompressionMode(
    GenApi::INodeMap & nodeMap
)

Retrieves the current compression mode from the camera's node map.

Parameters:

• nodeMap Node map of the camera to be used for retrieving the compression mode.

Return: Returns the current compression mode of the camera.

Error Safety:

Throws an exception if an error is encountered while determining the compression mode.

Thread Safety:

This method is thread-safe.

This indicates which kind of compression is active or whether compression is not enabled (or unavailable).

function GetCompressionDescriptor#

static void GetCompressionDescriptor(
    void * pCompressionDescriptor,
    size_t * pSizeCompressionDescriptor,
    GenApi::INodeMap & nodeMap
)

Gets the current compression descriptor from the camera's node map.

Parameters:

• pCompressionDescriptor Pointer to the buffer that will receive the compression descriptor or NULL if you only want to get the size of the buffer for buffer allocation.
• pSizeCompressionDescriptor On input, the variable specifies the size of the buffer (in bytes) for the compression descriptor (if pCompressionDescriptor is not NULL). On output, the variable will receive the actual buffer size required for the current compression descriptor. This parameter must not be NULL.
• nodeMap Node map of the camera to be used for retrieving the compression descriptor.

Error Safety:

Throws an exception if compression is not enabled in the camera (or unavailable) or the input parameters are invalid (e.g., if the size provided is not sufficient to hold the compression descriptor).

Thread Safety:

This method is thread-safe.

This method requires image compression to be enabled in the camera. You can determine this via the GetCompressionMode method.

function GetCompressionInfo#

static bool GetCompressionInfo(
    CompressionInfo_t & compressionInfo,
    const void * pGrabBuffer,
    size_t payloadSize,
    EEndianness endianness =Endianness_Auto
)

Gets compression information about a grab buffer.

Parameters:

• compressionInfo Reference to the struct that will receive the compression information if the grab buffer contains such information.
• pGrabBuffer Pointer to the grab buffer that holds the compressed data. This parameter must not be NULL.
• payloadSize Payload size (in bytes) of the data received (must be less or equal to the size of the grab buffer).
• endianness Endianness of the grab buffer's content. If not known, auto detection can be used.

Return: Returns true if compression information could be extracted from the the grab buffer or false otherwise.

Error Safety:

Throws an exception if the input parameters are invalid.

Thread Safety:

This method is thread-safe.

function GetCompressionInfo#

static bool GetCompressionInfo(
    CompressionInfo_t & compressionInfo,
    const Pylon::GrabResult & grabResult,
    EEndianness endianness =Endianness_Auto
)

Gets compression information about a grab result.

Parameters:

• compressionInfo Reference to the struct that will receive the compression information if the grab result contains such information.
• grabResult Grab result that holds the compressed data.
• endianness Endianness of the grab result content. If not known, auto detection can be used.

Return: Returns true if compression information could be extracted from the the grab result or false otherwise.

Error Safety:

Throws an exception if the input parameters are invalid.

Thread Safety:

This method is thread-safe.

function GetCompressionInfo#

static bool GetCompressionInfo(
    CompressionInfo_t & compressionInfo,
    const Pylon::CGrabResultPtr grabResultPtr,
    EEndianness endianness =Endianness_Auto
)

Gets compression information about a grab result.

Parameters:

• compressionInfo Reference to the struct that will receive the compression information if the grab result contains such information.
• grabResultPtr Pointer to grab result that holds the compressed data.
• endianness Endianness of the grab result content. If not known, auto detection can be used.

Return: Returns true if compression information could be extracted from the the grab result or false otherwise.

Error Safety:

Throws an exception if the input parameters are invalid.

Thread Safety:

This method is thread-safe.

function ComputeCompressionDescriptorHash#

static void ComputeCompressionDescriptorHash(
    void * pHash,
    size_t * pSizeHash,
    const void * pCompressionDescriptor,
    size_t sizeCompressionDescriptor
)

Computes the hash for a given compression descriptor.

Parameters:

• pHash Pointer to the buffer that will receive the compression descriptor hash or NULL if you only want to get the size of the buffer for buffer allocation.
• pSizeHash On input, the variable specifies the size of the buffer (in bytes) for the compression descriptor hash (if pHash is not NULL). On output, the variable will receive the actual buffer size required for the current compression descriptor hash. This parameter must not be NULL.
• pCompressionDescriptor Pointer to the compression descriptor. This parameter must not be NULL.
• sizeCompressionDescriptor Size of the data (in bytes) of the compression descriptor.

Error Safety:

Throws an exception if the input parameters are invalid (e.g., if the size provided is not sufficient to hold the compression descriptor hash).

Thread Safety:

This method is thread-safe.

function GetCompressionDescriptorHash#

static void GetCompressionDescriptorHash(
    void * pHash,
    size_t * pSizeHash,
    GenApi::INodeMap & nodeMap
)

Gets the hash of the current compression descriptor from the camera's node map.

Parameters:

• pHash Pointer to the buffer that will receive the compression descriptor hash or NULL if you only want to get the size of the buffer for buffer allocation.
• pSizeHash On input, the variable specifies the size of the buffer (in bytes) for the compression descriptor hash (if pHash is not NULL). On output, the variable will receive the actual buffer size required for the current compression descriptor hash. This parameter must not be NULL.
• nodeMap Node map of the camera to be used for retrieving the compression descriptor hash.

Error Safety:

Throws an exception if compression is not active in the camera (or unavailable) or the input parameters are invalid (e.g., if the size provided is not sufficient to hold the compression descriptor hash).

Thread Safety:

This method is thread-safe.

This method requires image compression to be enabled in the camera. You can determine this via the GetCompressionMode method.

function GetCompressionDescriptorHash#

static void GetCompressionDescriptorHash(
    void * pHash,
    size_t * pSizeHash,
    const void * pGrabBuffer,
    size_t payloadSize,
    EEndianness endianness =Endianness_Auto
)

Gets the hash of the compression descriptor that is required for decompressing the grab buffer provided.

Parameters:

• pHash Pointer to the buffer that will receive the compression descriptor hash or NULL if you only want to get the size of the buffer for buffer allocation.
• pSizeHash On input, the variable specifies the size of the buffer (in bytes) for the compression descriptor hash (if pHash is not NULL). On output, the variable will receive the actual buffer size required for the current compression descriptor hash. This parameter must not be NULL.
• pGrabBuffer Pointer to the grab buffer that holds the compressed data. This parameter must not be NULL.
• payloadSize Payload size (in bytes) of the data received (must be less or equal to the size of the grab buffer).
• endianness Endianness of the grab buffer's content. If not known, auto detection can be used.

Error Safety:

Throws an exception if the grab buffer does not contain compressed data, the data is corrupt, or the input parameters are invalid (e.g., if the size provided is not sufficient to hold the compression descriptor hash).

Thread Safety:

This method is thread-safe.

function GetCompressionDescriptorHash#

static void GetCompressionDescriptorHash(
    void * pHash,
    size_t * pSizeHash,
    const Pylon::GrabResult & grabResult,
    EEndianness endianness =Endianness_Auto
)

Gets the hash of the compression descriptor that is required for decompressing the grab result provided.

Parameters:

• pHash Pointer to the buffer that will receive the compression descriptor hash or NULL if you only want to get the size of the buffer for buffer allocation.
• pSizeHash On input, the variable specifies the size of the buffer (in bytes) for the compression descriptor hash (if pHash is not NULL). On output, the variable will receive the actual buffer size required for the current compression descriptor hash. This parameter must not be NULL.
• grabResult Grab result that holds the compressed data.
• endianness Endianness of the grab result content. If not known, auto detection can be used.

Error Safety:

Throws an exception if the grab result does not contain compressed data, the data is corrupt, or the input parameters are invalid (e.g., if the size provided is not sufficient to hold the compression descriptor hash).

Thread Safety:

This method is thread-safe.

function GetCompressionDescriptorHash#

static void GetCompressionDescriptorHash(
    void * pHash,
    size_t * pSizeHash,
    const Pylon::CGrabResultPtr grabResultPtr,
    EEndianness endianness =Endianness_Auto
)

Gets the hash of the compression descriptor that is required for decompressing the grab result provided.

Parameters:

• pHash Pointer to the buffer that will receive the compression descriptor hash or NULL if you only want to get the size of the buffer for buffer allocation.
• pSizeHash On input, the variable specifies the size of the buffer (in bytes) for the compression descriptor hash (if pHash is not NULL). On output, the variable will receive the actual buffer size required for the current compression descriptor hash. This parameter must not be NULL.
• grabResultPtr Pointer to grab result that holds the compressed data.
• endianness Endianness of the grab result content. If not known, auto detection can be used.

Error Safety:

Throws an exception if the grab result does not contain compressed data, the data is corrupt, or the input parameters are invalid (e.g., if the size provided is not sufficient to hold the compression descriptor hash).

Thread Safety:

This method is thread-safe.

function GetImageSizeForDecompression#

static size_t GetImageSizeForDecompression(
    GenApi::INodeMap & nodeMap
)

Gets size (in bytes) required for allocating buffers for decompressing the images during streaming.

Parameters:

• nodeMap Node map of the camera to be used for retrieving the image size required for decompression.

Return: Returns the buffer size (in bytes) required for image decompression.

Error Safety:

Throws an exception if an error is encountered while determining the image size required for decompression.

Thread Safety:

This method is thread-safe.

This method requires image compression to be enabled in the camera. You can determine this via the GetCompressionMode method.