HALCON 8.0 Image Acquisition Interface for Silicon Software microEnable III Boards
This page provides the documentation of the HALCON mEnableIII interface for the microEnable III frame grabber boards from Silicon Software GmbH. Registered customers can download the latest revision of this interface from the MVTec WWW server.
Revision: 3.6
System Requirements
- Intel compatible PC with Windows 2000/XP.
- Successfully installed Silicon Software driver (version 3.1 or 3.2). Make sure that the environment variable %SISODIR% is set correctly to the directory that contains the Dlls for the desired hardware applet, e.g., C:\Program Files\Silicon Software\dll\me_grab3.
- HALCON image acquisition interface hAcqmEnableIII.dll or parhAcqmEnableIII.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 a variety of Camera Link cameras based on the Silicon Software hardware applets.
- Multiple frame grabber boards.
- Synchronous and asynchronous grabbing.
- External and software trigger.
- Cropping of image parts.
- Software control of the digital input and output lines.
- Support of shaft encoders (microEnable III-XXL only).
Limitations
- Currently only the 'Single' hardware applets are supported.
- No LUTs.
Description
Parameters for open_framegrabber():
| Name | 'mEnableIII' | 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, width | The width of the desired image part ('0' stands for the maximum image height). This value has to be equal or smaller than the maximum image height. If the value does not fit in the step width, it is rounded to next valid value. Default: 0. | |
| ImageHeight | 0, height | The height of the desired image part ('0' stands for the maximum image height). This value has to be equal or smaller than the maximum image height. If the value does not fit in the step width, it is rounded to next valid value. Default: 0. | |
| StartRow | row | The row coordinate of the upper left pixel of the desired image part. If the value does not fit in the step width, it is rounded to next valid value. Default: 0. | |
| StartColumn | column | The column coordinate of the upper left pixel of the desired image part. If the value does not fit in the step width, it is rounded to next valid value. Default: 0. | |
| Field | --- | Ignored. | |
| BitsPerChannel | --- | Ignored (the desired pixel depth will be set accordingly to the parameter settings in the camera configuration file). | |
| ColorSpace | --- | Ignored (the desired color space will be set accordingly to the parameter settings in the camera configuration file). | |
| Generic | 'num_buffers=number',-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 integer between 1 and 1000. 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. Default: 2. | |
| ExternalTrigger | 'true', 'false' | If set to 'true', the trigger mode will be set to 'async_trigger', otherwise 'free_run' mode will be active. Default: 'false'. | |
| CameraType | 'mcf file' | Specify the name (including the full path name) of the desired camera configuration file (mcf file). To configure a specific camera setup please use the microDisplay program which is part of microEnable III software. | |
| Device | '0', '1', ... | The number of the frame grabber board (passed as a string!). Default: '0'. | |
| Port | 0, 1 | Specify the port the camera is connected to. Default: 0. | |
| LineIn | --- | Ignored. | |
Parameters for set_framegrabber_param():
| 'cc0_select' | 'exsync', '!exsync', 'exsync2', '!exsync2', 'flash', '!flash', 'clk', 'gnd', 'vcc' | Assign a particular signal to Camera Link's CC0 line. | |||
| 'cc1_select' | 'exsync', '!exsync', 'exsync2', '!exsync2', 'flash', '!flash', 'clk', 'gnd', 'vcc' | Assign a particular signal to Camera Link's CC1 line. | |||
| 'cc2_select' | 'exsync', '!exsync', 'exsync2', '!exsync2', 'flash', '!flash', 'clk', 'gnd', 'vcc' | Assign a particular signal to Camera Link's CC2 line. | |||
| 'cc3_select' | 'exsync', '!exsync', 'exsync2', '!exsync2', 'flash', '!flash', 'clk', 'gnd', 'vcc' | Assign a particular signal to Camera Link's CC3 line. | |||
| 'continuous_grabbing' | 'enable', 'disable' | Activate or deactivate the continuous grabbing mode. If the continuous mode is enabled, the frame grabber board will grab all the time. Note that in this mode you can acquire images from line scan cameras without loosing any image data. This mode is not allowed in combination with external triggering. Default: 'disable'. | |||
| 'current_buffer_index' | 0 ... num_buffers-1 | Index of the current image buffer. | |||
| 'digital_output' | 0, 1, 2, 3 | Specify the combination of the two digital output signals. | |||
| 'direct_buffer_access_mode' | 'enable', 'disable' |
The direct buffer access mode allows the user to obtain only the
pointer to the image buffer instead of the actual image data.
If set to 'enable', the output control parameter Data of the
operators grab_data[_async] will provide the buffer
pointer and the output image parameter Image will be empty.
If set to 'disable', the output parameter Image of the
operators grab_data[_async] will return
the grabbed image data like in grab_image[_async] and
the output control parameter Data will be empty. Warning:Accessing the image data directly via the buffer pointer can easily lead to memory access violations, thus, the user has to take care about the image dimensions and the validity of the buffer! |
|||
| 'exposure' | 0 ... 1000000 | Exposure time in µs. Default: 4000. | |||
| 'exposure_signal' | 'high_active', 'low_active' | Polarity of the exposure signal. Default: 'low_active'. | |||
| 'flash_signal' | 'high_active', 'low_active' | Polarity of the flash signal. Default: 'low_active'. | |||
| 'frame_rate' | 0.5 ... 20000.0 | Number of images per second. | |||
| 'grab_timeout' | msec | Specify the desired timeout (milliseconds passed as an integer) for aborting a pending grab. Default: 5000. | |||
| 'image_height' | height | The height of the desired image part. Note that due to image buffer re-allocation this setting may take some time. | |||
| 'image_trigger' | 'enable', 'disable' | Enable or disable the image trigger. | |||
| 'image_trigger_input' | 0, 1, 2, 3 | The input source, if the image trigger is in external mode. | |||
| 'image_trigger_mode' | 'free_run', 'async_trigger', 'async_gated' |
The image trigger for line scan cameras generates an socalled
Image Gate, which groups all lines to a valid frame, if it is
active. Specify the desired image trigger mode: 'free run'
means, that the Image Gate is valid all the time. In 'async_trigger'
mode the Image Gate is started by an external trigger signal.
'async_gated' means that the Image Gate is as long active as the
external trigger source is active. In all modes the Image Gate becomes inactive after reaching an image height of N lines. |
|||
| 'image_trigger_signal' | 'falling', 'rising' | The input signal of the image trigger, in case external mode. | |||
| 'image_width' | width | The width of the desired image part. Note that due to image buffer re-allocation this setting may take some time. | |||
| 'line_downscale' | 1 ... 255 | If your external trigger signal is too fast, you can set the value of how often the frequency of the trigger signal has to be divided. | |||
| 'line_downscale_phase' | 1 ... 255 | In additional to the downscale value you can set the phase position. For example, a value of 4 means to turn the phase position about 90°. | |||
| 'line_exposure' | 0 ... 20000 | The line exposure. | |||
| 'line_period' | 0 ... 4369.05 | The line period. | |||
| 'line_trigger_delay' | 0 ... 2184.517 | The delay of the line trigger. | |||
| 'line_trigger_input' | 0, 1, 2, 3 | The input source of the line trigger. | |||
| 'line_trigger_mode' | 'grabber_controlled', 'async_trigger', 'grabber_controlled_gated' | Specify the line trigger mode: 'grabber_controlled' means that a periodical signal is created, which defines the line frequency. In 'async_trigger' mode the signal is created by an external trigger. 'grabber_controlled_gated' is similar to the 'grabber_controlled' mode, except that it is only active, if the Image Gate is active. | |||
| 'line_trigger_signal' | 'falling', 'rising' | The polarity of the line trigger signal. | |||
| 'port' | 0, 1 | Switch to the camera with the specified number (0 for Port A, 1 for Port B). | |||
| 'shaft_encoder' | 'enable', 'disable' | Switch the shaft encoder on/off. By enabling it the encoder compensation is reset. This parameter is only available for microEnable III-XXL boards. | |||
| 'shaft_encoder_input' | 0, 1, 2, 3 | Selects the input signal for source B of the shaft encoder. This parameter is only available for microEnable III-XXL boards. | |||
| 'shaft_encoder_leading_source' | 0, 1, 2, 3 | Determines the leading signal (direction) of the shaft encoder filter. This parameter is only available for microEnable III-XXL boards. | |||
| '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'. | |||
| 'start_column' | column | The column coordinate of the upper left pixel of the desired image part. | |||
| 'start_row' | row | The row coordinate of the upper left pixel of the desired image part. | |||
| 'strobe_delay' | usec | Strobe pulse delay in µs. Default: 0. | |||
| 'trigger_input' | 0, 1, 2, 3 | Specify the desired channel of the trigger input signal. | |||
| 'trigger_mode' | 'free_run', 'grabber_controlled', 'async_trigger', 'async_software_trigger' | Specify the desired trigger mode: 'free_run' means that no signals are sent to the camera. In 'grabber_controlled' mode the frame grabber sends a signal to the camera in order to control the image acquisition. In 'async_trigger' mode the image acquisition is forced by an external trigger signal, and 'async_software_trigger' means that the image acquisition is performed by software via the action parameter 'do_force_trigger'. | |||
| 'trigger_signal' | 'falling', 'rising' | Polarity of the trigger signal. Default: 'falling'. | |||
| 'volatile' | 'enable', 'disable' | Grayscale only. In the volatile mode the 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'. | |||
| 'do_abort_grab' | --- | Cancel current grab. | |||
| 'do_exsync' | 'enable', 'disable' | Switch on/off the exsync signal to the camera. | |||
| 'do_flash' | 'enable', 'disable' | Switch on/off the flash signal to the camera. | |||
| 'do_force_trigger' | --- | Send a software trigger from the application to the camera. This action parameter is only applicable when the trigger mode is set to 'async_software_trigger'. | |||
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' | 'mEnableIII', 'mEnableIII_XXL' | Returns the actual board type. | |||
| 'camera_status' | status (long) | Return camera status on the used port: If the return value is 1 an active camera on the specified port is found, otherwise the return value is 0. | |||
| 'digital_input' | digin (long) | Read the current status of the digital input lines. | |||
| 'internal_device_pointer' | pointer(long) | Returns the internal device pointer to enable direct device access. Use on your own risk! | |||
| 'revision' | revision (string) | The revision number of the HALCON mEnableIII interface. | |||
| 'serial_number' | serial (string) | Returns the serial number of the board. | |||
| 'timestamp' | time (long) | Returns the 32bit timestamp from the image in micro seconds. If the continuous grabbing mode is enabled, this parameter always returns the most recent timestamp. | |||
Release Notes
-
Revision 3.6 (Jun 28, 2010):
- Added parameter 'direct_buffer_access_mode' to access only the pointer to the image buffer instead of the actual image data.
- Added implementation of the grab_data[_async] operators.
-
Revision 3.5 (Mar 16, 2010):
- Added read-only parameters 'internal_device_pointer' and 'timestamp'.
- Added implementation of info_framegrabber(..,'generic',...) to query all supported values for the Generic parameter in open_framegrabber.
-
Revision 3.4 (Jul 31, 2009):
- Fixed bug in open_framegrabber, grab_image, grab_image_async, and grab_image_start regarding the use of multiple cameras connected to the same physical board.
-
Revision 3.3 (Mar 13, 2009):
- Fixed bug in close_framegrabber if 'continuous_grabbing' was enabled.
- Added Generic parameter 'num_buffers' in open_framegrabber to enable specifying the number of used image buffers.
- Added parameter 'current_buffer_index'.
- Added parameters 'cc0_select', 'cc1_select', 'cc2_select', and 'cc3_select' to assign particular signals to Camera Link's CC0-3 lines.
- Added read-only parameter 'serial_number'.
-
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 (Jan 29, 2008):
- Fixed bug in info_framegrabber('info_boards') to ensure the correct information about actually installed devices also in case of multiple boards of the same type.
-
Revision 3.0 (May 15, 2007):
- HALCON 8.0 version of the interface (included in HALCON 8.0 DVD).
- Renaming the interface name from 'mEnable3' into 'mEnableIII'.
-
Revision 2.2 (Oct 18, 2006):
- Added parameter 'board_type'.
- Fixed bug in info_framegrabber.
-
Revision 2.1 (Jul 28, 2006):
- Adapted to SDK version 3.1.
- Added parameters for line scan cameras and shaft encoders: 'image_trigger', 'image_trigger_input', 'image_trigger_mode', 'image_trigger_signal', 'line_downscale', 'line_downscale_phase', 'line_exposure', 'line_period', 'line_trigger_delay', 'line_trigger_input', 'line_trigger_mode', 'line_trigger_signal', 'shaftencoder', 'shaftencoder_input', 'shaftencoder_leading_source'.
- Fixed bug in 'do_abort_grab' and in 'do_flash'.
- Added 'info_boards' in info_framegrabber.
-
Revision 2.0 (May 31, 2005):
- HALCON 7.1 version of the interface (included in HALCON 7.1 CD).
- First official release.
