MVTec Software GmbH
  Building Vision For Business
Halcon

HALCON 8.0 Image Acquisition Interface for Opteon Imaging Systems

This page provides the documentation of the HALCON Opteon image acquisition interface for the Opteon imaging systems distributed by VISICS. Registered customers can download the latest revision of this interface from the MVTec WWW server.

Revision: 3.3

System Requirements

  • Intel compatible PC with Windows NT 4.0 (SP 6), Windows 2000 or Windows XP.
  • Successfully installed Opteon driver v3.16 or higher (including the DLL depict.dll).
    This DLL must be within your search path %PATH%. If you do not have this DLL, please contact Opteon or the vendor from which you bought the imaging system.
  • HALCON image acquisition interface hAcqOpteon.dll or parhAcqOpteon.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

  • Supports Opteon Classic, USB 2.0, Ethernet, and Optinet cameras.
  • Supports multiple boards and multiple camera types.
  • Synchronous and asynchronous grabbing.
  • Variable image period for synchronous grabs.
  • External trigger.
  • Cropping of image parts.
  • Exposure, gain, and offset control.
  • Supports Bayer pattern single-chip color.
  • Supports 3-chip color.
  • Multiple Bayer conversion methods for Bayer color cameras..
  • Multiple white balance modes for color cameras.
  • Supports 'enumerated' camera type, allowing the user to open camera by index in the camera enumeration list.
  • Supports alternate queued acquisition mode (see description below).

Limitations

  • grab_data and grab_data_async not supported.
  • No LUTs.

Description

Parameters for open_framegrabber():

Name 'Opteon' The name of the HALCON image acquisition interface.
HorizontalResolution 1 The desired image resolution. Use '1' for full resolution. Default: 1.
VerticalResolution 1 The desired image resolution. Use '1' for full resolution. 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 ('0' obviously results in delivering the complete image). Default: 0.
StartColumn 0, column The column coordinate of the upper left pixel within the desired image part ('0' obviously results in delivering the complete image). Default: 0.
Field 'progressive' Fixed. Default: 'progressive'.
BitsPerChannel 8 Fixed. Default: 8.
ColorSpace 'default', 'gray', 'bayer', 'rgb' Selecting 'gray' will cause the camera to produce grayscale images as output; color cameras will average their color channels after any white balancing. Selecting 'rgb' will cause the camera to produce rgb color images as output; grayscale cameras will place the same image in all three channels. The 'bayer' color space is only valid for Bayer color cameras, and causes the camera to produce the raw Bayer-pattern image as output. Default: 'gray' for grayscale cameras, 'rgb' for color cameras.
Generic --- Ignored.
ExternalTrigger 'true', 'false' Activate/deactivate external triggering. Default: 'false'.
CameraType 'classic', 'usb', 'ethernet', 'optinet', 'enumerated' The Opteon camera platform to use. Default: 'enumerated'.
Device '0', '1', ... '9' The board number on the specified platform (passed as a string!). For Classic cameras this value can be in the range ['0', '9']. For USB 2.0 cameras, it must be '0'. For Ethernet and Optinet cameras it can be in the range ['0', '3']. Default: '0'.
Port num The camera number on the given platform and board number. For Classic cameras num can be in the range [0, 3]. For USB 2.0 cameras, num can be in the range [0, 9]. For Ethernet and Optinet cameras, num must be set to the camera's serial number. When using the 'enumerated' type, num indicates the index into the 0-indexed camera enumeration list to use. Default: 0.
LineIn --- Ignored.

Parameters for set_framegrabber_param():

'bayer_conversion' 'best_speed', 'good_speed_good_quality', 'best_quality' Sets the Bayer conversion method used (only valid for Bayer color cameras). The 'best_quality' method is only available for C1F and C2F Opteon cameras.
'exposure' usec Set the exposure time in microseconds for primary acquisition (see Opteon documentation for details).
'external_trigger' 'true', 'false' Activate/deactivate external triggering.
'gain' 0.0 - 100.0 The desired video gain: A floating point number between 0.0 and 100.0.
'grab_timeout' msec Sets the acquisition timeout. If an acquisition does not complete within the specified timeout period, the HALCON interface returns with an timeout error. Default: 5000.
'image_height' height The height of the desired image part.
'image_width' width The width of the desired image part.
'internal_strobe_current' milliamp The internal strobe current (in milliamps).
'internal_strobe_duration' 0.001 ... 1000.0 The internal strobe duration (in milliseconds). Note: If 'internal_strobe_mode' is set to 'exposure_following', this parameter has no effect.
'internal_strobe_min_off' 0.001 ... 1000.0 The internal strobe minimum off time (in milliseconds). Sets the minimum time that the strobe can be off before it can fire again. If another strobe signal is received before the off time expires, the strobe will not fire.
'internal_strobe_mode' 'exposure_following', 'fixed_duration' Sets the mode of strobe duration determination:
  • 'exposure_following': strobe duration is always the exposure duration.
  • 'fixed_duration': strobe duration is fixed at value of 'internal_strobe_duration'.
'offset' -255.0 ... 255.0 The desired video offset: A floating point number between -255.0 and 255.0.
'pipelined' 'true', 'false' Turns pipelined acquisitions on ('true') or off ('false') (see Opteon documentation for details).
'start_column' column The start column of the desired image part.
'start_row' row The start row of the desired image part.
'timebase' usec Sets the period for synchronous acquisitions in 'timebase' trigger mode (see Opteon documentation for details).
'trigger_mode' 'externala', 'externalb', 'immediate', 'master', 'slave', 'timebase' Set desired trigger mode.
'trigger_signal' 'rising', 'falling' Sets whether trigger occurs on a rising or falling edge.
'white_balance' 'disable', 'auto', 'auto_next_frame', 'user' Sets the desired white balancing mode:
  • 'disable': Disables white balancing.
  • 'auto': Runs auto white balancing on each frame. This incurs a per-frame processing cost.
  • 'auto_next_frame': Runs auto white balancing on the next frame only. The weights are stored in the user weight parameters, and the white balance mode is changed to 'user'.
  • 'user': Enable manual white balancing using the 'white_balance_X' parameters as weights.
'white_balance_b' 0.0 ... 5.0 Sets the desired scaling factor for the blue image channel in case of manual white balancing.
'white_balance_g' 0.0 ... 5.0 Sets the desired scaling factor for the green image channel in case of manual white balancing.
'white_balance_r' 0.0 ... 5.0 Sets the desired scaling factor for the red image channel in case of manual white balancing.

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'].
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.

'has_internal_strobe' 'false', 'true' If camera has an internal strobe controller the parameter returns 'true', 'false' otherwise.
'revision' revision The revision number of the HALCON Opteon image acquisition interface.

Description of alternate 'Queued' acquisition mode:

In order to support the advanced capabilities of Opteon cameras and the Depict camera interface, the HALCON Opteon interface supports an alternate 'queued' acquisition mode. In this mode, each camera has an acquisition queue. Calls to the HALCON grab_image function place an acquisition with the current camera settings onto the camera's queue and then return immediately. Each queued acquisition has an associated 'Wait Object' with which the user can wait for the acquisition to complete. The Wait Object also stores a timestamp for the acquisition that can be compared to those for other acquisitions to determine precise relative timing. Image data is placed directly into the HALCON image returned from the grab_image call, so the user must wait for the acquisition to be complete before performing any operations on the image, see also the example HDevelop script opteon_queued.dev in %HALCONROOT%/examples/hdevelop/Image/Acquisition.

Queued acquisitions are controlled through a set of frame grabber parameters accessed using the standard set_framegrabber_param and get_framegrabber_param HALCON calls. The names and uses of these parameters are documented below; they follow a different naming convention to differentiate them from standard parameters. Note that many of the parameters perform different operations depending on whether a set_framegrabber_param or a get_framegrabber_param operation is being performed.

The 'GrabWaitObject' and 'TriggerWaitObject' properties are particularly important. They control whether the standard HALCON grab functionality or the alternate grab mode is used. If both of these parameters are set to 0, standard HALCON grabs will be performed. If either is set to a non-zero Wait Object handle (see below), the alternate acquisition mode will be enabled.

'WaitObjectFactory' get Creates a new Wait Object and returns an integer-valued object handle that addresses the object. This handle can then be passed to other parameters that require a Wait Object handle.
set Destroys the Wait Object associated with the handle passed in.
'GrabWaitObject' get / set Handle of the Wait Object to be used as the 'acquisition complete' object for the acquisition queued by the next grab_image call. This object will become ready when the acquisition is complete. Either this parameter or the 'TriggerWaitObject' must be set to a value other than 0 to activate the queued acquisition mode. If both property values are 0, standard HALCON grab functionality will be used.

It is important to note that every acquisition that is in the queue at the same time must have an unique Wait Object. Therefore, if five acquisitions are to be queued (with five successive grab_image calls made before any of the acquisitions completes), the user must have called 'WaitObjectFactory' five times beforehand, stored the unique object handles returned, and set this property with the appropriate handle value before calling grab_image to queue each acquisition.
'TriggerWaitObject' get / set Handle of the Wait Object to be used as the 'acquisition triggered' object for the acquisition queued by the next grab_image call. This object will become ready when the acquisition is triggered and exposure begins. Either this parameter or the 'GrabWaitObject' must be set to a value other than 0 to activate the queued acquisition mode. If both property values are 0, standard HALCON grab functionality will be used.
'WaitObjectWait' set Specifies the handle for a Wait Object to be used in a subsequent 'get' operation (see below).
get Waits on the Wait Object specified by a prior 'set' operation. If this Wait Object was used in the 'GrabWaitObject' parameter for an acquisition, it will be ready when the acquisition is complete. If it was used in the 'TriggerWaitObject' parameter for an acquisition, it will be ready when the acquisition is triggered. If the object is not ready within the time period specified by the 'WaitObjectTime' property, this parameter returns a string value of 'timeout'. If the object is ready within the time period, it returns a string value of 'success'.
'WaitObjectTime' get / set Controls the length of time, in milliseconds, that the 'WaitObjectWait' property will wait (on a 'get' operation, see property description) before returning.
'WaitObjectDiff' set Specifies the handle for a Wait Object to be used in a subsequent 'get' operation (see below).
get Returns the timestamp difference, in milliseconds, between the last two Wait Objects passed (by handle) to the 'set' operation for this parameter. If the second object's timestamp was later than the first, the difference is positive; otherwise it is negative. If the 'set' operation has been called less than twice, an error is generated.
'ClearQueue' set When set to 'true', clears the camera's acquisition queue. This cancels any previously queued acquisitions, including any made using the standard HALCON functionality. This call would typically be used to cancel an externally triggered acquisition if a program detected that the trigger was not likely to arrive.
get Not defined.

Release Notes

  • Revision 3.3 (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.2 (Oct 16, 2007):
    • Added device auto-detection in info_framegrabber.
  • Revision 3.1 (Jul 27, 2007):
    • Bugfix in get_framegrabber_param regarding the parameters 'pipelined', 'trigger_mode', 'trigger_signal', and 'bayer_conversion'.
  • Revision 3.0 (May 15, 2007):
    • HALCON 8.0 version of the interface (included in HALCON 8.0 DVD).
    • Added new parameters 'exposure_range', 'gain_range', and 'offest_range'.
    • Added new parameters 'has_internal_strobe', 'internal_strobe_mode', 'internal_strobe_current', 'internal_strobe_current_range', 'internal_strobe_duration', and 'internal_strobe_min_off'.
    • Changed parameters 'exposure' and 'timebase' to be floating-point values specified in milliseconds.
  • Revision 2.8 (Jun 26, 2006):
    • Adaptation to Opteon driver v3.17.
  • Revision 2.7 (Nov 17, 2004):
    • HALCON 7.1 version of the interface (included in HALCON 7.1 CD).
    • Bugfix in grabbing grayscale images.
    • The query types 'bits_per_channel', 'camera_type', 'color_space', 'device', 'external_trigger', 'field', and 'port' for info_framegrabber provide now specific value lists for the corresponding parameters in open_framegrabber.
  • Revision 2.6 (Sep 23, 2004):
    • Bugfix in Bayer camera support.
    • Bugfix in async grab delay calc for non-classic cameras.
    • No-copy optimization for async grayscale grabs.
    • Added 3-chip camera support.
    • Added support for 'enumerated' camera type, which allows the user to open cameras by order in the enumeration list.
    • Changed default parameters in open_framegrabber to open the first enumerated camera and to select the color space.
    • Added new parameter 'bayer_conversion'.
    • Added new parameters 'white_balancing', 'white_balancing_b', 'white_balancing_g', and 'white_balancing_r'.
    • Added support for both 'gray' and 'rgb' color spaces on all cameras, with appropriate conversions.
    • Added 'bayer' color space that causes Bayer cameras to output raw Bayer pattern images.
    • Adaptation to Opteon driver v3.15.
  • Revision 2.5 (Mar 10, 2003):
    • HALCON 7.0 version of the interface (included in HALCON 7.0 CD).
    • Bugfix in accessing classic and ethernet camera systems.
  • Revision 2.4 (Jan 28, 2003):
    • Adaptation to latest Depict 3.0 driver: Internally the parameters 'gain' and 'offset' now are represented as floats and have different value ranges.
  • Revision 2.3 (Apr 11, 2002):
    • HALCON 6.1 version of the interface (included in HALCON 6.1 CD).
    • Added support for USB 2.0 and Ethernet cameras.
    • Adaptation to Depict 3.0 driver.
  • Revision 2.2 (Apr 9, 2002):
    • Added support for Bayer pattern color cameras.
    • Added 'offset', 'timebase', 'pipelined', 'trigger_signal', 'grab_timeout', and 'ClearQueue' parameters.
    • Documented alternate 'Queued' acquisition mode.
    • Canceling pending asynchronous grabs when calling grab_image_start or grab_image.
  • Revision 2.1 (Feb 14, 2001):
    • Bugfix in grab_image_async: When called without preceeding grab_image_start, wait for the first grabbed image.
    • Bugfix in grab_image_async: Always copy image into HALCON image structure to ensure database persistence.
    • Evaluation of the Device parameter during open_framegrabber.
  • Revision 2.0 (Nov 16, 2000):
    • First official release (included in the HALCON 6.0 CD).


© Copyright 2012, MVTec Software GmbH, corporate/legal/privacy information






Last modified: Wed Apr 23 13:45:14 CEST 2008