MVTec Software GmbH
 
heliCamC3 / HALCON 13.0 / MVTec Software GmbH

Image Acquisition Interface for heliCam C3 Cameras

Interface: heliCamC3
Revision: 13.0.2
Date: 2016-12-23
HALCON Version: 13.0

General

This page provides the documentation of the HALCON heliCamC3 interface for the heliotis heliCamC3.
Registered customers can download the latest revision of this interface from the MVTec WWW server. The HALCON heliCamC3 interface is compatible with all current Heliotis C3 camera systems. This includes:
  • heliCam C3
  • heliInspect H3
  • heliInspect H4
  • heliInspect H6
  • (heliProfiler M3)
  • (heliProfiler M3-XL)

System Requirements

  • Intel compatible PC with Windows 7 (32-bit or 64-bit) or newer that is also supported by the vendor-specific SDK, also WoW64 (using 32-bit HALCON on 64-bit Windows).
  • Installed Heliotis heliSDK 1.5.0.170 or higher.
    If you don't have these SDK, please contact your heliCam C3 supplier or heliotis.
  • Windows: HALCON image acquisition interface hAcqheliCamC3.dll or hAcqheliCamC3xl.dll, respectively. If you have properly installed the interface, all these DLLs should reside in bin\%HALCONARCH% within the HALCON base directory %HALCONROOT% you have chosen during the installation of HALCON.

Installation

Only when installing or updating the interface manually follow these steps:
Windows: Extract the archive containing the interface files to the HALCON base directory %HALCONROOT% (Note: Administrator privileges may be required for this step). Additionally, you have to move the interface examples to the directory %HALCONEXAMPLES% manually.
  • Linux: Extract the archive containing the interface files to the HALCON base directory $HALCONROOT.

Features

  • Full heliCam C3 configuration
  • Full linear motor configuration and control
  • Control the measurement sequence
  • Control the configuration sequence
  • Synchronous grabbing
  • External triggering

Limitations

  • No support of asynchronous grabbing.

Measurement sequence

The HALCON heliCamC3 interface supports two different scan sequences. For the simple single directional scan, one trigger position (tgu or tgd) has to be defined. The second trigger position must be set to zero!
If both trigger positions (tgu and tgd) are defined, a bidirectional scan is performed (one direction per grab_image call).
The following graphics illustrates the values from the motor positions.

Note that the axis needs 300um for accelerating and slowing down from the motion range.

Parameters for info_framegrabber

Parameter Value List Type Kind Description
'bits_per_channel' [] Ignored.
'camera_type' ['default', 'c3cam', 'c3cam_sl70'] string pre-defined Type of heliCam can be set. In case of 'default' the 'c3cam_sl70' is used.
'color_space' [] Unsupported Query
'defaults' [0, 0, 0, 0, 0, 0, 'default', -1, 'default', -1.0, 'true', 'default', 'default', -1, -1] mixed pre-defined Default values for open_framegrabber.
'device' 'default', 'HeliCamC3_<serialNumber>' string pre-defined Possible values to connect to a device. By 'default' the first available device will be used.
'external_trigger' 'true', 'false' string Configure the trigger mode. If ExternalTrigger = 'false', the heliCam register TrigFreeExtN is set to 1 (no external trigger source). More information are published in the register description file.
'generic' ' ', ['axis_ip=<IP address>','axis_port=<port>','axis_cnt_per_mm=<cnt/mm>'], 'axis_cnt_per_mm=<cnt/mm>' string pre-defined If you wish to control the z axis from HALCON, the following configuration need to do.
If one parameter missing, no motor will be initialized.
  • axis_ip: IP address from linear motor (e.g. 192.168.2.100)
  • axis_port: Port to control the linear motor. (e.g. 10001)
  • axis_cnt_per_mm: Encoder resolution (ticks per mm) (e.g. 10000)
'info_boards' device:HeliCamC3_<serialNumber> | serial:<serialNumber> string dynamic Return a list whit all connected heliCams and its serial number. The device name includes also the serial number.

Parameters for open_framegrabber

Parameter Values Default Type Description
Name 'heliCamC3' string Name of the HALCON interface.
'HorizontalResolution' -- Ignored.
'VerticalResolution' -- Ignored.
'ImageWidth' -- Ignored.
'ImageHeight' -- Ignored.
'StartRow' -- Ignored.
'StartColumn' -- Ignored.
'Field' -- Ignored.
BitsPerChannel -- -1 Ignored.
ColorSpace -- Ignored.
Generic ' ', ['axis_ip=<IP address>','axis_port=<port>','axis_cnt_per_mm=<cnt/mm>'], 'axis_cnt_per_mm=<cnt/mm>' [] string If you wish to control the z axis from HALCON, the following configuration need to do.
If one parameter missing, no motor will be initialized.
  • axis_ip: IP address from linear motor (e.g. 192.168.2.100)
  • axis_port: Port to control the linear motor. (e.g. 10001)
  • axis_cnt_per_mm: Encoder resolution (ticks per mm) (e.g. 10000)
ExternalTrigger 'true', 'false' 'true' string Configure the trigger mode. If ExternalTrigger = 'false', the heliCam register TrigFreeExtN is set to 1 (no external trigger source). More information are published in the register description file.
CameraType 'default', 'c3cam', 'c3cam_sl70' 'default' string Type of heliCam can be set. In case of 'default' the 'c3cam_sl70' is used.
Device 'default', 'HeliCamC3_<serialNumber>' 'default' string Possible values to connect to a device. By 'default' the first available device will be used.
'Port' -- Ignored.
'LineIn' -- Ignored.

Parameters for set_framegrabber_param

The following table shows HALCON specific parameters. All heliCam C3 parameters are also available with the HALCON interface. Parameter name, range and default values can be found in the register description file (pdf) from the heliCam installation, see Start->All programs->Heliotis->heliSDK
Parameter Values Default Type Description
'do_clear_buffer' 1 int Useful if you use the camera with external motor configuration. If you have triggered the camera, you can reset all buffers.
'do_reset_helicam' 1 int reset the system. You must redefine all parameters.
'do_reset_zTagCounter' 1 int Reset the heliCam internal zTag counter. Only required when the axis is controlled by a external interface.
'drive_speed' 0 - 100.5 50.0 double This is the general drive speed in mm per second. This speed is driven by moving axis without measuring. (Only available if a motor initialized)
'enable_abs_pos' 'true', 'false' 'false' string Calculate the z (high) information in absolut position. The absolute position is referenced to the axis position and reset by setting the axis home position.
'end_position_mm' 0 - 1000 double End position from the scan. Default value will be set after initialize the motor at the current position. (Only available if a motor initialized)
'grab_timeout' 1 - 65535 5000 int heliCam timeout in [ms].
'home_position_mm' 0 - 1000 double After a scan, the motor move to this position. Mostly this can be the same like start_position_mm. Default value will be set after initialize the motor at the current position. (Only available if a motor initialized)
'lambda_nm' 1 - 1000 650 int Wavelength from the light source in [nm]. This parameter is used to calculate the surface topology without z Tags (UseZTags='false')
'measurement_speed' 0 - 100.5 5.0 double Measurement speed in mm per second. This speed is driven between 'start_position_mm' and 'end_position_mm'. (Only available if a motor initialized)
'start_position_mm' 0 - 1000 double Start position from the scan. Default value will be set after initialize the motor at the current position. (Only available if a motor initialized)
'tgd_position' 0 - 1000 0 double The measurement will be triggered at this position by counting from higher position ('start_position_mm') down to lower position ('end_position_mm'). (Only available if a motor initialized)
'tgu_position' 0 - 1000 0 double The measurement will be triggered at this position by counting from lower position ('start_position_mm') up to higher position ('end_position_mm'). (Only available if a motor initialized)
'use_ztags' 'true', 'false' 'false' string Do you use zTags, the measure result will calculate with the encoder values from the z motor. For this, the encoder signal must be connected to the heliDriver. If you dont have a connection between motorcontroller and heliDriver, you can set the UseZTags parameter to false. In this case, the surface high will bee calculate with the measurement time.

Parameters for get_framegrabber_param

The following table shows HALCON specific parameters. All heliCam C3 parameters are also available with the HALCON interface. Parameter name, range and default values can be found in the register description file (pdf) from the heliCam installation, see Start->All programs->Heliotis->heliSDK
Parameter Values Default Type Kind Description
'axis_cnt_per_mm' <cnt/mm> string dynamic Return the encoder resolution. This value must be set by the open_framegrabber function. Used for surface calculation with zTags.
'axis_initialized' 'true', 'false' string dynamic If the motor correctly initialized and the HALCON interface control also the linear motor, this value is 'true'. If no motor used the value is 'false'
'axis_ip' <IP address> string pre-defined Return the IP address from connected motor. (Only available if a motor initialized)
'axis_port' <port> string dynamic Return the TCP/IP port from connected motor. (Only available if a motor initialized)
'axis_tp_mm' <motor position> double dynamic Return the current motor position in mm. If no motor initialized, it returns -1.0.
'drive_speed' 0 - 100.5 50.0 double dynamic This is the general drive speed in mm per second. This speed is driven by moving axis without measuring. (Only available if a motor initialized)
'enable_abs_pos' 'true', 'false' 'false' string dynamic Calculate the z (high) information in absolut position. The absolute position is referenced to the axis position and reset by setting the axis home position.
'end_position_mm' 0 - 1000 double dynamic End position from the scan. Default value will be set after initialize the motor at the current position. (Only available if a motor initialized)
'grab_timeout' 1 - 65535 5000 int dynamic heliCam timeout in [ms].
'he_hdl' 0 - 65535 int dynamic USB handle for heliCam. (Not used)
'header_framedur' 0 - 4294967295 int dynamic Measured frame duration in 70MHz clock cycles.
'header_nframes' 0 - 65535 int dynamic Number of frames in volume which was measured in LAST measurement. (= SensNFrames) (available after a measurement is done)
'header_nvolume' 0 - 4294967295 int dynamic Number of measurements since power up. (since open_framegrabber was called)
'header_scanduration_lsb' int dynamic Number of system clock cycles for the acquisition of the volume. -lsb
'header_scanduration_msb' int dynamic Number of system clock cycles for the acquisition of the volume. -msb
'header_timestamp_lsb' int dynamic Number of system clock cycles since power up. (since open_framegrabber was called) -lsb
'header_timestamp_msb' int dynamic Number of system clock cycles since power up. (since open_framegrabber was called) -msb
'header_ztags' 0 - 65535 int dynamic Array with zTag from LAST measurement. (Array size = SensNFrames) (available after a measurement is done)
'home_position_mm' 0 - 1000 double dynamic After a scan, the motor move to this position. Mostly this can be the same like start_position_mm. Default value will be set after initialize the motor at the current position. (Only available if a motor initialized)
'lambda_nm' 1 - 1000 650 int dynamic Wavelength from the light source in [nm]. This parameter is used to calculate the surface topology without z Tags (UseZTags='false')
'measurement_speed' 0 - 100.5 5.0 double dynamic Measurement speed in mm per second. This speed is driven between 'start_position_mm' and 'end_position_mm'. (Only available if a motor initialized)
'serial_number' int dynamic Serial number from connected heliCam.
'start_position_mm' 0 - 1000 double dynamic Start position from the scan. Default value will be set after initialize the motor at the current position. (Only available if a motor initialized)
'tgd_position' 0 - 1000 0 double dynamic The measurement will be triggered at this position by counting from higher position ('start_position_mm') down to lower position ('end_position_mm'). (Only available if a motor initialized)
'tgu_position' 0 - 1000 0 double dynamic The measurement will be triggered at this position by counting from lower position ('start_position_mm') up to higher position ('end_position_mm'). (Only available if a motor initialized)
'use_ztags' 'true', 'false' 'false' string dynamic Do you use zTags, the measure result will calculate with the encoder values from the z motor. For this, the encoder signal must be connected to the heliDriver. If you dont have a connection between motorcontroller and heliDriver, you can set the UseZTags parameter to false. In this case, the surface high will bee calculate with the measurement time.

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

Asynchronous grabbing is not supported by this interface.

Operator grab_image

grab_image starts a new measurement. If HALCON does control the motor, grab_image moves the axis and acquires the measurement result.
If HALCON controls only the heliCam C3, grab_image acquires a new measurement. If no measurement is done before, grab_image returns a timeout.

Operator grab_image_async

Asynchronous grabbing is not supported by this interface.

Operator grab_data

Not supported by this interface.

Operator grab_data_async

Asynchronous grabbing is not supported by this interface.

Operator close_framegrabber

This operator closes the device, turns off the light and closes the USB connection.
If the linear motor is controlled by the HALCON interface, the axis moves to the home position and the TCP socket will be closed.

HDevelop Examples

For this interface there are the following examples available:
  • helicamc3_simple.hdev -
    Simple example to use the heliCam C3 in minimize energy mode (measure a surface topology). It controls the camera and the motor. Please configure the axis parameter and scan range.
  • helicamc3_motor_control.hdev -
    Same example like helicamc3_simple but without direct motor control. You need to configure the motor and trigger the camera from an external source.
  • helicamc3_modes.hdev -
    Small example which switches between all supported camera modes. For each mode a specific procedure is written. This sample controls also the motor. Please configure the axis parameter and scan range.
  • helicamc3_bidirectional.hdev -
    A short example that scans in both motor moving directions. This is helpful for fast scans. Please configure the axis parameter and scan range.
  • helicamc3_2cameras.hdev -
    Example which works with two cameras. The heliCams are distinguished by their serial number.
    In this example, one camera is configured with motor control and does measurements in minimize energy mode. The second heliCam is initialized without motor control and works in intensity mode.

Release Notes

  • Revision 13.0.2 (Dec 15, 2016):
    • Support for Xvi42v8 axis controller has been added.
    • Support for measurement results in absolute high notation has been added.
  • Revision 13.0.1 (Oct 28, 2016):
    • HALCON 13 version of the interface.
    • The read-only parameter 'axis_tp_mm' has been added.
    • To improve the timing axis communication, the parameters in the example helicamc3_bidirectional.hdev have been adapted.
    • First official release