Back to Aurora Vision Studio website

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

GenICam_GrabMultiPartImage


Module: Genicam

Captures a multi-part image stream from a camera using a GenICam GenTL provider library.

Applications

Allows to receive multi-part video stream (with multiple images per frame) from special GenICam cameras, like separated color components in planar color formats, or separate depth, confidence and luminosity images in 3D cameras.
Name Type Range Description
Input value inAddress GenAddress GenTL Provider module and device identifying address
Input value inPixelFormat GenPixelFormat* Requested Pixel Format in GenICam pixel naming convention
Input value inInputQueueSize Integer 1 - 200 Number of incoming frames that can be buffered before the application is able to process them
Input value inTimeout Integer 100 - 3600000 Maximum time to wait for frame in milliseconds
Output value outFramePart1 Image? First part of the captured frame
Output value outFramePart2 Image? Second part of the captured frame
Output value outFramePart3 Image? Third part of the captured frame
Output value outFramePart4 Image? Fourth part of the captured frame
Output value outFrameID Long? Frame block ID set by the device (when supported)
Output value outTimestamp Long? Frame capture timestamp set by the device (when supported)

Description

This filter is intended for establishing connection with a general camera device using a dedicated driver software through a GenTL compliant interface, in a similar fashion as GenICam_GrabImage_WithTimeout or GenICam_GrabImage. This variant is useful when working with a devices streaming data in a GenTL multi part buffer format, like 3D depth cameras (providing separate images for depth, confidence or luminosity) or multi sensor cameras (providing separate color planes). Up to four buffer parts can be decoded with this filter and accessed as separate images on outputs.

This filter will wait for the next valid buffer no more than the selected timeout value (on the inTimeout port) in milliseconds. After timeout occurs Nil values are returned on all output ports.

Device address (inAddress port) is a structure defining a 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.

This filter will interpret the value of inAddress port only during the first iteration of its parent Task, when the connection to the device is established. During the next iterations the filter will use previously established connection and subsequent changes in the device address will be ignored.

inPixelFormat can be optionally used to configure the device pixel format when a single format setting is enough. Usually however it would be necessary to configure all parts of the buffer separately, which is a process dependent on the device. In such situation this input should be left empty and buffer parts structure should be configured using set parameter GenICam filters in initialization phase of the application.

Up to four parts of the buffer will be converted to a most appropriate application image format, in such a way that no data will be lost, and provided in order on outFramePart1 to outFramePart4 outputs. When the frame buffer contains less than four parts excessive outputs will be set to Nil.

When working with 3D depth cameras the filters MakeSurfaceFromImage and CreatePoint3DGridFromImage can be used to convert depth map and point cloud buffer parts into Surface and Point3DGrid primitives respectively. Refer to the device documentation for information about data real world coordinates interpretation and calibration.

outFrameID output returns a sequentially incremented number identifying current buffer in sequence. Support of this parameter is optional and for some devices this output can be not effective. The value of this output is supplied by the GenTL provider library. Its support, range and wrap around depends on GenTL provider library and transport technology of the device. Refer to device vendor documentation for more information about buffer FrameId. This value can be used to control correctness of received image sequence and detection of lost frames. Please note that this method can be used only to detect frames that was lost on application side. Detection of frames lost in device and transport layer depends on GenTL provider library implementation and device transport technology.

outTimestamp output returns a timestamp of current buffer. Support of this parameter is optional and for some devices this output can be not effective. Frequency of the timer used for this timestamp is device and GenTL provider library dependent. Refer to device documentation for details about timestamp timer.

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

Hints

  • Interactively select a camera available in your network by defining the inAddress input.
  • By setting inTimeout specify how many milliseconds the filter should wait for an incoming frame.

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
IoError Connection with the device lost.

Complexity Level

This filter is available on Basic Complexity Level.

Filter Group

This filter is member of GenICam_GrabImage filter group.

See Also

  • 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.
  • GenICam_GrabImage – Captures an image stream from a camera using a GenICam GenTL provider library.
  • Application Notes - set of documents about connecting devices or establishing communication with Aurora Vision Studio.