interfaces mvtec

Interface Documentation

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

Interface: INSPECTA
Revision: 6.0
Date: 2014-10-31
HALCON Version: 12.0
INSPECTA: Legacy Interface

General

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.

System Requirements

  • Intel compatible PC with Windows Vista/7.
  • Successfully installed Mikrotron driver mpfgnt.sys (version 3.92 or higher). Note that driver versions newer then version 4.10 do not support INSPECTA-3 boards!
  • 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 hAcqINSPECTAxl.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.

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 set_framegrabber_param(..., 'port', ...). 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(..., 'external_trigger', '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.

Parameters for info_framegrabber

Parameter Value List Type Kind Description
'bits_per_channel' [] Unused.
'camera_type' ['CAMFILE:', 'cam', 'C:\\'] string pre-defined Syntax for the camera configuration file.
'color_space' [] Unused.
'defaults' [1, 1, 0, 0, 0, 0, 'interlaced', 8, 'rgb', -1.0, 'false', '\\Inspecta\\mvfgcam.cam;Testmode', '0', -1, 0] mixed pre-defined Default values for open_framegrabber.
'device' ['0', '1', '2', '3'] string pre-defined Returns a pre-defined list of possible device numbers.
'external_trigger' ['false', 'true'] string pre-defined Values for the external trigger.
'field' [] Unused.
'general' [] string pre-defined Information about the HALCON INSPECTA interface.
'generic' [] Unsupported query.
'horizontal_resolution' 1 integer pre-defined Value list for horizontal resolution.
'image_height' [] Unsupported query.
'image_width' [] Unsupported query.
'info_boards' ' ' string pre-defined A list of the available devices.
'parameters' ['<parameters>'] string pre-defined Pre-defined parameters of the HALCON interface.
'parameters_readonly' ['<parameters>'] string pre-defined Pre-defined read-only parameters of the HALCON interface.
'parameters_writeonly' ['<parameters>'] string pre-defined Pre-defined write-only parameters of the HALCON interface.
'port' 0, 1, 2, ... 7 integer pre-defined Static list of possible values for port.
'revision' '<revision>' string pre-defined Revision number of the INSPECTA interface.
'start_column' [] Unsupported query.
'start_row' [] Unsupported query.
'vertical_resolution' 1 integer pre-defined Value list for vertical resolution.

Parameters for open_framegrabber

Parameter Values Default Type Description
Name 'INSPECTA' string Name of the HALCON interface.
HorizontalResolution --- Ignored (the desired image resolution is set via the camera configuration file specified in the CameraType parameter!).
VerticalResolution --- Ignored (the desired image resolution is set via the camera configuration file specified in the CameraType parameter!).
ImageWidth --- Ignored (the desired image part is set via the camera configuration file specified in the CameraType parameter!).
ImageHeight --- Ignored (the desired image part is set via the camera configuration file specified in the CameraType parameter!).
StartRow --- Ignored (the desired image part is set via the camera configuration file specified in the CameraType parameter!).
StartColumn --- Ignored (the desired image part is set via the camera configuration file specified in the CameraType parameter!).
Field --- Ignored.
BitsPerChannel --- Ignored (the desired number of bits per image channel set via the camera configuration file specified in the CameraType parameter!).
ColorSpace --- Ignored.
Generic --- Ignored.
ExternalTrigger 'false', 'true' 'false' string Activate/deactivate external triggering. Note that this setting overwrites the corresponding setup in the camera configuration file.
CameraType <file;camera> '\\Inspecta\\mvfgcam.cam;Testmode' 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' '0' string Number of the frame grabber board (passed as a string!).
Port <port> -1 integer 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)
LineIn --- Ignored.

Parameters for set_framegrabber_param

Parameter Values Type Description
'continuous_grabbing' 'disable', 'enable' string 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.
'do_abort_grab' --- Cancel current grab.
'external_trigger' 'false', 'true' string Activate/deactivate external triggering. Note that this setting overwrites the corresponding setup in the camera configuration file.
'grab_timeout' <milliseconds> integer Desired timeout (milliseconds) for aborting a pending grab. If -1 is specified, the timeout is set to INFINITE.
'photo' 0, 1, 2, ... integer 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' <port> integer Switch to the camera with the specified number.
'start_async_after_grab_async' 'disable', 'enable' string By default a new asynchronous grab command is automatically given to the acquisition device at the end of grab_image_async. If the parameter 'start_async_after_grab_async' is set to 'disable', this new grab command is omitted.
'trigger_mode' 'edge', 'pulse_width' string 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.
'volatile' 'disable', 'enable' string Grayscale only. 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!

Parameters for get_framegrabber_param

There may exist additional read-only parameters with the following postfixes:
  • '_description': These parameters provide the tool-tip of the corresponding parameter as a string.
  • '_range': These parameters provide the minimum, maximum, step width, and default 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,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.

Parameter Values Default Type Kind Description
'bits_per_channel' <default> value from camera configuration file integer pre-defined Number of bits per channel of the resulting HALCON image. In case of -1 the current bit depth of the camera is used. By specifying a value greater than 8 the grabbed images are delivered as uint2 images.
'camera_type' <file;camera> '\\Inspecta\\mvfgcam.cam;Testmode' string pre-defined Current camera type.
'color_space' '<default>' 'rgb' string pre-defined The value is not used, so a default value is returned.
'color_type' <color_type> -1 integer dynamic Current setting of the COLOR_TYPE parameter (see the INSPECTA documentation for more details).
'continuous_grabbing' 'disable', 'enable' 'disable' string pre-defined 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.
'device' '0', '1', '2', '3' '0' string pre-defined Returns the current device number.
'external_trigger' 'false', 'true' 'false' string pre-defined Activate/deactivate external triggering. Note that this setting overwrites the corresponding setup in the camera configuration file.
'field' '<default>' 'interlaced' string pre-defined The value is not used, so a default value is returned.
'generic' <default> -1 integer pre-defined The value is not used, so a default value is returned.
'grab_timeout' <milliseconds> 10000 integer pre-defined Current grab timeout in milliseconds.
'horizontal_resolution' <resolution> 1 integer pre-defined Current value of horizontal resolution.
'image_available' 0, 1 integer dynamic 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. Note that this parameter is especially useful in combination with external triggering.
'image_height' <height> 0 integer pre-defined Height of the desired image part ('0' stands for the complete image).
'image_width' <width> 0 integer pre-defined Width of the desired image part ('0' stands for the complete image).
'line_in' <default> 0 integer pre-defined The value is not used, so a default value is returned.
'name' 'INSPECTA' string pre-defined Name of the HALCON interface.
'photo' 0, 1, 2, ... 0 integer dynamic 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' <port> -1 integer pre-defined Port number.
'revision' '<revision>' string pre-defined Revision number of the INSPECTA interface.
'seq_color' <seq_color> -1 integer pre-defined Current setting of the SEQ_COLOR parameter (see the INSPECTA documentation for more details).
'start_async_after_grab_async' 'disable', 'enable' 'enable' string pre-defined Status of 'start_async_after_grab_async'.
'start_column' <column> 0 integer pre-defined Returns the current start column of the HALCON image.
'start_row' <row> 0 integer pre-defined Returns the current start row of the HALCON image.
'trigger_mode' 'edge', 'pulse_width' 'edge' string pre-defined 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.
'vertical_resolution' <resolution> 1 integer pre-defined Current value of vertical resolution.
'volatile' 'disable', 'enable' 'disable' string pre-defined Grayscale only. 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!

Operator set_framegrabber_lut

Not supported by this interface.

Operator get_framegrabber_lut

Not supported by this interface.

Operator set_framegrabber_callback

Not supported by this interface.

Operator get_framegrabber_callback

Not supported by this interface.

Operator grab_image_start

Starts a new asynchronous grab. See also grab_image_start.

Operator grab_image

grab_image starts a new synchronous grab. See also grab_image. Note that the interface converts the image from the device to the desired image format specified by the parameters 'image_width', 'image_height', 'start_row', 'start_column', 'bits_per_channel', and 'color_space'.

Operator grab_image_async

grab_image_async returns an image and starts the next asynchronous grab. See also grab_image_async. Note that the interface converts the image from the device to the desired image format specified by the parameters 'image_width', 'image_height', 'start_row', 'start_column', 'bits_per_channel', and 'color_space'.

Operator grab_data

Not supported by this interface.

Operator grab_data_async

Not supported by this interface.

Operator close_framegrabber

This operator closes the device. See also close_framegrabber.

HDevelop Examples

For this interface there are the following examples available:
  • inspecta_2parallel.hdev - Usage of a Mikrotron Inspecta frame grabber board with two cameras and parallel input.
  • inspecta_2ports.hdev - Shows the usage of two cameras and port switching.
  • inspecta.hdev - Benchmark
  • inspecta_parameters.hdev - Lists all parameters of a device.
  • inspecta_simple.hdev - A simple example to show the usage of the interface.

Release Notes

  • Revision 6.0 (Oct 31, 2014):
    • HALCON 12 version of the interface.
  • Revision 5.0 (May 15, 2012):
  • Revision 4.1 (Nov 23, 2009):
    • Fixed bug in color conversion.
    • HALCON 10 version of the interface (included in HALCON 10 DVD).
  • Revision 4.0 (Dec 1, 2008):
    • HALCON 9.0 version of the interface (included in HALCON 9.0 DVD).
  • 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 preceding 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'.
    • Bug fix 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.
    • Bug fix 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'.
    • Bug fix 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).
    • Bug fix, 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.
    • Bug fixes for color modes 16bpp and 32bpp.
  • Revision 1.1 (Jun 29, 1999):
    • First official release.