HALCON 9.0: Image Acquisition Interface for Silicon Software boards

This page provides the documentation of the HALCON SiliconSoftware interface for accessing the microEnable III, IV-A, and IV-V boards from Silicon Software GmbH. Registered customers can download the latest revision of this interface from the MVTec WWW server.

Revision: 4.4

System Requirements

• Intel compatible PC with Windows XP/Vista/7 or Windows XP/Vista/7 x64 Edition.
• Successfully installed Silicon Software driver (version 5.1.0 or higher). Make sure the environment variable %SISODIR5% is set correctly to the Silicon Software base directory.
• Visual Studio C++ 2008 Redistributable Runtime Package, particularly msvcp90.dll. If this package is not installed please download and install it from the Microsoft Download Center for Windows x86 or Windows x64. Note: It is not sufficient to copy the missing files!
• Suitable hardware applet, e.g., an acquisition applet, SmartApplet or a specific applet generated by Silicon Software VisualApplets together with the corresponding mcf-file. This configuration file can be easily created via the Silicon Software microDisplay application.
• HALCON image acquisition interface hAcqSiliconSoftware.dll or hAcqSiliconSoftwarexl.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.

Features

• Support of microEnable frame grabber boards from Silicon Software with Camera Link- and GigE- interface.
• Support of acquisition applets with more than one DMA channel.
• Approach of multiple frame grabber boards.
• Support of preprocessing functionality via SmartApplets and VisualApplets.
• Support of Segmentation SmartApplets via grab_data and grab_data_async to get also the preprocessed blob data.
• Support of Binarization SmartApplets via grab_image and grab_image_async to get the gray-value and the binary image.
• Support of coprocessor functionality with microEnable IV-V frame grabber boards.
• Synchronous and asynchronous grabbing.
• External and software trigger.
• Cropping of image parts.
• Software control of the digital input and output lines.

Limitations

• The knee lut functionality not yet supported.

Description

Parameters for open_framegrabber():

	Name	'SiliconSoftware'	The name of the HALCON image acquisition interface.
	HorizontalResolution	1	Ignored (the desired image resolution is set via the microEnable configuration file specified in the CameraType parameter!). Default: 1.
	VerticalResolution	1	Ignored (the desired image resolution is set via the microEnable configuration file specified in the CameraType parameter!). Default: 1.
	ImageWidth	0, width	The width of the desired image part ('0' stands for the maximum image height). This value has to be equal or smaller than the maximum image height. If the value does not fit in the step width, it is rounded to next valid value. Default: 0.
	ImageHeight	0, height	The height of the desired image part ('0' stands for the maximum image height). This value has to be equal or smaller than the maximum image height. If the value does not fit in the step width, it is rounded to next valid value. Default: 0.
	StartRow	row	The row coordinate of the upper left pixel of the desired image part. If the value does not fit in the step width, it is rounded to next valid value. Default: 0.
	StartColumn	column	The column coordinate of the upper left pixel of the desired image part. If the value does not fit in the step width, it is rounded to next valid value. Default: 0.
	Field	---	Ignored.
	BitsPerChannel	---	Ignored (the desired pixel depth will be set accordingly to the parameter settings in the microEnable configuration file).
	ColorSpace	---	Ignored (the desired color space will be set accordingly to the parameter settings in the microEnable configuration file).
	Generic	-1, 'num_buffers=num', 'num_dma_channels=num'	num_buffers With the Generic parameter 'num_buffers' the actual number of image buffers used in the HALCON acquisition interface can be set before the camera is initialized. Note that the parameter must be specified as a string, e.g., 'num_buffers=5'. Note that depending on the image size of the used camera a large number of buffers can exceed the available memory size of your computer. Default: 2. num_dma_channels With the Generic parameter 'num_dma_channels' the user can specify the number of actual used DMA channels supported by the applet (see also the use of DmaToPC or SmartApplets). If an applet uses multiple DMA channels, the parameter 'num_dma_channels' has to match this number, e.g., if a SmartApplet with two output DMA channels is used, the user must set 'num_dma_channels=2'. With the Port parameter value set to 0, the HALCON SiliconSoftware interface will provide a multi-channel image on the microEnable DMA channels 0 and 1 on every call of grab_image or grab_image_async. Default: 1.
	ExternalTrigger	'true', 'false'	If set to 'true', the trigger mode will be set to 'async_trigger', otherwise 'free_run' mode will be active. Default: 'false'.
	CameraType	'mcf file'	Specify the name (including the full path name) of the desired camera configuration file (mcf file). To configure a specific camera setup please use the microDisplay program which is part of microEnable software.
	Device	'0', '1', ...	The number of the frame grabber board (passed as a string!). Default: '0'.
	Port	0, 1, 2, 3	Specify the port the camera is connected to. Corresponds to the internally used DMA channel (0 for Port A, 1 for Port B, ...). Default: 0.
	LineIn	---	Ignored.

Parameters for set_framegrabber_param():

Note that most parameters of this interface are generic, i.e. all implemented HALCON parameters can be queried by calling info_framegrabber(...,'parameters',...). All actually available parameters and also the generic applet parameters can be queried by calling get_framegrabber_param(...,'available_param_names',...).

	'blob_area'		'enable', 'disable'		Controls the grab_data[_async] data tuple. The area represents the number of pixels from a detected blob. If this feature is disabled the information is not present. Note that this functionality is only available in combination with a Segmentation SmartApplet (Blob). Default: 'enable'.
	'blob_bounding_box'		'enable', 'disable'		Controls the grab_data[_async] data tuple. The bounding box is represented by the upper-left row, upper-left column, lower-left row, and lower-left column of each blob. If this feature is disabled the four coordinates are not present. Note that this functionality is only available in combination with a Segmentation SmartApplet (Blob). Default: 'disable'.
	'blob_center_of_gravity'		'enable', 'disable'		Controls the grab_data[_async] data tuple. Returns the coordinate row and coordinate column from the center of gravity of each blob. If this feature is disabled the two coordinates are not present. Note that this functionality is only available in combination with a Segmentation SmartApplet (Blob). Default: 'enable'.
	'blob_contour_length'		'enable', 'disable'		Controls the grab_data[_async] data tuple. The contour length is divided into a orthogonal and diagonal contour length. If this feature is disabled the two contour length values are not present. Note that this functionality is only available in combination with a Segmentation SmartApplet (Blob). Default: 'enable'.
	'blob_region'		'enable', 'disable'		The parameter controls the grab_data[_async] HALCON regions. The region information is derived by the bounding box given by the Segmentation SmartApplet. If this feature is disabled the HALCON regions are not present. Note that this functionality is only available in combination with a Segmentation SmartApplet (Blob). Default: 'enable'.
	'cc0_select'		'exsync', '!exsync', 'exsync2', '!exsync2', 'flash', '!flash', 'clk', 'gnd', 'vcc'		Assign a particular signal to Camera Link's CC0 line.
	'cc1_select'		'exsync', '!exsync', 'exsync2', '!exsync2', 'flash', '!flash', 'clk', 'gnd', 'vcc'		Assign a particular signal to Camera Link's CC1 line.
	'cc2_select'		'exsync', '!exsync', 'exsync2', '!exsync2', 'flash', '!flash', 'clk', 'gnd', 'vcc'		Assign a particular signal to Camera Link's CC2 line.
	'cc3_select'		'exsync', '!exsync', 'exsync2', '!exsync2', 'flash', '!flash', 'clk', 'gnd', 'vcc'		Assign a particular signal to Camera Link's CC3 line.
	'continuous_grabbing'		'enable', 'disable'		Activate or deactivate the continuous grabbing mode. If the continuous mode is enabled, the frame grabber board will grab all the time and the images will queued in the internal given buffers (see parameter 'num_buffers'). Note that in this mode you can acquire images also from line scan cameras without losing any image data. Default: 'disable'.
	'coprocessor'		'enable', 'disable'		Activate or deactivate the coprocessor mode. If the coprocessor mode is active the parameter 'do_process_image' can be used to send an image to the frame grabber. The frame grabber specific applet will process the image immediately. The processed image must be fetched via grab_image_async. During the activation of the coprocessor mode the current image processing will be stopped to adapt the buffer settings accordingly. Please check the Silicon Software documentation to get further information about generating an applet containing the coprocessor functionality. Up to now this functionality is only available with microEnable IV fx1/VD1 frame grabber. Default: 'disable'.
	'current_buffer_index'		0 ... num_buffers-1		Index of the current image buffer, see also parameter 'num_buffers'..
	'digital_output'		0, 1, 2, 3		Specify the combination of the two digital output signals.
	'do_abort_grab'		---		Cancel current grab.
	'do_process_image'		surrogate		Sends a HALCON image surrogate to the frame grabber for processing, see also parameter 'coprocessor'. This surrogate should be generated by calling the HALCON operator obj_to_integer.
	'do_exsync'		'enable', 'disable'		Switch on/off the exsync signal to the camera.
	'do_flash'		'enable', 'disable'		Switch on/off the flash signal to the camera.
	'do_force_trigger'		---		Send a software trigger from the application to the camera. This action parameter is only applicable when the trigger mode is set to 'async_software_trigger'.
	'exposure'		0 ... 1000000		Exposure time in µs. Default: 4000.
	'exposure_signal'		'high_active', 'low_active'		Polarity of the exposure signal. Default: 'low_active'.
	'flash_signal'		'high_active', 'low_active'		Polarity of the flash signal. Default: 'low_active'.
	'frame_rate'		0.5 ... 20000.0		Number of images per second.
	'grab_timeout'		msec		Specify the desired timeout in milliseconds for aborting a pending grab. Only values divisible by 1000 are accepted. In any other case the value will be rounded to the next lower value. The smallest possible timeout value is 2000. Default: 5000.
	'image_height'		height		The height of the desired image part. Note that due to image buffer re-allocation this setting may take some time.
	'image_width'		width		The width of the desired image part. Note that due to image buffer re-allocation this setting may take some time.
	'image_trigger'		'enable', 'disable'		Enable or disable the image trigger.
	'image_trigger_input'		0, 1, 2, 3		The input source, if the image trigger is in external mode.
	'image_trigger_signal'		'falling', 'rising'		The input signal of the image trigger, in case external mode.
	'image_trigger_mode'		'free_run', 'async_trigger', 'async_gated'		The image trigger for line scan cameras generates an so-called Image Gate, which groups all lines to a valid frame, if it is active. Specify the desired image trigger mode: 'free run' means, that the Image Gate is valid all the time. In 'async_trigger' mode the Image Gate is started by an external trigger signal. 'async_gated' means that the Image Gate is as long active as the external trigger source is active. In all modes the Image Gate becomes inactive after reaching an image height of N lines.
	'line_downscale'		1 ... 255		If your external trigger signal is too fast, you can set the value of how often the frequency of the trigger signal has to be divided.
	'line_downscale_phase'		1 ... 255		In additional to the downscale value you can set the phase position. For example, a value of 4 means to turn the phase position about 90°.
	'line_exposure'		0 ... 20000		The line exposure.
	'line_period'		0 ... 4369.05		The line period.
	'line_trigger_delay'		0 ... 2184.517		The delay of the line trigger.
	'line_trigger_input'		0, 1, 2, 3		The input source of the line trigger.
	'line_trigger_signal'		'falling', 'rising'		The polarity of the line trigger signal.
	'line_trigger_mode'		'grabber_controlled', 'async_trigger', 'grabber_controlled_gated'		Specify the line trigger mode: 'grabber_controlled' means that a periodical signal is created, which defines the line frequency. In 'async_trigger' mode the signal is created by an external trigger. 'grabber_controlled_gated' is similar to the 'grabber_controlled' mode, except that it is only active, if the Image Gate is active.
	'port'		0, 1		Switch to the camera with the specified number (0 for Port A, 1 for Port B).
	'shaft_encoder'		'enable', 'disable'		Switch the shaft encoder on/off. By enabling it the encoder compensation is reset.
	'shaft_encoder_input'		0, 1, 2, 3		Selects the input signal for source B of the shaft encoder.
	'shaft_encoder_leading_source'		0, 1, 2, 3		Determines the leading signal (direction) of the shaft encoder filter.
	'start_async_after_grab_async'		'enable', 'disable'		By default, at the end of grab_image_async a new asynchronous grab command is automatically given to the frame grabber board. If the parameter 'start_async_after_grab_async' is set to 'disable' this new grab command is omitted. This might be useful especially for switching between several connected cameras. Default: 'enable'.
	'start_column'		column		The column coordinate of the upper left pixel of the desired image part.
	'start_row'		row		The row coordinate of the upper left pixel of the desired image part.
	'strobe_delay'		usec		Strobe pulse delay in µs. Default: 0.
	'trigger_input'		0, 1, 2, 3		Specify the desired channel of the trigger input signal.
	'trigger_mode'		'free_run', 'grabber_controlled', 'async_trigger', 'async_software_trigger'		Specify the desired trigger mode: 'free_run' means that no signals are sent to the camera. In 'grabber_controlled' mode the frame grabber sends a signal to the camera in order to control the image acquisition. In 'async_trigger' mode the image acquisition is forced by an external trigger signal, and 'async_software_trigger' means that the image acquisition is performed by software via the action parameter 'do_force_trigger'.
	'trigger_signal'		'falling', 'rising'		Polarity of the trigger signal. Default: 'falling'.
	'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 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'].

	'applet_type'		type (string)		Returns the type of the used applet if this parameter is actually supported by the used applet.
	'available_param_names'		[names] ([string])		Returns a tuple containing the names of all available parameters. In contrast to this, the call of 'info_framegrabber(...'parameters',...)' returns only the static list of parameters, without the additional applet-specific parameters.
	'board_type'		type (string)		Returns the actual board type.
	'camera_status'		status (long)		Return camera status on the used port: If the return value is 1 an active camera on the specified port is found, otherwise the return value is 0.
	'digital_input'		digin (long)		Read the current status of the digital input lines.
	'image_available'		number (long)		Returns true if an image is available. The parameter is only supported if the parameter 'continuous_grabbing' is set to 'enable'.
	'image_tag'		number (long)		Returns the image tag of the most recently grabbed image.
	'internal_device_pointer'		pointer (long)		Returns the pointer to the device which enables direct device access. Use on your own risk!
	'revision'		revision  (string)		The revision number of the HALCON SiliconSoftware interface.
	'num_buffers'		num (long)		Gets the number of internally used image buffers.
	'num_dma_channels'		num (long)		Gets the number of internally used DMA channels.
	'serial_number'		serial (string)		Returns the serial number of the board.
	'timestamp'		time (long)		Gets the timestamp (32bit) from the previously grabbed image in microseconds. If 'continuous_grabbing' is enabled, the parameter returns always the most recent timestamp.

Parameterization of GigE Vision Cameras

The generic parameters of a GigE Vision camera can also be handled via the HALCON operators get_framegrabber_param and set_framegrabber_param. In this case the user has to add the prefix 'gbe:' to the parameter name, e.g., use set_framegrabber_param(hAcqHandle,'gbe:Gain',42) to set the camera paramter "Gain" to the value 42 or get_framegrabber_param(hAcqHandle,'gbe:Gain',RetVal) to query the current value.

To execute a write-only GigE Vision command parameter via the the operator set_framegrabber_param, the user has to add the prefix 'gbex:' to the parameter name, e.g., use set_framegrabber_param(hAcqHandle,'gbex:TriggerSoftware',-1) to send a software trigger to a GigE Vision camera. The value of the parameter will be ignored.

Note that the list of available camera parameters can not be queried in advance, e.g., by calling get_framegrabber_param('available_param_names') or info_framegrabber('SiliconSoftware','parameters',Val,Info). To list all actually available camera parameters you can use the Silicon Software GigE Explorer application.

Support of Segmentation SmartApplet Family

With the Segmentation SmartApplets Family, the user has the possibility to get preprocessed blob information by calling grab_data or grab_data_async. A Segmentation SmartApplet will find blobs which are based on a user specific parameterisation. The specific settings can be adjusted in the the configuration file or by setting the generic Segmentation SmartApplets parameter via set_framegrabber_param. The grab_data[async] operator returns the following information via the image, region and data parameters:

• The grabbed image from DMA channel 0.
• HALCON regions which are based on the bounding boxes of the blobs which are delivered by the Segmentation SmartApplets.
• Special data about each blob. The provided information about each blob will be delivered successively by one HALCON Tuple. Each blob provides the following information:
  • Center of gravity (cogx,cogy)
  • Contour length of the blob (conto,contd)
  • Area size of the blob (area)
  • Bounding box (bbx0,bby0,bbx1,bby1).

Support of Binarization SmartApplet Family

With the Binarization SmartApplets family, the HALCON SiliconSoftware interface will deliver also a binary image which is calculated by the FPGA. With the Port parameter value set to 0, the interface will provide for each call of grab_image or grab_image_async a multi-channel image corresponding to the microEnable DMA channels 0 and 1. The first channel contains the standard image data. The second channel provides the calculated binary image. The specific settings (e.g., the threshold) ca be adjusted in the configuration file or by setting the generic Binarization SmartApplets parameters via set_framegrabber_param.

Release Notes

• Revision 4.4 (Feb 10, 2012):
  • Fixed bug in the continuous grabbing mode. If a timeout occurred the internal used acquisition engine was erroneously restarted and the previously queued images were discarded.
  • Added parameter 'image_available'.
  • Improved error handling in open_framegrabber.
• Revision 4.3 (May 30, 2011):
  • Improved continuous grabbing mode: Now, this mode supports to queue an arbitrary number of trigger signals (corresponding to the parameter 'num_buffers').
  • Added parameter 'image_tag'.
  • Added support of GigE Vision command parameters.
• Revision 4.2 (Mar 15, 2011):
  • Implemented grab_data and grab_data_async to enable the use of Segmentation SmartApplets (Blob).
  • Added parameters 'blob_contour_length', 'blob_center_of_gravity', 'blob_area', 'blob_bounding_box', and 'blob_region' to control the Data and Region output parameters of grab_data and grab_data_async.
  • Added parameter 'applet_type'.
  • Fixed bug in 'continuous_grabbing'.
• Revision 4.1 (Sep 8, 2010):
  • Adapted to Silicon Software SDK 5.1.
  • Support of Silicon Software GigE Vision boards including generic parameterization.
  • Added functionality to use the SmartApplets or other applets with multiple DMA channels.
  • Updated error handling in coprocessor mode, i.e., in this mode grab_image and grab_image_start will return the error H_ERR_FNS.
  • Adapted the board names to new Silicon Software product names.
• Revision 4.0 (Mar 16, 2010):
  • First official release.