Image Acquisition Interface for Media Foundation

This page provides the documentation of the HALCON MediaFoundation image acquisition interface, which is based on GenICam GenTL and the Microsoft Media Foundation. Registered customers can download the latest revision of this interface from the MVTec WWW server.
The interface internally contains a GenTL producer based on Microsoft Media Foundation which is referred to as 'Media Foundation Producer' in this document.

• Windows 10 or newer operating system.
• HALCON image acquisition interface hAcqMediaFoundation.dll or hAcqMediaFoundationxl.dll, respectively. If you have properly installed the interface, all these DLLs should reside in bin\%HALCONARCH% within the HALCON base directory %HALCONROOT% you have chosen during the installation of HALCON.
• GenICam GenApi. The corresponding files are part of the HALCON MediaFoundation package and are located in the directory genicam within the HALCON base directory %HALCONROOT%. See section GenICam GenApi for more details.
• A Media Foundation compatible capture device and a successfully installed driver for that device.
• Allow desktop apps to access the camera (Windows > Settings > Privacy & security > Camera).

MVTec interfaces for digital I/O and image acquisition are always compatible to a range of HALCON versions. Therefore, the versioning scheme both describes the compatibility of the interface and also the revision of the interface itself. An interface version always consists of three numbers, separated by dots, i.e. 24.11.5. The first two numbers describe the minimum HALCON version the interface is compatible with. For the example version 24.11.5 this means that the interface is compatible with all HALCON versions since HALCON 24.11. The last number describes the revision of the interface, in this example this is revision 5.

Only when installing or updating the interface manually follow these steps:

• Windows: Extract the archive containing the interface files to the HALCON base directory %HALCONROOT% (Note: Administrator privileges may be required for this step). Additionally, you have to move the interface examples to the directory %HALCONEXAMPLES% manually.

• Multiple capture devices.
• Synchronous and asynchronous grabbing.
• Support of feature persistence.
• Support camera settings control.

• Only the following Microsoft Media Foundation video formats are fully supported: MFVideoFormat_L8, MFVideoFormat_L16, MFVideoFormat_RGB24, MFVideoFormat_RGB32, MFVideoFormat_YUY2, MFVideoFormat_NV12, MFVideoFormat_NV21, and MFVideoFormat_MJPG.
• No triggering.
• Only AcquisitionMode 'Continuous' is available.
• The following SFNC features are read-only: Height, Width and AcquisitionFrameRate.

The connection to the (acquisition) device is established through the open_framegrabber operator. The operator provides a set of parameters allowing to configure the basic properties of the device and how the HALCON MediaFoundation interface controls it – see corresponding section. Some of the parameters can be also modified at runtime through set_framegrabber_param. This section concentrates solely on the 'Device' parameter of open_framegrabber, identifying the device (usually camera) that should be opened.
A connection to the device accessible through the MediaFoundation interface is established using the device ID which is guaranteed to be unique per device and stays persistent across multiple sessions, as long as the device remains connected to the same system and USB port. The list of all devices currently available in the system can be obtained using info_framegrabber parameter 'device' or 'info_boards' – see corresponding section. Both parameters return a list of devices, each specified using entities in the format ' | device:<device id> | unique_name:<unique name> | ... '. To increase compatibility with other HALCON image acquisition Interfaces they are both listed. The full string (obtained from the info_framegrabber call) can be directly used for the 'Device' parameter of open_framegrabber, which uses the same format. Only the ' | device:<device id>' string entry is mandatory for open_framegrabber, the others might be omitted.

When a pure string without any 'token:' and without the ' | ' separator is used, it is interpreted directly as the device ID.
As a special case, the string 'default' can be used – in this case the HALCON acquisition interface will use the first available device (devices currently reported as non-accessible will be skipped). However this can result in non deterministic opening of devices when multiple devices are connected to the system.

• This interface uses GenApi version 3.5.0, for more details refer to the GenICam homepage. The corresponding files are part of the HALCON runtime installation and are located in the directory genicam within the HALCON base directory %HALCONROOT% or $HALCONROOT, respectively. This version is the same as the officially released version at the time of writing.
• The HALCON MediaFoundation interface sets all necessary environment variables on its own and ignores other installed GenICam packages by default.
  If you want to use another GenICam package, you need to set the environment variable HALCON_USE_EXTERNAL_GENAPI. This skips the step of setting all necessary variables and paths internally, so you have to make sure they are set correctly. Please note that it might not be possible to use different GenApi versions with different interfaces at the same time and that you must use the required GenApi version for this interface.
• The caching of device XML files is activated to speed up processing, writing to a temporary directory subject to availability of %TEMP%, %TMP%, $TMPDIR, /tmp or %HALCONROOT%.
• The remote device control features as well as the Media Foundation Producer control features of this interface are controlled via GenApi.

The features of a device or Media Foundation Producer are described by GenICam feature description files (XML files) that are automatically parsed and offered to the user. The HALCON MediaFoundation image acquisition interface provides access to the features exposed through the following GenICam feature description files:

• Features of the connected device are wrapped by the Media Foundation Producer and presented via a GenICam compatible XML file. Names for those features follow the SFNC recommendation as far as applicable.
• Features of the Media Foundation Producer are exposed through a set of GenICam description files, one for each internal entity to control the device tree:
  • The "system" – representing the overall behavior of the acquisition interface
  • The interface used to connect the device to the system.
  • A proxy (called "local device") to the device, controlling the Media Foundation Producer view of the device.
  • The data stream used for the acquisition (if the device provides any data streams).

In most cases the GenICam description files are provided by the device and the Media Foundation Producer. It is possible to store a copy of these files corresponding to an open connection by using the parameter 'do_write_configuration' (see set_framegrabber_param). The command will write all the GenICam description files and an "ini" file (details in set_framegrabber_param) with various information, including the location of the written GenICam description files, in the following format:

 
RemoteFile=%PATH_TO_GENICAM_FILE_OF_THE_DEVICE% 
SystemFile=%PATH_TO_GENICAM_FILE_OF_THE_SYSTEM_MODULE% 
InterfaceFile=%PATH_TO_GENICAM_FILE_OF_THE_INTERFACE_MODULE% 
DeviceFile=%PATH_TO_GENICAM_FILE_OF_THE_LOCAL_DEVICE_MODULE% 
StreamFile=%PATH_TO_GENICAM_FILE_OF_THE_STREAM_MODULE% 

The same ini-file format can be reused to force the HALCON acquisition interface to load an alternative XML file for one or more of these entities. This can be useful, e.g., for updates or troubleshooting. The files listed in the ini file will be used for the given entity instead of the original ones. For the entities excluded from the ini file, the GenICam description file will be searched and loaded the usual way. To apply the ini file, pass its full path to open_framegrabber in the 'CameraType' parameter.

Note that the ini-file can be reused also for other purposes such as storing/restoring configuration as described in Parameters – Persisting Device Status. Be aware that when persistence files are specified, they have priority over other explicit settings passed to open_framegrabber.

The following groups of parameters exist:

• Internal parameters of the MVTec GenTL Consumer itself (GenICamTL acquisition interface). These are named following the "underscore" naming style, e.g., color_space, and are all lowercase. However, MVTec EasyParams are prefixed with "[Consumer]", e.g., [Consumer]gain.
• GenICam-based parameters of the device, usually a camera, use by convention the "CamelCase" style, e.g., ExposureTime.
• GenICam-based parameters of the individual Media Foundation Producer modules (system, interface, device and data stream) use by convention the same style but are prefixed with the module name in square brackets. Beware that the system and interface modules might potentially be shared by multiple opened devices, so changing their configuration might have side effects on other connections as well. The following prefixes are used:
  • "[System]", e.g., [System]TLVendorName.
  • "[Interface]", e.g., [Interface]InterfaceType.
  • "[Device]", e.g., [Device]DeviceID.
  • "[Stream]", e.g., [Stream]StreamBufferHandlingMode.

Microsoft Media Foundation does not provide any mechanism to access the camera settings. Therefore, DirectShow IAMCameraControl and IAMVideoProcAmp interfaces are used for this purpose. All CameraControl and VideoProcAmp properties are implemented and accessible as remote device features. Each DirectShow parameter has an extra auto remote device feature to control its automatic mode, except for VideoProcAmp_BacklightCompensation and VideoProcAmp_ColorEnable. For instance, VideoProcAmp_Gamma is represented by the remote device feature Gamma and GammaAuto.
The availability of the parameters depends on the connected device.
For detailed information, check the parameter description in the parameters list.

The MVTec EasyParams is a group of MVTec GenTL Consumer parameters based on the regular GenICam features of the device. These parameters allow easy access to the most commonly used camera parameters.
The list of EasyParams can be obtained calling 'available_easyparam_names'. Note that 'available_param_names' does not include the EasyParams. The MVTec EasyParams start with the prefix [Consumer], indicating they are internal parameters of the HALCON GenTL consumer itself.
Since HALCON 22.11 they are available via an own tab in the HDevelop Image Acquisition Assistant.
If your device does not support one of the EasyParams, querying its access will return 'ni' (not implemented). If instead 'na' (not available) is returned, the EasyParam is supported but currently not available, e.g., it depends on the current state of another EasyParam or the access of one or more GenICam features, or because the image acquisition is running. In the latter case, use set_framegrabber_param(..., 'do_abort_grab', ...) to stop the acquisition.
List of MVTec EasyParams:

• General device information:
  • [Consumer]info_general
• Exposure feature:
  • [Consumer]exposure_auto
  • [Consumer]exposure
• Gain feature:
  • [Consumer]gain_auto
  • [Consumer]gain

Detailed information of each MVTec EasyParam can be found in sections about getting framegrabber parameters and setting framegrabber parameters.

HALCON native parameter types are

• integer – signed integer, 64-bit on 64-bit platforms, 32-bit on 32-bit ones
• real – floating point type
• string – classical string

When accessing GenICam-based features, the GenICam data types must be mapped to the parameter types recognized by HALCON. GenICam offers the following types:

• IInteger – integer value, mapped directly to HALCON's integer parameter type. It will also accept real parameters. When the GenICam feature in question has a representation associated that identifies it as IPV4Address, MACAddress or HexNumber, the corresponding string representation will also be accepted. It should be highlighted that a problem can occur when running HALCON on a 32-bit platform (where integer parameters are 32-bit wide) and accessing a GenICam feature that is naturally 64-bit. In such cases the full range of the feature will not be available to the application and its value might be truncated. Also the sign of the parameter might be misinterpreted. To solve this problem, the parameter 'split_param_values_into_dwords' can be used. This maps the 64-bit IInteger value into two 32-bit integer values and vice versa.
• IFloat – floating point value, mapped directly to HALCON's real parameter type. It will also accept integer parameters.
• IString – string value, mapped directly to HALCON's string parameter type.
• IBoolean – boolean type is handled through HALCON's integer parameters, a value of 0 (zero) means logical false, other values mean logical true.
• IEnumeration – enumeration is a type that allows selecting from a set of values that are primarily identified by their name (the values are called 'enum entries'). Enumerations are interfaced through HALCON's string parameter type, while the enum entry names are used as the parameter values.
• ICommand – The command type allows to "execute" actions. To execute a command, use set_framegrabber_param with an integer parameter of any value (the value is ignored). Some commands' execution might take longer time and the command provides feedback when it is done. To query the status, use get_framegrabber_param for that command. It will return an integer value of 1 if it "is done" (command execution has finished), 0 if it has not finished yet. Note that if some other features are designed to be dependent on the command, querying the "is done" status might be essential to get the depending features invalidated (and updated with new values) as soon as the command execution finishes.
• IRegister – The register data type is used for plain memory blobs that cannot be mapped to any other data type. They are interfaced through HALCON's string parameter type, the register value is the hexadecimal string representation of the register's memory.

The current status of the acquisition device settings (values of all the parameters defining its working state) might be persisted while no acquisition is active, i.e. before grab_image_start or grab_image_async or after set_framegrabber_param(..., 'do_abort_grab', 1). This applies not only to actual device parameters, but also to parameters configuring the Media Foundation Producer and internal parameters of the MediaFoundation image acquisition interface. Device parameters are usually kept until the device is powered down. The Media Foundation Producer modules and the Consumer parameters are kept until close_framegrabber is called. To indicate which parameters to persist, use the parameter 'settings_selector'. The persistence functionality consists of two steps, storing the current configuration to a file and later re-loading it back to the device. The selected module settings, indicated by 'settings_selector', can be stored using the 'do_write_settings' parameter and re-loaded later using the 'do_load_settings' parameter, specifying the desired persistence file path in both cases. To query if a feature can be persisted use the postfix '_streamable'.

Note that while the format of the files is intentionally human readable and the files can be hand-modified if desired, such modifications should be done with care by someone familiar with the GenICam persistence functionality internals and given device. Improper modifications of the files can lead to errors when using it.

The persistence related operations might be blocked by the device and/or Media Foundation Producer based on the current state, for example while an acquisition is in progress.

The same persistence files can be applied to the entire set of devices of the same type and firmware version. Applying the persistence files to a device of another type or using even different firmware version will probably lead to inconsistencies or will even fail completely .

Apart from the 'do_write_settings', the feature persistence file will also be written together with the ini file documented in the section Selection of GenICam Feature Description File(s) - using parameter 'do_write_configuration'. This command will generate extended version of the persistence file, storing not only the current device configuration, but also contents of its user sets and sequencer sets (if the device supports them). Additionally, it will also generate persistence files for all the Media Foundation Producer modules (system, interface, device and data stream). The persistence file entries in the ini file will have the format

 
RemotePersistence=%PATH_TO_PERSISTENCE_FILE_OF_THE_DEVICE% 
SystemPersistence=%PATH_TO_PERSISTENCE_FILE_OF_THE_SYSTEM_MODULE% 
InterfacePersistence=%PATH_TO_PERSISTENCE_FILE_OF_THE_INTERFACE_MODULE% 
DevicePersistence=%PATH_TO_PERSISTENCE_FILE_OF_THE_LOCAL_DEVICE_MODULE% 
StreamPersistence=%PATH_TO_PERSISTENCE_FILE_OF_THE_STREAM_MODULE% 

The image acquisition can be either synchronous (grab_image/grab_data) or asynchronous (grab_image_start/grab_image_async/grab_data_async), see the reference documentation of the operators.
The interface fully configures and controls the acquisition process on the camera. Note that some of the camera features might be locked by GenICam when an acquisition is active.
With synchronous grab (grab_image/grab_data), a new acquisition is started internally for each image, so that the application always gets a new image. Before delivering the image, the acquisition is stopped again, so between individual grab_image/grab_data calls, all acquisition related features remain unlocked.
With asynchronous grabbing, started explicitly by grab_image_start or implicitly by grab_image_async/grab_data_async, the interface keeps the acquisition running internally, collecting further images to be delivered through future grab_image_async/grab_data_async calls. The acquisition related features are locked, until the acquisition is stopped using set_framegrabber_param(..., 'do_abort_grab', ...).
The HALCON acquisition interface properly recognizes the 'Continuous', 'SingleFrame' and 'MultiFrame' acquisition modes configured on the device and adjusts the acquisition control logic accordingly.
Furthermore, the interface takes over exclusive access to several remote device features essential for the acquisition control (AcquisitionStart, AcquisitionStop, AcquisitionAbort, TLParamsLocked). The user application has no direct way to control these features.
The differences between the "image" and "data" version of the grab operators is documented in Acquisition – Grab Operators.

During open_framegrabber the best Microsoft Media Foundation media type is selected, meaning an RGB (if available) video subtype with the widest width, highest height and fastest frame rate combination. See 'MFMediaType' parameter for further information.

The interface allocates 4 buffers for the acquisition engine by default (the number of buffers can be changed through the 'Generic' parameter of open_framegrabber).
Whenever a new image is acquired successfully and passed to the application as a HALCON image, the interface keeps the buffer locked (not returning it to the acquisition engine) until a new grab-related operator is called by the application or the acquisition is aborted using set_framegrabber_param(..., 'do_abort_grab', ...). During this period, it is fully safe to query information about this "last acquired" buffer – for example query buffer properties through get_framegrabber_param parameters such as 'buffer_timestamp', 'buffer_is_incomplete', 'image_width' and 'image_height'.
When a new grab-related operator is called by the application, the interface returns the buffer to the acquisition engine and buffer-related queries are not valid anymore.

It can happen, that the camera is temporarily or constantly acquiring data in higher speed than the application is processing them. In such case the streaming engine of the Media Foundation Producer decides how to treat the acquired buffers based on the '[Stream]StreamBufferHandlingMode' parameter.

The acquisition interface provides two mechanisms for acquisition of the image (or other) data from the device, grab_image/grab_image_async and grab_data/grab_data_async. Each of them might be more suitable for different use cases. Internally, both mechanisms work exactly the same (in particular how they acquire and process the data from the device), they differ in the way how the outputs are provided to the application.
The "traditional" grab_image/grab_image_async operators are still well suitable in simple use cases when just a single 2D image is acquired from the device. It is also currently used e.g. by the HDevelop's Image Acquisition Assistant. However, in case when the device is streaming more complex data structures, such as 3D data, multi-AOI or similar data, grab_image/grab_image_async is not able to provide all the outputs. In all these cases it will simply provide the first image found in the acquired data.
The "extended" grab_data/grab_data_async operators allow to output arbitrary number of HALCON images and also arbitrary number of control data. It is therefore suitable for use in advanced use cases when more than just a single HALCON image should be output. An important use case is acquisition from 3D devices () when the operators can build and output the 3D object model through the control data output. It can be also used in other (possibly even device-specific) situations when the device outputs multiple images for a single acquisition.
The structure of the provided outputs can be queried with help of the 'image_contents', 'data_contents' and related parameters.
The grab_data/grab_data_async can also be used in the simple single-image use cases - in that case they will simply provide a single HALCON image and zero control data outputs. They can thus be used as full replacement of the traditional grab_image/grab_image_async operators.

The HALCON MediaFoundation image acquisition interface has a built-in converter from the pixel formats described in the GenICam Standard Features Naming Convention to the desired HALCON image format. The parameters ColorSpace and BitsPerChannel (open_framegrabber, eventually set_framegrabber_param) define the desired format of the resulting HALCON image. If these parameters are set to defaults, the original pixel format coming from the device is preserved.
To offer a basic support of custom pixel formats (i.e., pixel formats not defined by PFNC or not supported by HALCON), the ColorSpace value 'raw' can be used. In this case the image acquisition interface delivers the buffer to the application without any format conversions.
Note that the same principle is applied whenever a buffer containing other than image data is acquired. Examples of such buffers can be files (e.g., compressed images) or raw data (results of smart camera processing). Such buffers are not real "images", but can still be delivered to the application as 'raw' HALCON images. It is the responsibility of the application to know how to interpret such data.
Last but not least, the 'raw' color space can also be used if the user explicitly wishes to receive raw input data without any conversions. For example when acquiring Bayer encoded images, specifying 'raw' means that the interface should not attempt to decode them to RGB or monochrome format, but deliver the data directly to the application.
It is important to know that when the interface does not have full information about the image format (dimensions and pixel format), it has to choose an artificial one. In such a case it delivers always an 8-bit image with dimensions matching the buffer size (square root of the image size). Eventually an unused tail of the HALCON image (if such an artificial image is bigger than the source buffer) will be padded with zeroes. The fact whether the last acquired buffer contained an image of known properties or a blob of other data (so that the artificial HALCON image size had to be used) as well as the size of the eventual tail padding can be queried using 'image_raw_buffer_type' and 'image_raw_buffer_padding_bytes' parameters.

It is possible to receive notifications about changes of any features exposed through the GenICam interface by the camera and Media Foundation Producer as well as for internal parameters of the acquisition interface.
Note that the notifications might be raised in various circumstances, including:

• The application (you) explicitly changed that feature.
• Another feature has changed and the notified feature "depends" on the changed feature (the dependencies are defined in the GenICam description file).
• Access mode or current range for the feature has changed.
• As a result of regular "polling" in case of uncached features.
• As a result of device event delivery if the feature is connected to that event.
• As a result of new buffer delivery for features corresponding to chunk data.

Note that the notifications are raised whenever the feature is "marked dirty" (its cache invalidated) by one of the actions described above. It does not necessarily mean that its value has really changed, it is up to the application to check this.
Notification callbacks can be registered for individual features using set_framegrabber_callback - see corresponding operator documentation. Additionally, it is possible to use message queues to receive the event notification. In those cases it is necessary to create a message queue and then register the individual feature - see event message queues.

GenICam compatible devices can deliver asynchronous events which optionally carry additional data. It is usually necessary to enable delivery of individual event types using the features 'EventSelector'/'EventNotification' first. For SFNC-compliant events, this is done automatically if the parameter 'event_notification_helper' is enabled.
The decoding of the event data and matching them to the corresponding features, including potential notifications, is performed transparently by the interface.
The actual values might be read through the regular parameter reading mechanism like get_framegrabber_param or by get_message_tuple if you are using message queues to receive events. The choice of the event types to be generated is device-specific. The names of the event related features usually start by convention with a prefix 'Event' (examples might be 'EventFrameTrigger' and 'EventFrameTriggerTimestamp'), however, the device documentation should contain all the information about supported events and their corresponding feature names.
Although the data corresponding to the last delivered event can be in general read at any time, when using callback to receive events it is highly recommended that reading the event data is synchronized to notifications for corresponding event feature(s). Only in such a case it is guaranteed that the read data correspond exactly to the very event instance being notified – and that the feature values are not just being modified through a new instance of the same event. Note that the notifications are raised from context of the event handling/dispatching thread, so when processing the user callback, the event handling mechanism is paused. If multiple data items are associated with the same event, it is enough to register notification just for the actual event feature and read all the data during the callback.
If using message queues to receive events, you can decide to add additional data to be delivered with the corresponding event feature(s), see Event Message Queues. For this case the interface will read all the specified event features as soon as the event is generated and add it to the corresponding message. This guarantees that the delivered information corresponds with the actual value at the time the event was generated.
Besides the asynchronous events generated by the actual device, asynchronous events (optionally including additional data) can be generated by any module of the Media Foundation Producer (system, interface, device and data stream). The information provided above about handling of the device events applies similarly also to the Media Foundation Producer events, including enabling/disabling them (typically using 'EventSelector'/'EventNotification' features provided by given module, i.e. with corresponding module prefix in the feature name). For SFNC-compliant events, this is done automatically if the parameter 'event_notification_helper' is enabled.

This interface supports feature change notifications via message queues. Select the desired target feature with set_framegrabber_param(..., 'event_selector', ...). It is the same plain feature name (GenICam feature or internal parameter) as used with set_framegrabber_param, including a possible prefix, such as '[Device]' (refer to the Parameters – Naming Conventions).
Create a message queue at which you want to receive the notifications with create_message_queue and assign it to the selected feature with set_framegrabber_param(..., 'event_message_queue', QueueHandle).
The message queue can be registered for any GenICam based features, i.e., features published by the device and Media Foundation Producer or for internal features of the acquisition interface. On top of that, the notification can be registered also for internal events occurring within the acquisition interface, in particular 'event_new_buffer' which gets fired whenever the information about last acquired buffer is updated (new buffer grabbed or last buffer info invalidated when restarting the acquisition).
The list of supported targets can be queried by calling get_framegrabber_param(..., 'available_event_names', ...).
One of the important use cases for feature change callbacks is the device event delivery mechanism, see details in Event Data and Feature Change Notifications sections.
A new message would be added to the specified queue whenever a given feature is potentially changed (including its other properties such as range or access mode). Note that it does not necessarily always mean that the feature actually has a new value. A call to set_framegrabber_param(..., 'event_message_queue', 0) unregisters the previously registered message queue from the specified event. Note that the interface keeps just a single registration for every feature, if you attempt to register a new message queue for a feature that already had a message queue registered, the previous registration will be replaced with the new one.
The messages incoming on an event can be retrieved with dequeue_message and will contain at least three tuples. The first tuple (key 'id') is a unique identifier of the acquisition instance the event is coming from. It is a string composed as '<interface>:<unique_name>'. The second tuple (key 'event_name') is the name of the corresponding feature previously specified by 'event_selector'. The third tuple (key 'event_value') contains the value if the corresponding feature if available and readable.
If you decide to add additional data to be delivered with the corresponding event feature(s), add the features of interest with set_framegrabber_param(..., 'event_data', ...). Each event data feature will be appended to the event message with the key being its name and the tuple its value if readable. Note that duplicities possibly specified through 'event_data' are ignored The value of the notified feature itself (already reported in 'event_value') would also be considered as a duplicity and not reported again.

In case of using the HDevelop Image Acquisition Assistant the following hints will help to avoid problems:

• Some parameters depend on special conditions, e.g., a valid buffer or another parameter activated. After opening the camera these conditions may not yet be fulfilled, so the depending parameters are not shown. By using the 'Refresh' button, all parameters are read again and the depending parameters should appear if the conditions are fulfilled then.
• There are also some parameters regarding the image size and the payload size, which can only be changed if no acquisition takes place. The safest way to ensure this is to apply the action parameter 'do_abort_grab'. Please note that 'Update Image' has to be disabled first.
• The behavior of allowing changes to parameters while streaming is active depends on the capabilities of the device. It is possible that some cameras give you control over, e.g., the exposure time, while streaming and others do not.

The HALCON MediaFoundation interface supports an internal color conversion performed in software. The conversion is automatically applied for PFNC (Pixel Format Naming Convention) compatible cameras, when the color format delivered by the camera differs from the user defined format if set via the parameter 'color_space'. The used transformation algorithms are basic and optimized for speed.

Following transformations from the camera color space (see also PFNC) to the interface color space (see also 'color_space' parameter in this document) are supported:

• Bayer pattern to 'rgb':
  

  Bayer_LMMN R G1 G2 B ⇾ [R,G,B] [R,G,B] [R,G,B] [R,G,B]

  Bayer_NMML B G1 G2 R ⇾ [R,G,B] [R,G,B] [R,G,B] [R,G,B]

  with G = (G1 + G2) / 2.

• Y'CbCr to 'rgb' (Note: gamma correction is not considered):
  

  R = Y' + 1.4020 * (Cr- M)
G = Y' - 0.34414 * (Cb- M) -0.71414 * (Cr- M)
B = Y' + 1.7720 * (Cb - M)

• RGB to 'yuv' ('yuv' corresponds to Y'CbCr of PFNC, Note: gamma correction is not considered):
  

  Y' = 0.299 * R + 0.587 * G + 0.114 * B
Cb = -0.16874 * R - 0.33126 * G + 0.5 * B + M
Cr = 0.5 * R - 0.41869 * G - 0.08131 * B + M

• RGB to 'gray':
  

  Y' = 0.299 * R + 0.587 * G + 0.114 * B

with M = 128 for 8 bit raw data, and M = 32768 for 16 bit raw data.
The accuracy of the results is limited due to internal 16.16 fix-point arithmetic for 8 bit ( 0...255), and 24.8 fix-point arithmetic for 16 bit raw data.

The parameters of the cameras and Media Foundation Producer are accessed through GenICam and defined in GenICam description file(s) of the respective camera or Media Foundation Producer, so the parameter set is different for every product (although the parameter naming should adhere to SFNC and GenTL SFNC GenICam standard). A call of get_framegrabber_param(..., 'available_param_names', ...) returns a tuple containing all available parameters of the connected camera and Media Foundation Producer. See also section about parameter naming convention.
To set e.g. the current gain of the camera AcqHandle refers to (after calling open_framegrabber), the user can call set_framegrabber_param(AcqHandle, 'Gain', 6.0).
Please note that the interface sets the value of a parameter only if the value is valid. Integer and float values not matching the allowed range for given feature are aligned to the closest valid value. Invalid values of other feature types are refused.
Additionally to the GenICam parameters of the camera and of the Media Foundation Producer, the following HALCON interface parameters are supported by set_framegrabber_param:

There may exist additional read-only parameters with the following postfixes:

• '_access': These parameters provide the access permissions of the corresponding parameter as a string. Possible values are 'ro' (read-only), 'wo' (write-only), 'rw' (read/write), 'na' (not available), and 'ni' (not implemented).
• '_category': These parameters provide the category of the corresponding parameter as a string.
• '_description': These parameters provide the tool-tip of the corresponding parameter as a string.
• '_displayname': These parameters provide the displayname of the corresponding parameter as a string.
• '_longdescription': These parameters provide the description of the corresponding parameter as a string.
• '_range': These parameters provide the minimum, maximum, step width, and current values for the corresponding integer or float parameter as a tuple with 4 elements, e.g., get_framegrabber_param(.., 'Shutter_range', ..) will return the output tuple [min, max, step, current].
• '_representation': These parameters provide the GenICam representation of the corresponding parameter as a string. They only exist for integer-parameters. Possible values are 'Linear', 'Logarithmic', 'Boolean', 'PureNumber', 'HexNumber', 'IPV4Address' and 'MACAddress'. The purpose of the representation is to aid in GUI design.
• '_streamable': These parameters provide the persistence of the corresponding parameter as an integer. Possible values are 0 if false or 1 if true.
• '_string': These parameters provide the integer values formatted as a string according to the '_representation' postfix. Especially useful for the '_representation' values 'IPV4Address', 'MACAddress' and 'HexNumber'.
• '_type': These parameters provide the type of the corresponding parameter as string.
• '_values': These parameters provide the valid value list for the corresponding parameter as a tuple, e.g., get_framegrabber_param(.., 'volatile_values', ..) will return the output tuple ['enable', 'disable'].
• '_visibility': These parameters provide the visibility of the corresponding parameter as a string. Possible values are 'beginner', 'expert', and 'guru'.

All these postfixed parameter names are not returned when calling info_framegrabber(.., 'parameters', ..) and are used to enable the easy parameterization via a generic graphical user interface, particularly the HDevelop Image Acquisition Assistant.

Not supported by this interface.

Not supported by this interface.

This interface supports feature change callbacks via the operators set_framegrabber_callback and get_framegrabber_callback.
The callback can be registered for any GenICam based features, i.e., features published by the device and Media Foundation Producer through the GenICam description files as well as for internal parameters of the acquisition interface.
The list of supported callback targets can be queried by calling get_framegrabber_param(..., 'available_callback_types', ...).
One of the important use cases for feature change callbacks is the device event delivery mechanism, see details in event data and feature notifications sections. The 'CallbackType' parameter of set_framegrabber_callback defines the feature for which the callback is registered. It is the same plain feature name as used with set_framegrabber_param, including a possible prefix, such as '[Device]' (refer to the parameter naming convention).
The registered callback function would be called whenever a given feature is potentially changed (including its other properties such as range or access mode). Note that it does not necessarily always mean that the feature actually has a new value. If the callback function is set to NULL, the corresponding callback will be unregistered. Note that the interface keeps just a single registration for every feature, if you attempt to register a new callback for a feature that already had a callback registered, the previous registration will be replaced with the new one.

The signature of the callback function is Herror (__stdcall *HAcqCallback)(void *AcqHandle, void *Context, void *UserContext) and uses the following parameters:

• AcqHandle: Acquisition handle of the corresponding image acquisition instance.
• Context: Optional context data of the specific callback. Up to now, this parameter is not used, i.e., Context is set to NULL.
• UserContext: Optional context data of the specific callback. Up to now, this parameter is not used, i.e., UserContext is set to NULL.

Note that the execution time of a user-specific callback function must always be as short as possible since during the execution of a callback function the handling of further internal callbacks might be blocked. This can be achieved by removing the current processing from the user-specific callback function to a separate thread that is controlled via signals or events. The callback function is executed in the context of the underlying interface or driver.
It is also important to understand that the callbacks might be fired as a side-effect of parameter-setting or grab operations, ie. it might be called from within their respective locks. The user is responsible to take this into account in the callback handler to avoid risk of a deadlock.

This interface supports feature callbacks via the operators set_framegrabber_callback and get_framegrabber_callback. For more information see set_framegrabber_callback.

Starts a new asynchronous grab. See also grab_image_start and section about acquisition control. Note that this operator starts acquisition on the Media Foundation Producer and device and locks features protected during acquisition. If grab_image_start is called repeatedly, the acquisition is restarted on both Media Foundation Producer and device. That means, that the buffer queue and all stream related statistics parameters like 'buffer_frameid' are reset. The acquisition can be stopped (and the features unlocked) using set_framegrabber_param(..., 'do_abort_grab', ...).

grab_image starts a new synchronous grab of a single image. See also grab_image, section about acquisition control and about grab operators. Note that the interface converts the acquired image to the desired image format specified by the parameters 'bits_per_channel' and 'color_space'.

grab_image_async returns a single image and starts the next asynchronous grab. See also grab_image_async, section about acquisition control and about grab operators. Note that the interface converts the acquired image to the desired image format specified by the parameters 'bits_per_channel' and 'color_space'.
The 'MaxDelay' parameter of the grab_image_async operator is ignored by the HALCON MediaFoundation acquisition interface, because there is no way to support it reliably . If needed, the application needs to implement alternative functionality on its own.

grab_data starts a new synchronous grab, resulting possibly in tuple of output images and tuple of data outputs of various kind, depending on the input and configuration. See also grab_data, section about acquisition control and about grab operators. Note that the interface converts the acquired images to the desired image format specified by the parameters 'bits_per_channel' and 'color_space'. The output tuples are described using the 'data_contents', 'image_contents' and related parameters.

grab_data_async returns acquired images/data and starts the next asynchronous grab. See also grab_data_async, section about acquisition control and about grab operators. Note that the interface converts the acquired image to the desired image format specified by the parameters 'bits_per_channel' and 'color_space'. The output tuples are described using the 'data_contents', 'image_contents' and related parameters.
The 'MaxDelay' parameter of the grab_image_async operator is ignored by the HALCON MediaFoundation acquisition interface, because there is no way to support it reliably . If needed, the application needs to implement alternative functionality on its own.

This operator closes the device. See also close_framegrabber.

For this interface there are the following examples available:

• mediafoundation_mediatypes.hdev - Changing pixel format, image resolution and frame rate.

In case of problems with the HALCON MediaFoundation Interface the following hints might help to solve them.

General:

• Check if the latest revision of the HALCON MediaFoundation interface is used.
• Check the System Requirements.
• Check if the device has the latest firmware.
• Enable low-level error messages in HALCON to query more information about the problem (and check the output console in HDevelop if applicable).

GenICam:

• Check if the correct GenICam binaries are in use. HALCON uses the official binaries in a private installation (folder genicam in the HALCONROOT directory). If other GenICam binaries are in your path or in some system path (for Windows e.g. in c:\Windows\System32\ for Linux e.g. in /usr/lib or similar directories) make sure these are the official ones by comparing them with the ones in the HALCON installation. Using unofficial binaries might result in strange problems.

If there are still problems, please contact your local distributor.

The following information is needed for your support request to avoid unnecessary inquiries.

• Used HALCON and acquisition interface versions.
• Used HALCON architecture (especially 32 or 64 bit).
• Low-level error messages if there are any.
• Camera manufacturer, model and firmware version.
• Details about computer system, like operating system, RAM and CPU.
• Minimal sample code (e.g. HDevelop script) to reproduce the issue.
• Description of observed and expected behavior.

This interface depends on third-party libraries. See the file third_party_mediafoundation.txt in the HALCON base directory for copyright and license information. Libraries are used without modifications unless explicitly stated in the file.

You can request the source for those third-party libraries licensed under GPL or LGPL via email to info@mvtec.com with the subject "Request source code of third-party libraries".

• Revision 24.11.6 (Apr 28, 2026):
  • To comply with restrictions introduced in GenApi v3.4 (allowing only alphanumeric characters and underscores), the format of 'MFMediaType' values has changed. Additionally, unsupported video formats now include the '_unsupported' suffix for clarity, for example: 'GUID_70323159_0000_0010_8000_00AA00389B71_1440x1080_0fps_unsupported'.
  • The parameters '[Device]DeviceSerialNumber' and '[Interface]DeviceSerialNumber' returned incorrect values. They now always return an empty string, as this information cannot be reliably provided.
  • zlib has been updated to version 1.3.2.
• Revision 24.11.5 (Oct 9, 2025):
  • There was a memory leak when registering for feature change notifications with set_framegrabber_callback or with 'event_message_queue'. This problem has been fixed.
  • A Software Bill of Materials (SBOM) in the System Package Data Exchange (SPDX) format has been added next to each binary file with the same name extended by ".spdx.json".
• Revision 24.11.4 (Apr 16, 2025):
  • The underlying GenApi version has been updated to the latest official release 3.5.0. The previous version failed to load settings that contained empty string parameters. This problem has been fixed.
  • The first access to the MVTec EasyParam [Consumer]exposure_auto and [Consumer]gain_auto could lead to a change in ExposureTime or Gain GenICam device parameter, respectively. This problem has been fixed.
  • Multithread usage of the MVTec EasyParams could lead to abnormal program termination. This problem has been fixed.
• Revision 20.11.3 (Mar 5, 2024):
  • The underlying GenApi version has been updated to the latest official release 3.4.2. This fixes a compatibility break with certain persistence files introduced in version 3.4.1.
  • Loading of configuration files during open_framegrabber (with the parameter CameraType) did not raise an exception, even when the file could not be read. This problem has been fixed.
  • When passing GenICam persistence files to open_framegrabber, the remote device was silently ignored. This problem has been fixed.
• Revision 20.11.2 (Aug 7, 2023):
  • The underlying GenApi version has been updated to the latest official release 3.4.1. This improves the validation of the string representation of parameters written through the '_string' postfix.
  • This interface is now compiled against the Windows SDK version 10.0.22000.0.
  • Camera settings control is now supported.
  • Pixel formats 'YCbCr420_8_YY_CbCr_Semiplanar', 'YCbCr420_8_YY_CrCb_Semiplanar', 'YCbCr422_8_YY_CbCr_Semiplanar', and 'YCbCr422_8_YY_CrCb_Semiplanar' are now supported.
  • Microsoft Media Foundation video format MFVideoFormat_NV12, MFVideoFormat_NV21, and MFVideoFormat_MJPG are now supported.
  • Bottom-up images were not correctly interpreted. This problem has been fixed.
  • The first access to an MVTec EasyParam could change the value of its equivalent GenICam device parameter. This problem has been fixed.
  • Accessing an MVTec EasyParam could lead to a crash if any of the underlying GenICam parameters had an unexpected type. This problem has been fixed.
  • Querying the '_representation' of an MVTec EasyParam could in some cases lead to a crash. This problem has been fixed.
  • In rare cases, the access of not implementable MVTec EasyParams was erroneously set to 'na', instead of 'ni'. This problem has been fixed.
• Revision 20.11.1 (Apr 5, 2023):
  • First official release.