MVTec HALCON 6.0: Frame Grabber Interface for ELTEC PC

HALCON 6.0 Frame Grabber Interface for ELTEC PC_EYE® Boards

This page provides the documentation of the HALCON frame grabber interface HFGPCEye.dll for the ELTEC frame grabber boards PC_EYE® 1, PC_EYE® 2, PC_EYE® 2+, and PC_EYE® 4. Registered customers can download the latest revision of this interface from the MVTec WWW server.

Revision: 2.2

System Requirements

Intel compatible PC with Windows NT 4.0 (Service Pack 4) or Windows 2000.
Successfully installed ELTEC PC_EYE® 1, PC_EYE® 2, PC_EYE® 2+, or PC_EYE® 4 (or any combination of those).
ELTEC DLLs eleye116.dll, eleye216.dll, eleye516.dll, or eleye416.dll, respectively.
These DLLs must be within your search path %PATH% (e.g., in bin\i586-nt4 within the HALCON base directory %HALCONROOT% you have chosen during the installation of HALCON). If you do not have these DLLs, please contact ELTEC or the vendor from which you bought the frame grabber board.
PC_EYE® 4 and PC_EYE® 2+ only: ELTEC DLL el_hard.dll and eleye416.cam (or eleye516.cam, respectively).
These files must also be within your search path %PATH% (e.g., in bin\i586-nt4 within the HALCON base directory %HALCONROOT% you have chosen during the installation of HALCON). If you do not have these files, please contact ELTEC or the vendor from which you bought the frame grabber board.
HALCON frame grabber interface HFGPCEye.dll or parHFGPCEye.dll, respectively.
If you have properly installed the interface, both DLLs should reside in bin\i586-nt4 within the HALCON base directory %HALCONROOT% you have chosen during the installation of HALCON.
Configuration files for your boards, created with the PC_EYE® configuration tool.

Features

Multiple frame grabber boards (different board types may be mixed).
Synchronous and asynchronous grabbing.
Cropping of image parts.
External trigger.
LUTs (not with PC_EYE® 2+).
Software control of 'black' and 'white' levels.
Support of color CCD cameras with software control of 'gain', 'hue' ,'saturation', and 'gamma' (PC_EYE® 2 and PC_EYE® 4 only).
Software control of the digital output lines of the PC_EYE® boards.
Support of dual mode (PC_EYE® 4 only).

Limitations

grab_region() and grab_region_async() not supported.
Support of monochrome 8 bit and RGB 8-8-8 bit mode only.

Description

Parameters for open_framegrabber():

Name 'PCEye' The name of the HALCON frame grabber interface.

HorizontalResolution --- Ignored (value is set via the configuration file).

VerticalResolution --- Ignored (value is set via the configuration file).

ImageWidth 0, width The width of the desired image part (or 0 for the value set in the configuration file). Default: 0.

ImageHeight 0, height The height of the desired image part (or 0 for the value set in the configuration file). Default: 0.

StartRow 0, row 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). Default: 0.

StartColumn 0, column 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). Default: 0.

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

Gain --- Ignored (value is set via the configuration file).

ExternalTrigger --- Ignored (value is set via the configuration file).

CameraType 'filename' Name of the configuration file for the board. This has to be a valid '.dat'-file created with the PC_EYE® 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_pceye2_svhs0.dat').

Device 'name:id' The name and id of the frame grabber board. Devices must be named 'name:id', where name is either 'pceye1', 'pceye2', 'pceye4', or 'pceye5' (used for PC_EYE® 2+), and id is the HEX setting of the board (PC_EYE® 1, PC_EYE® 2, and PC_EYE® 2+: HEX switch, PC_EYE® 4: jumpers J101 and J102).
Example: 'pceye4:3' is a PC_EYE® 4 board with HEX jumpers set to 3. 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).

'volatile' 'enable', 'disable' In the volatile mode (8 bit, one channel only!) the two frame grabber 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! Default: 'disable'.

'start_row' row The row coordinate of the upper left pixel of the desired image part. row must not be larger than VerticalResolution - ImageHeight and should be divisible by the 'pixelalign' value (see below); otherwise, 'start_row' is adjusted to a smaller valid value.

'start_column' column The column coordinate of the upper left pixel of the desired image part. column must not be larger than HorizontalResolution - ImageWidth and should be divisible by the 'pixelalign' value (see below); otherwise, 'start_column' is adjusted to a smaller valid value.

'image_width' width 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.

'image_height' height 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.

'white_level' min_level ... max_level The desired voltage level for 'white' pixels in millivolts (floating point number). The valid range for a particular board can (and should) be queried via get_framegrabber_param(...,'white_level_min',...) and get_framegrabber_param(...,'white_level_max',...), respectively. Furthermore, 'white_level' must be larger than 'black_level'.

'black_level' min_level ... max_level The desired voltage level for 'black' pixels in millivolts (floating point number). The valid range for a particular board can (and should) be queried via get_framegrabber_param(...,'black_level_min',...) and get_framegrabber_param(...,'black_level_max',...), respectively. Furthermore, 'black_level' must be smaller than 'white_level'.

'color_mode' 'r', 'g', 'b' Set desired color plane (PC_EYE® 2 with 8 bits per pixel only).

'white_level_r' min_level ... max_level The desired voltage level for 'white' pixels in millivolts (floating point number) for the red channel (PC_EYE® 2 and PC_EYE® 2+ with RGB 24 bits per pixel only). The valid range for a particular board can (and should) be queried via get_framegrabber_param(...,'white_level_min',...) and get_framegrabber_param(...,'white_level_max',...), respectively. Furthermore, 'white_level_r' must be larger than 'black_level_r'.

'white_level_g' min_level ... max_level The desired voltage level for 'white' pixels in millivolts (floating point number) for the red channel (PC_EYE® 2 and PC_EYE® 2+ with RGB 24 bits per pixel only). The valid range for a particular board can (and should) be queried via get_framegrabber_param(...,'white_level_min',...) and get_framegrabber_param(...,'white_level_max',...), respectively. Furthermore, 'white_level_g' must be larger than 'black_level_g'.

'white_level_b' min_level ... max_level The desired voltage level for 'white' pixels in millivolts (floating point number) for the red channel (PC_EYE® 2 and PC_EYE® 2+ with RGB 24 bits per pixel only). The valid range for a particular board can (and should) be queried via get_framegrabber_param(...,'white_level_min',...) and get_framegrabber_param(...,'white_level_max',...), respectively. Furthermore, 'white_level_b' must be larger than 'black_level_b'.

'black_level_r' min_level ... max_level The desired voltage level for 'black' pixels in millivolts (floating point number) for the red channel (PC_EYE® 2 and PC_EYE® 2+ with RGB 24 bits per pixel only). The valid range for a particular board can (and should) be queried via get_framegrabber_param(...,'black_level_min',...) and get_framegrabber_param(...,'black_level_max',...), respectively. Furthermore, 'black_level_r' must be smaller than 'white_level_r'.

'black_level_g' min_level ... max_level The desired voltage level for 'black' pixels in millivolts (floating point number) for the red channel (PC_EYE® 2 and PC_EYE® 2+ with RGB 24 bits per pixel only). The valid range for a particular board can (and should) be queried via get_framegrabber_param(...,'black_level_min',...) and get_framegrabber_param(...,'black_level_max',...), respectively. Furthermore, 'black_level_g' must be smaller than 'white_level_g'.

'black_level_b' min_level ... max_level The desired voltage level for 'black' pixels in millivolts (floating point number) for the red channel (PC_EYE® 2 and PC_EYE® 2+ with RGB 24 bits per pixel only). The valid range for a particular board can (and should) be queried via get_framegrabber_param(...,'white_level_min',...) and get_framegrabber_param(...,'white_level_max',...), respectively. Furthermore, 'black_level_b' must be smaller than 'white_level_b'.

'offset' 0.0 ... 1.0 The desired offset level (PC_EYE® 2 and PC_EYE® 4 only, RGB 24 bits per pixel). The equation 0.0 <= 2*offset + gain <= 2.0 has to be satisfied; otherwise, 'gain' is decreased automatically.

'gain' 0.0 ... 2.0 The desired gain (PC_EYE® 2 and PC_EYE® 4 only, RGB 24 bits per pixel). The equation 0.0 <= 2*offset + gain <= 2.0 has to be satisfied; otherwise, 'offset' is decreased automatically.

'saturation' 0.0 ... 2.0 The desired color saturation (PC_EYE® 2 and PC_EYE® 4 only, RGB 24 bits per pixel).

'hue' -180.0 ... 180.0 The desired color hue in degree (PC_EYE® 2 and PC_EYE® 4 only, RGB 24 bits per pixel).

'gamma' 1.0, 1.4 The desired gamma correction (PC_EYE® 2 and PC_EYE® 4 only, RGB 24 bits per pixel): l_out = l_in * exp(gamma).

'port' 0, 1, 2, 3 (PC_EYE® 1)

0, 1, 16, 17, 32, 33 (PC_EYE® 2)

0, 2, 4, 6, 8, 9 (PC_EYE® 2+)

0, 1, 16, 17, 32, 33, 48, 49 (PC_EYE® 4)
Select the desired camera input port for acquisition during runtime. The following values are possible:

PC_EYE® 1: 0
1
2
3 video input #0
video input #1
video input #2
video input #3

PC_EYE® 2: 0
1
16
17
32
33 RGB input #0
RGB input #1
CVBS input #0
CVBS input #1
SVHS input #0
SVHS input #1

PC_EYE® 2+: 0
2
4
6
8
9 input R_A
input B_A
input R_B
input B_B
input RGB_A
input RGB_B

PC_EYE® 4: 0
1
16
17
32
33
48
49 b/w video input #0
b/w video input #1
CVBS input #0
CVBS input #1
SVHS input #0
SVHS input #1
dual mode
dual mode (channels swapped)

Note that after changing the camera input port the sync input port is also automatically set to the new port value.

'sync_in' 0, 1, 2, 3 (PC_EYE® 1)

0, 1, 32, 33 (PC_EYE® 2)

4, 5, 6, 7 (PC_EYE® 2+)
Select the desired sync input port for acquisition during runtime. The following values are possible:

PC_EYE® 1: 0
1
2
3 video input #0
video input #1
video input #2
video input #3

PC_EYE® 2: 0
1
32
33 green of RGB input #0
green of RGB input #1
extern sync #0
extern sync #1

PC_EYE® 2+: 4
5
6
7 ADC #0
ADC #1
ADC #2
ADC #3

'output_set' 1 ... 7 (PC_EYE® 1/2),
1 ... 3 (PC_EYE® 4) Set value to 1, 2, and 4 (or any combination) to set output lines 1, 2, and 3 (or any combination) to high state (PC_EYE® 4: output lines 1 and 2 only). Note, that the output status can not be read via get_framegrabber_param().

'output_reset' 1 ... 7 (PC_EYE® 1/2),
1 ... 3 (PC_EYE® 4) Set value to 1, 2, and 4 (or any combination) to set output lines 1, 2, and 3 (or any combination) to low state (PC_EYE® 4: output lines 1 and 2 only). Note, that the output status can not be read via get_framegrabber_param().

'grab_timeout' 100 ... 327680 Specify the desired timeout (milliseconds passed as an integer) for aborting a pending grab. Default: 5000.

'testacq_interval' 1 ... 10 Set time (in milliseonds) between two subsequent test calls while waiting for the end of a current grab. Default: 2.

'switch_buffer' 'enable', 'disable' This parameter controls the buffer switching after each grab. Usually, two image buffers are allocated, which are used alternately. Default: 'enable'. Attention: Do not disable the buffer switching if you are using the volatile mode!

Parameters for get_framegrabber_param():

Additional parameters supported by get_framegrabber_param only. Note that all parameters supported by set_framegrabber_param (except 'output_set' and 'output_reset') can also be accessed by get_framegrabber_param.

'revision' revision The revision number of the HALCON PCEye interface.

'pixelalign' bits 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.

'black_level_min' min_level The minimum allowed voltage level for 'black' pixels in millivolts.

'black_level_max' max_level The maximum allowed voltage level for 'black' pixels in millivolts.

'white_level_min' min_level The minimum allowed voltage level for 'white' pixels in millivolts.

'white_level_max' max_level The maximum allowed voltage level for 'white' pixels in millivolts.

Release Notes

Revision 2.2 (Mar 12, 2002):

Added support for PC_EYE® 2+.
New parameter 'sync_in'.
New parameters 'image_width' and 'image_height' for changing the acquisition window during runtime.

Revision 2.1 (Dec 19, 2000):

Query board information in info_framegrabber().
Bugfix in initializing frame grabber board.

Revision 2.0 (Sep 20, 2000):

Adaptation to the HALCON 6.0 frame grabber interface.

Revision 1.4 (Jan 24, 2000):

Timeout configuration while waiting for a grab (new parameters 'grab_timeout' and 'testacq_interval').
Bugfix in asynchronous image grabbing.
New parameter 'switch_buffer'.

Revision 1.0 (Nov 19, 1999):

First official release.

Last modified: Wed Apr 24 17:27:11 CEST 2002