HALCON 8.0 Image Acquisition Interface for Mikrotron INSPECTA-3 and INSPECTA-4 Boards

This page provides the documentation of the HALCON INSPECTA image acquisition interface for the Mikrotron frame grabber boards INSPECTA-3 and INSPECTA-4. Registered customers can download the latest revision of this interface from the MVTec WWW server.

Revision: 3.4

System Requirements

• Intel compatible PC with Windows NT 4.0 (Service Pack 4) or Windows 2000/XP.
• Successfully installed Mikrotron driver mpfgnt.sys (version 3.92 or higher).
• Mikrotron DLL mvfgd32.dll (version 2.47 or higher)
  This DLL must be within your search path %PATH%. If you do not have this DLL, please contact Mikrotron or the vendor from which you bought the frame grabber board.
• HALCON image acquisition interface hAcqINSPECTA.dll or parhAcqINSPECTA.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

• Multiple frame grabber boards (up to 4).
• Multiple compatible cameras per board (port switching or up to 4 cameras parallel).
• Synchronous and asynchronous grabbing.
• External trigger (with software override of the camera configuration file).
• Support of a large variety of analog and digital cameras based on the Mikrotron camera configuration files.
• Support of line scan cameras.

Limitations

• Only one frame grabber instance per frame grabber board (however, multiple compatible cameras can be accessed using port switching or parallel grabbing).
• No subsampling or cropping of image parts.
• No LUTs.
• grab_data and grab_data_async not supported.

Description

Parameters for open_framegrabber():

	Name		'INSPECTA'		The name of the HALCON image acquisition interface.
	HorizontalResolution		1		Ignored (the desired image resolution is set via the camera configuration file specified in the CameraType parameter!). Default: 1.
	VerticalResolution		1		Ignored (the desired image resolution is set via the camera configuration file specified in the CameraType parameter!). Default: 1.
	ImageWidth		0		Ignored (the desired image part is set via the camera configuration file specified in the CameraType parameter!). Default: 0.
	ImageHeight		0		Ignored (the desired image part is set via the camera configuration file specified in the CameraType parameter!). Default: 0.
	StartRow		0		Ignored (the desired image part is set via the camera configuration file specified in the CameraType parameter!). Default: 0.
	StartColumn		0		Ignored (the desired image part is set via the camera configuration file specified in the CameraType parameter!). Default: 0.
	Field		---		Ignored.
	BitsPerChannel		---		Ignored (the desired number of bits per image channel set via the camera configuration file specified in the CameraType parameter!). Default: -1.
	ColorSpace		---		Ignored.
	Generic		---		Ignored.
	ExternalTrigger		'true', 'false'		Activate/deactivate external triggering. Note that this setting overrides the corresponding setup in the camera configuration file. Default: 'false'.
	CameraType		'file;camera'		This parameter is used to specify the camera configuration file and the section within this file (e.g., 'c:\\inspecta-2\\mvfgcam.cam;TM-6701 HD out' for the configuration file 'mvfgcam.cam' and the camera 'TM-6701 HD out'). To check a camera or to alter the camera configuration file, use the VCAM95 program delivered with the INSPECTA software.
	Device		'0', '1', '2', '3'		The number of the frame grabber board (passed as a string!). Default: '0'.
	Port		number		The number attached to the desired camera channel (0: upper connector, 4: lower connector, or, if you use the breakout box, 0,1,2 with the upper connector and 4,5,6 with the lower connector). Default: 0.
	LineIn		---		Ignored.

Parameters for set_framegrabber_param():

	'continuous_grabbing'		'enable', 'disable'		Activate or deactivate 'continuous grabbing'. Sets grabbing mode from single frame capture to continuous mode. If the continuous mode is enabled, the frame grabber board will grab all the time. In this mode you can achieve full frame rate. This mode is not allowed in combination with external triggering. Default: 'disable'.
	'do_abort_grab'		---		Cancel current grab.
	'external_trigger'		'true', 'false'		Activate/deactivate external triggering. Note that this setting overwrites the corresponding setup in the camera configuration file.
	'grab_timeout'		msec		Specify the desired timeout (milliseconds passed as an integer) for aborting a pending grab (the default value is specified in the camera configuration file).
	'photo'		0, 1, 2, ...		Shutter time (in periods of the line-frequency) if you shutter the camera via the grabber (and shuttering is defined in the camera configuration file).
	'port'		number		Switch to the camera with the specified number.
	'start_async_after_grab_async'		'enable', 'disable'		By default, at the end of grab_image_async a new 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 switching between several connected cameras. Default: 'enable'.
	'trigger_mode'		'edge', 'pulse_width'		Specify desired trigger mode: 'edge' means that the trigger edge initiates the image acquisition (with a fixed image height). If trigger mode is set to 'pulse_width' the length of the trigger signal controls the actual image height. This mode is especially useful in combination with line scan cameras. Default: 'edge'.
	'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 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'].

	'color_type'		color_type		The current setting of the COLOR_TYPE parameter (see the INSPECTA documentation for more details).
	'image_available'		0, 1		Returns the status of the last asynchronous grab command. The value 1 means that the image is already acquired and thus can be fetched by grab_image_async without delay.
	'revision'		revision		The revision number of the HALCON INSPECTA interface.
	'seq_color'		seq_color		The current setting of the SEQ_COLOR parameter (see the INSPECTA documentation for more details).

Multiple Cameras (Port Switching)

It is possible to connect more than one camera to a INSPECTA board. Each one of the 6 input channels is attached with a number from 0 to 2 and 4 to 6 (if using the breakout box). Without usage of a breakout box, you can connect 2 cameras to the INSPECTA; the according numbers are 0 and 4. These numbers are used as port parameter in the HALCON interface. To access a specific camera, you have to specify the corresponding port. This setting can be changed dynamically using the operator set_framegrabber_param(AcqHandle, 'port', number). However, in this case the used cameras must be compatible, i.e. of the same type or with similar features (if in doubt please contact your local vendor or Mikrotron). If you use an additional high speed interface board, you may connect another 2 cameras with the INSPECTA (ports 3 and 7). Thus, up to 8 cameras may be connected with one INSPECTA board.

Multiple Cameras (Parallel Input)

In parallel input mode, it is possible to get the frames of up to 3 cameras (or 4, if you use an additional interface board) at a time. Both grab_image and grab_image_async simply will return all 3 (or 4) frames of the cameras. For this mode, you only have to select the appropriate section in the camera configuration file (e.g., '2 x TM-9701 digital shutter') during the open_framegrabber call.

External Triggering

If you enable this mode via open_framegrabber or set_framegrabber_param(AcqHandle, 'ExternalTrigger', 'enable'), one image will be acquired with the trigger and stored in the buffer, if you activated this via grab_image_start. Thus, your HALCON application can process other data without loosing the frame. After activating the external trigger for one frame with grab_image_start, both grab_image and grab_image_async simply will return the next frame (or wait if it has not been acquired so far). Note that the external trigger is only allowed for cameras, that are asynchronous resettable, e.g., the PULNIX TM-9701.

Release Notes

• Revision 3.4 (Nov 23, 2009):
  • The red and blue image channels were swapped for the 32BPP_XBGR pixel format. This bug has been fixed.
• Revision 3.3 (Aug 13, 2008):
  • info_framegrabber('info_boards') now returns an empty string instead of a NULL pointer to enable the basic auto-detection of actually available devices in HDevelop.
• Revision 3.2 (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.1 (Mar 27, 2008):
  • The first synchronous grab via grab_image after a preceeding asynchronous grab returned an old image. This bug has been fixed.
• Revision 3.0 (May 15, 2007):
  • HALCON 8.0 version of the interface (included in HALCON 8.0 DVD).
• Revision 2.10 (Jan 12, 2007):
  • Adaptation to driver version 3.92.
  • New parameters 'image_available' and 'do_abort_grab'.
  • Support of multiplexer for Camera Link cameras via the parameter 'port'.
  • Bugfix in grab_image_async if 'start_async_after_grab_async' is disabled.
• Revision 2.9 (Jan 18, 2006):
  • Support of more 10 bit cameras with special pixel arrangements.
  • Bugfix in color coding for 10 bit cameras.
• Revision 2.8 (Jul 27, 2005):
  • HALCON 7.1 version of the interface (included in HALCON 7.1 CD).
  • Speed-up for acquisition of RGB images (avoiding cache alignment failures when converting the interleaved image data into HALCON image objects).
• Revision 2.7 (Dec 16, 2004):
  • New parameter 'start_async_after_grab_async'.
  • Bugfix in grabbing images with more than 8bpp.
  • The query types 'bits_per_channel', 'camera_type', 'color_space', 'device', 'external_trigger', 'field', and 'port' for info_framegrabber provide now specific value lists for the corresponding parameters in open_framegrabber.
• Revision 2.6 (Jan 13, 2004):
  • Support of additional pixel formats.
• Revision 2.5 (Oct 1, 2003):
  • HALCON 7.0 version of the interface (included in HALCON 7.0 CD).
  • Enhanced debugging information in case of errors during initialization.
• Revision 2.4 (Jun 6, 2003):
  • New parameter 'trigger_mode' to allow image acquisition with the pulse length of the trigger signal controlling the actual height of the grabbed image.
• Revision 2.3 (Jul 17, 2002):
  • Adaptation to the Mikrotron INSPECTA driver 3.02 (end of grab now notified by event instead of polling).
• Revision 2.2 (Jul 10, 2001):
  • HALCON 6.1 version of the interface (included in HALCON 6.1 CD).
  • Renaming from 'Inspecta2' into 'Inspecta' (supports also the INSPECTA-3 and INSPECTA-4 boards).
  • Bugfix, mainly for line scan cameras (consideration of the subframes specified by req_frm).
• Revision 2.1 (Mar 23, 2001):
  • Bugfix in 3 planes modes.
• Revision 2.0 (Jul 19, 2000):
  • Adaptation to the HALCON 6.0 frame grabber integration interface.
• Revision 1.2 (Jun 13, 2000):
  • New b&w modes.
  • Bugfixes for color modes 16bpp and 32bpp.
• Revision 1.1 (Jun 29, 1999):
  • First official release.