Operator Reference
fetch_from_image_source (Operator)
fetch_from_image_source — Fetch images and corresponding meta data from the image source
buffer queue.
Signature
fetch_from_image_source( : Images : ImageSourceHandle : Data)
Description
fetch_from_image_source fetches Images
from the buffer queue of the image source defined in the handle
ImageSourceHandle. For conventional devices, Images
is most likely to be a single image, but complex sensors, e.g. 3D sensors,
might provide multiple images at once.
Additionally, meta information is returned in Data.
fetch_from_image_source tries to pull images from the buffer queue
of the image source and deliver it to the application.
If the buffer queue is empty, the operator waits for an image to arrive
in the buffer queue up to the configured timeout value
(see 'fetch_timeout' in get_image_source_param).
If images have arrived in the buffer queue before the call of
fetch_from_image_source it returns immediately by pulling one
buffer from the queue and delivering its contained images. The operator
runtime depends on various factors like for example the state of the buffer
queue and the current configuration of the imaging device.
See 'num_buffers' in get_image_source_param
on how to adapt the buffer queue capacity.
As far as supported by the respective plugin, the returned meta
information in Data provides the following parameters:
- 'frame_id'
Linearly increasing image counter transmitted by the device alongside the image data. Inconsistencies in the counter sequence indicate lost buffers.
- 'is_incomplete'
-
Completeness status of the acquired data. Incomplete data might indicate data transmission problems.
List of values: 0 (complete), 1 (incomplete).
- 'timestamp_ns'
Timestamp [ns] of the image transmitted by the device alongside the image data. It reflects the value of the devices internal clock at the moment of exposure.
The device and a corresponding stream defined in
ImageSourceHandle need to be connected and started
when calling fetch_from_image_source.
See connect_image_source on how to connect and
start_image_source on how to start your image source.
For further information about the states of an image source see Image Source.
Execution Information
- Multithreading type: reentrant (runs in parallel with non-exclusive operators).
- Multithreading scope: global (may be called from any thread).
- Processed without parallelization.
This operator returns a handle. Note that the state of an instance of this handle type may be changed by specific operators even though the handle is used as an input parameter by those operators.
Parameters
Images (output_object) image(-array) → object (byte / int1 / int2 / uint2 / int4 / int8 / real)
Retrieved images.
ImageSourceHandle (input_control) image_source → (handle)
Handle of the image source whose buffer queue should be accessed.
Data (output_control) dict → (handle)
Meta information about the images.
Result
If the parameter values are correct, fetch_from_image_source
returns the value 2 (
H_MSG_TRUE)
. Otherwise an exception is raised.
Possible Predecessors
Possible Successors
Module
Foundation