MVTec Software GmbH
 

Documentation

DahengCAM / HALCON 12.0 / MVTec Software GmbH

Image Acquisition Interface for Daheng Cameras

Interface: DahengCAM
Revision: 6.0
Date: 2014-10-31
HALCON Version: 12.0

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/8 or Windows 7/8 x64.
  • 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 Type Description
'adc_level' 'adc0', 'adc1', 'adc2', 'adc3' string Level of the A/D translation:
  • adc0: low-order 7 bits of 10 bits data are used.
  • adc1: low-order 8 bits of 10 bits data are used.
  • adc2: mid-order 8 bits of 10 bits data are used.
  • adc3: high-order 8 bits of 10 bits data are used.
'bayer_convert_type' 'high', 'low', 'normal' string One of the possible conversion types.
'bayer_layout' 'bayer_bg', 'bayer_gb', 'bayer_gr', 'bayer_rg' 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 float Gain value of the camera.
'grab_timeout' 100 ... 327680 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' 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' 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' string I/O to output 2 of the camera (supported by SV-xxxx cameras only).
'resolution' 'mode0', 'mode1', 'mode2', 'mode3', 'mode4', 'mode5', 'mode6' 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' string Unit of the shutter.
'snap_mode' 'continuous', 'trigger', 'trigger_edge', 'trigger_level' 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' 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' string Enables/disables the strobe mode (supported by SV-xxxx cameras only).
'trigger_delay' 'enable', 'disable' string Enables or disables the use of the trigger delay parameters.
'trigger_delay_time_unit' 'us', 'ms', 's' string Sets the trigger delay time unit. The trigger delay time unit is used by the parameter 'trigger_delay'.
'trigger_delay_value' <time> 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' string Type of the trigger signal.
'trigger_source' 'input0', 'input1', 'input2' string Trigger source (supported by SV-xxxx cameras only).
'white_balance' 'disable', 'enable' string Enables/disables the white balance mode.
'white_balance_b' <white_balance_b> float White balance for the blue channel.
'white_balance_g' <white_balance_g> float White balance for the green channel.
'white_balance_r' <white_balance_r> 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]. 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'].

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 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.