HALCON 10 Image Acquisition Interface for MATRIX VISION Boards
This page provides the documentation of the HALCON MatrixVision image acquisition interface for the MATRIX VISION GmbH boards mvDELTA, mvSIGMA, pcIMAGE, mvTITAN, and mvGAMMA. Registered customers can download the latest revision of this interface from the MVTec WWW server.
Revision: 4.1
System Requirements
- Intel compatible PC with Windows XP, Vista or Windows 7.
- Successfully installed MATRIX VISION driver from the MATRIX VISION Driver CD (CD2008/B or higher).
-
Successfully installed mvConfig or mvAcquireControl
(version 3.144 or higher).
If you do not find this version on your CD, please download it from the MATRIX VISION WWW server. - Make sure that the allocated buffer size of the MATRIX VISION driver is big enough (the HALCON interface uses 6 buffers alternately!). Please check the parameter setting of AllocFrameBuffer in the file grabber.ini, which is usually located in the %WINDOWSROOT%\Matrix directory! If you are working with linear memory, check the settings of the tool 'setdma.exe' in %WINDOWSROOT%\Matrix. Otherwise the grabbing will lead to an error ("no video signal").
- Working under XP you must enable at least the following advanced user right when not working with an Administrator account: 'Increase scheduling priority' (for the German version of Windows: 'Anheben der Zeitplanungspriorität'). These settings can be made under Windows XP via 'Settings -> Control Panel -> Administrative Tools -> Local Security Policy -> Local Policies -> User Rights Assignment').
- HALCON image acquisition interface hAcqMatrixVision.dll or hAcqMatrixVisionxl.dll, respectively. If you have installed the interface properly, 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.
- Multiple compatible cameras per board.
- Synchronous and asynchronous grabbing.
- External trigger (not available for mvDELTA).
- Support of a large assortment of analog and digital cameras based on the MATRIX VISION camera configurations.
- Software control of a variety of acquisition parameters directly from the HALCON application.
- Online configuration via the mvAcquireControl.
Limitations
- No subsampling or cropping of image parts.
- No LUTs.
- grab_data and grab_data_async not supported.
Description
Parameters for open_framegrabber():
| Name | 'MatrixVision' | The name of the HALCON image acquisition interface. | |||
| HorizontalResolution | 1 | Ignored (the desired image resolution is set via the camera configuration specified in the CameraType parameter or via the online camera control dialog!). Default: 1. | |||
| VerticalResolution | 1 | Ignored (the desired image resolution is set via the camera configuration specified in the CameraType parameter or via the online camera control dialog!). Default: 1. | |||
| 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 | The row coordinate of the upper left pixel within the desired image part. Default: 0. | |||
| StartColumn | 0 | The column coordinate of the upper left pixel within the desired image part. Default: 0. | |||
| Field | --- | Ignored (the desired field is set via the camera configuration specified in the CameraType parameter or via the online camera control dialog!). | |||
| BitsPerChannel | 8 | Number of bits per image channel which will be delivered by the board via the PCI bus. Default: 8. | |||
| ColorSpace | 'gray', 'rgb' | Specify the desired color space and thus the number of image channels of the resulting HALCON image. Note that not all MATRIX VISION board types support both modes! Default: 'gray'. | |||
| Generic | --- | Ignored. | |||
| ExternalTrigger | 'true', 'false' | Activate/deactivate external triggering. Note that this setting overrides the corresponding setup in the camera configuration. Default: 'false'. | |||
| CameraType | 'configname' | This parameter is used to specify the camera configuration which is stored in the Windows registry. To check a camera or to alter the camera configuration file, use the mvConfig program delivered with the MATRIX VISION software. | |||
| Device | --- | Ignored. | |||
| Port | number |
Specifies the port the camera is connected to. The possible
values (default: 1) depend on the specific board type: mvDELTA: number = 1, 2, 3, 4 mvSIGMA-SLx: number = 1, 2, 3, 4 pcIMAGE-SG/SGVS: number = 1, 2, 3, 4 pcIMAGE-SC: number = 1, 2, 3, 4 mvTITAN-G1: number = 1, 2, 3, 4 mvGAMMA-G: number = 1, 2, 3, 4 pcIMAGE-SRGB: number = 1, 2 mvTITAN-RGB: number = 1, 2 mvTITAN-CL: number = 1, 2 PCimage-SDIG: number = 1 mvTITAN-DIG: number = 1 mvSIGMA-SQ: number = 1 ... 16 mvTITAN-C16: number = 1 ... 16 mvTITAN-2C16: number = 1 ... 16 pcIMAGE-SRGB(CCIR mode): number = 1 ... 8 mvTITAN-RGB(CCIR mode): number = 1 ... 8 |
|||
| LineIn | --- | Ignored. | |||
Parameters for set_framegrabber_param():
| 'active_dig_io_mask' | 'integration_start', 'integration_stop', 'flush', 'trigger', 'user_defined' |
This parameter can be used to apply a certain signal mask to the
digital I/O pins of the frame grabber (if supported). Once activated
the signal mask remains applied to the digital I/O pins until either
the board is closed or another mask is applied. The first 4 masks
are applied as they are defined in the configuration of the
mvAcquireControl. The last one ('user_defined') can be modified with
the HALCON parameter 'define_dig_io_mask'.
Default: 'integration_stop'. |
|||
| 'brightness' | 0 ... 100 |
Specify the brightness of the acquired image (or the position
of the corresponding slider in the mvAcquireControl).
Please make sure, that your frame grabber
supports this feature (if not, this slider will not be visible in
mvAcquireControl).
Default: Actual selection from the mvAcquireControl configuration. |
|||
| 'camera_definition' | name |
This parameter can be used to switch between different camera
definitions without closing the frame grabber in between.
Valid names are all camera definitions from the camdefs.ini file.
Default: Actual selection from the mvAcquireControl configuration. |
|||
| 'contrast' | 0 ... 100 |
Specify the contrast of the acquired image (or the position
of the corresponding slider in the mvAcquireControl).
Please make sure, that your frame grabber
supports this feature (if not, this slider will not be visible in
mvAcquireControl).
Default: Actual selection from the mvAcquireControl configuration. |
|||
| 'define_dig_io_mask' | mask |
This parameter works by defining a new signal mask for the
mvAcquireControl, which is also stored into the configuration data.
This mask can be written to by passing a 32-charater string to the
function containing '1' for each digital I/O pin which shall be
set to HIGH, '0' for each digital I/O pin which shall be set to
LOW and an arbitrary character for each pin to leave untouched.
To apply these mask to the digital I/O pins of the frame grabber the
parameter 'active_dig_io_mask' must be set to 'user_defined'.
Attention: You always have to pass 32 characters!
Example: '00000000000000000000000000000111' sets the last 3 digital I/O pins to HIGH, the rest to LOW; 'xxxxxxxxxxxxxxxxxxxxxxxxxxx10xxx' sets pin 5 to HIGH, pin 4 to LOW and leaves the other ones untouched. Please make sure, that your frame grabber supports the pins you are trying to apply the changes to. Default: 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'. |
|||
| 'dialog' | 'enable', 'disable' |
Open/close the online acquisition control of the MATRIX VISION
configuration software. Using this dialog you can modify
the settings of the current camera configuration.
Default: 'disable'. |
|||
| 'do_abort_grab' | --- | Abort the current image acquisition. | |||
| 'expose_period_time' | usec |
Specifies the period of the generated exposure signal. This feature
is frame grabber dependent and therefore will only be available
in HALCON if it is available in mvAcquireControl.
Default: Actual selection from the mvAcquireControl configuration. |
|||
| 'expose_time' | usec |
Specifies the length of the generated exposure signal pulse.
This feature is frame grabber dependent and therefore will only
be available in HALCON if it is available in mvAcquireControl.
Default: Actual selection from the mvAcquireControl configuration. |
|||
| 'external_trigger' | 'true', 'false' |
Activate/deactivate external triggering.
Default: Actual selection from the mvAcquireControl configuration. |
|||
| 'grab_timeout' | msec |
Specify the desired timeout (milliseconds passed as an integer) for
aborting a pending grab (without external triggering).
Default: Actual selection from the mvAcquireControl configuration. |
|||
| 'port' | number |
Switch to the camera connected to the specified port number
(see the description of possible values above).
Default: 1. |
|||
| 'queued_mode' | 'true', 'false' |
When activating this mode lossless acquisition becomes possible.
This mode is not available for all frame grabbers offered by
MATRIX VISION. If not supported, an error will be generated when
trying to activate this mode. After setting this parameter to 'true'
the next asynchronous grab will send a couple of snap requests to
the frame grabber, which will be handled in the background.
This mode must be switched of when not needed anymore!
Default: 'false'. |
|||
| 'shutter_time' | lines |
Specifies the length of the generated shutter signal pulse in lines.
This feature is frame grabber dependent and therefore will only
be available in HALCON if it is available in mvAcquireControl.
Default: Actual selection from the mvAcquireControl configuration. |
|||
| 'snapqueue_level' | number |
Specifies the input snap request queue level as defined
by the user (or the default value, which is equal to
'max_snapqueue_level' for this device). This parameter is
only taken into account, when the queueing mode for this
device is available and enabled. The value defines the
number of image requests used in the devices request queue,
when working in queued mode with asynchronous image capture.
The queue can be useful to overcome high CPU peak loads
without loosing images. This value can't be higher than
'max_snapqueue_level'. More information regrading this
topic can be found in the device manual in sections about
queuing mechanisms.
Default: 5. |
|||
| 'start_async_after_grab_async' | 'enable', 'disable' |
By default, at the end of grab_image_async the frame
grabber board automatically receives a new asynchronous grab
command. 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'. |
|||
| 'sync_channel' | number |
Selects the sync channel (for RGB grabbers only).
Default: Actual selection from the mvAcquireControl configuration. |
|||
| 'trigger_mode' | 'auto', 'external', 'external_start_stop' |
Specify the desired trigger mode. Note that these settings
are not available for every board type (see mvConfig documentation
for more information).
Default: 'external'. |
|||
| 'trigger_timeout' | msec |
Specify the desired timeout (milliseconds passed as an integer) for
aborting a pending grab when using an external trigger.
Default: Actual selection from the mvAcquireControl configuration. |
|||
| 'volatile' | 'enable', 'disable' |
In volatile mode HALCON images are stored directly into the
two image acquisition interface buffers. 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 except the ones with prefix 'do_' can also be accessed by get_framegrabber_param.
| 'current_dig_in_status' | value | Returns the current status of the digital inputs as a long parameter. Every digital input set to high will be represented as a one in the binary representation of this value. Please refer to the manual of your board to find out if this feature is supported by the device you are working with. | |||
| 'current_snapqueue_level' | value | Returns the current input snap request queue level of the device. This parameter only returns expedient values, if the queueing mode for this device is available and enabled. In that case it will return the number of snap requests the device still has to process in its request queue. This might be helpful in order to check if the current system load is too high. When the system runs normally, the value returned by this function should match (or may be one less) the value returned by get_framegrabber_param( .. , 'snapqueue_level', .. ). If the value decreases (in worst case to 0), the computer can't handle the images delivered by the hardware anymore, because there are more images transferred by the device than the computer can cope with. | |||
| 'image_available' | 0, 1 | Returns 1 if a new image has been captured, but not read back into HALCON. Otherwise 0 is returned. | |||
| 'max_snapqueue_level' | value | Returns the maximum input snap request queue level, which can be set for this device. This parameter only returns expedient values, if the queueing mode for this device is available and enabled. In that case it will return the maximum number of snap requests the device can process in its request queue. This value currently is hardcoded into the HALCON interface DLL and therefore can't be modified in any way from outside. Its current value is 5. | |||
| 'revision' | revision | The revision number of the HALCON MatrixVision image acquisition interface. | |||
| 'snapqueue_level' | value | Returns the input snap request queue level as defined by the user (or the default value, which is equal to 'max_snapqueue_level') for this device. This parameter only returns expedient values if the queueing mode for this device is available and enabled. In that case it will return the number of image requests used in the devices request queue, when working in queued mode with asynchronous image capture. The queue can be useful to overcome high CPU peak loads without loosing images. This value can't be greater than 'max_snapqueue_level'. | |||
Release Notes
-
Revision 4.1 (Jul 30, 2010):
- Some internal re-structuring. No changes in the behaviour of the interface.
- HALCON 10 version of the interface (legacy only).
-
Revision 4.0 (Dec 1, 2008):
- HALCON 9.0 version of the interface (legacy only).
-
Revision 3.0 (Jun 28, 2007):
- HALCON 8.0 version of the interface (legacy only).
-
Revision 2.14 (Jan 12, 2007):
- New parameter 'image_available' to query the status of an image.
-
Revision 2.13 (Nov 11, 2006):
- Fixed bug in grab_image after changing the camera definition.
-
Revision 2.12 (Feb 21, 2006):
- Renamed parameter 'do_abort' to 'do_abort_grab' to follow the HALCON naming convention. The parameter 'do_abort' is still available for backward compatibility.
-
Revision 2.11 (Aug 12, 2005):
- New parameters 'current_snapqueue_level', 'max_snapqueue_level', and 'snapqueue_level'.
- Fixed bug in close_framegrabber.
-
Revision 2.10 (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.9 (Oct 28, 2004):
- New parameter 'sync_channel' to specify the sync channel in case of RGB grabbers.
- The actual stored configurations of the mvAcquireControl can now be queried by calling info_framegrabber('camera_type').
-
Revision 2.7 (Sep 24, 2004):
- New parameter 'current_dig_in_status' to query the current status of the digital input lines.
- The length of the dig I/O mask has been increased from 16 to 32 bits in order to reflect recent features of the mvCAM. IMPORTANT: You might need to modify your existing source code if you have worked with the parameter 'define_dig_io_mask'!
- New parameter 'queued_mode' to ensure lossless image acquisition. IMPORTANT: This revision requires more DMA memory then previous versions! Make sure that up to 6 images fit into the frame grabber DMA memory. The size of the DMA memory can be adjusted either by using the tool 'setdma.exe' which can be found under %SYSTEMROOT%\Matrix or by using the AllocFrameBuffer command in the grabber.ini file.
- Adaptation to version 3.144 of mvAcquireControl.
-
Revision 2.5 (Nov 24, 2003):
- HALCON 7.0 version of the interface (included in HALCON 7.0 CD).
- New parameters 'active_dig_io_mask' and 'define_dig_io_mask' for control of the digital input/output masks.
- New parameters 'brightness', 'contrast', 'expose_period_time', and 'expose_time'.
-
Revision 2.4 (Oct 2, 2003):
- New parameter 'shutter_time' to define the shutter time.
- Check if the installed version of the mvAcquireControl fulfills the requirements of this interface or if a newer version is needed.
-
Revision 2.3 (Jul 28, 2003):
- New parameter 'do_abort' to stop the current image acquisition when using Parallel HALCON.
- New parameters 'trigger_mode' and 'start_async_after_grab_async'.
- Bugfixes in using more than one handle to the same frame grabber in connection with channel switching.
- Adaptation to version 3.121 of mvAcquireControl.
-
Revision 2.2 (Feb 12, 2003):
- New parameter 'camera_definition' to switch between different camera definitions during runtime.
- New parameter 'external_trigger' to activate/deactivate the external trigger during runtime.
- Bugfix in close_framegrabber (freeing the previously created AcquireControl instance).
-
Revision 2.1 (Dec 19, 2000):
- HALCON 6.1 version of the interface (included in HALCON 6.1 CD).
- Check sdk library existence in info_framegrabber('info_boards').
-
Revision 2.0 (Aug 29, 2000):
- Adaptation to the HALCON 6.0 frame grabber integration interface.
-
Revision 1.0 (Mar 15, 2000):
- First official release.
