LOG OUT
interfaces mvtec

Interface Documentation

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

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:

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:
  • 1: Use full resolution.
  • 2: Use half resolution. The horizontal offset can be set by calling set_framegrabber_param(.., 'horizontal_offset', ..).
    If sensor image cropping is not supported by a camera, the value is ignored.
    Note: The value may be 'rounded' to a width supported by the camera.
VerticalResolution 1, 2, <height> 1 integer Desired vertical resolution of the camera image:
  • 1: Use full resolution.
  • 2: Use half resolution. The vertical offset can be set by calling set_framegrabber_param(.., 'vertical_offset', ..).
    If sensor image cropping is not supported by a camera, the value is ignored.
    Note: The value may be 'rounded' to a height supported by the camera.
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:
  • 'trigger_mode': 0
  • 'trigger_polarity': 'positive'
  • 'trigger_delay': 0
These parameters can be changed via set_framegrabber_param after a successful call to open_framegrabber.
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
  • 0: disables gamma
  • 1: enables gamma
Note: For color cameras only.
'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.
  • 1: use entire width.
  • 2: use half width.
'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.
  • 0: low active
  • 1: high active
'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.
  • 1: use entire height.
  • 2: use half height.

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
  • 0: disables gamma
  • 1: enables gamma
Note: For color cameras only.
'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.
  • 0: low active
  • 1: high active
'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).
Products/MVTec Interfaces