资料
Image Acquisition Interface for Lumenera USB 2.0, USB 3.0 and GigE Vision Cameras
| Interface: | LuCam |
| Revision: | 13.0.1 |
| Date: | 2016-10-28 |
| HALCON Version: | 13.0 |
- General
- System Requirements
- Features
- Limitations
- 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 LuCam image acquisition interface for the USB 2.0, USB 3.0 and GigE Vision cameras
from Lumenera Corporation.
Registered customers can download the
latest revision of this interface from the
MVTec WWW server.
System Requirements
- Intel compatible PC with Windows 7 (32-bit or 64-bit) or newer that is also supported by the vendor-specific SDK, and USB 2.0 card, USB 3.0 card or a Gigabit Ethernet network adapter.
- Installed LuCam Software v6.1 (or higher) from Lumenera for USB 2.0 and GigE Vision cameras, or LuCam Software v6.3 (or higher) for USB 3.0 cameras.
- HALCON image acquisition interface hAcqLuCam.dll or
hAcqLuCamxl.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 return the last internal grabbed image. 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.
- Only 8 bit RGB color images.
- The maximum camera frame rate may not be achieved, due to the fact that the grabbing method is not based on the LuCam streaming callback.
Parameters for info_framegrabber
| Parameter | Value List | Type | Kind | Description |
|---|---|---|---|---|
| 'bits_per_channel' | 8, 10, 12 | integer | pre-defined | Values for bits per channel. |
| 'camera_type' | [] | Unused. | ||
| 'color_space' | ['default', 'gray', 'rgb', 'bayer'] | string | pre-defined | Values for color space. |
| 'defaults' | [1, 1, 0, 0, 0, 0, 'interlaced', 8, 'default', -1.0, 'false', 'default', '1', 0, 0] | mixed | pre-defined | Default values for open_framegrabber. |
| 'device' | ['device:usb:<id>', 'device:gige:<id>'] | string | dynamic | List of available device IDs. |
| 'external_trigger' | ['false', 'true'] | string | pre-defined | Values for the external trigger. |
| 'field' | [] | Unused. | ||
| 'general' | [] | string | pre-defined | Information about the HALCON LuCam interface. |
| 'generic' | ['', 'post_dual_tap_correction=0'] | string | pre-defined | Value list for the Generic parameter. |
| 'horizontal_resolution' | [1, 2, 4] | integer | pre-defined | Value list for horizontal resolution. |
| 'image_height' | [] | Unsupported query. | ||
| 'image_width' | [] | Unsupported query. | ||
| 'info_boards' | ['device:usb:<num> | serial:<num>', 'device:gige:<num>'] | string | dynamic | 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' | [] | Unused. | ||
| 'revision' | '<revision>' | string | pre-defined | Revision number of the LuCam interface. |
| 'start_column' | [] | Unsupported query. | ||
| 'start_row' | [] | Unsupported query. | ||
| 'vertical_resolution' | [1, 2, 4] | integer | pre-defined | Value list for vertical resolution. |
Parameters for open_framegrabber
| Parameter | Values | Default | Type | Description |
|---|---|---|---|---|
| Name | 'LuCam' | string | Name of the HALCON interface. | |
| HorizontalResolution | 1, 2, 4 | 1 | integer | Desired horizontal resolution of the camera image:
|
| VerticalResolution | 1, 2, 4 | 1 | integer | Desired vertical resolution of the camera image:
|
| ImageWidth | 0, <width> | 0 | integer | Width of the desired image part ('0' stands for the complete image). If the value isn't valid, it will be set to the next smaller value divisible by 8. |
| ImageHeight | 0, <height> | 0 | integer | Height of the desired image part ('0' stands for the complete image). If the value isn't valid, it will be set to the next smaller value divisible by 8. |
| StartRow | 0, <row> | 0 | integer | Row coordinate of the upper left pixel within the desired image part. If the value isn't valid, it will be set to the next smaller value divisible by 8. |
| StartColumn | 0, <column> | 0 | integer | Column coordinate of the upper left pixel within the desired image part. If the value isn't valid, it will be set to the next smaller value divisible by 8. |
| Field | --- | Ignored. | ||
| BitsPerChannel | 8, <bits_per_channel> | 8 | integer | Desired pixel depth of the image. The value must be supported by the camera, e.g., 12. |
| ColorSpace | 'default', 'gray', 'rgb', 'bayer' | 'default' | string | 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. |
| Generic | '', 'post_dual_tap_correction=0', -1 | -1 | mixed | If the camera is based on a dual tap sensor, the post dual tap correction will be automatically used. To disable it, set 'post_dual_tap_correction=0'. |
| ExternalTrigger | 'false', 'true' | 'false' | string | Status of the external trigger. |
| CameraType | --- | Ignored. | ||
| Device | 'usb:<id>', 'gige:<id>', '<device_id>' | '1' | string | The device string must contain the prefix 'usb:' in case of the Lumenera USB camera models, and 'gige:' in case of the Lumenera GigE Vision camera models. After the prefix, the ID or logical number of the desired camera must be set (the complete information is 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). For example, the first GigE Vision camera can be set via 'gige:1'. If no prefix is given, the USB interface is used. |
| Port | --- | Ignored. | ||
| LineIn | --- | Ignored. |
Parameters for set_framegrabber_param
| Parameter | Values | Default | Type | Description |
|---|---|---|---|---|
| 'acquisition_mode' | 'fast_frame', 'snapshot' | 'fast_frame' | string | Internal used acquisition mode. In special cases the 'snapshot' mode is needed, e.g., to set very long exposure times. |
| 'buffer_last_frame' | 'disable', 'enable' | 'disable' | string | If set to 'enable', the last acquired frame is stored for later retrieval. Only useful when used with a HW trigger. |
| 'clock_speed' | 'fast', 'medium', 'slow', 'very_slow' | 'fast' | string | Clock speed of the camera. |
| 'correction_matrix' | 'none', 'fluorescent', 'daylight', 'incandescent', 'xenon_flash', 'halogen', 'identity' | string | Color correction is used, when converting the raw camera data to RGB24 (see documentation from Lumenera for details). | |
| 'demosaicing_method' | 'none', 'fast', 'high_quality', 'higher_quality', 'simple' | 'simple' | string | Demosaicing method is used, when converting raw Bayer data from the camera to RGB24 (see documentation from Lumenera for details). |
| 'do_abort_grab' | --- | Cancel current grab. | ||
| 'do_calibrate_auto_lens' | --- | Perform auto calibration of the lens (not supported by all cameras). | ||
| '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' | <exposure> | float | Desired exposure time of the camera in milliseconds. | |
| 'exposure_delay' | 0.0 ... 32768 | float | Time interval from when the trigger occurs to when the exposure starts. | |
| 'external_trigger' | 'false', 'true' | string | Status of the external trigger. | |
| 'focus' | <focus> | float | Uncalibrated focus of the lens (not supported by all cameras). | |
| 'focus_abs' | <focus_abs> | float | 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. | |
| 'frame_rate' | <fps> | float | Frame rate in frames per second. | |
| 'gain_b' | <gain_b> | float | Gain for blue pixels as a multiplicative factor. | |
| 'gain_g1' | <gain_g1> | float | Gain for green pixels on red rows as a multiplicative factor. | |
| 'gain_g2' | <gain_g2> | float | Gain for green pixels on blue rows as a multiplicative factor. | |
| 'gain_master' | <gain_master> | float | Overall gain as a multiplicative factor. | |
| 'gain_r' | <gain_r> | float | Gain for red pixels as a multiplicative factor. | |
| 'gamma' | <gamma> | float | Gamma value of the camera. | |
| 'gpio_configure' | <byte> | integer | Configures the digital input/output lines of the camera. | |
| 'gpio_write' | <byte> | integer | Writes the specified byte value to the digital output of the camera. | |
| 'gpo_select' | <byte> | integer | Selects the digital output lines of the camera. | |
| 'grab_timeout' | 100 ... 32768 | 5000 | integer | Desired timeout (milliseconds) for aborting a pending grab. If -1 is specified, the timeout is set to INFINITE. |
| 'image_height' | <height> | integer | Height of the desired image part ('0' stands for the complete image). | |
| 'image_width' | <width> | integer | Width of the desired image part ('0' stands for the complete image). | |
| 'iris' | <iris> | float | Desired iris of the lens (not supported by all cameras). | |
| 'start_column' | <column> | integer | Column coordinate of the upper left pixel within the desired image part. | |
| 'start_row' | <row> | integer | Row coordinate of the upper left pixel within the desired image part. | |
| 'strobe' | 'disable', 'enable' | 'disable' | string | Strobe mode. |
| 'strobe_delay' | 0.0 ... 32768 | float | Time interval (in milliseconds) from when exposure starts to the time the flash is fired. | |
| 'strobe_duration' | <milliseconds> | float | Length of the strobe signal in milliseconds. | |
| 'strobe_from_start_of_exposure' | 'disable', 'enable' | 'disable' | string | 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' | <white_balance_u> | float | White balance u. | |
| 'white_balance_v' | <white_balance_v> | float | White balance v. |
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].
- '_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 |
|---|---|---|---|---|---|
| 'acquisition_mode' | 'fast_frame', 'snapshot' | 'fast_frame' | string | pre-defined | Internal used acquisition mode. In special cases the 'snapshot' mode is needed, e.g., to set very long exposure times. |
| 'bits_per_channel' | <bits_per_channel> | 8 | 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. |
| 'buffer_last_frame' | 'disable', 'enable' | 'disable' | string | pre-defined | If set to 'enable', the last acquired frame is stored for later retrieval. Only useful when used with a HW trigger. |
| 'camera_type' | '<default>' | 'default' | string | pre-defined | The value is not used, so a default value is returned. |
| 'clock_speed' | 'fast', 'medium', 'slow', 'very_slow' | 'fast' | string | pre-defined | Clock speed of the camera. |
| 'color_format' | '<color_format>' | string | dynamic | Color format of the camera, e.g., 'mono', or 'bayer_rggb'. | |
| 'color_space' | 'gray', 'rgb', 'bayer' | 'default' | string | pre-defined | Desired color space and thus the number of image channels of the resulting HALCON image. |
| 'correction_matrix' | 'none', 'fluorescent', 'daylight', 'incandescent', 'xenon_flash', 'halogen', 'identity' | string | dynamic | Color correction is used, when converting the raw camera data to RGB24 (see documentation from Lumenera for details). | |
| 'demosaicing_method' | 'none', 'fast', 'high_quality', 'higher_quality', 'simple' | 'simple' | string | pre-defined | Demosaicing method is used, when converting raw Bayer data from the camera to RGB24 (see documentation from Lumenera for details). |
| 'device' | '<device_id>' | '1' | string | pre-defined | Current device ID. |
| 'exposure' | <milliseconds> | float | dynamic | Desired exposure time of the camera in milliseconds. | |
| 'exposure_delay' | <milliseconds> | float | dynamic | Time interval from when the trigger occurs to when the exposure starts. | |
| 'external_trigger' | 'false', 'true' | 'false' | string | pre-defined | Status of the external trigger. |
| 'field' | '<default>' | 'interlaced' | string | pre-defined | The value is not used, so a default value is returned. |
| 'focus' | <focus> | float | dynamic | Uncalibrated focus of the lens (not supported by all cameras). | |
| 'focus_abs' | <focus_abs> | float | dynamic | Calibrated focus of the lens. | |
| 'frame_rate' | <fps> | float | dynamic | Frame rate in frames per second. | |
| 'gain_b' | <gain_b> | float | dynamic | Gain for blue pixels as a multiplicative factor. | |
| 'gain_g1' | <gain_g1> | float | dynamic | Gain for green pixels on red rows as a multiplicative factor. | |
| 'gain_g2' | <gain_g2> | float | dynamic | Gain for green pixels on blue rows as a multiplicative factor. | |
| 'gain_master' | <gain_master> | float | dynamic | Overall gain as a multiplicative factor. | |
| 'gain_r' | <gain_r> | float | dynamic | Gain for red pixels as a multiplicative factor. | |
| 'gamma' | <gamma> | float | dynamic | Gamma value of the camera. | |
| 'generic' | '', 'post_dual_tap_correction=0', -1 | -1 | mixed | pre-defined | Values of the Generic parameter. |
| 'gpio_configure' | <byte> | integer | dynamic | Configures the digital input/output lines of the camera. | |
| 'gpio_read' | <byte> | integer | dynamic | Digital input of the camera. | |
| 'gpio_write' | <byte> | integer | dynamic | Writes the specified byte value to the digital output of the camera. | |
| 'gpo_select' | <byte> | integer | dynamic | Selects the digital output lines of the camera. | |
| 'grab_timeout' | <milliseconds> | 5000 | integer | pre-defined | Current grab timeout in milliseconds. |
| 'horizontal_resolution' | <resolution> | 1 | integer | pre-defined | Current value of horizontal resolution. |
| 'host_ip_address' | '<ip_address>' | string | dynamic | IP address of the network interface card. The parameter is only accessible if the Lumenera GigE Vision cameras are used. | |
| 'host_subnet_mask' | '<subnet_mask>' | string | dynamic | Subnet mask of the network interface card. The parameter is only accessible if the Lumenera GigE Vision cameras are used. | |
| '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). |
| 'ip_address' | '<ip_address>' | string | dynamic | IP address of the camera. The parameter is only accessible if the Lumenera GigE Vision cameras are used. | |
| 'iris' | <iris> | float | dynamic | Desired iris of the lens (not supported by all cameras). | |
| 'line_in' | <default> | 0 | integer | pre-defined | The value is not used, so a default value is returned. |
| 'name' | 'LuCam' | string | pre-defined | Name of the HALCON interface. | |
| 'port' | <default> | 0 | integer | pre-defined | The value is not used, so a default value is returned. |
| 'revision' | '<revision>' | string | pre-defined | Revision number of the LuCam interface. | |
| 'sensor_height' | <height> | integer | dynamic | Vertical sensor size in pixel. | |
| 'sensor_width' | <width> | integer | dynamic | Horizontal sensor size in pixel. | |
| '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. |
| 'strobe' | 'disable', 'enable' | 'disable' | string | pre-defined | Strobe mode. |
| 'strobe_delay' | <milliseconds> | float | dynamic | Time interval (in milliseconds) from when exposure starts to the time the flash is fired. | |
| 'strobe_duration' | <milliseconds> | float | dynamic | Length of the strobe signal in milliseconds. | |
| 'strobe_from_start_of_exposure' | 'disable', 'enable' | 'disable' | string | pre-defined | 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). |
| 'subnet_mask' | '<subnet_mask>' | string | dynamic | Subnet mask of the camera. The parameter is only accessible if the Lumenera GigE Vision cameras are used. | |
| 'vertical_resolution' | <resolution> | 1 | integer | pre-defined | Current value of vertical resolution. |
| 'white_balance_u' | <white_balance_u> | float | dynamic | White balance u. | |
| 'white_balance_v' | <white_balance_v> | float | dynamic | White balance v. |
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. Notice that grab_image_async returns the last internal grabbed image.
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 the last internal grabbed 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'.
The 'MaxDelay' argument parameter is ignored, i.e., the image age
check is deactivated.
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:
- lucam_2cameras.hdev - Shows concurrent grabbing from two connected cameras.
- lucam_crop.hdev - Grabbing images with software image cropping.
- lucam_parameters.hdev - Lists all parameters of a device.
- lucam_simple.hdev - A simple example to show the usage of the interface.
Release Notes
- Revision 13.0.1 (Oct 28, 2016):
- HALCON 13 version of the interface.
- Revision 6.0 (Oct 31, 2014):
- HALCON 12 version of the interface.
- Revision 5.1 (Aug 28, 2013):
- Added support for Lumenera USB 3.0 cameras.
- Fixed bug in open_framegrabber in case of 'Generic' parameter with empty string values.
- Reviewed and adapted documentation.
- 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.2 (Sep 19, 2011):
- Adapted to SDK version 6.1.
- Added support of LuCam GigE Vision cameras.
- Added generic parameter 'post_dual_tap_correction'.
- Added parameters 'acquisition_mode', 'ip_address', 'subnet_mask', 'host_ip_address' and 'host_subnet_mask'.
- Implemented query info_framegrabber(..., 'device', ...). The query returns now a dynamic list of all detected USB and GigE Vision devices.
- Adapted query info_framegrabber(..., 'info_boards', ...). The actually available GigE Vision and USB cameras are now identified via the prefix 'usb' or 'gige'.
- Revision 4.1 (Mar 12, 2009):
- Added parameters 'do_abort_grab' and 'strobe_from_start_of_exposure'.
- 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.4 (Nov 27, 2008):
- Added support of Windows XP x64 (using LuCam SDK version 5.0).
- Accelerated the execution time of the parameters 'gpio_write', 'gpio_configure', 'gpo_select'.
- Fixed remaining temporary memory in close_framegrabber.
- Revision 3.3 (Aug 12, 2008):
- Added read-only parameters 'sensor_width' and 'sensor_height' to query the actual size of the sensor.
- Added parameters 'frame_rate' and 'frame_rate_values'.
- Fixed problem, that all range queries of get_framegrabber_param returned the range values incorrectly in the order [min, max, default, step] instead of [min, max, step, default].
- 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):
- Adapted to SDK version 4.5.
- Added parameters 'focus', 'focus_abs', 'iris', and 'do_calibrate_auto_lens' for focus and iris control.
- Added parameter 'strobe_duration'.
- Added 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):
- Adapted 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.