HALCON 8.0: Image Acquisition Interface for Basler GigE Vision and IEEE 1394 cameras via pylon library

This page provides the documentation of the HALCON pylon interface. Currently, the Basler pilot, runner and scout GigE Vision and IEEE 1394a/b cameras are supported by this interface. Registered customers can download the latest revision of this interface from the MVTec WWW server.

Revision: 3.5

System Requirements

• Intel compatible PC with Windows 2000/XP/Vista.
• Successfully installed pylon SDK (version 2.0).
• GigE Vision: Successfully installed pylon GigE Vision Streaming Filter or High Performance driver.
  IEEE 1394a/b: Successfully installed pylon 1394 driver.
• HALCON image acquisition interface hAcqpylon.dll or parhAcqpylon.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.
• Please note that you need administrator privileges to access the GigE Transport Layer of the network. So even your application needs these settings to access the camera.
• If you are using a firewall, e.g., Windows XP with Service Pack 2, please make sure that your firewall settings allow to connect to the camera, otherwise the grabbing fails.

Features

• Multiple device support.
• Generic parameter access.
• Synchronous and asynchronous grabbing.
• Cropping of image parts.
• Decimation.
• External trigger.
• Software control of all acquisition parameters directly from the HALCON application.

Limitations

• No LUTs.
• grab_data and grab_data_async not supported.

Description

Parameters for open_framegrabber():

Note that in case of a IEEE 1394 camera, the parameter 'PacketSize' is set to the maximum value during open_framegrabber.

	Name		'pylon'		The name of the HALCON interface.
	HorizontalResolution		1, 2, 4		The desired horizontal image resolution. Use '1' for full resolution, '2' for decimation by factor 2, and '4' for decimation by factor 4. Default: 1.
	VerticalResolution		1, 2, 4		The desired vertical image resolution. Use '1' for full resolution, '2' for decimation by factor 2, and '4' for decimation by factor 4. Default: 1.
	ImageWidth		0, width		The width of the desired image part ('0' stands for the complete image). Default: 0. The image width can also be changed by  set_framegrabber_param via the parameter 'Width'.
	ImageHeight		0, height		The height of the desired image part ('0' stands for the complete image). Default: 0. The image height can also be changed by  set_framegrabber_param via the parameter 'Height'.
	StartRow		0, row		The row coordinate of the upper left pixel within the desired image part. Default: 0. The StartRow can also be changed by  set_framegrabber_param via the parameter 'OffsetY'.
	StartColumn		0, column		The column coordinate of the upper left pixel within the desired image part. Default: 0. The StartColumn can also be changed by  set_framegrabber_param via the parameter 'OffsetX'.
	Field		---		Ignored.
	BitsPerChannel		-1, 8, 10, 12, 16		The number of significant bits per channel. Default: 8.
	ColorSpace		'gray', 'yuv', 'raw', 'rgb'		Specify the desired color space and thus the number of image channels of the resulting HALCON image. Default: 'gray'.
	Generic		---		Ignored.
	ExternalTrigger		'true', 'false'		Enables / disables the external trigger. Default: 'false'. The following parameters are set, if external trigger is enabled: TriggerSource: 'Line1' TriggerSelector: 'AcquisitionStart' TriggerActivation: 'RisingEdge' These are the default values which were only set if you activate the external trigger in open_framegrabber. You can change these values via   set_framegrabber_param. The external trigger can also be activated by  set_framegrabber_param via the parameter 'TriggerMode'.
	CameraType		---		Ignored.
	Device		'DeviceID', 'Number'		The device can be selected via the device ID which you can get by calling 'info_framegrabber(..,info_boards,..)'. Another possibility is the increasing device number, e.g. the first camera is number '0', the second camera is number '1', etc. Default: '0'.
	Port		---		Ignored.
	LineIn		---		Ignored.

Parameters for set_framegrabber_param():

The parameters of all cameras are based on the GenApi, so they can be different for each camera. A call of info_framegrabber('parameters', InfoParameters, AvailableParameters) returns a tuple containing all available parameters of the connected camera.
To read e.g. the current gain of the camera AcqHandle refers to (after calling open_framegrabber), the user can call get_framegrabber_param(AcqHandle, 'GainRaw', Gain)
Apart from that the user can query additional information about the properties. Some might define limits like min, max or step width. These values can be queried as a list by by postfixing the parameters name with '_range' . So, to query the limits of the gain parameter the user can call get_framegrabber_param(AcqHandle, 'GainRaw_range', Gain). This might e.g. result in a list like this: [ 0, 30, 1, 5 ]. The first value indicates the minimum value for this parameter, the second value is the maximum value for this parameter, the third value is the step width and the last value is the current value.
Other parameters like the trigger source can only be set to certain values. To find out which values are valid for a certain parameter the user has to postfix it with '_values'. So to find out which values are allowed for the trigger source parameter the user has to call get_framegrabber_param(AcqHandle, 'TriggerSource_values', TriggerSources). Afterwards the variable TriggerSources will contain a list of strings defining the allowed trigger sources for this device. This list might look like this: [ 'Line1', 'Line2', 'Line3', 'Line4', 'Software' ].
Additionally to the GenApi parameters of the camera the following HALCON parameters are supported:

	'color_space'		'gray', 'raw', 'rgb', 'yuv'		Specify the desired color space of the image. You can also adapt this setting with the generic parameter 'PixelFormat'. Default: 'gray'.
	'do_abort_grab'		---		Abort the current image acquisition.
	'do_unlock_parameters'		---		After grabbing an image the parameters regarding the image size and position are locked. This parameter unlocks them.
	'grab_timeout'		msec		Specify the desired timeout (milliseconds) for aborting a pending grab. Default: 5000.
	'start_async_after_grab_async'		'disable', 'enable'		By default, at the end of grab_image_async a new asynchronous grab command is automatically given to the acquisition device. If the parameter 'start_async_after_grab_async' is set to 'disable' this new grab command is omitted. Default: 'enable'.
	'volatile'		'enable', 'disable'		Grayscale only. In the volatile mode the two image 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'.

Parameters for get_framegrabber_param():

Additional parameters supported by get_framegrabber_param only. Note that all parameters supported by set_framegrabber_param except the ones with prefix 'do_' can also be accessed by get_framegrabber_param. Furthermore, corresponding to the parameters supported by set_framegrabber_param, there may exist additional read-only parameters with the following postfixes:

• '_description': These parameters provide the tooltip of the corresponding parameter as a string.
• '_range': These parameters provide the minimum, maximum, stepwidth, and default values for the corresponding integer or float parameter as a tuple with 4 elements, e.g., get_framegrabber_param(..,'exposure_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'].

	'available_param_descriptions'		descriptions		Returns a list containing additional information about all parameters. The order of the entries is equal to the order of the parameter names returned by 'available_param_names'.
	'available_param_names'		parameters		Returns a list containing the names of all available parameters.
	'available_param_types'		types		Returns a list containing the types of all parameters. The following types are possible: 'I' (integer value) 'F' (float value) 'SE' (string enumeration) The order of the entries is equal to the order of the parameter names returned by 'available_param_names'.
	'image_available'		0, 1		Returns the status of the last asynchronous grab command. The value 1 means that the image is already acquired and thus can be fetched by grab_image_async without delay. Note that this parameter is especially useful in combination with external triggering.
	'revision'		revision		The revision number of the HALCON pylon interface.

Release Notes

• Revision 3.5 (Apr 22, 2008):
  • Adapted to pylon SDK 2.0.
  • Added color transformation functionality, i.e., depending on the parameter ColorType the resulting HALCON image of each grab is converted accordingly.
  • Bugfix in continuous grabbing mode.
• Revision 3.4 (Oct 15, 2007):
  • Bugfix in grab_image_start and grab_image.
• Revision 3.3 (Sep 20, 2007):
  • Bugfix in grab_image and grab_image_async.
  • Bugfix in software trigger function.
  • Bugfix in 'raw' color space.
• Revision 3.2 (Sep 05, 2007):
  • Bugfix in first usage of grab_image_start.
  • Improved buffer handling for external triggering.
• Revision 3.1 (Jul 27, 2007):
  • Adapted to pylon SDK 1.0.
  • Bugfix in grab_image/grab_image_async in case of incomplete images.
  • Bugfix in open_framegrabber regarding external triggering and maximum image size.
  • Removed setting of the parameter 'ExposureTimeRaw' during open_framegrabber.
• Revision 3.0 (May 15, 2007):
  • HALCON 8.0 version of the interface (included in HALCON 8.0 DVD).
• Revision 2.2 (Mar 28, 2007):
  • Added access to the parameters of the TransportLayer and StreamGrabber node map.
  • Added string prefix 'device:' to info_framegrabber(...,'info_boards',...).
  • Added parameter 'start_async_after_grab_async'.
• Revision 2.1 (Feb 21, 2007):
  • Adapted to pylon SDK 0.9.
  • Added support of the scout IEEE 1394a/b cameras.
  • Added support of color images.
  • Added parameters 'color_space', 'color_space_values', and 'volatile_values'.
  • Fixed bug in info_framegrabber and open_framegrabber which led to problems if a device was closed and reopened again.
  • Fixed bug in grab_image(_async) which caused a black image after changing image-specific parameters.
• Revision 2.0 (Nov 03, 2006):
  • First official release.