MVTec Software GmbH
  Building Vision For Business
Halcon

HALCON 10 Image Acquisition Interface for Matrox Helios, Meteor-II, Morphis, Odyssey, Solios, and Vio Boards

This page provides the documentation of the HALCON MILLite interface for the Matrox Helios, Meteor-II, Morphis, Odyssey, Solios, and Vio frame grabber boards. Registered customers can download the latest revision of this interface from the MVTec WWW server.

Revision: 4.9

System Requirements

  • Intel compatible PC with Windows XP/Vista/7 or Windows XP/Vista/7 x64.
  • Successfully installed Matrox board driver.
  • Matrox DLLs mil.dll, milmet2.dll, milsolios.dll.
    These DLLs must be within your search path %PATH% (typically, they reside in the directory C:\Winnt\system32). If you do not have these DLLs, please contact Matrox or the vendor from which you bought the frame grabber board. Note that this interface requires the Matrox DLLs version 9.0, i.e., MIL-Lite 9.0..
  • HALCON image acquisition interface hAcqMILLite.dll or hAcqMILLitexl.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.

Features

  • Support of Helios eA/XA, Helios eCL/XCL,, Matrox Meteor-II, Meteor-II/1394, Meteor-II/CL, Meteor-II/DIG, Meteor-II/MC, Morphis, Odyssey eA/XA, Odyssey eCL/XCL, Odyssey eD/XD, Solios eA/XA, Solios eCL/XCL, Solios eCL/XCL-B, Solios eV-CL, and Vio frame grabber boards.
  • Multiple compatible cameras per board (port switching).
  • Synchronous and asynchronous grabbing.
  • External trigger (with software override of the camera configuration file).
  • Support of multiple analog and digital cameras based on camera configuration files.
  • Support of user-specific callback functions.

Limitations

  • No support of Solios GigE boards.
  • No support of Morphis Evo and Morphis QxT frame grabber boards.
  • Only one image acquisition instance per frame grabber board for Meteor-II, Meteor-II/cl, and Meteor-II/dig boards. However, multiple compatible cameras can be accessed using port switching.
  • No support of onboard image preprocessing capabilities.
  • No support of JPEG and JPEG2000 video compression.
  • grab_data and grab_data_async not supported.
  • No LUTs.

Description

Parameters for open_framegrabber():

Name 'MILLite' 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 ('0' obviously results in delivering the complete image). Default: 0.
StartColumn 0,column The column coordinate of the upper left pixel within the desired image part ('0' obviously results in delivering the complete image). Default: 0.
Field --- Ignored.
BitsPerChannel --- Ignored.
ColorSpace 'gray', 'rgb' Desired color space. Default: 'gray'.
Generic 'num_buffers=num',-1 With the Generic parameter 'num_buffers' the actual number of image buffers used in the HALCON acquisition interface can be set before the camera is initialized. Note that the parameter must be specified as a string, e.g., 'num_buffers=5'. The specified value for num_buffers has to be an positive integer. Note that depending on the image size of the used camera a high number of buffers can exceed the available memory size of your computer, see also the non-paged memory size settings with the Matrox MILConfig configuration tool. Default: 2.
ExternalTrigger 'true', 'false' Activate/deactivate external triggering. Note that this setting overrides the corresponding setup in the camera configuration file. Default: 'false'.
CameraType 'configuration' Specify the name (including the full path name) of the desired camera configuration file (e.g., 'c:\\temp\\rs170.dcf') or a predefined configuration (e.g., 'M_DEFAULT', 'M_RS170'). For possible values, please see the documentation of your board.
Device '<BoardType>:<nr>[:DIG:<nr>]' The type ('METEOR_II', 'METEOR_II_1394', 'METEOR_II_CL', 'METEOR_II_DIG', 'MORPHIS', 'HELIOS', 'SOLIOS', 'ODYSSEY', or 'VIO') and the number ('0', '1', '2' ...) of the frame grabber board, optionally plus ':DIG:' and the number ('0', '1', '2' ...) of the independent digitizer (passed as one string!), e.g., 'HELIOS:0' or 'METEOR_II_1394:1:DIG:4'. For Meteor-II/1394 boards the digitizer equals the number of the camera in the chain. If no digitizer is specified, the first digitizer (i.e., number '0') is chosen. The installed boards can be inquired calling info_framegrabber(...,'info_boards',...).
Port -1, 0, 1, ..., 23 Specifies the channel, i.e. the video input. For possible values and assignment, please see the documentation of your Matrox frame grabber board. By specifying the default '-1' the corresponding setting of the camera configuration file is used. Default: -1.
LineIn --- Ignored.

Parameters for set_framegrabber_param():

'cc1_select' 'default', 'grab_exposure', 'pixclk', 'user_bit_cc_a', 'user_bit_cc_b', 'hsync', 'vsync' Assign a particular signal to Camera Link cc1 line.
'cc2_select' 'default', 'grab_exposure', 'pixclk', 'user_bit_cc_a', 'user_bit_cc_b', 'hsync', 'vsync' Assign a particular signal to Camera Link cc2 line.
'cc3_select' 'default', 'grab_exposure', 'pixclk', 'user_bit_cc_a', 'user_bit_cc_b', 'hsync', 'vsync' Assign a particular signal to Camera Link cc3 line.
'cc4_select' 'default', 'grab_exposure', 'pixclk', 'user_bit_cc_a', 'user_bit_cc_b', 'hsync', 'vsync' Assign a particular signal to Camera Link cc4 line.
'continuous_grabbing' 'enable', 'disable' Enables/disables the continuous grabbing mode. If the continuous grabbing mode is enabled, the camera grabs all the time. Note that in this mode the grab_image and grab_image_async calls will always deliver the most recent image! The continuous grabbing mode is not supported in combination with software trigger. Default: 'disable'.
Note that in combination with the continuous grabbing mode you can exploit the specific Trigger Arm Characteristics settings which can be configured in the used DCF file, see also below for more information.
'current_buffer_index' 0 ... num_buffers-1 Index of the current image buffer.
'exposure_time' nanoseconds Sets the time (in nanoseconds) for the active portion of the exposure signal (that is, the exposure time). By specifying 0, exposure is disabled and the grab is performed immediately. Note, that an error is returned if the specified exposure time cannot be generated.
'exposure_time_delay' nanoseconds Sets the delay (in nanoseconds) between the trigger and the start of exposure. Note, that an error is returned if the specified delay cannot be generated.
'external_trigger' 'true', 'false' Activate/deactivate external triggering.
'gpio_mode:XX' 'input', 'output', 'default' Controls the direction of the specified GPIO signal (with XX = 0,1,...,15 as unique index of the desired GPIO line).
'gpio_format:XX' 'default', 'disable', 'enable', 'lvds', 'opto', 'tri-state', 'ttl' Sets the format of the specified GPIO signal (with XX = 0,1,...,15 as unique index of the desired GPIO line).
'grab_timeout' milliseconds Specify the desired timeout (milliseconds passed as an integer) for aborting a pending grab. Default: 5000.
'image_height' height Dynamically change the current image height of the grabbed image. Note that by changing this value, all active image grabs are cancelled.
'image_width' width Dynamically change the current image width of the grabbed image. Note that by changing this value, all active image grabs are cancelled.
'port' -1, 0, 1, ..., 23 Switch to the video input (or the number of the camera in the chain). For possible values and assignment, please see the documentation of your frame grabber board. Using this port switching you can access multiple cameras with one frame grabber board.
'rotary_counter' 'true', 'false' Activate/deactivate the rotary counter. Default: 'false'.
'rotary_counter_direction' 'forward', 'backward' Sets the direction of the rotary counter, i.e. the rotary counter gets incremented for a value of 'forward', or decremented for a value of 'backward', respectively . Default: 'forward'.
'rotary_counter_trigger_position' 0, ..., 65535 Specifies the rotary counter value upon which a trigger is generated.
'start_async_after_grab_async' 'enable', 'disable' By default, at the end of grab_image_async a new request for an asynchronous grab command is automatically given to the frame grabber board. If the parameter 'start_async_after_grab_async' is set to 'disable' this new grab command is omitted. This might be useful especially for random switching between several connected cameras. Default: 'enable'.
'start_column' 0 ... max Sets the column coordinate of the upper left corner of the resulting HALCON image part.
'start_field' 'even', 'odd', 'next', 'default' Specifies the field that the grabbing of a frame starts with. If the parameter 'start_field' is set to 'even' the grabbing starts with the even field, if it is 'odd' it starts with the 'odd' field, and in case of 'next' the grabbing starts with the next field. If 'start_field' is set to 'default' the grabbing starts with the board-specific default. For the actual default start field, please see the documentation of your Matrox frame grabber board. Default: 'default'.
'start_row' 0 ... max Sets the row coordinate of the upper left corner of the resulting HALCON image part.
'trigger_signal' 'default', 'rising', 'falling', 'high', 'low' Defines the expected type of input trigger. 'rising' ('falling') requires the external trigger to go low (high) and high (low) again before the next image can be acquired; in case of 'high' ('low') an image can be acquired during the whole time the trigger is high (low). 'default' specifies the trigger mode in the DCF file or, if none, 'rising'.
'trigger_source' 'none', 'default', 'hw_port_camera', 'hw_port0', ..., 'hw_port11', 'rotary_counter', 'software', 'timer1', 'timer2' Defines the source of the input trigger. For details, please see the documentation of your frame grabber board.
'do_abort_grab' --- Abort the current image acquisition.
'do_force_trigger' --- Forces an event trigger from the application, when using the external trigger. This might be useful for testing purposes. Note, that 'do_force_trigger' requires an asynchronous grab already pending!
'do_gpio_write:XX' 0,1 Sets the functional state of a specific GPIO line (with XX = 0,1,...,15 as unique index of the desired GPIO line).
'do_reset_rotary_counter' --- Resets the rotary counter to zero.

The following parameters apply only to Matrox Meteor-II/1394 boards. Note that they (and also the valid parameter values!) depend on the capabilities of the used camera.

You can request the valid minimal and maximal integer values by calling get_framegrabber_param(...,'parameter_name_range',...) Note that the default values of most of the following parameters depend on the current camera settings!

'brightness' min ... max Sets the brightness value of the camera. If the used camera does not support brightness adjustment, H_ERR_FGPARAM is returned (or an empty tuple in the corresponding call to get_framegrabber_param, respectively).
'exposure' min ... max Sets the auto exposure value of the camera. If the used camera does not support exposure adjustment, H_ERR_FGPARAM is returned (or an empty tuple in the corresponding call to get_framegrabber_param, respectively).
'focus' min ... max Sets the focus value of the camera. If the used camera does not support focus adjustment, H_ERR_FGPARAM is returned (or an empty tuple in the corresponding call to get_framegrabber_param, respectively).
'gamma' min ... max Sets the gamma value of the camera. If the used camera does not support gamma adjustment, H_ERR_FGPARAM is returned (or an empty tuple in the corresponding call to get_framegrabber_param, respectively).
'hue' min ... max Sets the hue value of the camera. If the used camera does not support hue adjustment, H_ERR_FGPARAM is returned (or an empty tuple in the corresponding call to get_framegrabber_param, respectively).
'iris' min ... max Sets the iris value of the camera. If the used camera does not support iris adjustment, H_ERR_FGPARAM is returned (or an empty tuple in the corresponding call to get_framegrabber_param, respectively).
'saturation' min ... max Sets the saturation value of the camera. If the used camera does not support saturation adjustment, H_ERR_FGPARAM is returned (or an empty tuple in the corresponding call to get_framegrabber_param, respectively).
'shutter' min ... max Sets the shutter value of the camera. If the used camera does not support shutter adjustment, H_ERR_FGPARAM is returned (or an empty tuple in the corresponding call to get_framegrabber_param, respectively).
'ub' min ... max Sets the ub value of the camera. If the used camera does not support ub adjustment, H_ERR_FGPARAM is returned (or an empty tuple in the corresponding call to get_framegrabber_param, respectively).
'video_gain' min ... max Sets the gain value of the camera. If the used camera does not support gain adjustment, H_ERR_FGPARAM is returned (or an empty tuple in the corresponding call to get_framegrabber_param, respectively).
'vr' min ... max Sets the vr value of the camera. If the used camera does not support vr adjustment, H_ERR_FGPARAM is returned (or an empty tuple in the corresponding call to get_framegrabber_param, respectively).
'zoom' min ... max Sets the zoom value of the camera. If the used camera does not support zoom adjustment, H_ERR_FGPARAM is returned (or an empty tuple in the corresponding call to get_framegrabber_param, respectively).

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. Furthermore, corresponding to the parameters supported by set_framegrabber_param, there may exist additional read-only parameters with the following postfixes:

  • '_description': These parameters provide the tooltip of the corresponding parameter as a string.
  • '_range': These parameters provide the minimum, maximum, stepwidth, and default values for the corresponding integer or float parameter as a tuple with 4 elements, e.g., get_framegrabber_param(..,'exposure_range',..) will return the output tuple [min,max,step,default]. Optionally, this tuple can also contain additional valid string values like 'auto' or 'manual'.
  • '_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'].
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.

'available_callback_types' callback_type  Query all callback types which are supported by this interface.
'board_type' board_type (long) Returns the actual board type.
'gpio_read:XX' 0, 1 Gets the current state of the specified GPIO input (with XX = 0,1,...,15 as unique index of the desired GPIO line).
'revision' revision (string) Revision of the HALCON MILLite image acquisition interface.
'rotary_counter_position' position (long) Returns the current value of the rotary counter.

Parameters for set_framegrabber_callback():

The following callback types are supported by this interface:

'frame_end' Corresponds to the M_GRAB_FRAME_END hook function inside MIL-Lite.
'frame_start' Corresponds to the M_GRAB_FRAME_START hook function inside MIL-Lite.
'transfer_end' Corresponds to the M_GRAB_END hook function inside MIL-Lite.

All actually supported callback types of a specific image acquisition device can be queried by calling get_framegrabber_param with the parameter 'available_callback_types'. Once the callback is registered, on every occurrence of the underlying event (e.g., the notification that the exposure has finished) the specified callback function will be called. If the callback function is set to NULL, the corresponding callback will be unregistered.

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. In the MILLite interface, this parameter is not used, i.e., Context is set to NULL.
UserContext User context as set via set_framegrabber_callback.

Using user-callback functions

Note that the execution time of a user-specific callback function should 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 actual processing from the user-specific callback function to a separate thread that is controlled via signals or events.

Multiple Cameras (Port Switching) on Meteor-II boards

It is possible to connect more than one camera to a Meteor-II board. To access a specific camera, you have to specify the corresponding port. This setting can be changed dynamically using the operator set_framegrabber_param(...,'port',...) (port switching). However, in this case the used cameras must be compatible, that is of the same type or with similar features (if in doubt please contact your local vendor or Matrox).

With this mechanism you can access multiple cameras with one image acquisition handle. Note that a pending asynchronous job blocks the switching of the port. Therefore, it does not make much sense to use grab_image_async in combination with port switching. Please see also the HDevelop example program millite_2ports.dev you will find in %HALCONROOT%\examples\hdevelop\Image\Acquisition.

Meteor-II/1934 and Meteor-II/Multi-Channel boards also allow multiple image acquisition instances per frame grabber board, with different camera settings per image acquisition instance. Thus, multiple incompatible cameras can be accessed with one frame grabber board.

Trigger Arm Characteristics

The so-called Trigger Arm Characteristics (like Frame Retrigger, Software Ignore Frame Retrigger, Hardware Ignore Frame Retrigger, and Frame Retrigger Latched) is specified inside the Matrox DCF files. To use this functionality within the HALCON MILLite interface, both the continuous grabbing mode and external triggering has to be enabled, see the parameters 'continuous_grabbing' and 'external_trigger'. Please make sure that your MIL-Lite version already supports this feature!

Release Notes

  • Revision 4.9 (Jan 24, 2011):
    • Added support of parameters ImageWidth, ImageHeight, StartRow, and StartColumn in open_framegrabber to allow specifying a certain image part.
    • Added parameters 'image_width', 'image_height', 'start_row', and 'start_column' to dynamically change the current image size during runtime.
  • Revision 4.8 (May 30, 2011):
    • Support also of Morphis boards.
  • Revision 4.7 (Dec 13, 2010):
    • Added parameters 'gpio_read:XX', 'do_gpio_write:XX', 'gpio_mode:XX', 'gpio_format:XX', 'cc1_select', 'cc2_select', 'cc3_select' and 'cc4_select' to control the GPIO lines of the Helios, Odyssey and Solios frame grabber boards.
  • Revision 4.6 (Aug 25, 2010):
    • Removed obsolete internal parameter queries in open_framegrabber.
    • Fixed bug regarding error handling in continuous grabbing mode.
    • HALCON 10 version of the interface (included in HALCON 10 DVD).
  • Revision 4.5 Erratum (May 19, 2010):
    • Re-added the support of Meteor-II boards in the documentation. This information was deleted in the original release of revision 4.5 by mistake.
  • Revision 4.5 (Mar 16, 2010):
    • Adapted to Matrox MIL-Lite 9.0.
    • Support also of Windows XP/Vista x64 Editions.
    • Added Generic parameter 'num_buffers' in open_framegrabber to allow to set the number of internally used buffers.
    • New read-only parameter 'num_buffers' to query the number of internally used buffers.
    • Added implementation of info_framegrabber(..,'generic',...) to query all supported values for the Generic parameter in open_framegrabber.
    • Decreased the default number of allocated images buffers for each initialized camera from 5 to 2.
    • New expert parameter 'current_buffer_index' to manually control the buffer ordering.
  • Revision 4.4 (Jan 22, 2010):
    • New parameter 'continuous_grabbing' to enable the use of the continuous grabbing mode.
    • Increased the number of allocated images buffers for each initialized camera from 2 to 5.
    • Added section "Trigger Arm Characteristics" in this documentation.
  • Revision 4.3 (Nov 11, 2009):
    • Support also of Solios eCL/XCL-B boards.
    • Adapted open_framegrabber to enable the use of boards with multiple input channels in general.
  • Revision 4.2 (Sep 18, 2009):
    • Bugfix in set_framegrabber_param('do_abort_grab') to ensure the proper behaviour also in case that no corresponding grab operator is called concurrently.
    • Bugfix regarding the order of the parameters when calling the user-specific callback functions: Erroneously, the parameters UserContext and Context were swapped, i.e., the parameter UserContext now is used as third parameter.
    • Bugfix regarding the AcqHandle parameter when calling the user-specific callback functions: In case of multiple instances, the wrong acquisition handle was returned.
    • Added note in documentation that Solios GigE boards are not supported.
  • Revision 4.1 (Aug 31, 2009):
    • Bugfix in close_framegrabber to enable the cleanup of all ressources also in case of external triggering.
    • Bugfix in open_framegrabber, grab_image, grab_image_async, and grab_image_start regarding the use of multiple cameras connected to the same physical board.
    • Bugfix in set_framegrabber_param('do_abort_grab').
  • Revision 4.0 (Dec 1, 2008):
    • HALCON 9.0 version of the interface (included in HALCON 9.0 DVD).
    • Bugfix in grab_image_async to reach the full frame rate in case of free-running analog cameras.
    • Bugfix in grab_image_async for software triggering.
    • Support also of Vio boards.
    • Add functionality to handle 'frame_start', 'frame_end', and 'transfer_end' callbacks.
  • Revision 3.3 (Apr 22, 2008):
    • Added read-only parameters with postfix '_description', '_range', and '_values' to enable the easy parameterization via a generic graphical user interface.
  • Revision 3.2 (Sep 5, 2007):
    • Bugfix in buffer handling.
    • New parameter 'board_type'.
  • Revision 3.1 (Jul 27, 2007):
    • Bugfix in open_framegrabber when accessing the actual board type.
  • Revision 3.0 (May 15, 2007):
    • HALCON 8.0 version of the interface (included in HALCON 8.0 DVD).
  • Revision 2.3 (Mar 20, 2007):
    • Bugfix in grab_image and grab_image_async (grab_timeout).
    • Bugfix in buffer handling (M_GRAB_FRAME_END no longer used for buffer switching).
  • Revision 2.2 (Aug 14, 2006):
    • Improved use of double buffering.
    • New parameter 'start_field'.
    • Improved error messages.
    • M_GRAB_END event used for image transfer.
  • Revision 2.1 (Apr 19, 2006):
    • Change of semantics of parameters Device and Port in open_framegrabber.
    • Bugfix to enable setting of the grab timeout.
  • Revision 2.0 (Dec 06, 2005):
    • First official release.


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






Last modified: Tue Jan 24 13:12:23 CET 2012