You are here: Start » Function Reference » GenICam » GenICam_GrabImage_WithTimeout

GenICam_GrabImage_WithTimeout

This is Filter Equivalent. This function may be present in generated code, but should not be used in hand-written code.

Header:	Genicam.h
Namespace:	avs
Module:	Genicam

Captures an image stream from a camera using a GenICam GenTL provider library; returns Nil if no frame comes in the specified time.

Applications: Use this filter if the trigger may be not coming for some time, while the application should perform other operations in the main loop continuously, or when the timeout situation must be explicitly detected, or when you want to process images from multiple cameras in a single loop and the cameras are sending images asynchronously.

Syntax

bool avs::GenICam_GrabImage_WithTimeout
(
	GenICam_GrabImage_State& ioState,
	const avl::GenAddress& inAddress,
	const avl::GenPixelFormat& inPixelFormat,
	int inInputQueueSize,
	int inTimeout,
	atl::Conditional<avl::Image>& outFrame,
	atl::Conditional<atl::int64>& outFrameID,
	atl::Conditional<atl::int64>& outTimestamp
)

Parameters

Name	Type	Range	Default	Description
ioState	GenICam_GrabImage_State&			Object used to maintain state of the function.
inAddress	const GenAddress&			GenTL Provider module and device identifying address
inPixelFormat	const GenPixelFormat&		\"Mono8\"	Requested Pixel Format in GenICam pixel naming convention
inInputQueueSize	int	1 - 200	1	Number of incoming frames that can be buffered before the application is able to process them
inTimeout	int	100 - 3600000	5000	Maximum time to wait for frame in milliseconds
outFrame	Conditional<Image>&			Captured frame
outFrameID	Conditional<int64>&			Frame block ID set by device (when supported)
outTimestamp	Conditional<int64>&			Frame capture timestamp set by 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, for streaming images out of it in a continuous mode.

This filter will wait for next valid frame not more that selected timeout value (on inTimeout port) in milliseconds. After timeout occurs a Nil value is returned on outFrame port instead of image.

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 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, 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.

Pixel format is a textual name of image pixel (color) format. Name of format must correspond to one of format names supported by device or error at program run will be raised. Use GenTL Device Manager to select format name from list of formats supported by connected device.

Filter will internally stream images in selected device pixel format. This format will be than converted to most appropriate application image format, in such way that no data will be lost.

outFrameID output returns a sequentially incremented number identifying current frame in video 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 frame. 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.

Similarly to outFrame, outputs outFrameID and outTimestamp will return Nil on timeout condition.

Hints

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

Errors

List of possible exceptions: