HALCON 9.0 Image Acquisition Interface for Basler eXcite

This page provides the documentation of the HALCON eXcite image acquisition interface for the eXcite smart camera from Basler Vision Technologies. Registered customers can download the latest revision of this interface from the MVTec WWW server.

Revision: 4.0

Operation modes

There are three ways to use the eXcite smart camera:

• Remote mode with Linux OS.
• Remote mode with Windows OS.
• Local mode with Linux OS (MIPS processor).

Attention using remote mode:

• Before grabbing images remote from the camera make sure that the gxbaslercam service is running on the camera.
• There can occur timeouts (black images), if the network load is too high.
• Many users can connect to the camera, but only one user is able to grab images.
• If you are using Windows XP with Service Pack 2, please make sure that your firewall settings allow to connect to the camera, otherwise the grabbing fails (timeouts).
• All modes: The user (usually excite) accessing the camera either when starting gxbaslercam for remote access or when using the camera locally must have read and write access to the necessary device files /dev/ttycci0, /dev/xcam/xicap0 and /dev/watchdog.

System Requirements

• Basler eXcite software package:
  Linux (local): Successfully installed Linux operating system and camera driver on the eXcite.
  Windows (remote): The eXcite\bin directory and the successfully installed eXcite camera library gttrans.dll must be within your search path %PATH%. If you do not have this library, please contact Basler or the vendor from which you bought the camera.
  Linux (remote): The eXcite\bin directory and the successfully installed eXcite camera library libbaslercam.so (and also libgxcam.so) must be in the search path of your system. If you do not have these libraries, please contact Basler or the vendor from which you bought the camera.
• Linux (local): HALCON image acquisition interface hAcqeXcite.so for Linux. If you have properly installed the interface, the shared objects should reside in lib/mips64-basler-linux2.6 within the HALCON base directory $HALCONROOT you have chosen during the installation of HALCON.
• Windows (remote): HALCON image acquisition interface hAcqeXcite.dll or hAcqeXcitexl.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.
• Linux (remote): HALCON image acquisition interface hAcqeXcite.so or hAcqeXcitexl.so, respectively. If you have properly installed the interface, the shared objects should reside in lib/$HALCONARCH within the HALCON base directory $HALCONROOT you have chosen during the installation of HALCON.

Features

• Synchronous and asynchronous grabbing.
• External trigger.
• Software control of shutter time.
• Software control of gain and brightness.
• Software control of the digital input and output lines.

Limitations

• grab_data and grab_data_async not supported.
• No LUTs.
• YUV 4:2:2 not supported yet.
• Strobe not supported yet.

Description

Parameters for open_framegrabber():

	Name		'eXcite'		The name of the HALCON image acquisition interface.
	HorizontalResolution		---		Ignored.
	VerticalResolution		---		Ignored.
	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		8, 10, 12		Number of bits per image channel. Default: 8.
	ColorSpace		'gray', 'bayer'		Specify the desired color space and thus the number of image channels of the resulting HALCON image. Default: 'gray'.
	Generic		---		Ignored.
	ExternalTrigger		'true', 'false'		Activate/deactivate external triggering. Default: 'false'.
	CameraType		---		Ignored.
	Device		'0', 'ip_address'		Select the camera to connect. '0' selects the first detected camera. With the IP address any available camera in the network can be selected. Default: '0'.
	Port		---		Ignored.
	LineIn		---		Ignored.

Parameters for set_framegrabber_param():

	'brightness'		brightness		Sets the brightness of the camera.
	'digital_output'		[port0  (long), port1  (long), port2  (long), port3  (long)]		Sets the values of the digital output ports. The value could be either 0 or 1.
	'do_abort_grab'		---		Aborts the current grab.
	'external_trigger'		'true', 'false'		Enables/disables the trigger mode. Be aware of the settings your camera supplies.
	'grab_timeout'		100 ... 327680		Specifies the desired timeout (milliseconds passed as an integer) for aborting a pending grab. Default: 500.
	'image_height'		height (long)		Specifies the height of the grabbed image. If the value is not divisible by two, it will be rounded to next valid value.
	'image_width'		width (long)		Specifies the width of the grabbed image. If the value is not divisible by two, it will be rounded to next valid value.
	'shutter'		shutter		Specifies the desired exposure time of the camera. The exposure time is 20 microseconds multiplied with the shutter value.
	'start_async_after_grab_async'		'enable', 'disable'		By default, at the end of grab_image_async a new request for an asynchronous grab command is automatically given to the camera. If the parameter 'start_async_after_grab_async' is set to 'disable' this new grab command is omitted. Default: 'enable'.
	'start_async_after_timeout'		'enable', 'disable'		If this parameter is enabled, the buffer is flushed after a timeout occurred. Otherwise, you get the last image acquired before the timeout.
	'start_column'		column (long)		Specifies the start column of the grabbed image. If the value is not divisible by two, it will be rounded to next valid value. Please note that you can only change the 'start_column' value if you have reduced the image width.
	'start_row'		row (long)		Specifies the start row of the grabbed image. If the value is not divisible by two, it will be rounded to next valid value. Please note that you can only change the 'start_row' value if you have reduced the image height.
	'trigger_mode'		0, 1, 2, 3		Specifies the desired trigger mode. 0 is the 'Programmable Mode', which means that the exposure time is determined by the shutter. 1 is the 'Level Controlled Exposure Mode', which means that the duration of the specified trigger signal determines the exposure time.
	'trigger_signal'		'falling', 'rising'		Specifies the desired type of trigger signal.
	'trigger_source'		0, 1, 2, 3		Sets the physical input ports for the trigger.
	'video_gain'		video gain		Sets the video gain of the camera.
	'volatile'		'enable', 'disable'		Grayscale only. In the volatile mode the image acquisition 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'.

Parameters for get_framegrabber_param():

Additional parameters supported by get_framegrabber_param only. Note that all parameters supported by set_framegrabber_param 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'].

	'digital_input'		[port0  (long), port1  (long), port2  (long), port3  (long)]		Gets the values of the digital input ports.
	'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 eXcite interface.

Release Notes

• Revision 4.0 (Dec 1, 2008):
  • HALCON 9.0 version of the interface (included in HALCON 9.0 DVD).
• Revision 3.2 (Apr 22, 2008):
  • Added read-only parameters with postfix '_description', '_range', and '_values' to enable the easy parameterization via a generic graphical user interface.
• Revision 3.1 (Oct 18, 2007):
  • Bugfix in grab_image after a timeout occurred.
  • Added parameters 'start_async_after_grab_async', 'start_async_after_grab_async_values', 'start_async_after_timeout', and 'start_async_after_timeout_values'.
• Revision 3.0 (May 15, 2007):
  • HALCON 8.0 version of the interface (included in HALCON 8.0 DVD).
• Revision 2.2 (Dec 7, 2006):
  • Fixed bug in grab_image_async in combination with external trigger.
• Revision 2.1 (Jun 6, 2006):
  • Fixed bug in external trigger settings.
  • Fixed bug in buffer handling (old images in grab_image_async).
  • Removed the parameters 'continuous_grabbing' and 'software_trigger'.
  • Changed 'ColorSpace' parameter 'raw' to 'bayer'.
  • Enhanced error handling in remote mode.
  • Added support for 12 bpp cameras.
  • Several small bugfixes.
• Revision 2.0 (Apr 19, 2006):
  • First official release.