HALCON 9.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: 4.3

System Requirements

• Intel compatible PC with Windows 2000, Windows XP or Windows XP x64.
• Successfully installed pylon SDK (version 2.1).
• 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 hAcqpylonxl.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, width		The desired horizontal image resolution. Use '1' for full resolution, '2' for decimation by factor 2, and '4' for decimation by factor 4. Set the horizontal resolution of the camera sensor, if no decimation is used. Default: 1.
	VerticalResolution		1, 2, 4, height		The desired vertical image resolution. Use '1' for full resolution, '2' for decimation by factor 2, and '4' for decimation by factor 4. Set the vertical resolution of the camera sensor, if no decimation is used. Default: 1.
	ImageWidth		0, width		The width of the desired image part ('0' stands for the complete image). Default: 0.
	ImageHeight		0, height		The height of the desired image part ('0' stands for the complete image). Default: 0.
	StartRow		0, row		The row coordinate of the upper left pixel within the desired image part. Default: 0.
	StartColumn		0, column		The column coordinate of the upper left pixel within the desired image part. Default: 0.
	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		'num_buffers=number'		Optionally the number of used buffers can be specified. Default: 2.
	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:

	'bits_per_channel'		8, 10, 12, 14, 16		Specify the desired bits per channel of the HALCON image. Default: 8.
	'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.
	'image_height'		height		The height of the HALCON image.
	'image_width'		width		The width of the HALCON image.
	'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'.
	'start_column'		column		The upper left pixel of the HALCON image.
	'start_row'		row		The upper left pixel of the HALCON image.
	'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:

• '_access': These parameters provide the access permissions of the corresponding parameter as a string. Possible values are 'ro' (read-only), 'wo' (write-only), and 'rw' (read/write).
• '_category': These parameters provide the category of the corresponding parameter as a string.
• '_description': These parameters provide the tooltip 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'].
• '_visibility': These parameters provide the visibility of the corresponding parameter as a string. Possible values are 'beginner', 'expert', and 'guru'.

	'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.
	'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 4.3 (Feb 12, 2010):
  • Fixed crashes caused by wrong device names.
  • When using an external trigger in continuous grabbing mode, the first call of grab_image or grab_image_async always returned an image even if there was no trigger signal. This bug has been fixed.
• Revision 4.2 (May 25, 2009):
  • Adapted to pylon SDK 2.1.
  • Added additional parameters with postfixes '_access', '_category', and '_visibility' to query access mode, category name, and visibility of a specific parameter.
• Revision 4.1 (Mar 05, 2009):
  • Bugfix in Generic parameter 'num_buffers'.
  • Bugfix regarding mutex and parameter 'do_abort_grab', which could have caused a deadlock. Furthermore, the parameter now also works, if no image was grabbed before.
  • Bugfix in parameter 'volatile' in case of enabling it twice.
  • Adapted set_framegrabber_param to allow also integer values for parameters with float values and vice versa.
• Revision 4.0 (Dec 10, 2008):
  • HALCON 9.0 version of the interface (included in HALCON 9.0 DVD).
  • Support of Windows XP x64.
  • Bugfix in grab_image and grab_image_async for multiple camera configurations. Furthermore, the error message "Wrong color space" now only appears, if there is no valid color space conversion available.
  • Bugfix in grab_image and grab_image_async in case of errors during the image acquisition (not in all cases the buffer was re-queued correctly).
  • Added a mutex to protect the buffer queue during image acquisition in multithread applications.
• Revision 3.7 (Jul 15, 2008):
  • Bugfix in open_framegrabber regarding the device names.
  • Bugfix using multiple devices.
  • Added parameter 'bits_per_channel'.
• Revision 3.6 (May 30, 2008):
  • Bugfix in color transformation.
  • Bugfix in open_framegrabber. Now the device name can also be the full name of the device.
  • Bugfix in close_framegrabber. Now the device is also closed correctly when no image was acquired so far.
  • Bugfix in info_framegrabber. If using multiple Basler cameras, the HDevelop Image Acquisition Assistant now lists all of them.
  • Bugfix regarding GenICam enumeration values. Now only the actually supported values are listed.
  • Added software cropping functionality. Thus, the behavior of the parameters 'image_width', 'image_height', 'start_row', and 'start_column' in open_framegrabber changed. These parameters now are only used for specifying the size and position of the resulting HALCON image and can also be used dynamically via set_framegrabber_param or get_framegrabber_param.
  • Removed parameter 'available_param_types'.
  • Added categories for the generic parameters.
• 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.