Back to Aurora Vision Library website

You are here: Start » Function Reference » GigE Vision » AvsFilter_GigEVision_GrabImage_WithTimeout

AvsFilter_GigEVision_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 GigE Vision compliant camera; 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::AvsFilter_GigEVision_GrabImage_WithTimeout
(
	GigEVision_GrabImage_State& ioState,
	const avl::GevAddress& inAddress,
	const avl::GevPixelFormat& 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
Input will be modified ioState GigEVision_GrabImage_State& Object used to maintain state of the function.
Input value inAddress const GevAddress& GigE Vision Device identifying address (IP, MAC or Serial Number)
Input value inPixelFormat const GevPixelFormat& \"Mono8\" Requested Pixel Format in GenICam pixel naming convention
Input value inInputQueueSize int 1 - 400 1 Number of incoming frames that can be buffered before the application is able to process them
Input value inTimeout int 100 - 3600000 5000 Maximum time to wait for frame in milliseconds
Output value outFrame Conditional<Image>& Captured frame
Output value outFrameID Conditional<int64>& Frame block ID set by device
Output value outTimestamp Conditional<int64>& Frame capture timestamp set by device (when supported)

Description

This filter is intended for establishing connection with GigE Vision® compliant, single stream video transmitter, and for streaming images out of it in continuous, potentially triggered 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 textual definition of either IP, MAC or serial number. Use Device Manager to select appropriate address of connected device.

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 Device Manager to select format name from list of formats supported by 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 number identifying current frame in video sequence. This number is generated by device and incremented by one at the beginning of transmission of every frame block. The valid range of this id, for devices compliant with GigEVision version 1.2 or older, is 1...65535 (starting at 1 and incrementing sequentially up to 65535, then wrapping back to 1). 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 transmitted by device but lost before application could process them. This method cannot be used when lost image was not transmitted by device (e.g. when device missed a trigger signal).

outTimestamp output returns a timestamp of current frame that was marked by the device at point of grabbing the image. Support of this parameter by the device is optional and for some devices this output can be not effective. Frequency of the timer used for this timestamp is device dependent. Refer to device documentation for details about timestamp timer. Usually a frequency of this timer can be retrieved using a GevTimestampTickFrequency parameter available in device parameters tree. Value of this output will wrap around in range from 0 to 231-1.

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

For general information about working with GigE Vision devices, please refer to the following article.

To learn more about camera acquisition thread works please go to this article.

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:

Error type Description
IoError Connection with device lost.