Skip to content

Image source🔗

The image source concept enables the HALCON user to configure and handle the usage of machine vision cameras to acquire images for their machine vision task. It replaces the framegrabber operator set (see Image / Acquisition) as HALCON’s recommended way to access cameras.

This chapter gives guidance on the concept and usage of image sources. Refer to the MVTec Interfaces Reference Documentation for the documentation of individual MVTec image source plugins.

Image source concept🔗

The machine vision device and all further components that are involved in the process of acquiring image data can be controlled using an image source handle. It is designed to encapsulate the so-called modules of the image source:

  • plugins,
  • interfaces,
  • devices, and
  • streams.

These modules are structured in a hierarchical parent-child configuration, with each module acting as a parent to the subsequent one. The module concept of the image sources is modeled after the GenICam GenTL standard.

To acquire images from the image source handle, an image source plugin is used to communicate to the imaging device through an interface. The imaging device provides access to one or multiple image streams. The images transmitted through that stream eventually arrive in multiple buffers in the memory of the host application.
All this complexity is hidden from the user in most applications, and per default, any image source handle will try to connect to a full chain of image source modules: plugin > interface > device > stream.

Figure 1. Schematic representation of the image source modules

However, for certain applications it can be necessary to connect to a specific module. For instance, using the scheme above as a representation of an exemplary system, one may wish to configure the parameters of a framegrabber before a camera is connected to it. Image source handles can be configured to solely connect to the parent image source plugin \(P_{1}\) and the respective GenTL interface module \(I_{1}\). The interface module then allows to configure the framegrabber without a connection to a child module.
Likewise, image source handles can be used to connect to any other available module or to specify a desired module if multiple options are available (for example, whether to choose stream \(S_{3}\) or \(S_{4}\) of the device \(D_{3}\) in the scheme above).

States of the image source handle🔗

An image source handle can be in different states. In each state, a different set of operations is available. The image source operators can be used to trigger such state changes.

Figure 2. Schematic representation of the possible states of an image source handle. The scheme shows which image source operators cause a change of the image source handle state between initialized (gray), connected (green), and streaming (red) state.

The possible states are:

Initialized
The image source handle should contain enough information to specify which device should be connected with connect_image_source. The operators set_image_source_param and get_image_source_param provide access to the parameters of the 'image_source' group. These are always existent, regardless of the connection state.
Connected

The operator snap_from_image_source is only available in this state. snap_from_image_source briefly changes the image source handle to the streaming state, but resets it again when an image has arrived.

The operators set_image_source_param and get_image_source_param provide access to the parameters of all different modules, including the device module. The device module allows to configure the imaging hardware, for example, a machine vision camera.

In this state, typical machine vision devices are utilized exclusively, meaning other applications can discover, but not access them.

Streaming

In this state, the imaging device can transmit image data continuously in the background. The images arrive in an internal image buffer queue, from which they can be pulled with fetch_from_image_source. fetch_from_image_source is only available in this state.

In the streaming state, the device might prevent certain parameters from being changed. This is done to ensure a reliable image transmission. As a consequence, the operator set_image_source_param may not be able to change all device parameters and might deliver an error instead. In that case, return to the connected state first.

Parameter groups and their relation to the modules🔗

Each module can be configured with get_image_source_param.
To indicate which module of the image source to configure, the parameters are divided into groups. This is how the grouped parameters are related to the GenTL modules. Plugins that are not provided by MVTec may group their parameter documentation according to the GenTL module names.

Parameter group
GenTL module name Remarks
'image_source' - The parameter group 'image_source' configures the module chain plugin > interface > device > stream and as such it sits “on-top” of the GenTL modules. These parameters are implemented by MVTec and exist all the time, regardless of the connection state. They are described in get_image_source_param.
'plugin' System Parameters for global configuration in the loaded plugin. Parameters in this group depend on which plugin is loaded and are implemented by the provider of the loaded plugin. Plugins can be provided by MVTec (see MVTec Interfaces Reference Documentation) or other manufacturers.
'interface' Interface Parameters for configuring the hardware component that is interfacing to the devices. Parameters in this group depend on which plugin is loaded and are implemented by the provider of the loaded plugin. Plugins can be provided by MVTec (see MVTec Interfaces Reference Documentation) or other manufacturers.
'local_device' Device Software abstraction for the hardware device. This group exists for technical reasons of the GenTL standard and can be ignored most of the cases. Parameters in this group depend on which plugin is loaded and are implemented by the provider of the loaded plugin. Plugins can be provided by MVTec (see MVTec Interfaces Reference Documentation) or other manufacturers.
'device' Remote Device Parameters for configuring the imaging hardware (for example machine vision cameras, sensors, devices). Use this to configure the most important properties of the image generation like exposure time, gain, width, height and trigger mode. Parameters in this group depend on which device is connected and are implemented by the manufacturer of the connected device.
'stream' Stream Parameters for configuring the details of the image transmission on the receiving side. Parameters in this group depend on which plugin is loaded and are implemented by the provider of the loaded plugin. Plugins can be provided by MVTec (see MVTec Interfaces Reference Documentation) or other manufacturers.

Migration notes🔗

Table 1 provides a comparison between the old framegrabber and the new image source operators. When switching an application to the newer image sources, replace each framegrabber operator with its corresponding image source operator.

Comparison table for operators
Table 1: Comparison of old and new operators
Old operator
New operator
Remarks
info_framegrabber query_image_sources info_framegrabber per default returns a string for each found device, which can be used for open_framegrabber. query_image_sources per default returns an image source handle for each device, which can be used for connect_image_source.
No direct equivalent create_image_source create_image_source creates an image source handle in an unconnected state. This is not possible with framegrabber operators.
open_framegrabber connect_image_source open_framegrabber is creating the framegrabber handle and connecting to the imaging hardware at the same time. Image source handles split this into two operations: create_image_source followed by connect_image_source. This allows using connect_image_source with handles obtained by create_image_source or by query_image_sources.
close_framegrabber disconnect_image_source close_framegrabber at the same time destroys the framegrabber handle. It can only be re-created with open_framegrabber. disconnect_image_source leaves the image source handle intact. It can be used with connect_image_source to re-connect.
get_framegrabber_param get_image_source_param Works similar, but the parameter group is now specified with the GenParam 'group' instead of using the [] prefix. Example: get_framegrabber_param(AcqHandle, '[Stream]StreamBufferHandlingMode', Value) get_image_source_param(ImageSourceHandle, 'StreamBufferHandlingMode', 'group', 'stream', Value)
set_framegrabber_param set_image_source_param Works similar. The relation is analogous to get_framegrabber_param and get_image_source_param (see above).
No direct equivalent control_image_source framegrabber handles provide parameters with the prefix ‘do_’. This kind of parameters is replaced by actions available via control_image_source. control_image_source also allows listing all parameters (previously get_framegrabber_param).
grab_image snap_from_image_source Works similar.
grab_image_start start_image_source grab_image_start is automatically executed by the first grab_image_async call, if grab_image_start was not previously called. start_image_source is not automatically executed by the first fetch_from_image_source call.
No direct equivalent stop_image_source Some framegrabber handles provide the special parameter 'do_abort_grab', which serves the same purpose that stop_image_source does.
grab_image_async fetch_from_image_source Works similar.
grab_data No direct equivalent snap_from_image_source combines the use cases covered by grab_image and grab_data. Additionally, meta data like buffer timestamps and frame IDs is returned alongside and does not need to be queried separately.
grab_data_async No direct equivalent fetch_from_image_source combines the use cases covered by grab_image_async and grab_data_async. Additionally, meta data like buffer timestamps and frame IDs is returned alongside and does not need to be queried separately.
get_framegrabber_callback set_framegrabber_callback get_framegrabber_lut set_framegrabber_lut No direct equivalent

Table 2 shows the relations between MVTec image source plugins (see MVTec Interfaces Reference Documentation for detailed information) and classical image acquisition interfaces:

Comparison table for interfaces and plugins
Table 2: Comparison of old interfaces and new plugins
Image source plugin
Corresponding image acquisition interface Remarks
'mvtec_gigevision' GigEVision2 The 'mvtec_gigevision' plugin contains the same GigE Vision standard implementation that is contained in the GigEVision2 image acquisition interface. Despite its name (GigEVision2) the plugin, as well as the image acquisition interface, allow access to all GigE Vision cameras, regardless of which version of the GigE Vision standard the camera implements.
'mvtec_usb3vision' USB3Vision The 'mvtec_usb3vision' plugin contains the same implementation of the USB3 Vision standard that is contained in the USB3Vision image acquisition interface.
'mvtec_realsense' RealSense The 'mvtec_realsense' plugin interfaces to the Intel RealSense SDK and contains the same low-level implementation that is contained in the RealSense image acquisition interface.
'mvtec_mediafoundation' MediaFoundation The 'mvtec_mediafoundation' plugin interfaces to the Microsoft Media Foundation API and contains the same low-level implementation that is contained in the MediaFoundation image acquisition interface. (Only available on Windows platforms)
'mvtec_gstreamer' GStreamer The 'mvtec_gstreamer' plugin interfaces to the open source GStreamer multimedia platform and contains the same low-level implementation that is contained in the GStreamer Image Acquisition Interface. (Only available on Linux platforms)

More image source plugins for additional image transmission technologies will be provided in the future.

Classical image acquisition interfaces not mentioned here (like “File”, “SaperaLT”, “DirectShow”) do not have a corresponding image source plugin. They must be used with the framegrabber operators.