Interface Documentation
Image Acquisition Interface for heliCam C3 Cameras
| Interface: | heliCamC3 |
| Revision: | 6.4 |
| Date: | 2018-06-27 |
| HALCON Version: | 12.0 |
- General
- System Requirements
- Installation
- Features
- Limitations
- Measurement sequence
- 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 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:
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.7.2.233 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.
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.
|
| '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.
|
| 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 absolute position. The absolute position is referenced to the axis position and reseted 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) | |
| 'stay_on_endposition' | 'true', 'false' | 'false' | string | If a single direction measurement sequence used, the motor move back to the home position after each measurement. If it preferred to wait on the end position, this flag could be enabled. (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. |
| 'zCorrection' | -1.5 - 1.5 | 0.0 | double | In bidirectional scanning and absolute position calculation, the absolute surface position could jump depended on the scan direction. The size of the jump depend on different factors. With this parameter, the correction of the absolute position could be adjust. |
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 absolute position. The absolute position is referenced to the axis position and reseted 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) | |
| 'header_ztagsreference' | double | dynamic | unwrapped and processed zTag array 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) | |
| 'stay_on_endposition' | 'true', 'false' | 'false' | string | dynamic | If a single direction measurement sequence used, the motor move back to the home position after each measurement. If it preferred to wait on the end position, this flag could be enabled. (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. |
| 'zCorrection' | -1.5 - 1.5 | 0.0 | double | dynamic | In bidirectional scanning and absolute position calculation, the absolute surface position could jump depended on the scan direction. The size of the jump depend on different factors. With this parameter, the correction of the absolute position could be adjust. |
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.
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.
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 6.4 (Jun 27, 2018):
- The required heliSDK version is now 1.7.4.246 or higher.
- Revision 6.3 (Jun 28, 2017):
- The required heliSDK version is now 1.7.2.233 or higher.
- Support for the Segmented Volume feature has been added.
- A bug in the motion control interface has been fixed.
- Revision 6.2 (Dec 22, 2016):
- Support for Xvi42v8 axis controller has been added.
- Support for measurement results in absolute high notation has been added.
- Revision 6.1 (Jul 22, 2015):
- 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.
- Revision 6.0 (May 13, 2015):
- First official release