HALCON 7.1 Frame Grabber Interface for Opteon Imaging Systems
This page provides the documentation of the HALCON frame grabber 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: 2.9
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 frame grabber interface HFGOpteon.dll or parHFGOpteon.dll, respectively. If you have properly installed the interface, both DLLs should reside in bin\i586-nt4 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_region and grab_region_async not supported.
- No LUTs.
Description
Parameters for open_framegrabber():
| Name | 'Opteon' | The name of the HALCON frame grabber 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. | |||
| Gain | 0.0 - 100.0 | The desired video gain: A floating point number between 0.0 and 100.0. Default: 1.0. | |||
| 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:
|
|||
| '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:
|
|||
| '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.
| 'exposure_range' | [min, max, step, default] | Valid range of values for 'exposure' parameter (in milliseconds). | |||
| 'gain_range' | [min, max, step, default] | Valid range of values for 'gain' parameter. | |||
| 'has_internal_strobe' | 'false', 'true' | If camera has an internal strobe controller the parameter returns 'true', 'false' otherwise. | |||
| 'internal_strobe_current_range' | [min, max, step, default] | Valid range of values for 'internal_strobe_current' parameter (in milliamps). | |||
| 'offset_range' | [min, max, step, default] | Valid range of values for 'offset' parameter. | |||
| '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/Framegrabber.
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 2.9 (July 27, 2007):
- 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 (June 26, 2006):
- Adaptation to Opteon driver v3.17.
-
Revision 2.7 (November 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 (September 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 (March 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 (January 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 (April 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 (April 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 (February 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 (November 16, 2000):
- First official release (included in the HALCON 6.0 CD).
