Pylon::CPylonDataContainer#

Provides methods for accessing grab results consisting of multiple components. More…

#include <pylon/PylonDataContainer.h>

Public Functions#

Detailed Description#

class Pylon::CPylonDataContainer;

Provides methods for accessing grab results consisting of multiple components.

Attention: Any CPylonDataContainer or CPylonDataComponent will hold a reference to the CGrabResultData from which it has been created. To allow the instant camera to reuse the CGrabResultData and prevent buffer underruns, you must destroy the CPylonDataContainer and all its CPylonDataComponent objects.

Thread Safety:

This class is not thread-safe. If you access the same instance from multiple threads, you must make sure to synchronize the access accordingly.

Some cameras can return complex grab results consisting of multiple components. For example, Basler blaze cameras return a data stream that is composed of range, intensity, and confidence components. To access the individual components, you can use the CPylonDataContainer class.

A CPylonDataContainer can hold one or more components. You can obtain a container by calling Pylon::CGrabResultData::GetDataContainer(). You can then use the container to query for the number of components by calling Pylon::CGrabResultData::GetDataComponentCount(). To retrieve a specific component, you can call Pylon::CGrabResultData::GetDataComponent(). Each component in the container can be used to access the actual data, e.g., the range values, and its metadata.

Public Functions Documentation#

function CPylonDataContainer#

explicit CPylonDataContainer(
    const CGrabResultPtr & ptrGrabResult
)

Creates a CPylonDataContainer from a given CGrabResultPtr.

Parameters:

• ptrGrabResult The grab result to create a container from.

Postcondition:

• A new reference to the grab result passed in ptrGrabResult has been set.

Error Safety:

Does not throw an exception if the CGrabResultPtr was invalid or points to an invalid/unsuccessful result. Instead, an empty container is returned. Can throw exceptions if the data in the result is invalid or malformed. Can throw exceptions in low-memory conditions.

Thread Safety:

This class is not thread-safe. If you access the same instance from multiple threads, you must make sure to synchronize the access accordingly.

Creates a CPylonDataContainer from a given CGrabResultPtr. The CPylonDataContainer instance created will hold a reference to the CGrabResultData from which it has been created. To allow the instant camera to reuse the grab result and prevent buffer underruns, you must destroy the CPylonDataContainer.

function CPylonDataContainer#

explicit CPylonDataContainer(
    const GrabResult & grabResult
)

Creates a CPylonDataContainer from a given GrabResult.

Parameters:

• grabResult The grab result to create a container from.

Error Safety:

Does not throw an exception if the GrabResult contains an unsuccessful result. Instead, an empty container is returned. Can throw exceptions if the data in the buffer of the GrabResult is invalid or malformed. Can throw exceptions in low-memory conditions.

Thread Safety:

This class is not thread-safe. If you access the same instance from multiple threads, you must make sure to synchronize the access accordingly.

Creates a CPylonDataContainer from a given GrabResult. The CPylonDataContainer instance created is only valid as long as the associated buffer is not queued or deregistered and deleted.

function CPylonDataContainer#

explicit CPylonDataContainer(
    const Pylon::String_t & filename
)

Creates a CPylonDataContainer by loading the data from the file passed.

Parameters:

• filename Name and path of the file to load.

Postcondition:

• The reference to a previous grab result or buffer has been released.
• A new buffer has been allocated to hold the data loaded.

Error Safety:

Throws an exception if the container cannot be read. Throws an exception if the contents of the file does not contain a valid container.

Thread Safety:

This class is not thread-safe. If you access the same instance from multiple threads, you must make sure to synchronize the access accordingly.

Loads a container and all its components from a file on disk.

function CPylonDataContainer#

CPylonDataContainer()

Creates an empty CPylonDataContainer.

Error Safety:

Can throw exceptions in low-memory conditions.

Thread Safety:

This class is not thread-safe. If you access the same instance from multiple threads, you must make sure to synchronize the access accordingly.

Creates an empty CPylonDataContainer. The CPylonDataContainer instance created will not be valid.

function CPylonDataContainer#

CPylonDataContainer(
    const CPylonDataContainer & rhs
)

Creates a shallow copy of an existing CPylonDataContainer.

Parameters:

• rhs Container to copy from.

Postcondition:

• A new reference to the grab result or buffer of the container passed in rhs has been set.

Error Safety:

Can throw exceptions in low-memory conditions.

Thread Safety:

This class is not thread-safe. If you access the same instance from multiple threads, you must make sure to synchronize the access accordingly.

function ~CPylonDataContainer#

~CPylonDataContainer()

Destroys the CPylonDataContainer instance. If the instance has been created through a GrabResultPtr, the reference to that CGrabResultData will be released.

Postcondition:

• The reference to a grab result or buffer has been released.

Error Safety:

Does not throw C++ exceptions.

Thread Safety:

This class is not thread-safe. If you access the same instance from multiple threads, you must make sure to synchronize the access accordingly.

function operator=#

CPylonDataContainer & operator=(
    const CPylonDataContainer & rhs
)

Assigns a shallow copy of the CPylonDataContainer to this instance.

Parameters:

• rhs CPylonDataContainer to copy data from.

Return: Returns a reference to the current instance.

Postcondition:

• The reference to a previous grab result or buffer has been released.
• A new reference to the grab result or buffer of the container passed in rhs has been set.

Error Safety:

Can throw exceptions in low-memory conditions.

Thread Safety:

This class is not thread-safe. If you access the same instance from multiple threads, you must make sure to synchronize the access accordingly.

function GetDataComponentCount#

size_t GetDataComponentCount() const

Returns the number of components contained in the container.

Return: Returns the number of components contained in the container.

Error Safety:

Does not throw C++ exceptions.

Thread Safety:

This class is not thread-safe. If you access the same instance from multiple threads, you must make sure to synchronize the access accordingly.

You can use the return value to iterate over the existing components by calling Pylon::CPylonDataContainer::GetDataComponent().

function GetDataComponent#

const CPylonDataComponent GetDataComponent(
    const size_t index
) const

Returns a specific component from the container.

Parameters:

• index Index of the component to return. The index must be less than the value returned by Pylon::CPylonDataContainer::GetComponentCount().

Return: Returns the component specified by the index parameter.

Error Safety:

Throws an exception if the index parameter is out of range. Can throw exceptions in low-memory conditions.

Thread Safety:

This class is not thread-safe. If you access the same instance from multiple threads, you must make sure to synchronize the access accordingly.

function Save#

void Save(
    const Pylon::String_t & filename
) const

Saves the container to disk.

Parameters:

• filename Name and path of the file to save the container to.

Precondition: The container must contain at least one component.

Error Safety:

Throws an exception if the container cannot be saved.

Thread Safety:

This class is not thread-safe. If you access the same instance from multiple threads, you must make sure to synchronize the access accordingly.

function Load#

void Load(
    const Pylon::String_t & filename
)

Loads a container from a file.

Parameters:

• filename Name and path of the file to load.

Postcondition:

• The reference to a previous grab result or buffer has been released.
• A new buffer has been allocated to hold the data loaded.

Error Safety:

Throws an exception if the container cannot be read. Throws an exception if the contents of the file does not contain a valid container.

Thread Safety:

This class is not thread-safe. If you access the same instance from multiple threads, you must make sure to synchronize the access accordingly.

Loads a container and all its components from a file on disk.