资料
PixeLINK Image Acquisition Interface for PixeLINK IEEE 1394 (FireWire), USB 2.0, USB 3.0, and GigE Cameras
Interface: | PixeLINK |
Revision: | 5.1 |
Date: | 2015-12-07 |
HALCON Version: | 11.0 |
- General
- System Requirements
- Features
- Limitations
- Hardware Cropping of Images
- 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 PixeLINK Image Acquisition Interface. With this interface you can acquire images
from PixeLINK cameras.
Registered customers can download the
latest revision of this interface from the
MVTec WWW server.
System Requirements
- Intel compatible PC with Windows XP SP1/Vista/7/8, Windows XP SP1/Vista/7/8 x64, also WoW64 (using 32-bit HALCON on 64-bit Windows).
- An OHCI compliant IEEE 1394 adapter, an USB port, or a Gigabit Ethernet (GigE) network interface card.
- Successfully installation of the PixeLINK SDK Release v8.7. You must make sure you have added %PIXELINK_SDK_ROOT%\bin\ (for 32-Bit) and/or %PIXELINK_SDK_ROOT%\bin\x64\ (for 64-Bit) to your PATH variable.
- HALCON image acquisition interface hAcqPixeLINK.dll or
hAcqPixeLINKxl.dll
If you have properly installed the interface, both DLLs should reside in bin\%HALCONARCH% within the HALCON base directory %HALCONROOT% chosen during the installation of HALCON.
Features
- Supports PixeLINK cameras.
- Multiple cameras.
- External camera triggering.
Limitations
- Hot plugging is not supported.
- PixeLINK cameras do not support asynchronous grabbing. Therefore grab_image_start and grab_image_async are supported, but are merely wrappers around grab_image.
- Software cropping currently not supported.
- GigE Vision cameras of other companies are detected and displayed but they cannot be opened.
Hardware Cropping of Images
For cameras that support hardware cropping, you can crop images by changing the camera sensor size with the following parameters:
- horizontal_offset
- horizontal_resolution (also in open_framegrabber)
- vertical_offset
- vertical_resolution (also in open_framegrabber)
Note that sensor size will affect frame rate.
Software cropping via 'image_height', 'image_width', 'start_column' and
'start_row' is currently not supported. They are read-only, and when
queried will reflect the corresponding sensor parameter.
(e.g. Reading 'image_width' will return the current value for
'horizontal_resolution')
Parameters for info_framegrabber
Parameter | Value List | Type | Kind | Description |
---|---|---|---|---|
'bits_per_channel' | [] | Unsupported query | ||
'camera_type' | [] | Unsupported query | ||
'color_space' | ['gray', 'rgb'] | string | pre-defined | Values for color space. |
'defaults' | [1, 1, 0, 0, 0, 0, 'default', -1, 'default', 0.0, 'false', 'default', '0', -1, -1] | mixed | pre-defined | Default values for open_framegrabber. |
'device' | ['<serial_number>'] | string | dynamic | Serial numbers of the available devices. |
'external_trigger' | ['false', 'true'] | string | pre-defined | Values for the external trigger. |
'field' | [] | Unsupported query | ||
'general' | [] | string | pre-defined | Information about the HALCON PixeLINK 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' | ['<serial_number>'] | string | dynamic | Serial numbers 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 PixeLINK driver. |
'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 | 'PixeLINK' | string | Name of the HALCON interface. | |
HorizontalResolution | 1, 2, <width> | 1 | integer | Desired horizontal resolution of the camera image:
|
VerticalResolution | 1, 2, <height> | 1 | integer | Desired vertical resolution of the camera image:
|
ImageWidth | --- | Ignored. | ||
ImageHeight | --- | Ignored. | ||
StartRow | --- | Ignored. | ||
StartColumn | --- | Ignored. | ||
Field | --- | Ignored (value is set via the configuration file). | ||
BitsPerChannel | -1, 8, 10, 12 | -1 | integer | Number of significant bits per channel. -1 means to adopt the highest value supported by the camera. Colour cameras currently support only 8 bits per channel. All monochrome cameras support 8 bits and either 10 or 12 bits per pixel. |
ColorSpace | 'default', 'gray', 'rgb' | 'default' | string | Color space of the resulting HALCON image. 'default' means to adopt the camera setting. |
Generic | --- | Ignored. | ||
ExternalTrigger | 'false', 'true' | 'false' | string | Activate/deactivate hardware triggering. If 'true', the default triggering configuration is:
|
CameraType | --- | Ignored. | ||
Device | '0', '<serial_number>' | '0' | string | Select the desired camera. To get a list of cameras you can call info_framegrabber(..., 'device', ...). '0' selects any camera. i.e. the PixeLINK API will choose a camera. |
Port | --- | Ignored. | ||
LineIn | --- | Ignored. |
Parameters for set_framegrabber_param
Note that most of the following parameters (and also the valid parameter values!) depend on the capabilities of the specific camera in use.
Parameter | Values | Default | Type | Description |
---|---|---|---|---|
'bits_per_channel' | 8, 10, 12 | integer | Number of significant bits per channel. Color cameras currently only support RGB24, i.e. 8 bits per channel. All monochrome cameras support 8 bits and either 10 or 12 bits per pixel. |
|
'brightness' | <brightness> | integer | On cameras that support brightness, adjusts the analog black level offset. | |
'color_temperature' | <Kelvin> | float | Color temperature. Temperature is in degrees Kelvin. 'color_temperature_enable' must be set to 'enable' for this to take effect. Note: For color cameras only. | |
'color_temperature_enable' | 'disable', 'enable' (or 0, 1). | mixed | Used to enable or disable color temperature. Note: For color cameras only. | |
'do_auto_exposure' | --- | Perform an auto-exposure. | ||
'do_white_balance' | --- | Perform white balance. | ||
'exposure' | <exposure>, 'auto', 'one_push', 'off' | mixed | Exposure mode of the camera if a string value is passed. In case of an double value the exposure value is set. Note that changing the exposure may change the frame rate limits. | |
'external_trigger' | 'false', 'true' | string | Status of the external trigger. | |
'flip_horizontal' | 'disable', 'enable' (or 0, 1). | mixed | When supported, flips the image horizontally. (i.e. about the vertical axis). | |
'flip_vertical' | 'disable', 'enable' (or 0, 1). | mixed | When supported, flips the image vertically. (i.e. about the horizontal axis). | |
'frame_rate' | <fps> | integer | Frame rate in frame per second. 'frame_rate_enable' must be set to 'enable' for this to take effect. Note that changing the frame rate may change the exposure limits. | |
'frame_rate_enable' | 'disable', 'enable' (or 0, 1). | mixed | Enables/disables frame rate control. | |
'gain' | <gain> | integer | Analog gain. Gain values are discrete and can be queried via 'gain_values'. | |
'gain_blue' | <gain> | integer | Blue channel of the digital channel gains. Note: For color cameras only. | |
'gain_green' | <gain> | integer | Green channel of the digital channel gains. Note: For color cameras only. | |
'gain_red' | <gain> | integer | Red channel of the digital channel gains. Note: For color cameras only. | |
'gamma' | <gamma> | integer | Gamma value. Gamma must be enabled with 'gamma_enable'. Note: For color cameras only. | |
'gamma_enable' | 'disable', 'enable' (or 0, 1) | mixed |
|
|
'grab_timeout' | <milliseconds> | 5000 | integer | Desired timeout (milliseconds) for aborting a pending grab. If -1 is specified, the timeout is set to INFINITE. |
'horizontal_offset' | <offset> | integer | When supported by the camera, sets the horizontal offset of the image sensor. | |
'horizontal_resolution' | 0, 1, 2 ... <max_width> | integer | When supported by the camera, sets the horizontal resolution of the image sensor.
|
|
'pixel_addressing_mode' | 'average', 'bin', 'decimate', 'resample' | string | When supported by the camera, sets the pixel addressing mode. Modes supported by the camera can be queried by reading 'pixel_addressing_mode_values'. | |
'pixel_addressing_value' | <pixel_addressing> | integer | When supported by the camera, sets the pixel addressing value. Pixel addressing is disabled by setting this to 1. Supported pixel addressing modes can be queried by reading 'pixel_addressing_value_values'. Note that pixel addressing values other than 1 will affect the size of a grabbed image, but not sensor ROI parameters such as 'horizontal_resolution' or 'vertical_offset'. |
|
'saturation' | <saturation> | integer | On color cameras that support saturation, sets the saturation. | |
'trigger_delay' | <delay> | integer | Trigger delay value. See PixeLINK documentation for information on which trigger modes support delay. | |
'trigger_mode' | <mode> | integer | Trigger mode. See the PixeLINK documentation for more information on triggering. | |
'trigger_parameter' | <number> | integer | Trigger parameter needed for various trigger modes. See the PixeLINK documentation for more information on triggering and
which triggering modes support a triggering parameter. Note: Before changing to a mode that uses the parameter, set the triggering parameter before setting the triggering mode. |
|
'trigger_polarity' | 'negative', 'positive' (or 0, 1) | mixed | The trigger polarity and distinguishes whether the rising or falling edge triggers the camera.
|
|
'vertical_offset' | <offset> | integer | Vertical offset of the image sensor. | |
'vertical_resolution' | 0, 1, 2 ... <max_height> | integer | When supported by the camera, sets the vertical resolution of the image sensor.
|
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 |
---|---|---|---|---|---|
'available_param_descriptions' | ['<available_param_descriptions>'] | string | pre-defined | A set of descriptions for each parameter supported by the camera. | |
'available_param_names' | ['<parameters>'] | string | dynamic | The list contains the names of all available parameters. | |
'bits_per_channel' | -1, 8, 10, 12 | -1 | integer | pre-defined | Number of bits per channel of the resulting HALCON image. In case of -1 the current bit depth of the camera is used. By specifying a value greater than 8 the grabbed images are delivered as uint2 images. |
'brightness' | <brightness> | integer | dynamic | On cameras that support brightness, adjusts the analog black level offset. | |
'camera_name' | '<camera_name>' | string | dynamic | Camera name. See the PixeLINK documentation for the camera_name field of the CAMERA_INFO struct. | |
'camera_type' | '<default>' | 'default' | string | pre-defined | The value is not used, so a default value is returned. |
'color_space' | 'gray', 'rgb' | 'default' | string | pre-defined | Desired color space and thus the number of image channels of the resulting HALCON image. |
'color_temperature' | <Kelvin> | float | dynamic | Color temperature. Temperature is in degrees Kelvin. 'color_temperature_enable' must be set to 'enable' for this to take effect. Note: For color cameras only. | |
'color_temperature_enable' | 'disable', 'enable' (or 0, 1). | mixed | dynamic | Used to enable or disable color temperature. Note: For color cameras only. | |
'device' | '<device_id>' | '0' | string | dynamic | Current device ID. |
'exposure' | <exposure>, 'auto', 'one_push', 'off' | mixed | dynamic | Exposure mode of the camera if a string value is passed. In case of an double value the exposure value is set. Note that changing the exposure may change the frame rate limits. | |
'external_trigger' | 'false', 'true' | 'false' | string | pre-defined | Status of the external trigger. |
'field' | '<default>' | 'default' | string | pre-defined | The value is not used, so a default value is returned. |
'firmware_version' | '<firmware_version>' | string | dynamic | Camera firmware version. | |
'flip_horizontal' | 'disable', 'enable' (or 0, 1). | mixed | dynamic | When supported, flips the image horizontally. (i.e. about the vertical axis). | |
'flip_vertical' | 'disable', 'enable' (or 0, 1). | mixed | dynamic | When supported, flips the image vertically. (i.e. about the horizontal axis). | |
'fpga_version' | '<fpga_version>' | string | dynamic | Camera FPGA version. | |
'frame_rate' | <fps> | integer | dynamic | Frame rate in frame per second. 'frame_rate_enable' must be set to 'enable' for this to take effect. Note that changing the frame rate may change the exposure limits. | |
'frame_rate_enable' | 'disable', 'enable' (or 0, 1). | mixed | dynamic | Enables/disables frame rate control. | |
'gain' | <gain> | integer | dynamic | Analog gain. Gain values are discrete and can be queried via 'gain_values'. | |
'gain_blue' | <gain> | integer | dynamic | Blue channel of the digital channel gains. Note: For color cameras only. | |
'gain_green' | <gain> | integer | dynamic | Green channel of the digital channel gains. Note: For color cameras only. | |
'gain_red' | <gain> | integer | dynamic | Red channel of the digital channel gains. Note: For color cameras only. | |
'gamma' | <gamma> | integer | dynamic | Gamma value. Gamma must be enabled with 'gamma_enable'. Note: For color cameras only. | |
'gamma_enable' | 'disable', 'enable' (or 0, 1) | mixed | dynamic |
|
|
'generic' | <default> | 0.0 | float | 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_offset' | <offset> | integer | dynamic | When supported by the camera, sets the horizontal offset of the image sensor. | |
'horizontal_resolution' | 1, 2, 4 | 1 | integer | pre-defined | Current value of horizontal resolution. |
'image_height' | <height> | 0 | integer | pre-defined | Returns 'vertical_resolution' value. |
'image_width' | <width> | 0 | integer | pre-defined | Returns 'horizontal_resolution' value. |
'line_in' | <default> | -1 | integer | pre-defined | The value is not used, so a default value is returned. |
'model_name' | '<model_name>' | string | dynamic | Camera model name. | |
'name' | 'PixeLINK' | string | pre-defined | Name of the HALCON interface. | |
'pixel_addressing_mode' | 'average', 'bin', 'decimate', 'resample' | string | dynamic | When supported by the camera, sets the pixel addressing mode. Modes supported by the camera can be queried by reading 'pixel_addressing_mode_values'. | |
'pixel_addressing_value' | <pixel_addressing> | integer | dynamic | Pixel addressing value. | |
'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 PixeLINK driver. | |
'saturation' | <saturation> | integer | dynamic | On color cameras that support saturation, sets the saturation. | |
'serial_number' | '<serial_number>' | string | dynamic | Camera serial number. | |
'start_column' | <column> | 0 | string | pre-defined | Returns the current start column of the HALCON image. |
'start_row' | <row> | 0 | string | pre-defined | Returns the current start row of the HALCON image. |
'temperature' | <Celsius> | float | dynamic | Sensor temperature, in degrees Celsius. | |
'trigger_delay' | <delay> | integer | dynamic | Trigger delay value. See PixeLINK documentation for information on which trigger modes support delay. | |
'trigger_mode' | <mode> | integer | dynamic | Trigger mode. See the PixeLINK documentation for more information on triggering. | |
'trigger_parameter' | <number> | integer | dynamic | Trigger parameter needed for various trigger modes. See the PixeLINK documentation for more information on triggering and
which triggering modes support a triggering parameter. Note: Before changing to a mode that uses the parameter, set the triggering parameter before setting the triggering mode. |
|
'trigger_polarity' | 'negative', 'positive' (or 0, 1) | mixed | dynamic | The trigger polarity and distinguishes whether the rising or falling edge triggers the camera.
|
|
'vendor_name' | '<vendor_name>' | string | dynamic | Camera vendor name. | |
'vertical_offset' | <offset> | integer | dynamic | Vertical offset of the image sensor. | |
'vertical_resolution' | <resolution> | 1 | integer | pre-defined | Current value of vertical resolution. |
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 not supported, so this operator does nothing.
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
Asynchronous grabbing not supported, so grab_image_async behaves like grab_image.
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:
- pixelink_2cameras.hdev - Shows concurrent grabbing from two connected cameras.
- pixelink.hdev - Benchmark
- pixelink_parameters.hdev - Lists all parameters of a device.
- pixelink_simple.hdev - A simple example to show the usage of the interface.
Release Notes
- Revision 5.1 Addendum (Dec 7, 2015):
- Added USB 3.0 devices.
- The PL-C and PL-D cameras will work with SDK Revision 9.3 or higher.
- Revision 5.1 (Jul 23, 2013):
- Updated to PixeLINK SDK Release v8.7 and Visual Studio 2008 environment.
- Added support for 64-bit Windows.
- Added support for PL-C USB cameras.
- Adapted documentation to reflect new system requirements and limitations.
- Revision 5.0 (May 15, 2012):
- HALCON 11 version of the interface (included in HALCON 11 DVD).
- Revision 4.1 (Aug 20, 2010):
- Fixed bug in implementation of parameter 'trigger_mode_values' to avoid a possible application crash caused by accessing uninitialized memory.
- HALCON 10 version of the interface (included in HALCON 10 DVD).
- Revision 4.0 (Dec 1, 2008):
- HALCON 9.0 version of the interface (included in HALCON 9.0 DVD).