Back to Aurora Vision Studio website

You are here: Start » Filter Reference » GenICam » GenICam_MultiDevice_GrabImages

GenICam_MultiDevice_GrabImages


Module: Genicam

Captures frame streams from multiple synchronously triggered general cameras using GenICam GenTL provider library.

Name Type Range Description
Input value inAddress1 GenAddress GenTL Provider module and device identifying address of first device
Input value inAddress2 GenAddress GenTL Provider module and device identifying address of second device
Input value inAddress3 GenAddress* GenTL Provider module and device identifying address of third device
Input value inAddress4 GenAddress* GenTL Provider module and device identifying address of fourth device
Input value inAddress5 GenAddress* GenTL Provider module and device identifying address of fifth device
Input value inAddress6 GenAddress* GenTL Provider module and device identifying address of sixth device
Input value inPixelFormat GenPixelFormat Requested Pixel Format in GenICam pixel naming convention
Input value inInputQueueSize Integer 1 - 50 Number of incoming frames that can be buffered before the application is able to process them
Input value inMaxTimeDiff Integer 30 - 3600000 Maximum time difference between received frames in milliseconds
Input value inTimeout Integer* 200 - 3600000 Maximum time to receive first frame
Output value outFrame1 Image? Captured frame from first device
Output value outFrame2 Image? Captured frame from second device
Output value outFrame3 Image? Captured frame from third device
Output value outFrame4 Image? Captured frame from fourth device
Output value outFrame5 Image? Captured frame from fifth device
Output value outFrame6 Image? Captured frame from sixth device
Diagnostic input diagCurrentTimeDiff Integer Time difference between receive of currently captured frames

Description

This filter is intended for establishing connection with and streaming images from up to six general camera devices working with a single common trigger source (synchronously triggered) through a GenTL compliant interface. It is intended to be used in systems with from two to six cameras (configured to work with an external trigger source), in which a single signal source is triggering all cameras synchronously and images from this trigger events must be received with their synchronization maintained.

This filter is an equivalent of six combined GenICam_GrabImage_WithTimeout filters, that additionally helps to start streaming in multiple cameras at once, helps to maintain synchronization between cameras working with common trigger signal (e.g. in a situation when one of the frames in the set captured after the trigger is dropped due to network errors), and allows to define a single timeout value to wait for all cameras at once.

For cameras using Ethernet as a communication interface special caution must be paid when connecting multiple cameras to a single computer. Such systems may require additional configuration of the cameras in order to properly utilize network throughput or computer hardware. For more information refer to the Connecting Multiple Devices to a Single Computer section of Connecting Device.

In the first iteration this filter will start acquisition in all configured cameras to prepare all of them for the first trigger event. Later during normal work it will wait for a set of frames for not longer than the selected timeout value (on inTimeout port) in milliseconds. After timeout occurs a Nil value is returned on all outFrame ports instead of images.

To maintain frames synchronization a receive time (at application level) of every separate frame is tracked internally. Frames are considered to originate from a single trigger event when their receive time is within the specified interval. When the receive time of the frames differs by more than the specified threshold value, they are considered to originate from a different trigger event and are not returned from the filter in the same iteration. When a frame is received later than the allowed time difference after the first received frame, its corresponding outFrame output returns Nil instead and this frame is left to be returned in the next iteration.

It is required to manually configure the receive time difference threshold for a target system. This value must be set on inMaxTimeDiff input. The time must be greater that the maximum frame receive time dispersion observed in the system, but less than the time between two consecutive trigger events. A diagnostic output diagCurrentTimeDiff can be used to determine the frame receive time dispersion in the target system. This output returns the difference between receive times of frames currently returned on the outFrame outputs. Statistics can be gather from this output during the system test to empirically determine the absolute minimal value of the time difference threshold.

To select devices for the filter appropriate inAddress inputs must be set to their network addresses. At least inAddress1 and inAddress2 inputs must be set. To use more devices additional optional inAddress inputs can be used. A device address is a structure of information defining unique device and its GenTL provider module in the system. It is recommended to use the GenTL Device Manager (click the "..." button in Filter Properties) to select the appropriate device, connected to the local system, whose identification information will be used.

Device address consists of the following fields:

  • VendorName - Vendor name of the GenTL provider module, which will be used to communicate with the device.
  • TLType - Identification code of interface transport technology type (for example "GEV", "IIDC", "UVC", "USB3", "PCI", "Custom"). The exact code depends on the GenTL provider module.
  • DeviceID - Unique ID of the device in the selected interface technology of the used provider module. The format of this field must be always an exact ID string and depends on the used GenTL provider module.

The inPixelFormat input specifies an image pixel format to be set in all devices before acquisition is started. The value for this input may be left empty to not change the format in the cameras and to leave the formats set up earlier. Pixel format is a textual name of image pixel (color) format. Name of the format must correspond to one of the format names supported by the device. Use GenTL Device Manager (click "..." button in filter properties) to select the format name from a list of formats supported by the connected device.

Filter will internally stream images in a selected device's pixel format. This format will be then converted to the most appropriate application Image format, in such a way that no data will be lost.

When the filter receives a valid set of frames from the cameras all active outFrame outputs return valid images. When timeout occurs before the first frame from the cameras is received all outFrame outputs returns Nil. When the first frame is received before timeout, but not all frames are received before additional maximum time difference elapses, some of outFrame outputs return valid images and the rest of the outputs return Nil.

For general information about working with Gen TL devices, please refer to the following article.

Hints

  • Interactively select cameras available in your system by defining the inAddress inputs.
  • Choose inPixelFormat from those supported by your camera.
  • Determine and set a proper value for inMaxTimeDiff.
  • By setting inTimeout specify how many milliseconds the filter should wait for the incoming frames.

Errors

This filter can throw an exception to report error. Read how to deal with errors in Error Handling.

List of possible exceptions:

Error type Description
RuntimeError Multiple cameras are not supported in SMART edition

Complexity Level

This filter is available on Basic Complexity Level.

See Also

  • GenICam_GrabImage – Captures an image stream from a camera using a GenICam GenTL provider library.
  • GenICam_GrabImage_WithTimeout – Captures an image stream from a camera using a GenICam GenTL provider library; returns Nil if no frame comes in the specified time.
  • Application Notes - set of documents about connecting devices or establishing communication with Aurora Vision Studio.