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
- System Requirements
- Features
- Limitations
- Multiple Cameras (Port Switching)
- Multiple Cameras (Parallel Input)
- External Triggering
- Parameters for info_framegrabber
- Parameters for open_framegrabber
- Parameters for set_framegrabber_param
- Parameters for get_framegrabber_param
- Operator set_framegrabber_lut
- Operator get_framegrabber_lut
- Operator set_framegrabber_callback
- Operator get_framegrabber_callback
- Operator grab_image_start
- Operator grab_image
- Operator grab_image_async
- Operator grab_data
- Operator grab_data_async
- Operator close_framegrabber
- HDevelop Examples
- Release Notes
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):
- HALCON 11 version of the interface (included in HALCON 11 DVD).
- Fixed thread safety problem in grab_image and grab_image_async that could occur if a pending grab was aborted via the 'do_abort_grab' parameter of set_framegrabber_param.
- 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.