interfaces mvtec

Dokumentation

Image Acquisition Interface for Silicon Software Boards

Interface: SiliconSoftware
Revision: 6.6
Date: 2016-09-26
HALCON Version: 12.0

General

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

System Requirements

  • Intel compatible PC with Windows Vista/7/8, Windows Vista/7/8 x64, also WoW64 (using 32-bit HALCON on 64-bit Windows).
  • Successfully installed Silicon Software driver (version 5.4 or higher). Make sure the environment variable %SISODIR5% is set correctly to the Silicon Software base directory.
  • 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, CoaXPress, and GigE interface.
  • Support of acquisition applets with more than one DMA channel.
  • Approach of multiple frame grabber boards.
  • Support of pre-processing functionality via SmartApplets and VisualApplets.
  • Support of Segmentation SmartApplets via grab_data and grab_data_async to get also the pre-processed blob data.
  • Support of Binarization SmartApplets via grab_image and grab_image_async to get the gray-value and the binary image.
  • Support of 3D Triangulation SmartApplets via grab_data and grab_data_async to get a disparity image that is calculated on the base of a laser line.
  • Support of coprocessor functionality with microEnable IV-V and V-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

  • Simultaneous independent grabbing of a single camera source that is divided into a second DMA channel is not supported. In this case the internal read out of further channels will be done sequentially.

Parameters for info_framegrabber

Parameter Value List Type Kind Description
'bits_per_channel' [] Ignored.
'camera_type' ['CAMFILE:', 'mcf', 'C:\\'] string pre-defined Syntax for the camera configuration file.
'color_space' [] Ignored.
'defaults' [1, 1, 0, 0, 0, 0, 'interlaced', 8, 'gray', -1.0, 'false', '', '0', 0, 0] mixed pre-defined Default values for open_framegrabber.
'device' ['<device_id>'] string dynamic A list of available devices.
'external_trigger' ['false', 'true'] string pre-defined Values for the external trigger.
'field' [] Unused.
'general' [] string pre-defined Information about the HALCON SiliconSoftware interface.
'generic' ['', 'discovery_timeout=<ms>', 'genicam_xml_file=<filepath>', 'num_buffers=<num>', 'num_dma_channels=<num>'] string pre-defined Value list for the Generic parameter.
'horizontal_resolution' 1 integer pre-defined Value list for horizontal resolution.
'image_height' [] Unsupported query.
'image_width' [] Unsupported query.
'info_boards' ['device:<device_id> board_type:<board_type>'] string dynamic A list 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' [0, 1, 2, 3] integer pre-defined Pre-defined list of possible port numbers.
'revision' '<revision>' string pre-defined Revision number of the SiliconSoftware interface.
'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 'SiliconSoftware' string Name of the HALCON interface.
HorizontalResolution 1 1 integer Ignored (the desired image resolution is set via the microEnable configuration file specified in the CameraType parameter!).
VerticalResolution 1 1 integer Ignored (the desired image resolution is set via the microEnable configuration file specified in the CameraType parameter!).
ImageWidth 0, <width> 0 integer 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.
ImageHeight 0, <height> 0 integer 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.
StartRow <row> 0 integer Row coordinate of the upper left pixel within the desired image part.
StartColumn <column> 0 integer Column coordinate of the upper left pixel within the desired image part.
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 '', ['discovery_timeout=<ms>', 'genicam_xml_file=<filepath>', 'num_buffers=<num>', 'num_dma_channels=<num>'], -1 -1 mixed
  • discovery_timeout
    With the Generic parameter 'discovery_timeout' a time in ms can be specified to detect the devices connected to a Silicon Software GigE Vision board. Default: 2000.
  • genicam_xml_file
    With the Generic parameter 'genicam_xml_file' a CoaXPress xml file with the needed configuration could be passed. Please use the GenICam Explorer tool provided by Silicon Software to generate a proper xml file.
  • 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 'false', 'true' 'false' string If set to 'true', the trigger mode will be set to 'async_trigger', otherwise the configuration of the camera file will be used.
CameraType '<mcf_file>' '' string 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. In case of a board with multiple ports, each port will obtain his own acquisition handle by calling open_framegrabber(). Please note, that the first open_framegrabber() call to a device will initialise all provided ports. Further passed configuration files to an already initialized board will be ignored.
Device '<device_id>' string Opens the the device with the specific device id.
Port 0, 1, 2, 3 0 integer Specify the port the camera is connected to. Corresponds to the internally used DMA channel (0 for Port A, 1 for Port B, ...)
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', ...).
Parameter Values Default Type Description
'acquisition_mode' 'select_next_image', 'select_act_image', 'select_new_image' 'select_next_image' string
  • select_next_image
    The 'select_next_image' acquisition mode is the 'default' acquisition mode. The buffer index will be incremented to acquire all existing buffers. If a buffer is grabbed, the buffer will be automatically removed from the queue. If all buffers are filled the next grabbed image will not be buffered and will be lost. In this case, the 'num_block_lost_images' parameter will be increased. Every query will return the oldest image (FIFO).
  • select_new_image
    With 'select_new_image' the last grabbed image will be returned. In case a new buffer is being filled in this moment, the grab will wait until it is completely filled and then it will return this buffer (LIFO) .
  • select_act_image
    In contrast the 'select_act_image' does not take care about unfilled buffers, and will always return the last filled buffer. In both cases, a new acquired image will overwrite the last buffer (LIFO).
'blob_area' 'disable', 'enable' 'enable' string Controls the grab_data/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).
'blob_bounding_box' 'disable', 'enable' 'disable' string Controls the grab_data/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).
'blob_center_of_gravity' 'disable', 'enable' 'enable' string Controls the grab_data/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).
'blob_contour_length' 'disable', 'enable' 'enable' string Controls the grab_data/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).
'blob_region' 'disable', 'enable' 'enable' string Controls the grab_data/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).
'cc0_select' 'clk', 'exsync', '!exsync', 'exsync2', '!exsync2', 'flash', '!flash', 'gnd', 'vcc' string Assign a particular signal to Camera Link's CC0 line.
'cc1_select' 'clk', 'exsync', '!exsync', 'exsync2', '!exsync2', 'flash', '!flash', 'gnd', 'vcc' string Assign a particular signal to Camera Link's CC1 line.
'cc2_select' 'clk', 'exsync', '!exsync', 'exsync2', '!exsync2', 'flash', '!flash', 'gnd', 'vcc' string Assign a particular signal to Camera Link's CC2 line.
'cc3_select' 'clk', 'exsync', '!exsync', 'exsync2', '!exsync2', 'flash', '!flash', 'gnd', 'vcc' string Assign a particular signal to Camera Link's CC3 line.
'continuous_grabbing' 'disable', 'enable' 'disable' string 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.
'coprocessor' 'disable', 'enable' 'disable' string 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.
'digital_output' 0, 1, 2, 3 integer Combination of the two digital output signals.
'do_abort_grab' --- Cancel current grab.
'do_exsync' 'disable', 'enable' string Switch on/off the exsync signal to the camera.
'do_flash' 'disable', 'enable' string 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'.
'do_process_image' <surrogate> integer Sends a HALCON image surrogate to the frame grabber for processing, see also parameter 'coprocessor'. This surrogate should be generated by calling the operator obj_to_integer.
'exposure' 0 ... 1000000 4000 integer Exposure time in microseconds.
'exposure_signal' 'high_active', 'low_active' 'low_active' string Polarity of the exposure signal.
'flash_signal' 'high_active', 'low_active' 'low_active' string Polarity of the flash signal.
'frame_rate' 0.5 ... 20000.0 float Number of images per second.
'grab_timeout' <milliseconds> 5000 integer 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. If -1 is specified, the timeout is set to to the maximum value of 2^32-1 milli seconds. Default: 5000.
'image_height' <height> integer Height of the desired image part. Note that due to image buffer re-allocation this setting may take some time.
'image_trigger' 'disable', 'enable' string Enable or disable the image trigger.
'image_trigger_input' 0, 1, 2, 3 integer Input source, if the image trigger is in external mode.
'image_trigger_mode' 'async_gated', 'async_trigger', 'free_run' string Image trigger for line scan cameras generates a so-called Image Gate, which groups all lines to a valid frame, if it is active. Specify the desired image trigger mode:
  • 'async_gated': Image Gate is as long active as the external trigger source is active.
  • 'async_trigger': Image Gate is started by an external trigger signal.
  • 'free run': Image Gate is valid all the time.
In all modes the Image Gate becomes inactive after reaching an image height of N lines.
'image_trigger_signal' 'falling', 'rising' string Input signal of the image trigger, in case external mode.
'image_width' <width> integer Width of the desired image part. Note that due to image buffer re-allocation this setting may take some time.
'line_downscale' 1 ... 255 integer 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 integer 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 integer Line exposure.
'line_period' 0 ... 4369.05 float Line period.
'line_trigger_delay' 0 ... 2184.517 float Delay of the line trigger.
'line_trigger_input' 0, 1, 2, 3 integer Input source of the line trigger.
'line_trigger_mode' 'grabber_controlled', 'async_trigger', 'grabber_controlled_gated' string 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.
'line_trigger_signal' 'falling', 'rising' string Polarity of the line trigger signal.
'multi_roi_module_name' <string> string Specifies the base name of the RoI module. This functionality is only supported if a RoI module from VisualApplets is used.
'multi_roi_num' 1 ... <num> integer Specifies the number of RoIs to request. This functionality is only supported if a RoI module from VisualApplets is used.
'multi_roi_xlength' 1 ... <image_width> integer Specifies the xlength (width) for each RoI. In case of multiple RoIs, the parameter values are specified as tuple. This functionality is only supported if a RoI module from VisualApplets is used.
'multi_roi_xoffset' 1 ... <image_width> integer Specifies the xoffset (start column) for each RoI. In case of multiple RoIs, the parameter values are specified as tuple. This functionality is only supported if a RoI module from VisualApplets is used.
'multi_roi_ylength' 1 ... <image_height> integer Specifies the ylength (height) for each RoI. In case of multiple RoIs, the parameter values are specified as tuple. This functionality is only supported if a RoI module from VisualApplets is used.
'multi_roi_yoffset' 1 ... <image_heigth> integer Specifies the yoffset (start row) for each RoI In case of multiple RoIs, the parameter values are specified as tuple. This functionality is only supported if a RoI module from VisualApplets is used.
'num_field_parameter' 1 ... <num> integer Some generic applet parameter values are provided as parameter fields. To readout the parameter fields the number of parameter values has to set in advance since querying this information internally is currently not supported by the Silicon Software SDK. The number of field parameters can be determined by querying the generic parameter which contains the number of field parameters. It is also sufficient to remember the number of parameters if the values were set before. Please note that in case of a erroneously set number, e.g., a to height value, a misleading result will be returned.
'num_scans' 1 ... <num> integer Controls the number of scans to define the height of the disparity image. This parameter is only needed by the 3D Triangulation SmartApplets in combination with the operators grab_data and grab_data_async. In any other case this parameter is ignored. Per default the 'num_scans' parameter is 1. In this case only one disparity image with one disparity line and one camera image will be created. Please note that the 'num_scans' parameter affects the number of internal grabbed images. In case of a slow camera a high number of scans needs time to achieve the images. See also the section "Support of 3D Triangulation SmartApplet Family" below.
'port' 0, 1 integer Switch to the camera with the specified number (0 for Port A, 1 for Port B).
'shaft_encoder' 'disable', 'enable' string Switch the shaft encoder on/off. By enabling it the encoder compensation is reset.
'shaft_encoder_input' 0, 1, 2, 3 integer Selects the input signal for source B of the shaft encoder.
'shaft_encoder_leading_source' 0, 1, 2, 3 integer Determines the leading signal (direction) of the shaft encoder filter.
'start_async_after_grab_async' 'disable', 'enable' 'enable' string By default a new asynchronous grab command is automatically given to the acquisition device at the end of grab_image_async. If the parameter 'start_async_after_grab_async' is set to 'disable', this new grab command is omitted.
'start_column' <column> integer Column coordinate of the upper left pixel within the desired image part.
'start_row' <row> integer Row coordinate of the upper left pixel within the desired image part.
'strobe_delay' <microseconds> 0 integer Strobe pulse delay in microseconds.
'trigger_input' 0, 1, 2, 3 integer Channel of the trigger input signal.
'trigger_mode' 'async_software_trigger', 'async_trigger', 'free_run', 'grabber_controlled' string Specify the desired trigger mode:
  • 'async_software_trigger': the image acquisition is performed by software via the action parameter 'do_force_trigger'.
  • 'async_trigger': the image acquisition is forced by an external trigger signal.
  • 'free_run': no signals are sent to the camera.
  • 'grabber_controlled': the frame grabber sends a signal to the camera in order to control the image acquisition.
'trigger_signal' 'falling', 'rising' 'falling' string Polarity of the trigger signal.
'volatile' 'disable', 'enable' 'disable' string Grayscale only. In the volatile mode the two 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!

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].
  • '_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
'acquisition_mode' 'select_next_image', 'select_act_image', 'select_new_image' 'select_next_image' string pre-defined
  • select_next_image
    The 'select_next_image' acquisition mode is the 'default' acquisition mode. The buffer index will be incremented to acquire all existing buffers. If a buffer is grabbed, the buffer will be automatically removed from the queue. If all buffers are filled the next grabbed image will not be buffered and will be lost. In this case, the 'num_block_lost_images' parameter will be increased. Every query will return the oldest image (FIFO).
  • select_new_image
    With 'select_new_image' the last grabbed image will be returned. In case a new buffer is being filled in this moment, the grab will wait until it is completely filled and then it will return this buffer (LIFO) .
  • select_act_image
    In contrast the 'select_act_image' does not take care about unfilled buffers, and will always return the last filled buffer. In both cases, a new acquired image will overwrite the last buffer (LIFO).
'applet_type' '<type>' string dynamic Type of the used applet if this parameter is actually supported by the used applet.
'available_param_names' ['<names>'] string dynamic A tuple containing the names of all available parameters. In contrast to this, the call of info_framegrabber(...'parameters', ...)' returns only the pre-defined list of parameters, without the additional applet-specific parameters.
'bits_per_channel' <default> 8 integer pre-defined The value is not used, so a default value is returned.
'blob_area' 'disable', 'enable' 'enable' string pre-defined Controls the grab_data/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).
'blob_bounding_box' 'disable', 'enable' 'disable' string pre-defined Controls the grab_data/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).
'blob_center_of_gravity' 'disable', 'enable' 'enable' string pre-defined Controls the grab_data/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).
'blob_contour_length' 'disable', 'enable' 'enable' string pre-defined Controls the grab_data/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).
'blob_region' 'disable', 'enable' 'enable' string pre-defined Controls the grab_data/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).
'board_type' '<type>' string dynamic Actual board type.
'camera_status' <status> integer dynamic 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.
'camera_type' '<mcf_file>' '<mcf_file>' string pre-defined Current camera type.
'cc0_select' 'clk', 'exsync', '!exsync', 'exsync2', '!exsync2', 'flash', '!flash', 'gnd', 'vcc' string dynamic Assign a particular signal to Camera Link's CC0 line.
'cc1_select' 'clk', 'exsync', '!exsync', 'exsync2', '!exsync2', 'flash', '!flash', 'gnd', 'vcc' string dynamic Assign a particular signal to Camera Link's CC1 line.
'cc2_select' 'clk', 'exsync', '!exsync', 'exsync2', '!exsync2', 'flash', '!flash', 'gnd', 'vcc' string dynamic Assign a particular signal to Camera Link's CC2 line.
'cc3_select' 'clk', 'exsync', '!exsync', 'exsync2', '!exsync2', 'flash', '!flash', 'gnd', 'vcc' string dynamic Assign a particular signal to Camera Link's CC3 line.
'color_space' '<color_space>' 'gray' string pre-defined The value is not used, so a default value is returned.
'continuous_grabbing' 'disable', 'enable' 'disable' string pre-defined 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.
'coprocessor' 'disable', 'enable' 'disable' string pre-defined 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.
'device' '<device_id>' string dynamic Returns the device id of the current device.
'digital_input' <digin> integer dynamic Read the current status of the digital input lines.
'digital_output' 0, 1, 2, 3 integer dynamic Combination of the two digital output signals.
'exposure' <microseconds> 4000 integer dynamic Exposure time in microseconds.
'exposure_signal' 'high_active', 'low_active' 'low_active' string pre-defined Polarity of the exposure signal.
'external_trigger' 'false', 'true' 'false' string pre-defined Status of the external trigger.
'field' '<default>' 'interlaced' string pre-defined The value is not used, so a default value is returned.
'flash_signal' 'high_active', 'low_active' 'low_active' string pre-defined Polarity of the flash signal.
'frame_rate' 0.5 ... 20000.0 float dynamic Number of images per second.
'generic' '', ['discovery_timeout=<ms>', 'genicam_xml_file=<filepath>', 'num_buffers=<num>', 'num_dma_channels=<num>'], -1 -1 mixed pre-defined Values of the Generic parameter.
'grab_timeout' <milliseconds> 5000 integer pre-defined Current grab timeout in milliseconds.
'horizontal_resolution' <resolution> 1 integer pre-defined Current value of horizontal resolution.
'image_available' 0, 1 integer dynamic 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.
'image_height' <height> 0 integer pre-defined Height of the desired image part ('0' stands for the complete image).
'image_tag' <number> integer dynamic Image tag of the most recently grabbed image.
'image_trigger' 'disable', 'enable' string dynamic Enable or disable the image trigger.
'image_trigger_input' 0, 1, 2, 3 integer dynamic Input source, if the image trigger is in external mode.
'image_trigger_mode' 'async_gated', 'async_trigger', 'free_run' string dynamic Image trigger mode.
'image_trigger_signal' 'falling', 'rising' string dynamic Input signal of the image trigger, in case external mode.
'image_width' <width> 0 integer pre-defined Width of the desired image part ('0' stands for the complete image).
'internal_device_pointer' <pointer> integer dynamic Pointer to the device which enables direct device access. Use at your own risk!
'line_downscale' 1 ... 255 integer dynamic 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 integer dynamic 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 integer dynamic Line exposure.
'line_in' <default> 0 integer pre-defined The value is not used, so a default value is returned.
'line_period' 0 ... 4369.05 float dynamic Line period.
'line_trigger_delay' 0 ... 2184.517 float dynamic Delay of the line trigger.
'line_trigger_input' 0, 1, 2, 3 integer dynamic Input source of the line trigger.
'line_trigger_mode' 'grabber_controlled', 'async_trigger', 'grabber_controlled_gated' string dynamic 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.
'line_trigger_signal' 'falling', 'rising' string dynamic Polarity of the line trigger signal.
'multi_roi_module_name' <string> string dynamic Specifies the base name of the RoI module. This functionality is only supported if a RoI module from VisualApplets is used.
'multi_roi_num' 1 ... <num> integer dynamic Specifies the number of RoIs to request. This functionality is only supported if a RoI module from VisualApplets is used.
'multi_roi_xlength' 1 ... <image_width> integer dynamic Specifies the xlength (width) for each RoI. In case of multiple RoIs, the parameter values are specified as tuple. This functionality is only supported if a RoI module from VisualApplets is used.
'multi_roi_xoffset' 1 ... <image_width> integer dynamic Specifies the xoffset (start column) for each RoI. In case of multiple RoIs, the parameter values are specified as tuple. This functionality is only supported if a RoI module from VisualApplets is used.
'multi_roi_ylength' 1 ... <image_height> integer dynamic Specifies the ylength (height) for each RoI. In case of multiple RoIs, the parameter values are specified as tuple. This functionality is only supported if a RoI module from VisualApplets is used.
'multi_roi_yoffset' 1 ... <image_heigth> integer dynamic Specifies the yoffset (start row) for each RoI In case of multiple RoIs, the parameter values are specified as tuple. This functionality is only supported if a RoI module from VisualApplets is used.
'name' 'SiliconSoftware' string pre-defined Name of the HALCON interface.
'num_block_lost_images' <number> integer dynamic Number of all images, which are lost by blocking of the internal buffer. Only useful with continuous grabbing.
'num_blocked_images' <number> integer dynamic Number of blocked images. Only useful with continuous grabbing.
'num_buffers' <number> 2 integer pre-defined Number of buffers used for the image acquisition.
'num_dma_channels' <number> integer dynamic Number of internally used DMA channels.
'num_field_parameter' 1 ... <num> integer dynamic Some generic applet parameter values are provided as parameter fields. To readout the parameter fields the number of parameter values has to set in advance since querying this information internally is currently not supported by the Silicon Software SDK. The number of field parameters can be determined by querying the generic parameter which contains the number of field parameters. It is also sufficient to remember the number of parameters if the values were set before. Please note that in case of a erroneously set number, e.g., a to height value, a misleading result will be returned.
'num_grabbed_images' <number> integer dynamic Number of all acquired images. Only useful with continuous grabbing.
'num_images_in_progress' <number> integer dynamic Number of images which haven't been received, yet. It's the Number of buffers in the queue available to receive with grab_data_async or grab_image_asnyc. This parameter is in particular useful in case that continuous grabbing is enabled. In this case a real queuing is possible and the buffer queue could be set to a value higher than two. See the parameter 'num_buffers'.
'num_last_image' <number> integer dynamic Number of the last grabbed image. The num_last_image parameter always iterates between 1 and the maximum number of buffers. Before grabbing the first image, the value is 0.
'num_next_image' <number> integer dynamic Number of next image after last grabbed image. Only useful with continuous grabbing.
'num_scans' 1 ... <num> integer dynamic Controls the number of scans to define the height of the disparity image. This parameter is only needed by the 3D Triangulation SmartApplets in combination with the operators grab_data and grab_data_async. In any other case this parameter is ignored. Per default the 'num_scans' parameter is 1. In this case only one disparity image with one disparity line and one camera image will be created. Please note that the 'num_scans' parameter affects the number of internal grabbed images. In case of a slow camera a high number of scans needs time to achieve the images. See also the section "Support of 3D Triangulation SmartApplet Family" below.
'port' 0, 1, 2, 3 0 integer pre-defined Port number.
'revision' '<revision>' string pre-defined Revision number of the SiliconSoftware interface.
'serial_number' '<serial>' string dynamic Serial number of the board.
'shaft_encoder' 'disable', 'enable' string dynamic Switch the shaft encoder on/off. By enabling it the encoder compensation is reset.
'shaft_encoder_input' 0, 1, 2, 3 integer dynamic Selects the input signal for source B of the shaft encoder.
'shaft_encoder_leading_source' 0, 1, 2, 3 integer dynamic Determines the leading signal (direction) of the shaft encoder filter.
'start_async_after_grab_async' 'disable', 'enable' 'enable' string pre-defined Status of 'start_async_after_grab_async'.
'start_column' <column> 0 integer pre-defined 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.
'start_row' <row> 0 integer pre-defined 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.
'strobe_delay' <microseconds> 0 integer dynamic Strobe pulse delay in microseconds.
'timestamp' <microseconds> integer dynamic Gets the timestamp (32bit) from the previously grabbed image in microseconds. If 'continuous_grabbing' is enabled, the parameter returns always the most recent timestamp.
'trigger_input' 0, 1, 2, 3 integer dynamic Channel of the trigger input signal.
'trigger_mode' 'async_software_trigger', 'async_trigger', 'free_run', 'grabber_controlled' string dynamic Specify the desired trigger mode:
  • 'async_software_trigger': the image acquisition is performed by software via the action parameter 'do_force_trigger'.
  • 'async_trigger': the image acquisition is forced by an external trigger signal.
  • 'free_run': no signals are sent to the camera.
  • 'grabber_controlled': the frame grabber sends a signal to the camera in order to control the image acquisition.
'trigger_signal' 'falling', 'rising' 'falling' string pre-defined Polarity of the trigger signal.
'vertical_resolution' <resolution> 1 integer pre-defined Current value of vertical resolution.
'volatile' 'disable', 'enable' 'disable' string pre-defined Grayscale only. In the volatile mode the two 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!

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

Starts a new asynchronous grab. See also grab_image_start.

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

grab_image_async returns an image and starts the next asynchronous grab. See also grab_image_async. 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_data

The behavior of the operator depends on the used SmartApplets family. The operator is needed to work with the Segmentation and Triangulation SmartApplets family. Please see the section "Support of Segmentation SmartApplets Family" or "Support of Binarization SmartApplets Family" to get further information.

Operator grab_data_async

Same return values as grab_data, but here an asynchronous grab is started.

Operator close_framegrabber

This operator closes the device. See also close_framegrabber.

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(..., 'gbe:Gain', 42) to set the camera parameter "Gain" to the value 42 or get_framegrabber_param(..., 'gbe:Gain', ...) to query the current value.

To execute a write-only GigE Vision command parameter via the operator set_framegrabber_param, the user has to add the prefix 'gbex:' to the parameter name, e.g., use set_framegrabber_param(..., '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(..., 'parameters', ...). To list all actually available camera parameters you can use the Silicon Software GigE Explorer application.

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.

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.

To accelerate the call of grab_data/grab_data_async the calculation of these features can be disabled via the parameters 'blob_region', 'blob_center_of_gravity', 'blob_contour_length', 'blob_area', and 'blob_bounding_box'. By default, all features except the integer values for the bounding box are enabled. If all features are enabled, the region tuple will return the detected blobs and the data tuple will return the following integer values for each blob: cogx, cogy, conto, contd, area, bbx0, bby0, bbx1, bby1.
Parameter Type Count Description
'image' 1 Returns the grabbed image from DMA channel 0.
'contours' not used
'region' HALCON regions which are based on the bounding boxes of the blobs which are delivered by the Segmentation SmartApplets.
'data' tuple with integers 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 3D Triangulation SmartApplet Family

With the 3D Triangulation SmartApplets family, the HALCON SiliconSoftware interface will deliver also a disparity image that is calculated by the FPGA. The user has the possibility to receive this pre-processed image by calling grab_data or grab_data_async.
To receive an image with multiple disparity lines at once, the number of disparity lines can be set via set_framerabber_param(..., 'num_scans', ...). The default is 1.
Please use the generic 3D Triangulation SmartApplets parameter 'FG_3D_IMAGE_OUTPUT' to enable or disable the output of images which correspond to the calculated disparity image lines. By default, the parameter 'FG_3D_IMAGE_OUTPUT' is enabled, and grab_data or grab_data_async returns multiple images. The first image is always the disparity image. Please note, if you change the parameter 'FG_3D_IMAGE_OUTPUT' after calling grab_data_async, a current pending grab will be aborted.
Please use the generic 3D Triangulation SmartApplets parameter 'FG_3D_THRESHOLD' to set the threshold parameter that influences the detection of the laser line. The default value for this parameter is 155.
The image width of the camera and the corresponding disparity image is always aligned (reduced) to a divisible value of 8 pixels.
Parameter Type Count Description
'image' float Contains the disparity information in the first channel of the image parameter. The content of the image parameter is controlled by the HALCON parameter 'num_scans' and the generic SmartApplets parameter 'FG_3D_IMAGE_OUTPUT'. If the 'FG_3D_IMAGE_OUTPUT' parameter is set to 0 (laserline and image), the image parameter provides a multichannel image.
'contours' not used
'region' not used
'data' not used

Support of Multi RoI Visual Applet Modules

With the Multi RoI module provided by VisualApplets the HALCON SiliconSoftware image acquisition interface supports the request of multiple Region of Interests (RoI) for each buffered image. The RoIs are accessible via images returned by grab_data and grab_data_async. The configuration of the RoI module can be done by using the parameters listed in the table below. Please use the set_parameter_param and get_framegrabber_param operators as usual. To get further information about the RoI functionality, please read the module section provided in the VisualApplets documentation. Please use the following parameters to configure the RoI module:
multi_roi_module_name: Specifies the base name of the RoI module string
multi_roi_num: Specifies the number of RoIs to request integer
multi_roi_xlength: Specifies the xlength (width) for each RoI integer tuple
multi_roi_xoffset: Specifies the xoffset (start column) for each RoI integer tuple
multi_roi_ylength: Specifies the ylength (height) for each RoI integer tuple
multi_roi_yoffset: Specifies the yoffset (start row) for each RoI integer tuple
Please note, if you have trouble setting the parameter 'multi_roi_num', please check the maximum number of RoIs provided by the RoI module. The maximum number can only be changed before the applet is generated. If an applet with RoI functionality is used, the parameter 'continuous_grabbing' is not supported. The multi RoI parameters are not accessible by the HALCON Image Acquisition Assistant.

HDevelop Examples

For this interface there are the following examples available:
  • siliconsoftware_continuous.hdev - Grabbing images with continuous grabbing.
  • siliconsoftware_gige_vision.hdev - Shows usage of a Silicon Software GigE Vision frame grabber.
  • siliconsoftware.hdev - Benchmark
  • siliconsoftware_parameters.hdev - Lists all parameters of a device.
  • siliconsoftware_simple.hdev - A simple example to show the usage of the interface.
  • siliconsoftware_smartapplets.hdev - Shows usage of Silicon Software SmartApplets.
  • siliconsoftware_multiroi.hdev - Shows usage of Silicon Software VisualApplets' RoI functionality.
  • siliconsoftware_fieldparameter.hdev - Shows how to access the Silicon Software generic field parameter.
  • siliconsoftware_objectmodel3d.hdev - Shows usage of Silicon Software Triangulation SmartApplets, and how to create a HALCON 3D object model.

Release Notes

  • Revision 6.6 (Sep 26, 2016):
    • Adapted range of maximum possible timeout value to 2^32-1 milli seconds. With -1 the maximum possible value will be set.
    • Improved error handling of Generic parameter in open_framegrabber.
  • Revision 6.5 (Jul 27, 2016):
    • If a generic visual applets field parameter was queried, the last value of the list was not returned. This problem has been fixed.
  • Revision 6.4 (May 13, 2016):
    • open_framegrabber failed with error 5312 when the Generic parameter 'genicam_xml_file' was used. This problem has been fixed.
    • close_framegrabber in rare cases crashed when using more than one GenICam device. This problem has been fixed.
  • Revision 6.3 (Apr 27, 2016):
    • set_framegrabber_param crashed when setting 'do_exsync' or 'do_flash' with an empty tuple. This problem has been fixed.
    • Fixed memory leak in close_framegrabber which led to a crash in rare cases. This problem has been fixed.
    • In continuous mode the synchronous call grab_image always returned a timeout. This problem has been fixed.
    • If a generic float parameter was set with an integer value a later call with get_framegrabber_param returned the wrong result. This problem has been fixed.
    • The description of the parameters 'num_last_image' and 'num_images_in_progress' has been improved.
    • The legacy parameter 'current_buffer_index' has been removed from this documentation. This parameter is no longer supported. Please use the parameters 'num_blocked_images', 'num_block_lost_images', 'num_grabbed_images', 'num_last_image', 'num_next_image', and 'num_images_in_progress' instead.
  • Revision 6.2 (Feb 15, 2016):
    • Grabbing images with microEnable GigE Vision boards failed. Any attempt at grabbing returned with a timeout and it was not possible to get or set the GenICam parameters. This problem has been fixed.
    • If the parameter 'multi_roi_xlength', 'multi_roi_xoffset', 'multi_roi_ylength' and 'multi_roi_yoffset' were not supported by the used hardware applet, the call of set_framegrabber_param and get_framegrabber_param with these parameters might have crashed. This problem has been fixed.
  • Revision 6.1 (Oct 20, 2015):
    • Adapted to Silicon Software SDK 5.4.
    • Added support of microEnable V frame grabber family.
    • Added new parameters 'num_blocked_images', 'num_block_lost_images', 'num_grabbed_images', 'num_last_image', 'num_next_image', and 'num_images_in_progress' to get a status information of the buffer queue.
    • Added new parameter 'acquisition_mode' to control the behaviour of the buffer queue.
    • A call of info_framegrabber with the parameter 'device' returned a static list with possible device values. Now the dynamic values of connected devices are returned.
    • Added generic parameter 'genicam_xml_file' to pass a predefined configuration in case of a microEnable CoaXPress frame grabber.
    • Removed limitation of 'num_buffers'. Previously it was only possible to use up to 255 buffers.
    • In case of an error, the information of some low level errors is not sufficient. Detailed information is not available. This problem has been fixed.
    • Every DMA channel on a micro enable board is controlled by its own acquisition handle. The initialization of the board for all DMA channels will be done by the first call of open_framegrabber. There is no low level error to notify the user that the second open_framegrabber call on the same board will ignore the passed configuration file. This problem has been fixed.
  • Revision 6.0 (Oct 31, 2014):
    • HALCON 12 version of the interface.
  • Revision 5.5 (Jan 27, 2014):
    • Fixed bug in parameter 'grab_timeout'. If the parameter was set via set_framegrabber_param, also the DMA timeout of the frame grabber was adapted. This setting could lead to unexpected timeout errors.
    • Corrected documentation by adding support of WoW64.
  • Revision 5.4 (Jun 12, 2013):
    • Fixed bug in continuous grabbing mode. In case of a Standard Acquisition Applet with a single camera that is not connected to Camera Link port A, a wrong DMA channel was internally selected.
    • Fixed bug in buffer allocation during the activation of continuous grabbing.
    • Added missing parameter 'do_process_image_values'.
    • Fixed bug in close_framegrabber.
  • Revision 5.3 (May 24, 2013):
    • Adapted to Silicon Software SDK 5.2.1.
    • Added support of VisualApplets modules with RoI functionality. Now also the CoaXPress frame grabbers are supported.
    • Improved the 'generic' Silicon Software parameter configuration by adding access to field parameters.
    • Added parameters 'multi_roi_module_name', 'multi_roi_num', 'multi_roi_xlength', 'multi_roi_xoffset', 'multi_roi_ylength', 'multi_roi_yoffset', and 'num_field_parameter'.
    • Added new HDevelop example programs 'siliconsoftware_multiroi.hdev' and 'siliconsoftware_fieldparameter.hdev'.
    • Fixed bug if an unknown 'description' parameter was used.
    • Corrected documentation of the Generic parameter.
    • Fixed bug in close_framegrabber when using more than one camera in case of Silicon Software GigE Vision boards.
    • Fixed bug in open_framegrabber: The horizontal_resulution and vertical_resolution parameters are now ignored as documented.
    • Adapted and unified all existing HDevelop example programs.
  • Revision 5.2 (Oct 29, 2012):
    • Fixed bug in parameter 'available_param_names'.
    • Adapted evaluation of 'applet_type' parameter inside HDevelop example 'siliconsoftware_smartapplets.hdev'.
    • Added generic parameter 'discovery_timeout'.
    • Fixed bug in open_framegrabber. Cleanup the already opened device handles, if the initialization of a connected device or the initialization of the Silicon Software GigE Vision board fails.
    • Added new example 'siliconsoftware_objectmodel3d.hdev'.
  • Revision 5.1 (Jul 18, 2012):
    • Extended grab_data and grab_data_async to support the 3D Triangulation SmartApplets family.
    • Added parameter 'num_scans' to control the number of disparity lines.
  • Revision 5.0 (May 15, 2012):
    • HALCON 11 version of the interface (included in HALCON 11 DVD).
    • Fixed thread safety problem in grab_image and grab_image_async that can occur if grabbing was aborted via the 'do_abort_grab' parameter of set_framegrabber_param.
    • Adapted return value if grab_image or grab_image_async was aborted by the user. The return value now is H_ERR_FGF ("Failed grabbing of an image").
  • Revision 4.4 (Feb 4, 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.
    • HALCON 10 version of the interface (included in HALCON 10 DVD).
  • Revision 4.0 (Mar 16, 2010):
    • First official release.