MVTec Software GmbH
  Building Vision For Business
Halcon

HALCON 10 Image Acquisition Interface for MATRIX VISION Boards and Cameras

This page provides the documentation of the HALCON MatrixVisionAcquire interface that supports frame grabber boards and cameras from MATRIX VISION GmbH. This interface offers full control over the mvBlueFOX USB 2.0 camera series, the mvBlueCOUGAR and mvBlueLYNX-M7 GigE camera series, the mvHYPERION, mvDELTA, mvGAMMA, mvSIGMA, and mvTITAN frame grabber boards. For also accessing pcIMAGE frame grabber boards from MATRIX VISION please refer to the existing HALCON MatrixVision interface (legacy). Registered customers can download the latest revision of this interface from the MVTec WWW server.

Revision: 4.7

System Requirements

  • Intel compatible PC with Windows XP/Vista/7, Windows x64, Linux, or Linux x64_64 with kernel 2.6.x.
  • Successfully installed MATRIX VISION driver from the MATRIX VISION Driver CD (Windows: version 1.10.49 or higher, Linux: version 1.9.12 or higher).
  • Windows: HALCON image acquisition interface hAcqMatrixVisionAcquire.dll or hAcqMatrixVisionAcquirexl.dll, respectively. If you have properly installed the interface, both DLLs should reside in bin\%HALCONARCH%within the HALCON base directory %HALCONROOT% you have chosen during the installation of HALCON.
    Linux: HALCON image acquisition interface hAcqMatrixVisionAcquire.so or hAcqMatrixVisionAcquirexl.so, respectively. Both files should reside in the directory /lib/$HALCONARCH within the HALCON base directory $HALCONROOT.

Features

  • Multiple devices.
  • Generic access to all device-specific parameters.
  • Synchronous and asynchronous grabbing.
  • Cropping of image parts.
  • Subsampling.
  • External trigger.

Limitations

  • No LUTs.
  • grab_data and grab_data_async not supported.

Multiple devices

The HALCON MatrixVisionAcquire interface supports working with multiple devices. To allow the interface to distinguish between multiple devices of the same type, each device should be assigned with an unique ID, that is stored inside the devices non-volatile memory. To assign an ID to a device please use mvDeviceConfigure tool, that is part of the MATRIX VISION installation. A list of all currently installed devices can be obtained by calling info_framegrabber('MatrixVisionAcquire', 'info_boards', infoBoardsInfoText, installedDevices)
Currently, an ID must be assigned to USB devices only.

Description

Parameters for open_framegrabber():

Name 'MatrixVisionAcquire' The name of the HALCON image acquisition interface.
HorizontalResolution --- Ignored.
VerticalResolution --- Ignored.
ImageWidth 0, width The width of the desired image part ('0' stands for the complete image). Default: 0.
ImageHeight 0, height The height of the desired image part ('0' stands for the complete image). Default: 0.
StartRow 0, row The row coordinate of the upper left pixel within the desired image part. Default: 0.
StartColumn 0, column The column coordinate of the upper left pixel within the desired image part. Default: 0.
Field --- Ignored.
BitsPerChannel --- Ignored.
ColorSpace 'gray', 'rgb', 'yuv' Specify the desired color space and thus the number of image channels of the resulting HALCON image. Note that not all MATRIX VISION devices support both modes! Default: 'gray'.
Generic --- Ignored.
ExternalTrigger --- Ignored. The external trigger can be activated by  set_framegrabber_param with the parameter 'Camera/TriggerMode'.
CameraType 'mvBlueFOX*', 'mvBlueCOUGAR*', 'mvBlueLYNX-M7*',
'mvDELTA*', 'mvSIGMA*', 'mvGAMMA*', 'mvTITAN*', 'mvHYPERION*' 		This parameter is used to specify the type of device the user wants to access. To access a certain product, the string parameter passed here can be used with several levels of precision. Internally the driver tries to locate a device that matches the search string up to the wildcard ('*') in connection with the value passed via the 'Device' parameter. EXAMPLE: 'mvBlueFOX-M124*' with 'Device' set to 2 will try to open any mvBlueFOX-M124 device (color or gray) that has the device ID 2, while 'mvHY*' and 'Device' set to 0 will try to open the first mvHYPERION device found on the bus. '*' will therefore try to open the first device supported by this device interface driver. Default: '*'.
Device 'DeviceID' The device ID which has been assigned to that device using mvDeviceConfigure. Assigning different IDs to each device allows to work with multiple devices of the same type. Default: '0'.
Port number Specifies the port the device is connected to. For mvBlueFOX cameras this value is always 0. Default: 0.
LineIn --- Ignored.

Parameters for set_framegrabber_param():

Note that most parameters of this interface are generic, i.e., all available parameters can be queried directly from the acquisition device by use of the parameters 'available_param_names', 'readable_device_properties', 'readable_instance_properties', 'writeable_device_properties', and 'writeable_instance_properties'.

'do_abort_grab' --- Abort the current image acquisition.
'do_invalidate_property_cache' --- Invalidates the internal property cache. This might be useful when modifying a property at runtime, that in terms results in the creation or deletion of other features. For performance reasons changes like this must be explicitly applied by the application. Thus, in order to get access to dynamically created features after certain changes the internal property cache should be invalidated. When calling get_framegrabber_param with a parameter that returns a list of parameters, the list will be invalidated automatically.
'do_update_digital_inputs' --- Updates the digital input related properties with the values currently applied to the physical inputs. Without calling this parameter, reading the digital input related properties might NOT reflect the current state of the physical inputs.
'grab_timeout' msec Specify the desired timeout (milliseconds) for aborting a pending grab. Default: 5000.
'image_height' height Specify the desired image height. '0' means to use maximum image height. Note that you can also adapt this setting with the parameter 'Camera/Aoi/H'.
'image_width' width Specify the desired image width. '0' means to use maximum image width. Note that you can also adapt this setting with the parameter 'Camera/Aoi/W'.
'port' number Switch to the camera connected to the specified port number. Default: 0.
'request_queue_depth' 1, 2, ... This parameter sets the internal queue size that is used in combination with grab_image_async: To achieve optimal performance, a certain number of image requests will be sent down to the driver the first time an asynchronous grab is requested. Once send down to the driver the acquisition parameters for this image request (e.g., the gain) can't be modified anymore. Default: 1.
'start_column' start_column Sets the column coordinate of the upper left corner of the resulting HALCON image part. Note that you can also adapt this setting with the parameter 'Camera/Aoi/X'.
'start_row' start_row Sets the row coordinate of the upper left corner of the resulting HALCON image part. Note that you can also adapt this setting with the parameter 'Camera/Aoi/Y'.
'volatile' 'enable', 'disable' In the volatile mode the two image acquisition interface buffers are used directly to store HALCON images. This is the fastest mode avoiding to copy raw images in memory. However, be aware that older images are overwritten again and again as a side-effect. Thus, you can only process one image while you grab another image. Older images are invalid! Default: 'disable'.

Parameters for get_framegrabber_param():

Additional parameters supported by get_framegrabber_param only. Note that all parameters supported by set_framegrabber_param except the ones with prefix 'do_' can also be accessed by get_framegrabber_param.

Note that there are two levels of detail: The parameters with prefix 'available_' return all supported parameters of the camera. If you want to get an detailed overview which parameter is read-only or which parameter is valid for a device or an instance, you can use the parameters with prefix 'readable_' and 'writeable_', respectively.

'available_param_access' accessability Returns a list containing the accessibility of all parameters. The following types are possible:
  • 'ro' (read only)
  • 'rw' (read and write)
  • 'wo' (write only)
The order of the entries is equal to the order of the parameter names returned by 'available_param_names'.
'available_param_descriptions' descriptions Returns a list containing additional information about all parameters. The order of the entries is equal to the order of the parameter names returned by 'available_param_names'.
'available_param_names' parameters Returns a list containing the names of all available parameters.
'available_param_types' types Returns a list containing the types of all parameters. The following types are possible:
  • 'I' (integer value)
  • 'F' (float value)
  • 'S' (string value)
  • 'SE' (string enumeration)
The order of the entries is equal to the order of the parameter names returned by 'available_param_names'.
'image_available' --- Returns 1, if a new image has been captured, but not read back. Otherwise, 0 is returned.
'readable_device_properties' properties Returns a list containing the names of additional device-specific properties the user can query using the operator get_framegrabber_param. The values of these parameters will be valid for each handle/instance referring to that device, i.e., this data is shared between multiple instances referring to the same device.
'readable_instance_properties' properties Returns a list containing the names of additional instance-specific properties the user can query using the operator get_framegrabber_param. The values of these parameters will be valid for the current handle/instance referring to that device only, i.e., this data is NOT shared between multiple instances referring to the same device. Note: Not every parameter returned by 'readable_instance_parameters' is also writeable!
'revision' revision The revision number of the HALCON MatrixVisionAcquire interface.
'writeable_device_properties' properties Returns a list containing the names of additional device-specific properties the user can write to using the operator set_framegrabber_param. The values of these parameters will be valid for each handle/instance referring to that device, i.e., this data is shared between multiple instances referring to the same device.
Note: The user can't use the prefixes 'limits.' and 'dictionary.' when calling set_framegrabber_param.
'writeable_instance_properties' properties Returns a list containing the names of additional instance-specific properties the user can write to using the operator set_framegrabber_param. The values of these parameters will be valid for the current handle/instance referring to that device only, i.e., this data is NOT shared between multiple instances referring to the same device.
Note: The user can't use the prefixes 'limits.' and 'dictionary.' when calling set_framegrabber_param.

Further Information

Assume a call to get_framegrabber_param(AcqHandle, 'readable_instance_properties', readableInstanceProplist) returns a tuple containing three strings: [ 'Camera/ExposeTime_us', 'Camera/TriggerMode', 'Camera/Gain_dB' ]. This tells the user that
  • these properties can be set differently for each handle to that device.
  • these properties will be valid in all future releases for this particular device without ever calling reading the property list again, i.e., during design time the user needs to query the property list once, but in the final solution of his application he can just work with the string once read.
  • '_us' indicates that this property can be set in microseconds, '_dB' indicates that this property can be set in decibel. Other possible postfixes are '_pc' for percent, '_ms' for milliseconds, '_s' for seconds, '_kB' for kilobytes, and '_MB' for megabytes.

Now to read e.g. the current gain of the instance AcqHandle the user can call get_framegrabber_param(AcqHandle, 'Camera/Gain_dB', CurrentGain)

There are some properties that store more than a single value. One example for such a property is 'ImageProcessing/LUTOperations/LUTs/LUT-0/DirectValues'. If this parameters is read by using get_framegrabber_param(AcqHandle, 'ImageProcessing/LUTOperations/LUTs/LUT-0/DirectValues', myLUT) the interface will return a tuple containing all values. For writing to such a property a tuple must be used as well.

Furthermore, the user can query additional information about the properties. Some might define limits like min, max or step width. These values can be queried as a list by postfixing the properties name with '_range' or by prefixing it with 'limits.'.
Thus, to query the limits of the gain property the user can call get_framegrabber_param(AcqHandle, 'limits.Camera/Gain_dB', GainLimits). This might e.g. result in a list like this: [ 0.0, 30.0, 0.045, 3.5 ]. The first value indicates the minimum value, the second value is the maximum value, the third value is the step width and the last value is the current value for this property. Values written to the property, that don't match the stepwidth, will be rounded to the closest matching step automatically. Note, that you can also obtain this list by get_framegrabber_param(AcqHandle, 'Camera/Gain_dB_range', GainRange).

Other properties like e.g. the trigger mode property can only be set to certain values. To find out which values are valid for a certain property the user can either prefix the property's name with 'dictionary.' or postfix it with '_values'. Thus, to find out which values are allowed for the trigger mode property the user can either call get_framegrabber_param(AcqHandle, 'dictionary.Camera/TriggerMode', AllowedTriggerModes) or get_framegrabber_param(AcqHandle, 'Camera/TriggerMode_values', AllowedTriggerModes). Afterwards the variable AllowedTriggerModes will contain a list of strings defining the allowed trigger modes for this device. This list might look like this: [ 'Continuous', 'OnDemand', 'OnRisingEdge', 'OnFallingEdge' ]. Again: These modes will stay consistent. New ones may occur, but the modes once queried will be valid for all future releases.

Now e.g. to switch the trigger mode to 'OnDemand' the user could call set_framegrabber_param(AcqHandle, 'Camera/TriggerMode', 'OnDemand').

Certain properties can be set by the user, but won't affect the behaviour of the acquisition. For example, the user might have switched on the AGC (Automatic Gain Control). Then writing the property 'Camera/ExposeTime_us' will not affect the expose time used for the image acquisition. However, the value written to the property will have affect as soon as the AGC is switched off again. Some properties therefore will be shadowed by values applied to other properties.

To find out if a property currently is shadowed the user can prefix the name of the property in question with the word 'isVisible.'. Then a call to get_framegrabber_param(AcqHandle, 'isVisible.Camera/TriggerMode', trigModePropVisible) will return either 0 to indicate that the property currently is NOT shadowed or 1 to indicate that the property is currently not active.

Release Notes

  • Revision 4.7(Jul 27, 2011)
    • Added parameter 'do_invalidate_property_cache'.
    • Added support for unlimited 'grab_timeout' (-1).
    • mvIMPACT Acquire vector properties (properties that store more than a single value) will be displayed in the image acquisition assistant and the property lists displayed within HDevelop's set_framegrabber_param and get_framegrabber_param configuration dialog.
  • Revision 4.6(Feb 23, 2011)
    • Bugfix in parameter 'do_abort_grab', which is actually working now.
  • Revision 4.5(Oct 10, 2010)
    • Bugfix for color images, where 'R' and 'B' channel where flipped. This problem was introduced in revision 4.1.
  • Revision 4.4 (Aug 2S, 2010):
    • Added support for mvIMPACT Acquire pixel format ibpfBGR888Packed.
  • Revision 4.3 (Jul 30, 2010):
    • Bugfix of a memory leak of ImageWidth * ImageHeight * BitsPerChannel * ChannelCount. Each call to close_framegrabber after a successful call to open_framegraber caused a memory leak.
    • Bugfix when passing width and height values larger then the AOI limits the open_framegrabber operator doesn't crash anymore.
    • HALCON 10 version of the interface (included in HALCON 10 DVD).
  • Revision 4.2 (Mar 16, 2010):
    • Added support for some more mvIMPACT Acquire pixel formats: ibpfRGB888Packed, ibpfYUV444Planar, ibpfRGB101010Packed, ibpfRGB121212Packed, ibpfRGB141414Packed, ibpfRGB161616Packed, ibpfYUV422Planar, ibpfYUV422Packed and ibpfYUV422Packed_UYVY.
    • Added value 'yuv' to parameter 'color_space'.
    • Changed return value of info_framegrabber(..,'camera_type',...) to improve the auto-detection of HDevelop.
  • Revision 4.1 (Feb 6, 2009):
    • Added support for mvBlueLYNX-M7 devices.
    • Improved syntax for parameter 'CameraType' to provide several levels of precision.
  • Revision 4.0 (Dec 1, 2008):
    • HALCON 9.0 version of the interface (included in HALCON 9.0 DVD).
    • Added support for mvBlueCOUGAR devices and mvHYPERION-CLe frame grabbers.
    • Added postfix '_access' to all parameters to query the access mode.
    • Bugfix when working with the 'MaxDelay' parameter of the grab_image_async operator deadlock situations could arise.
    • Bugfix regarding parameter 'grab_timeout'. Before calling set_framegrabber_param with 'grab_timeout' at least once the grab timeout of the camera was 2000 ms, while reading its current value returned 5000 ms.
  • Revision 3.3 (Feb 27, 2008):
    • Bugfix in grab_image and grab_image_async where the first grabbing of an image failed if 'request_queue_depth' was set to 1.
  • Revision 3.2 (Oct 25, 2007):
    • Added parameter 'grab_timeout' to parameter 'available_param_names'.
    • Bugfix in parameters 'available_param_names', 'available_param_types', and 'available_param_descriptions'.
    • Bugfix in grab_image_start for Windows 32-bit operating systems.
  • Revision 3.1 (Oct 16, 2007):
    • Bugfix for timeout/trigger related situations where the system didn't recover correctly.
    • Bugfix in close_framegrabber, which left dead threads in connection with certain devices.
    • Added parameter 'do_update_digital_inputs'.
  • Revision 3.0 (May 15, 2007):
    • HALCON 8.0 version of the interface (included in HALCON 8.0 DVD).
    • Support of the Linux driver for MATRIX VISION cameras and boards.
  • Revision 2.4 (Jan 12, 2007):
    • Added parameter 'image_available' to query the status of the current grab.
  • Revision 2.3 (Apr 25, 2006):
    • Some internal modifications, no change in behaviour.
    • Added support for mvSIGMA, mvDELTA, mvTITAN, and mvGAMMA boards.
  • Revision 2.2 (Mar 27, 2006):
    • Added new parameters 'available_param_access', 'available_param_names', 'available_param_types', and 'available_param_descriptions'.
    • First official release.
  • Revision 2.1 (Aug 2, 2005):
    • Adapted to planar pixel formats.
  • Revision 2.0 (Apr 27, 2005):
    • Currently supports only mvBlueFOX devices
    • First beta release.

© Copyright 2012, MVTec Software GmbH, corporate/legal/privacy information






Last modified: Fri Jul 29 15:36:57 CEST 2011