HALCON 8.0 Image Acquisition Interface for Lumenera USB 2.0 Cameras
This page provides the documentation of the HALCON LuCam image acquisition interface for the USB 2.0 cameras from Lumenera Corporation. Registered customers can download the latest revision of this interface from the MVTec WWW server.
Revision: 3.5
System Requirements
- Intel compatible PC with Windows 2000, Windows XP, Windows XP x64, Windows Vista, Windows Vista x64 and USB 2.0 interface.
- Installed LuCam Software v4.5 (or higher) from Lumenera.
-
HALCON image acquisition interface hAcqLuCam.dll or
parhAcqLuCam.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 cameras.
- Image cropping.
- External trigger.
- Software control of exposure.
- Software control of focus, gain, iris and white balancing.
- Software control of the strobe parameters.
- Software control of the digital input/output signals.
Limitations
- grab_image_start and grab_image_async not supported. Note that the grab_image operator behaves similar to grab_image_async if an external trigger is used and the parameter 'buffer_last_frame' is enabled.
- grab_data and grab_data_async not supported.
- RGB color images only with 8 Bit.
- No LUTs.
Description
Parameters for open_framegrabber():
| Name | 'LuCam' | The name of the HALCON image acquisition interface. | |||
| HorizontalResolution | 1, 2, 4 | The desired image resolution. Use '1' for full resolution, '2' for subsampling by factor 2, and '4' for subsampling by factor 4. Default: 1. | |||
| VerticalResolution | 1, 2, 4 | The desired image resolution. Use '1' for full resolution, '2' for subsampling by factor 2, and '4' for subsampling by factor 4. Default: 1. | |||
| ImageWidth | 0, width | The width of the desired image part ('0' stands for the complete image). The value of 'ImageWidth' will be set to the next smaller value divisible by 8. Default: 0. | |||
| ImageHeight | 0, height | The height of the desired image part ('0' stands for the complete image). The value of 'ImageHeight' will be set to the next smaller value divisible by 8. Default: 0. | |||
| StartRow | 0, row | The row coordinate of the upper left pixel within the desired image part. The value of 'StartRow' will be set to the next smaller value divisible by 8. Default: 0. | |||
| StartColumn | 0, column | The column coordinate of the upper left pixel within the desired image part. The value of 'StartColumn' will be set to the next smaller value divisible by 8. Default: 0. | |||
| Field | --- | Ignored. | |||
| BitsPerChannel | 8, bits_per_channel | The desired pixel depth of the image. The value must be supported by the camera, e.g., 12. Default: 8. | |||
| ColorSpace | 'default', 'gray', 'rgb', 'bayer' | Specify the desired color space and thus the number of image channels of the resulting HALCON image. If 'ColorSpace' is set to 'default', the color space is set to 'rgb' in case of color cameras, otherwise to 'gray'. The 'bayer' color space is only valid for Bayer color cameras, and causes the camera to produce the raw Bayer pattern image as output. Default: 'default'. | |||
| Generic | --- | Ignored. | |||
| ExternalTrigger | 'true', 'false' | Activate/deactivate external triggering. Default: 'false'. | |||
| CameraType | --- | Ignored. | |||
| Device | '1', DeviceId | The ID or logical number of the desired camera (passed as a string!). The logical number is assigned by the operating system ('1' for the first camera, '2' for second camera and so on). Default: '1'. | |||
| Port | --- | Ignored. | |||
| LineIn | --- | Ignored. | |||
Parameters for set_framegrabber_param():
| 'buffer_last_frame' | 'enable', 'disable' | If set to 'enable', the last acquired frame is stored for later retrieval. Only useful when used with a HW trigger. Default: 'disable'. | |||
| 'clock_speed' | 'fast', 'medium', 'slow', 'very_slow' | The clock speed of the camera. Default: 'fast'. | |||
| 'correction_matrix' | 'none', 'fluorescent', 'daylight', 'incandescent', 'xenon_flash', 'halogen', 'identity' | Color correction used, when converting the raw camera data to RGB24 (see documentation from Lumenera for details). | |||
| 'demosaicing_method' | 'none', 'fast', 'high_quality', 'higher_quality', 'simple' | Demosaicing method used, when converting raw bayer data from the camera to RGB24 (see documentation from Lumenera for details). Default: 'simple'. | |||
| 'do_calibrate_auto_lens' | --- | Perform auto calibration of the lens (not supported by all cameras). | |||
| 'do_abort_grab' | --- | Abort the current image acquisition. | |||
| 'do_flush_buffer' | --- | Flushes the image buffer of the camera. This is useful, when you acquire images via HW trigger with the 'buffer_last_frame' option set. Use of this parameter will force the camera to acquire a new image upon the subsequent grab. | |||
| 'do_reset_camera' | --- | Resets the camera to the power-on default state. | |||
| 'exposure' | 0.0, min ... max (float) | Specifies the desired exposure time of the camera in ms. The value range can be queried by get_framegrabber_param(...,'exposure_range',...). | |||
| 'exposure_delay' | 0.0 ... 32768 (float) | Time interval from when the trigger occurs to when the exposure starts. | |||
| 'external_trigger' | 'true', 'false' | Enables/disables the trigger mode. Default: 'false'. | |||
| 'focus' | min ... max (float) | Specifies the desired uncalibrated focus of the lens (not supported by all cameras). The value range can be queried by get_framegrabber_param(...,'focus_range',...). | |||
| 'focus_abs' | min ... max (float) | Specifies the desired calibrated focus of the lens (not supported by all cameras). Note that you cannot access this parameter without calling set_framegrabber_param(...,'do_calibrate_auto_lens',...) before. The value range can be queried by get_framegrabber_param(...,'focus_abs_range',...). | |||
| 'frame_rate' | fps (float) | Sets the desired frame rate. The available frame rates can be queried by get_framegrabber_param(..,'frame_rate_values', ...). | |||
| 'gain_b' | min ... max (float) | Gain for blue pixels as a multiplicative factor. The value range can be queried by get_framegrabber_param(...,'gain_b_range',...). | |||
| 'gain_g1' | min ... max (float) | Gain for green pixels on red rows as a multiplicative factor. The value range can be queried by get_framegrabber_param(...,'gain_g1_range',...). | |||
| 'gain_g2' | min ... max (float) | Gain for green pixels on blue rows as a multiplicative factor. The value range can be queried by get_framegrabber_param(...,'gain_g2_range',...). | |||
| 'gain_master' | min ... max (float) | Overall gain as a multiplicative factor. The value range can be queried by get_framegrabber_param(...,'gain_master_range',...). | |||
| 'gain_r' | min ... max (float) | Gain for red pixels as a multiplicative factor. The value range can be queried by get_framegrabber_param(...,'gain_r_range',...). | |||
| 'gamma' | min ... max (float) | Sets the gamma value of the camera. The value range can be queried by get_framegrabber_param(...,'gamma_range',...). | |||
| 'gpio_configure' | byte | Configures the digital input/output lines of the camera. | |||
| 'gpio_write' | byte | Writes the specified byte value to the digital output of the camera. | |||
| 'gpo_select' | byte | Selects the digital output lines of the camera. | |||
| 'grab_timeout' | 100 ... 32768 | Specifies the desired timeout in milliseconds for aborting a pending grab. Default: 5000. | |||
| 'image_height' | height (long) | Sets the height of the output image. | |||
| 'image_width' | width (long) | Sets the width of the output image. | |||
| 'iris' | min ... max (float) | Specifies the desired iris of the lens (not supported by all cameras). The value range can be queried by get_framegrabber_param(...,'iris_range',...). | |||
| 'start_column' | column (long) | Sets the column coordinate of the upper left corner of the output image. | |||
| 'start_row' | row (long) | Sets the row coordinate of the upper left corner of the output image. | |||
| 'strobe' | 'enable', 'disable' | Enables or disables the strobe mode. Default: 'disable'. | |||
| 'strobe_delay' | 0.0 ... 32768 (float) | Time interval from when exposure starts to the time the flash is fired in milliseconds. | |||
| 'strobe_duration' | min ... max (float) | Length of the strobe signal in milliseconds. | |||
| 'strobe_from_start_of_exposure' | 'enable', 'disable' | Identifies the strobe signal from the start of the exposure of the sensor. Please be aware that this parameter is not used in the Lumenera Capture application (see as an example the Lumenera Snapshot sample application). | |||
| 'white_balance_u' | min ... max (float) | Perform white balance. The value range can be queried by get_framegrabber_param(...,'white_balance_u_range',...). | |||
| 'white_balance_v' | min ... max (float) | Perform white balance. The value range can be queried by get_framegrabber_param(...,'white_balance_v_range',...). | |||
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'].
| 'color_format' | color format (string) | Color format of the camera, e.g., 'mono', or 'bayer_rggb'. | |||
| 'gpio_read' | byte (integer) | Reads the digital input of the camera. | |||
| 'revision' | revision | The revision number of the HALCON LuCam interface. | |||
| 'sensor_height' | height (integer) | Returns the vertical sensor size in pixel. | |||
| 'sensor_width' | width (integer) | Returns the horizontal sensor size in pixel. | |||
Release Notes
-
Revision 3.5 (Mar 12, 2009):
- New parameters 'do_abort_grab' and 'strobe_from_start_of_exposure'.
-
Revision 3.4 (Nov 25, 2008):
- Support of Windows XP x64 (using LuCam SDK version 5.0).
- Accelerate the execution time of the parameters 'gpio_write', 'gpio_configure', 'gpo_select'.
- Cleanup temporary memory in close_framegrabber.
-
Revision 3.3 (Aug 12, 2008):
- New read-only parameters 'sensor_width' and 'sensor_height' to query the actual size of the sensor.
- New parameters 'frame_rate' and 'frame_rate_values'.
- All range queries of get_framegrabber_param provided the range values incorrectly in the order [min, max, default, step] instead of [min, max, step, default]. This bug has been fixed.
-
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 31, 2008):
- Adaptation to SDK version 4.5.
- New parameters 'focus', 'focus_abs', 'iris', and 'do_calibrate_auto_lens' for focus and iris control.
- New parameter 'strobe_duration'.
- New parameters 'gpio_read', 'gpio_write', 'gpio_configure', and 'gpo_select' for software control of the digital input/output signals.
-
Revision 3.0 (May 15, 2007):
- HALCON 8.0 version of the interface (included in HALCON 8.0 DVD).
-
Revision 2.1 (Jan 12, 2007):
- Adaption to SDK version 4.0.
- Added parameters 'do_flush_buffer', 'gamma', and 'gamma_range'.
- Renamed parameter 'do_camera_reset' to 'do_reset_camera'. For backward compatibility the old name still works.
-
Revision 2.0 (Jun 27, 2006):
- First official release.
