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

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

Revision: 3.10

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 parhAcqMILLite.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, 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.

Limitations

• Only one image acquisition instance per frame grabber board for Meteor-II, Meteor-II/cl, and Metor-II/dig boards. However, multiple compatible cameras can be accessed using port switching.
• No support of onboard image preprocessing capabilities.
• No support of Solios GigE boards.
• 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		---		Ignored.
	ImageHeight		---		Ignored.
	StartRow		---		Ignored.
	StartColumn		---		Ignored.
	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', '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():

	'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.
	'grab_timeout'		milliseconds		Specify the desired timeout (milliseconds passed as an integer) for aborting a pending grab. Default: 5000.
	'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_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' lthe 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'.
	'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_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'].

	'board_type'		board_type (long)		Returns the actual board type.
	'revision'		revision (string)		Revision of the HALCON MILLite image acquisition interface.
	'rotary_counter_position'		position (long)		Returns the current value of the rotary counter.

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 paramters 'continuous_grabbing' and 'external_trigger'. Please make sure that your MIL-Lite version already supports this feature!

Release Notes

• Revision 3.10 (Aug 25, 2010):
  • Removed obsolete internal parameter queries in open_framegrabber.
  • Fixed bug regarding error handling in continuous grabbing mode.
• Revision 3.9 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 3.9 by mistake.
• Revision 3.9 (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 3.8 (Jan 26, 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 3.7 (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 3.6 (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.
  • Added note in documentation that Solios GigE boards are not supported.
• Revision 3.5 (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 3.4 (Dec 1, 2008):
  • Bugfix in grab_image_async to reach the full frame rate in case of free-running analog cameras.
  • Bugfix in grab_image_async to allow software triggering.
  • Support also of Vio boards.
• 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.