MVTec Software GmbH
  Building Vision For Business
Follow us on YouTube  Subscribe our RSS feed
Halcon

HALCON 10 Image Acquisition Interface for Ginga++ Boards

This page provides the documentation about the HALCON Ginga++ image acquisition interface for the LinX Ginga++M2/M4 frame grabber boards. Registered customers can download the latest revision of this interface from the MVTec WWW server or from the Support Area of the LinX WWW server. In case of installation problems please send an e-mail (techimage@linx.jp) or fax (81-45-979-0732) to LinX technical support center.

Revision: 4.1

System Requirements

  • Intel compatible PC with Windows XP.
  • Successfully installed GINGA++ Initial Software Kit (ISK):
    <GINGA++M4>
    GINGA++ device driver version 1.3.5.9 or later
    <GINGA++M2>
    GINGA++ device driver version 1.1.3.4 or later
  • Successfully installed GINGA++ driver GingaPP.sys (GINGA++M4) or GingaM2.sys (GINGA++M2) in %SystemDrive\Winnt\system32\drivers.
  • HALCON image acquisition interface hAcqGinga++.dll or hAcqGinga++xl.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

  • Multiple cameras on multiple frame grabber boards.
  • Serial and parallel (simultaneously from several cameras) grabbing.
  • Synchronous and asynchronous grabbing.
  • Using arbitrary cameras by setting the camera file name.
  • Different grabbing modes: external trigger, sequence grabbing, continuous grabbing.
  • Subsampling.
  • Software cropping of image parts.

Limitations

  • grab_data and grab_data_async not supported.
  • No LUTs.

Description

Parameters for open_framegrabber() :

Name 'Ginga++' The name of the HALCON image acquisition interface.
HorizontalResolution 1, 2, 4 The desired horizontal image resolution. Use '1' for full resolution, '2' for subsampling by factor 2, and '4' for subsampling by factor 4. Default: 1.
VerticalResolution 1, 2, 4 The desired vertical image resolution. Use '1' for full resolution, '2' for subsampling by factor 2, and '4' for subsampling by factor 4. Default: 1.
ImageWidth 0, width The width of the desired image part (use '0' for the maximum image width). Default: 0.
ImageHeight 0, height The height of the desired image part (use '0' for the maximum image height). Default: 0.
StartRow 0, row The row coordinate of the upper left pixel within the desired image part (use '0' for the complete image). Default: 0.
StartColumn 0, column The column coordinate of the upper left pixel within the desired image part. Default: 0.
Field --- Ignored.
BitsPerChannel --- Ignored.
ColorSpace --- Ignored.
Generic --- Ignored.
ExternalTrigger --- Ignored.
Note that the external trigger mode depends on the settings of the camera file described below!
CameraType cam_name The CameraType parameter is used to specify the file name of the desired camera configuration. Note that the file name has to be relative to the environment variable %GingaPPConfigPath%.
Example: jai/CVM40_NI_NORM

For details please refer to the rule for camera file naming.

<GINGA++M4> You have to use the same camera name for pair port, which consists of even and odd channel number. Channel 0 and 1 compose pair port.
<GINGA++M2> You have to use the same camera name for the same board.
Device 'GINGA++M4', 'GINGA++M2' Board type of the GINGA++ board.
Port 0, 1, 2, ... The port parameter specifies the channel number the camera(s) is/are connected to. The channel number must be set from 0 for the first channel of the smallest PCI bus and slot number when multiple cameras on multiple frame grabber boards are installed in the same system. For example, in case of
[Board 1] bus number = 0, slot number = 0
[Board 2] bus number = 0, slot number = 1
[Board 3] bus number = 1, slot number = 0
then:
Port number of [Board 1] must be set to [0-3]
Port number of [Board 2] must be set to [4-7]
Port number of [Board 3] must be set to [8-11]
LineIn --- Ignored.

Parameters for set_framegrabber_param():

'abort_wait' msec Time to wait in milliseconds after aborting a grab. Default: 0.
'continuous_grabbing' 'enable', 'disable' Activate/deactivate continuous grabbing mode. Default: 'disable'.
'external_drive' 'enable', 'disable' When this mode is enabled, the GINGA++ board sends the HD (horizontal drive) signal to the camera(s). In this case the horizontal synchronization of the camera is driven by the GINGA++ board. This mode is especially useful for simultaneous grabbing with multiple cameras. If this mode is disabled, switching of synchronization signal source of the cameras, which are connected to a pair port, is made automatically. This disabled mode is used for grabbing by switching between multiple cameras. Default: 'enable'.
'external_trigger' 'true', 'false' Activate/deactivate external triggering. If enabled, the grabbing starts with the shot (external trigger) signal input to the GINGA++ board. Note that you cannot disable the external trigger mode when using a reset shutter mode camera file.
'grab_timeout' msec Timeout value for image acquisition in milliseconds. Default: 5000.
'long_exposure_time' 1 ... 256 Specify long exposure time.
'sequence_grabbing' 'enable', 'disable' Activate/deactivate sequence grabbing mode. Default: 'disable'.
'shutter_speed' > 0 Specify shutter speed (exposure time) in seconds if camera is used in reset shutter mode.
'signal_range_max' -0.285 ... 0.990 Specify maximum value for the intensity range of the grabbed images. If the grabbed video signal intensity is greater or equal than this value the corresponding pixels become white (255).
'signal_range_min' -0.285 ... 0.990 Specify minimum value for the intensity range of the grabbed images. If the grabbed video signal intensity is lower or equal than this value the corresponding pixels become black (0).
'software_trigger' 'enable', 'disable' Enable or disable the software trigger mode (shot grabbing). In case you specify a camera file for reset shutter mode in the CameraType parameter during open_framegrabber, the GINGA++ board sends the trigger signal to the camera for shuttering. This trigger signal is synchronized with the shot (external trigger) signal input to GINGA++ from an external device if the parameter 'software_trigger' is set to 'disable' (default).
However, if you enable the software trigger mode, the GINGA++ baord sends the trigger signal to the camera synchronized with the software operation instead of the external device signal. When calling grab_image or grab_image_async in this software trigger mode (also called shot grabbing mode) the trigger signal is sent immediately to the camera for shuttering and grabbing the desired image. Default: 'disable'.
'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. Default: 'enable'.
'volatile' 'enable', 'disable' 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! Default: 'disable'.
'wait_frame_exposure' 0, 1, 2 Wait for the completion of camera exposure for the period specified by 'wait_frame_exposure_timeout'. The possible return values are
  • 0 (failed): Failure of the waiting process for the completion of camera exposure.
  • 1 (timeout): Inform that the time specified by the parameter 'wait_frame_exposure_timeout' has passed.
  • 2 (success): Success of the waiting process for the completion of camera exposure.
'wait_frame_exposure_timeout' > 0 Specify timeout value in milliseconds for waiting process for the completion of camera exposure by 'wait_frame_exposure' of get_framegrabber_param, when image acquisition is made by random trigger shutter of camera.
Default: 1000.
'do_abort_capture' --- Abort the current image acquisition.
'do_clear_ring_buffer' -1 If 'continuous_grabbing' is enabled, the parameter clears the internal used buffers.
'do_force_trigger' --- This parameter is prepared for shot operation similar to the 'software_trigger' parameter. When set_framegrabber_param operator with 'do_force_trigger' is called, a shot operation is invoked and a trigger signal is sent to the camera. This mode is useful to abort a pending grab_image_async when using a reset shutter mode camera file.

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

'abs_counter' number The number of grabbed images.
'next_buffer_acquired' index Index of the next buffer which could be acquired.
'next_buffer_returned' index Index of the next buffer which is returned.
'revision' revision The revision number of the HALCON Ginga++ interface.
'ring_buffer_last_index' index Returns the index of the last ring buffer.

Release Notes

  • Revision 4.1 (Sep 8, 2010):
    • Added parameters 'do_clear_ring_buffer', 'next_buffer_acquired' and 'next_buffer_returned'.
    • Fixed bug in grab_image and grab_image_async.
    • Removed internally used debug functions.
    • HALCON 10 version of the interface (included in HALCON 10 DVD).
  • Revision 4.0 (Dec 1, 2008):
    • Added read-only parameters 'do_force_trigger_values' and 'do_abort_capture_values' to enable this functionality also in the HDevelop Image Acquisition Assistant.
    • Special thread handling in continuous grabbing mode.
    • HALCON 9.0 version of the interface (included in HALCON 9.0 DVD).
  • Revision 3.1 (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.0 (May 15, 2007):
    • HALCON 8.0 version of the interface (included in HALCON 8.0 DVD).
    • New parameters 'abort_wait' and 'abs_counter'.
    • Support of absorb frame buffer mode.
  • Revision 2.3 (Dec 17, 2004):
    • HALCON 7.1 version of the interface (included in HALCON 7.1 CD).
    • New parameters 'long_exposure_time' and 'do_abort_capture'.
    • 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.2 (Jun 24, 2003):
    • HALCON 7.0 version of the interface (included in HALCON 7.0 CD).
    • info_framegrabber('info_boards') returns now an error in case that no GINGA++ boards are actually installed.
  • Revision 2.1 (Dec 19, 2002):
    • Support of GINGA++M2 boards.
    • Waiting process for the completion of camera exposure (new parameters 'wait_frame_exposure' and 'wait_frame_exposure_timeout').
    • Additional parameters for continuous grabbing mode.
  • Revision 2.0 (Apr 28, 2002):
    • First official release (included in HALCON 6.1 CD).


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






Last modified: Fri Sep 10 18:39:24 CEST 2010