Back to Aurora Vision Library website

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

GenICam_GetStreamingStatistics


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

Retrieves basic statistics of video streaming out of GenICam device.

Syntax

void avs::GenICam_GetStreamingStatistics
(
	GenICam_GetStreamingStatistics_State& ioState,
	const avl::GenAddress& inAddress,
	int& outReceivedFrames,
	int& outLostFrames,
	int& outDroppedFrames,
	int& outDamagedFrames,
	int& outCurrentQueueSize
)

Parameters

Name Type Default Description
Input will be modified ioState GenICam_GetStreamingStatistics_State& Object used to maintain state of the function.
Input value inAddress const GenAddress& GenTL Provider module and device identifying address
Output value outReceivedFrames int& Number of received valid frames that were put into the input queue.
Output value outLostFrames int& Number of all frames that the device should have sent but were not retrieved by the application.
Output value outDroppedFrames int& Number of received valid frames that were lost because of input queue overflow.
Output value outDamagedFrames int& Number of frames that were partially received but were discarded because of data damage.
Output value outCurrentQueueSize int& Number of frames currently held in the input queue.

Description

This filter is intended for retrieving the video streaming statistics and diagnosing video streaming problems related to video device connected through GenTL compliant interface. It is usually used beside other GenICam filters, especially GenICam_GrabImage or GenICam_GrabImage_WithTimeout performing actual video streaming, and only for diagnostic purpose.

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.

This filter is based on the information retrieved from the GenTL provider library. When used GenTL provider library does not implements properly all required counters the statistics from this filter may be incomplete or inaccurate.

On every execution this filter will return the following statistics on its outputs:

  • outReceivedFrames - Number of all frames that were internally received from the device without any errors, and that were put into the image input queue. Those frames are intended for processing by the application through GenICam_GrabImage and equivalent filters. It is possible that not all of those frames were processed by the application.
  • outLostFrames - Estimated number of all frames that should have been generated by the device (based on frames counter) but were not, for any reason, processed by the application through the GenICam_GrabImage or equivalent filter. This statistic is based on the frame ID counter provided by the GenTL library. When the GenTL provider does not supports the frame ID information this statistic is ineffective. This counter includes dropped frames, damaged frames, and other frames that were fully lost (not received even partially).
  • outDroppedFrames - Number of frames that were internally received from the device without any errors, and that were put into the image input queue, but were not consumed by the application on time using the GenICam_GrabImage or equivalent filter and was discarded because of the input queue overflow. Large values of this statistic and its constant continuous growth means that the application is not keeping up with processing frames generated by the device and may indicate application performance issues or too large camera framerate. Occasional short growths of this statistic may indicate periodic performance problems in the application and (when loosing of frames is not acceptable) may indicate the need to increase capacity of the input queue.
  • outDamagedFrames - Number of all frames that were internally received from the device but were incomplete (some data were lost on transport layer) or were otherwise damaged (some data was corrupted or not recognized), and was discarded without putting them into the images input queue. Large values of this statistic may indicate transport layer problems.
  • outCurrentQueueSize - Number of valid frames that at the time of this filter execution was stored in the frames input queue and waiting for retrieving through the GenICam_GrabImage or equivalent filter. This value can be changing rapidly due too the race condition between filter execution time and internal receiving of new frames from the device.

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.