Interface Documentation
Image Acquisition Interface for Daheng Cameras
| Interface: | DahengCAM |
| Revision: | 13.0.1 |
| Date: | 2016-10-28 |
| HALCON Version: | 13.0 |
- General
- System Requirements
- Features
- Using Multiple Cameras
- Using Asynchronous Grabbing
- 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 DahengCAM interface for USB 2.0 and 1394IIDC cameras from Daheng Group.
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.
- DahengCAM driver <camera name>.sys, e.g.,
HV3103UC.sys from driver CD or website download.
Typically, this file resides in the directory %WINDIR\system32\drivers. If you do not have this driver, please contact Daheng Group or the vendor from which you bought the camera. - Needed DLL files: Raw2Rgb.dll, HVDailt.dll, HVUtil.dll
from driver CD or website download.
These files must be within your search path %PATH% (typically, it resides in the directory %WINDIR%\system32). If you do not have these DLLs, please contact Daheng Group or the vendor from which you bought the camera. - HALCON image acquisition interface hAcqDahengCAM.dll or
hAcqDahengCAMxl.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.
- Synchronous and asynchronous grabbing.
- External trigger.
- Software control of gain, shutter, and white balancing.
Using Multiple Cameras
When using multiple Daheng USB 2.0 cameras each camera has an unique ID number starting with '1'.
Using Asynchronous Grabbing
Daheng USB 2.0 cameras differ only between continuous grabbing and triggered grabbing. Thus, when calling grab_image_async in continuous mode
you will always get the newest available image.
Parameters for info_framegrabber
| Parameter | Value List | Type | Kind | Description |
|---|---|---|---|---|
| 'bits_per_channel' | 8 | integer | pre-defined | Values for bits per channel. |
| 'camera_type' | ['HV-13xx', 'HV-20xx', 'HV-30xx', 'HV-31xx', 'HV-50xx', 'HV-xx51', 'SV-xxxx'] | string | pre-defined | Pre-defined list of possible values for camera type. |
| 'color_space' | ['gray', 'rgb'] | string | pre-defined | Values for color space. |
| 'defaults' | [1, 1, 0, 0, 0, 0, 'interlaced', 8, 'gray', -8.0, 'false', 'HV-13xx', '1', 1, 0] | mixed | pre-defined | Default values for open_framegrabber. |
| 'device' | ['1', '2', '3'] | string | pre-defined | Pre-defined list of possible values for device. |
| 'external_trigger' | ['false', 'true'] | string | pre-defined | Values for the external trigger. |
| 'field' | [] | Unused. | ||
| 'general' | [] | string | pre-defined | Information about the HALCON DahengCAM 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' | ['device:<device_id>'] | 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 DahengCAM 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 | 'DahengCAM' | string | Name of the HALCON interface. | |
| HorizontalResolution | --- | Ignored. | ||
| VerticalResolution | --- | Ignored. | ||
| ImageWidth | <width> | 0 | integer | Width of the desired image part ('0' stands for the complete image). |
| ImageHeight | <height> | 0 | integer | Height of the desired image part ('0' stands for the complete image). |
| StartRow | <width> | 0 | integer | Row coordinate of the upper left pixel within the desired image part. |
| StartColumn | <column> | 0 | integer | Column coordinate of the upper left pixel within the desired image part. |
| Field | --- | Ignored. | ||
| BitsPerChannel | --- | Ignored. | ||
| ColorSpace | 'default', 'gray', 'rgb' | 'gray' | string | Desired color space and thus the number of image channels of the resulting HALCON image. |
| Generic | --- | Ignored. | ||
| ExternalTrigger | 'false', 'true' | 'false' | string | Status of the external trigger. |
| CameraType | 'HV-13xx', 'HV-20xx', 'HV-30xx', 'HV-31xx', 'HV-50xx', 'HV-xx51', 'SV-xxxx' | 'HV-xx51' | string | Type of the connected camera series. |
| Device | '1', '2', '3', ... | '1' | string | ID of the camera. If you have two cameras connected the first one has device ID '1', the second has device ID '2'. |
| Port | --- | Ignored. | ||
| LineIn | --- | Ignored. |
Parameters for set_framegrabber_param
| Parameter | Values | Default | Type | Description |
|---|---|---|---|---|
| 'adc_level' | 'adc0', 'adc1', 'adc2', 'adc3' | 'adc2' | string | Level of the A/D translation:
|
| 'bayer_convert_type' | 'high', 'low', 'normal' | 'low' | string | One of the possible conversion types. |
| 'bayer_layout' | 'bayer_bg', 'bayer_gb', 'bayer_gr', 'bayer_rg' | 'bayer_rg' (if SV-13xx camera is used) otherwise 'bayer_gr' | string | Associated bayer mode for the camera. |
| 'color_space' | 'gray', 'rgb', 'yuv' | string | Desired color space and thus the number of image channels of the resulting HALCON image. | |
| 'dh_lut_table' | <file name> | string | Sets the LUT table via reading the information from the specified file (supported by SV-xxxx cameras only). | |
| 'gain' | 0.0 ... 127.0 | 8.0 | float | Gain value of the camera. |
| 'grab_timeout' | 100 ... 327680 | 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). | |
| 'output_io_0' | 'integration_signal', 'strobe', 'trigger_ready', 'user_set' | 'strobe' | string | I/O to output 0 of the camera (supported by SV-xxxx cameras only). |
| 'output_io_1' | 'integration_signal', 'strobe', 'trigger_ready', 'user_set' | 'trigger_ready' | string | I/O to output 1 of the camera (supported by SV-xxxx cameras only). |
| 'output_io_2' | 'integration_signal', 'strobe', 'trigger_ready', 'user_set' | 'integration_signal' | string | I/O to output 2 of the camera (supported by SV-xxxx cameras only). |
| 'resolution' | 'mode0', 'mode1', 'mode2', 'mode3', 'mode4', 'mode5', 'mode6' | 'mode0' | string | Resolution of the image depending of the camera model. Mode0 always is the maximum resolution of the camera. |
| 'shutter' | 0 ... 16383 | integer | Shutter (exposure time) of the camera. | |
| 'shutter_unit' | 'us', 'ms', 's' | 'ms' | string | Unit of the shutter. |
| 'snap_mode' | 'continuous', 'trigger', 'trigger_edge', 'trigger_level' | 'continuous' | string | Snap mode of the camera. If set to 'trigger' an external trigger signal is needed to grab an image. In continuous mode the camera grabs images continuously. |
| 'snap_speed' | 'high', 'normal' | 'high' | string | Snap speed modus. |
| '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' | 'enable' | string | Enables/disables the strobe mode (supported by SV-xxxx cameras only). |
| 'trigger_delay' | 'enable', 'disable' | 'disable' | string | Enables or disables the use of the trigger delay parameters. |
| 'trigger_delay_time_unit' | 'us', 'ms', 's' | 'us' | string | Sets the trigger delay time unit. The trigger delay time unit is used by the parameter 'trigger_delay'. |
| 'trigger_delay_value' | <time> | 20 | integer | Sets the trigger delay time. The unit of the parameter depends of the used time unit. Please see 'trigger_delay_time_unit' for more information (supported by SV-xxxx cameras only). |
| 'trigger_signal' | 'high_active', 'low_active' | 'high_active' | string | Type of the trigger signal. |
| 'trigger_source' | 'input0', 'input1', 'input2' | 'input0' | string | Trigger source (supported by SV-xxxx cameras only). |
| 'white_balance' | 'disable', 'enable' | 'disable' | string | Enables/disables the white balance mode. |
| 'white_balance_b' | <white_balance_b> | 1.0 | float | White balance for the blue channel. |
| 'white_balance_g' | <white_balance_g> | 1.0 | float | White balance for the green channel. |
| 'white_balance_r' | <white_balance_r> | 1.0 | float | White balance for the red channel. |
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 |
|---|---|---|---|---|---|
| 'adc_level' | 'adc0', 'adc1', 'adc2', 'adc3' | 'adc2' | string | pre-defined | Level of the A/D translation. |
| 'bayer_convert_type' | 'high', 'low', 'normal' | 'low' | string | pre-defined | One of the possible conversion types. |
| 'bayer_layout' | 'bayer_bg', 'bayer_gb', 'bayer_gr', 'bayer_rg' | 'bayer_rg' (if SV-13xx camera is used) otherwise 'bayer_gr' | string | pre-defined | Associated bayer mode for the camera. |
| 'bits_per_channel' | <default> | 8 | integer | pre-defined | The value is not used, so a default value is returned. |
| 'camera_type' | 'HV-13xx', 'HV-20xx', 'HV-30xx', 'HV-31xx', 'HV-50xx', 'HV-xx51', 'SV-xxxx' | 'HV-xx51' | string | pre-defined | Type of the connected camera series. |
| 'color_space' | 'gray', 'rgb', 'yuv' | 'gray' | string | pre-defined | Desired color space and thus the number of image channels of the resulting HALCON image. |
| 'device' | '1', '2', '3', ... | '1' | string | pre-defined | ID of the used camera. |
| 'dh_lut_table' | <file name> | string | dynamic | LUT table. | |
| 'external_trigger' | 'false', 'true' | 'false' | string | pre-defined | Status of the external trigger. |
| 'field' | '<default>' | 'progressive' | string | pre-defined | The value is not used, so a default value is returned. |
| 'gain' | 0.0 ... 127.0 | 8.0 | float | dynamic | Gain value of the camera. |
| 'generic' | <default> | -1 | mixed | pre-defined | The value is not used, so a default value is returned. |
| 'grab_timeout' | 100 ... 327680 | 5000 | integer | pre-defined | Current grab timeout in milliseconds. |
| 'horizontal_resolution' | <resolution> | 1 | integer | pre-defined | Current value of horizontal resolution. |
| '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' | 'DahengCAM' | string | pre-defined | Name of the HALCON interface. | |
| 'output_io_0' | 'integration_signal', 'strobe', 'trigger_ready', 'user_set' | 'strobe' | string | pre-defined | I/O to output 0 of the camera (supported by SV-xxxx cameras only). |
| 'output_io_1' | 'integration_signal', 'strobe', 'trigger_ready', 'user_set' | 'trigger_ready' | string | pre-defined | I/O to output 1 of the camera (supported by SV-xxxx cameras only). |
| 'output_io_2' | 'integration_signal', 'strobe', 'trigger_ready', 'user_set' | 'integration_signal' | string | pre-defined | I/O to output 2 of the camera (supported by SV-xxxx cameras only). |
| 'port' | <default> | 1 | integer | pre-defined | The value is not used, so a default value is returned. |
| 'resolution' | 'mode0', 'mode1', 'mode2', 'mode3', 'mode4', 'mode5', 'mode6' | 'mode0' | string | pre-defined | Resolution of the image depending of the camera model. Mode0 always is the maximum resolution of the camera. |
| 'revision' | '<revision>' | string | pre-defined | Revision number of the DahengCAM interface. | |
| 'shutter' | 0 ... 16383 | integer | dynamic | Shutter (exposure time) of the camera. | |
| 'shutter_unit' | 'us', 'ms', 's' | 'ms' | string | pre-defined | Unit of the shutter. |
| 'snap_mode' | 'continuous', 'trigger', 'trigger_edge', 'trigger_level' | 'continuous' | string | pre-defined | Snap mode of the camera. If set to 'trigger' an external trigger signal is needed to grab an image. In continuous mode the camera grabs images continuously. |
| 'snap_speed' | 'high', 'normal' | 'high' | string | pre-defined | Snap speed modus. |
| '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' | 'enable' | string | pre-defined | Enables/disables the strobe mode (supported by SV-xxxx cameras only). |
| 'trigger_delay' | 'enable', 'disable' | 'disable' | string | pre-defined | Enables or disables the use of the trigger delay parameters. |
| 'trigger_delay_time_unit' | 'us', 'ms', 's' | 'us' | string | pre-defined | Sets the trigger delay time unit. The trigger delay time unit is used by the parameter 'trigger_delay'. |
| 'trigger_delay_value' | <time> | 20 | integer | pre-defined | Sets the trigger delay time. The unit of the parameter depends of the used time unit. Please see 'trigger_delay_time_unit' for more information (supported by SV-xxxx cameras only). |
| 'trigger_signal' | 'high_active', 'low_active' | 'high_active' | string | pre-defined | Type of the trigger signal. |
| 'trigger_source' | 'input0', 'input1', 'input2' | 'input0' | string | pre-defined | Trigger source (supported by SV-xxxx cameras only). |
| 'vertical_resolution' | <resolution> | 1 | integer | pre-defined | Current value of vertical resolution. |
| 'white_balance' | 'disable', 'enable' | 'disable' | string | pre-defined | Enables/disables the white balance mode. |
| 'white_balance_b' | <white_balance_b> | 1.0 | float | dynamic | White balance for the blue channel. |
| 'white_balance_g' | <white_balance_g> | 1.0 | float | dynamic | White balance for the green channel. |
| 'white_balance_r' | <white_balance_r> | 1.0 | float | dynamic | White balance for the red channel. |
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:
- dahengcam_2cameras.hdev - Concurrent grabbing of images from two connected Daheng cameras.
- dahengcam.hdev - Benchmark
- dahengcam_parameters.hdev - Lists all parameters of a device.
- dahengcam_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.
- Added support of Windows 64-bit.
- Revision 5.1 (Oct 24, 2014):
- Fixed problem with parameter 'snap_speed' and 'shutter_unit', where the selected value wasn't set in the camera.
- Added support of HV-xx51 camera series.
- Added parameter 'snap_speed_level' for HV-5051 cameras.
- Added resolution modes 'mode4', 'mode5', and 'mode6' for HV-5051 cameras.
- Changed default of 'camera_type' from 'HV-13xx' to 'HV-xx51'.
- Revision 5.0 (May 15, 2012):
- HALCON 11 version of the interface (included in HALCON 11 DVD).
- Added support of HV-50xx camera series.
- Added parameter 'trigger_delay', 'trigger_delay_value' and 'trigger_delay_time_unit'.
- Revision 4.1 (Sep 3, 2010):
- Fixed memory problem in info_framegrabber(.., 'info_boards', ..).
- Added missing descriptions ('paramname__description') for 9 parameters.
- HALCON 10 version of the interface (included in HALCON 10 DVD).
- Revision 4.0 (Dec 1, 2008):
- Added support of the SV-xxxx camera series.
- Added parameters 'color_space', 'output_io_0', 'output_io_1', 'output_io_2', 'strobe', and 'trigger_source'.
- HALCON 9.0 version of the interface (included in HALCON 9.0 DVD).
- Revision 3.1 (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.0 (May 15, 2007):
- HALCON 8.0 version of the interface (included in HALCON 8.0 DVD).
- Added support of SV-13xx camera series.
- Bug fix using multiple cameras.
- Added parameters 'bayer_convert_type', 'bayer_layout', 'dh_lut_table', 'image_height', 'image_width', 'shutter_unit', 'snap_speed', 'start_col', and 'start_row'.
- Added 'trigger_edge' and 'trigger_level' to parameter 'snap_mode'.
- Changed camera type names.
- Changed type of gain parameter from float to long (float still supported).
- Revision 2.0 (Jul 28, 2006):
- First official release.