Pylon::CInstantCameraArray#

Module: Instant Camera

Supports grabbing with multiple camera devices. More…

#include <pylon/InstantCameraArray.h>

Inherited by Pylon::CDeviceSpecificInstantCameraArrayT< CBaslerUniversalInstantCamera >, Pylon::CDeviceSpecificInstantCameraArrayT< CameraT >

Public Types#

Public Functions#

Protected Functions#

Detailed Description#

class Pylon::CInstantCameraArray;

Supports grabbing with multiple camera devices.

Thread Safety:

The CInstantCameraArray class is not thread-safe.

Public Types Documentation#

typedef InstantCamera_t#

typedef CInstantCamera Pylon::CInstantCameraArray::InstantCamera_t;

The type of the camera class in the array.

Public Functions Documentation#

function CInstantCameraArray#

CInstantCameraArray()

Creates an Instant Camera Array of size 0.

Error Safety:

Does not throw C++ exceptions.

Initialize() can be used to adjust the size of the array.

function CInstantCameraArray#

CInstantCameraArray(
    size_t numberOfCameras
)

Creates an Instant Camera Array.

Parameters:

• numberOfCameras The number of cameras the array shall hold. Can be 0.

Error Safety:

Does not throw C++ exceptions, except when memory allocation fails.

Calls Initialize() to adjust the size of the array.

The index operator can be used to access the individual cameras for attaching a Pylon Device or for configuration.

Example:

// Create an array of two devices.
CInstantCamera array(2);
// Attach Pylon Devices.
array[0].Attach( pDevice1);
array[1].Attach( pDevice2);

function ~CInstantCameraArray#

virtual ~CInstantCameraArray()

Destroys the Instant Camera Array.

Error Safety:

Does not throw C++ exceptions.

If a grab is in progress, it is stopped by calling StopGrabbing().

function Initialize#

virtual void Initialize(
    size_t numberOfCameras
)

Initializes the array.

Parameters:

• numberOfCameras The number of cameras the array shall hold.

Error Safety:

Does not throw C++ exceptions, except when memory allocation fails.

• If a grab is in progress, it is stopped by calling StopGrabbing().
• All cameras of the array are destroyed.
• A new set of cameras is created. No Pylon Devices are attached.
• The camera context values are set to the index of the camera in the array using CInstantCamera::SetCameraContext. The index operator can be used to access the individual cameras for attaching a Pylon Device or for configuration.

function IsPylonDeviceAttached#

virtual bool IsPylonDeviceAttached() const

Returns the attachment state of cameras in the array.

Return: True if all cameras in the array have a Pylon Device attached. False is returned if the size of the array is 0.

Error Safety:

Does not throw C++ exceptions.

function IsCameraDeviceRemoved#

virtual bool IsCameraDeviceRemoved() const

Returns the connection state of the camera devices used by the Instant Cameras in the array.

Return: True if the camera device removal from the PC for any camera in the array has been detected.

Error Safety:

Does not throw C++ exceptions.

The device removal is only detected if the Instant Cameras and therefore the attached Pylon Devices are open.

The Pylon Device is not operable after this event. After it is made sure that no access to the Pylon Device or any of its node maps is made anymore the Pylon Device should be destroyed using InstantCamera::DeviceDestroy(). The access to the Pylon Device can be protected using the lock provided by GetLock(), e.g. when accessing parameters.

function DestroyDevice#

virtual void DestroyDevice()

Destroys the Pylon Devices that are attached to the Instant Cameras in the array.

Postcondition: No Pylon Devices are attached to the cameras in the array.

Attention: The node maps, e.g. the camera node map, of the attached Pylon Device must not be accessed anymore while destroying the Pylon Device.

Error Safety:

Does not throw C++ exceptions.

• If a grab is in progress, it is stopped by calling StopGrabbing().
• DestroyDevice is called for all cameras. See CInstantCamera::DestroyDevice() for more information.

function DetachDevice#

virtual void DetachDevice()

Detaches all Pylon Devices that are attached to the Instant Cameras in the array.

Postcondition:

• No Pylon Devices are attached to the cameras in the array.
• The ownership of the Pylon Devices goes to the caller who is responsible for destroying the Pylon Devices.

Error Safety:

Does not throw C++ exceptions.

• If a grab is in progress, it is stopped by calling StopGrabbing().
• DetachDevice is called for all cameras, see CInstantCamera::DetachDevice() for more information.

function Open#

virtual void Open()

Opens all cameras in the array.

Precondition:

• The size of the array is larger than 0.
• All devices are attached.

Postcondition: The cameras are open.

Error Safety:

If one camera throws an exception, all cameras are closed by calling Close().

Open is called for all cameras. See CInstantCamera::Open() for more information.

function IsOpen#

virtual bool IsOpen() const

Returns the open state of the cameras in the array.

Return: Returns true if all cameras in the array are open. False is returned if the size of the array is 0.

Error Safety: Does not throw C++ exceptions.

function Close#

virtual void Close()

Closes all cameras in the array.

Postcondition: All cameras in the array are closed.

Error Safety:

Does not throw C++ exceptions.

• If a grab is in progress, it is stopped by calling StopGrabbing().
• Close is called for all cameras, see CInstantCamera::Close() for more information.

function GetSize#

virtual size_t GetSize() const

Returns the size of the array.

Error Safety:

Does not throw C++ exceptions.

function operator[]#

virtual CInstantCamera & operator[](
    size_t index
)

Retrieve a camera by index.

Precondition: The index is smaller than GetSize();

Error Safety:

Throws an exception if the index is not valid.

Reimplemented by: Pylon::CBaslerUniversalInstantCameraArray::operator[], Pylon::CBaslerUniversalInstantCameraArray::operator[]

function operator[]#

virtual const CInstantCamera & operator[](
    size_t index
) const

Retrieve a camera by index.

Precondition: The index is smaller than GetSize();

Error Safety:

Throws an exception if the index is not valid.

Reimplemented by: Pylon::CBaslerUniversalInstantCameraArray::operator[], Pylon::CBaslerUniversalInstantCameraArray::operator[]

function StartGrabbing#

virtual void StartGrabbing(
    EGrabStrategy strategy =GrabStrategy_OneByOne,
    EGrabLoop grabLoopType =GrabLoop_ProvidedByUser
)

Starts the grabbing of images for all cameras.

Parameters:

• strategy The grab strategy, see Pylon::InstantCamera::EStrategy for more information.
• grabLoopType Indicates using the internal grab thread of the camera.

Precondition:

• The size of the array is larger than 0.
• All devices are attached.
• The grabbing is stopped.
• The preconditions for calling StartGrabbing() are met for every camera in the array.

Postcondition: The grabbing is started.

Error Safety:

The camera objects may throw an exception. The grabbing is stopped calling StopGrabbing() in this case.

• StartGrabbing is called for all cameras with the provided parameters, see CInstantCamera::StartGrabbing() for more information.
• The grabbing is started.
• The starting position for retrieving results is set to the first camera.

function RetrieveResult#

virtual bool RetrieveResult(
    unsigned int timeoutMs,
    CGrabResultPtr & grabResult,
    ETimeoutHandling timeoutHandling =TimeoutHandling_ThrowException
)

Retrieves a grab result according to the strategy, waits if it is not yet available.

Parameters:

• timeoutMs A timeout value in ms for waiting for a grab result, or the INFINITE value.
• grabResult Receives the grab result.
• timeoutHandling If timeoutHandling equals TimeoutHandling_ThrowException, a timeout exception is thrown on timeout.

Return: True if the call successfully retrieved a grab result, false otherwise.

Precondition: The preconditions for calling StartGrabbing() are met for every camera in the array.

Postcondition:

• If successful, one image is removed from the output queue of a camera and is returned in the grabResult parameter.
• If not successful, an empty grab result is returned in the grabResult parameter.

Error Safety:

The Instant Camera Array object is still valid after error. The grabbing is stopped by calling StopGrabbing() if an exception is thrown.

• The content of the passed grab result is released.
• If the grabbing is not started, the method returns immediately false.
• If GrabStrategy_UpcomingImage strategy: RetrieveResult is called for a camera. Cameras are processed using a round-robin strategy.
• If GrabStrategy_OneByOne, GrabStrategy_LatestImageOnly or GrabStrategy_LatestImages strategy: Pending images or camera events are retrieved. Cameras are processed using a round-robin strategy.
• If GrabStrategy_OneByOne, GrabStrategy_LatestImageOnly or GrabStrategy_LatestImages strategy: Wait for a grab result if it is not yet available. Camera events are handled. The camera array index is assigned to the context value of the instant camera when Initialize() is called. This context value is attached to the result when the result is retrieved and can be obtained using the grab result method GrabResultData::GetCameraContext(). The context value can be used to associate the result with the camera from where it originated.

function StopGrabbing#

virtual void StopGrabbing()

Stops the grabbing of images.

Postcondition: The grabbing is stopped.

Error Safety:

Does not throw C++ exceptions.

Thread Safety:

Can be called while one other thread is polling RetrieveResult() in a IsGrabbing()/RetrieveResult() loop to stop grabbing.

The grabbing is stopped. StopGrabbing is called for all cameras. See CInstantCamera::StopGrabbing() for more information.

function IsGrabbing#

virtual bool IsGrabbing() const

Returns state of grabbing.

Return: Returns true if still grabbing.

Error Safety:

Does not throw C++ exceptions.

The camera array is grabbing after a successful call to StartGrabbing() until StopGrabbing() has been called.

Protected Functions Documentation#

function CreateInstantCamera#

virtual CInstantCamera * CreateInstantCamera()

Reimplemented by: Pylon::CBaslerUniversalInstantCameraArray::CreateInstantCamera, Pylon::CBaslerUniversalInstantCameraArray::CreateInstantCamera

function DestroyInstantCamera#

virtual void DestroyInstantCamera(
    CInstantCamera * pCamera
)

Reimplemented by: Pylon::CBaslerUniversalInstantCameraArray::DestroyInstantCamera, Pylon::CBaslerUniversalInstantCameraArray::DestroyInstantCamera