Interface Documentation
Image Acquisition Interface for ELTEC PC_EYE/CL Boards
| Interface: | PcEyeCL |
| Revision: | 6.0 |
| Date: | 2014-10-31 |
| HALCON Version: | 12.0 |
PcEyeCL: Legacy Interface
- 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 PcEyeCL image acquisition interface for the ELTEC PC_EYE/CL (PCI Express)
frame grabber boards.
Registered customers can download the
latest revision of this interface from the
MVTec WWW server.
System Requirements
- Intel compatible PC with Windows Vista/7.
- Successfully installed ELTEC PC_EYE/CL board and driver.
- HALCON image acquisition interface hAcqpPcEyeCL.dll or hAcqPcEyeCLxl.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.
- Configuration files for your boards, created with the p3i configuration tool.
Features
- Multiple frame grabber boards (different board types may be mixed).
- Synchronous and asynchronous grabbing.
- Cropping of image parts.
- External trigger.
- Software control of exposure time and digital output lines.
Limitations
- Only RGB 24 and 32 bit modes are supported by this interface.
Parameters for info_framegrabber
| Parameter | Value List | Type | Kind | Description |
|---|---|---|---|---|
| 'bits_per_channel' | [] | Unused. | ||
| 'camera_type' | ['CAMFILE:', 'dat', '\\'] | string | pre-defined | Syntax for camera configuration file. |
| 'color_space' | [] | Unused. | ||
| 'defaults' | [1, 1, 0, 0, 0, 0, 'interlaced', -1, 'default', -1.0, 'false', 'default', 'default', -1, 1] | mixed | pre-defined | Default values for open_framegrabber. |
| 'device' | ['0', '1', ..., '15'] | string | pre-defined | Pre-defined list of possible device numbers. |
| 'external_trigger' | [] | Unused. | ||
| 'field' | [] | Unused. | ||
| 'general' | [] | string | pre-defined | Information about the HALCON PcEyeCL interface. |
| 'generic' | [] | Unused. | ||
| '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' | [] | Ignored. | ||
| 'revision' | '<revision>' | string | pre-defined | Revision number of the PcEyeCL 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 | 'PcEyeCL' | string | Name of the HALCON interface. | |
| HorizontalResolution | --- | Ignored (value is set via the configuration file). | ||
| VerticalResolution | --- | Ignored (value is set via the configuration file). | ||
| ImageWidth | 0, <width> | 0 | integer | Width of the desired image part ('0' stands for the complete image). |
| ImageHeight | 0, <height> | 0 | integer | Height of the desired image part ('0' stands for the complete image). |
| StartRow | 0, <row> | 0 | integer | The row coordinate of the upper left pixel of the desired image part (if ImageWidth and ImageHeight are set to 0, this value is ignored and taken from the configuration file). |
| StartColumn | 0, <column> | 0 | integer | The column coordinate of the upper left pixel of the desired image part (if ImageWidth and ImageHeight are set to 0, this value is ignored and taken from the configuration file). |
| Field | --- | Ignored (value is set via the configuration file). | ||
| BitsPerChannel | --- | Ignored (value is set via the configuration file). | ||
| ColorSpace | --- | Ignored (value is set via the configuration file). | ||
| Generic | --- | Ignored. | ||
| ExternalTrigger | --- | Ignored (value is set via the configuration file). | ||
| CameraType | <filename> | 'default' | string | Name of the configuration file for the board. This has to be a valid '.dat'-file created with the p3i4 configuration tool. All the basic board setup is done using this file. Note that only the 'gray' (8 bit) and 'rgb' (8-8-8 bit) color modes are supported by this interface. A full path name has to be entered (e.g., 'C:\\my_configurations\\my_p3i4_svhs0.dat'). |
| Device | '<id>' | 'default' | string | HEX setting of the frame grabber board (passed as a string!). Note that different boards have to use different HEX settings. |
| Port | --- | Ignored (value is set via the configuration file). | ||
| LineIn | --- | Ignored. |
Parameters for set_framegrabber_param
All these settings are valid for all input lines (if applicable), i.e., cameras connected to one frame grabber board. Note that not all of
these settings may be used with all boards. Some of these settings do not
influence the grabbing on all camera inputs (see below).
| Parameter | Values | Type | Description |
|---|---|---|---|
| 'exposure' | <microseconds> | integer | Exposure time in microseconds. Valid ranges depend on the camera selected in the configuration file. |
| 'grab_timeout' | 100 ... 327680 | integer | Specify the desired timeout (milliseconds) for aborting a pending grab. |
| 'image_height' | <height> | integer | The height of the desired image part. width must not be larger than VertcialResolution - StartRow and should be divisible by the 'pixelalign' value (see below); otherwise, 'image_height' is adjusted to a smaller valid value. |
| 'image_width' | <width> | integer | The width of the desired image part. width must not be larger than HorizontalResolution - StartColumn and should be divisible by the 'pixelalign' value (see below); otherwise, 'image_width' is adjusted to a smaller valid value. |
| 'output_reset' | 1 ... 15 | integer | Sets value to 1, 2, 4 or 8 (or any combination) to set output lines 1, 2, 3 and 4 (or any combination) to low state. |
| 'output_set' | 1 ... 15 | integer | Set value to 1, 2, 4 or 8 (or any combination) to set output lines 1, 2, 3 and 4 (or any combination) to high state. |
| 'port' | <port> | integer | Select the desired camera input port for acquisition during runtime. |
| 'start_async_after_grab_async' | 'disable', 'enable' | string | By default a new asynchronous grab command is automatically given to the acquisition device at the end of grab_image_async. If the parameter 'start_async_after_grab_async' is set to 'disable', this new grab command is omitted. |
| '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. |
| 'switch_buffer' | 'disable', 'enable' | string | This parameter controls the buffer switching after each grab. Usually, two image buffers are allocated, which are used alternately. Attention: Do not disable the buffer switching if you are using the volatile mode! |
| 'testacq_interval' | 1 ... 10 | integer | Time (in milliseconds) between two subsequent test calls while waiting for the end of a current grab. |
| 'volatile' | 'disable', 'enable' | string | Grayscale only. In the volatile mode the two image acquisition interface buffers are used directly to store HALCON images. This is the fastest mode avoiding to copy raw images in memory. However, be aware that older images are overwritten again and again as a side-effect. Thus, you can only process one image while you grab another image. Older images are invalid! |
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 |
|---|---|---|---|---|---|
| 'bits_per_channel' | '<default>' | -1 | integer | pre-defined | The value is not used, so a default value is returned. |
| 'camera_type' | <filename> | 'default' | string | pre-defined | Current camera type. |
| 'color_space' | '<default>' | 'default' | string | pre-defined | The value is not used, so a default value is returned. |
| 'device' | '<device_id>' | 'default' | string | pre-defined | Current device ID. |
| 'exposure' | <microseconds> | integer | dynamic | Exposure time in microseconds. Valid ranges depend on the camera selected in the configuration file. | |
| 'external_trigger' | <default> | 'false' | string | pre-defined | The value is not used, so a default value is returned. |
| 'field' | '<default>' | 'interlaced' | string | pre-defined | The value is not used, so a default value is returned. |
| 'generic' | <default> | -1 | integer | pre-defined | The value is not used, so a default value is returned. |
| 'grab_timeout' | <milliseconds> | 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> | 1 | integer | pre-defined | The value is not used, so a default value is returned. |
| 'name' | 'PcEyeCL' | string | pre-defined | Name of the HALCON interface. | |
| 'pixelalign' | <bits> | integer | dynamic | Alignment of the desired acquisition window in the memory: The parameter values for 'start_row', 'start_column', 'image_width', and 'image_height' must be divisible by bits. | |
| 'port' | <default> | -1 | integer | pre-defined | The value is not used, so a default value is returned. |
| 'revision' | '<revision>' | string | pre-defined | Revision number of the PcEyeCL interface. | |
| 'revision_drv' | <revision> | string | dynamic | Revision number of the ELTEC driver. | |
| 'revision_fw' | <revision> | string | dynamic | Revision number of the PCI- and the Application-Xilinx. | |
| 'revision_hw' | <revision> | string | dynamic | Revision number of the board hardware. | |
| 'revision_sw' | <revision> | string | dynamic | Revision number of the ELTEC software. | |
| 'start_async_after_grab_async' | 'disable', 'enable' | 'enable' | string | pre-defined | Status of 'start_async_after_grab_async'. |
| '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. |
| 'switch_buffer' | 'disable', 'enable' | 'enable' | string | pre-defined | This parameter controls the buffer switching after each grab. Usually, two image buffers are allocated, which are used alternately. Attention: Do not disable the buffer switching if you are using the volatile mode! |
| 'testacq_interval' | <milliseconds> | 2 | integer | pre-defined | Time (in milliseconds) between two subsequent test calls while waiting for the end of a current grab. |
| 'vertical_resolution' | <resolution> | 1 | integer | pre-defined | Current value of vertical resolution. |
| 'volatile' | 'disable', 'enable' | 'disable' | string | pre-defined | Grayscale only. In the volatile mode the two image acquisition interface buffers are used directly to store HALCON images. This is the fastest mode avoiding to copy raw images in memory. However, be aware that older images are overwritten again and again as a side-effect. Thus, you can only process one image while you grab another image. Older images are invalid! |
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:
- pceyecl_crop.hdev - Grabbing image parts of size 256x256 with an ELTEC PC_EYE/CL frame grabber board.
- pceyecl.hdev - Benchmark
- pceyecl_parameters.hdev - Lists all parameters of a device.
- pceyecl_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.
- Revision 5.0 (May 15, 2012):
- HALCON 11 version of the interface (included in HALCON 11 DVD).
- Revision 4.1 (Sep 3, 2010):
- First official release.
- HALCON 10 version of the interface (included in HALCON 10 DVD).