HALCON Frame Grabber Interface for GINGA++ Boards

This document provides information about the continuous grabbing mode that can be used by the HALCON Ginga++ interface. The latest revision of this interface can be downloaded from the Support Area of the LinX WWW server. In case of installation problems please send e-mail (techimage@linx.jp) or fax (81-45-979-0732) to LinX technical support center.

Continuous Grabbing Mode

The principle idear of th continuous grabbing mode is that images will be acquired with each external trigger and stored into the specified number of buffers (ring buffer) in a cyclic way without any additional explicit software trigger like grab_image. Your HALCON application, which runs using asynchronous image grabbing, can process other data without loosing any frame. You can acquire several frames into the ring buffers in parallel and the number of frames (specified with the 'num_buffers' parameter in advance) is limited only by system memory size.

This mode is usually applied with external trigger and cannot be used with software trigger (shot operation). However, this method can be used in normal mode also without trigger.

Note that the frame rate for grabbing can be adjusted either automatically or dynamically according to the PCI load by setting the grabbing frequency.

Parameters for set_framegrabber_param():

	'capture_frequency'	'Capture=x Drop=y' (1≤x≤15, 0≤y≤15)	Specify the grabbing frequency to adjust the desired frame rate automatically and dynamically according to the PCI load. The frames specified by x are grabbed sequentially. After that, the grabbing is suspended for the next y frames. This parameter is effective only in sequence or continuous grabbing mode. Default: value specified in the camera file.
	'continuous_grabbing'	'enable', 'disable'	Activate/deactivate continuous grabbing mode. Default: 'disable'.
	'num_buffers'	2, 3, 4, ...	The number of allocated frame buffers is specified in case of continuous grabbing or sequence grabbing mode. The maximum number of frame buffers is limited by system memory size. Note that 'num_buffers' must be set before enabling the continuous grabbing mode!
	'overwrite_method'	'abort', 'ignore'	In this continuous grabbing mode you might encounter situations where the images are acquired at a faster rate than they are read by your application. Thus, the buffers will fill up and finally you will encounter a buffer that was not read so far, but should be overwritten by the next frame. You can decide what to do in this situation via the parameter 'overwrite_method': 'abort': Before overwriting any frame, abort the acquisition. This is the most safe method. The main user will be able to process any good buffers still in the system before an error is returned. 'ignore': Ignore the problem and overwrite the ring buffer. Thus, some of the older frames that already have been acquired (but not processed so far) will be lost. Default: 'abort'. Note: When 'abort' is specified and acquisition is completed, HALCON error H_ERR_FGF is returned during runtime of grab_image or grab_image_async.
	'ring_buffer_stop_margin'	0 ... (num_buffers-1)	When 'overwrite_method' is set to 'abort', empty frame number is specified for the condition of completion of image acquisition. You may have the problem that you cannot stop acquisition at the expected frame number when the load of application is big or highspeed camera is used. The image may by overwritten before converting it into HALCON object. Please specify enough number of frames to avoid this situation. Default: 1.
	'walk_ring_buffer'	'enable','disable'	If you specify 'enable' to this parameter, you can convert the remained images in the ring buffer into HALCON objects sequentially using grab_image or grab_image_async after completion of continuous grabbing. The total number of remaining images in the ring buffer can be calculated by the parameters 'ring_buffer_last_index', 'ring_buffer_current_index', and 'num_buffers'. HALCON error H_ERR_FGF is returned if you invoke grab_image or grab_image_async after all images stored in the ring buffer are read. Default: 'disable'.

Parameters for get_framegrabber_param():

'ring_buffer_last_index'	0 ... (num_buffers-1)	Return the last index number of the ring buffer when image acquisition is completed. The index number is between 0 and (num_buffers-1).
'ring_buffer_current_index'	0 ... (num_buffers-1)	Return the index number of the last ring buffer which is converted into HALCON object when image acquisition is completed. The index number is between 0 and (num_buffers-1).

Example

  num_buffers:       5
  capture_frequency: 'Capture=2 Drop=1'

Reference of Ring Buffer

This paragraph describes how to transfer the remaining images in the ring buffer to HALCON when the image acquisition stops in continuous grabbing mode.

The figure on the right shows the status of the ring buffer when the image acquisition is terminated in the condition of 'abort' for the parameter 'overwrite_method'. The gray area shows the remaining images which have not been transferred to HALCON. The condition of the continuous grabbing mode is num_buffers = 6 overwrite_method = 'abort' ring_buffer_stop_margin = 1 The image acquisition is terminated because it has reached the last frame number specified by 'ring_buffer_stop_margin' although the acquisition is made to Frame2. You can transfer the images to HALCON according to the sequence of Frame5->Frame0->Frame1->Frame2 by setting the parameter 'walk_ring_buffer' to 'enable' and calling grab_image or grab_image_async.

Limitation

The continuous grabbing mode can not be combined with the software trigger (shot grabbing) mode!

Sample Program

dev_close_window ()
* 
Width := 640
Height := 480
* 
NumBuffers := 100
* 
dev_open_window (0, 0, Width*0.5, Height*0.5, 'black', WindowHandle1)
* 
MyCameraType := 'jai/CVM40_NI_TRIG_DEMAND'
MyBoardType := 'GINGA++M2'
* MyBoardType := 'GINGA++M4'
* 
dev_update_pc ('off')
dev_update_time ('off')
dev_update_var ('off')
dev_update_window ('off')
* 
close_all_framegrabbers ()
open_framegrabber ('Ginga++', 1, 1, 0, 0, 0, 0, 'default', -1, 'default', -1, 'default', MyCameraType, MyBoardType, 0, -1, FGHandle1)
* 
set_framegrabber_param (FGHandle1, 'shutter_speed', 500E-6)
* 
set_framegrabber_param (FGHandle1, 'num_buffers', 100)
set_framegrabber_param (FGHandle1, 'continuous_grabbing', 'enable')
set_framegrabber_param (FGHandle1, 'overwrite_method', 'abort')
set_framegrabber_param (FGHandle1, 'ring_buffer_stop_margin', 5)
* 
stop ()
* 
grab_image_start (FGHandle1, -1)
for i := 1 to 150 by 1
    grab_image_async (Image1, FGHandle1, -1)
    mean_image (Image1, ImageMean1, 9, 9)
    dev_set_window (WindowHandle1)
    dev_display (ImageMean1)
* wait_seconds (0.5)
endfor
* 
wait_seconds (0.5)
* 
set_framegrabber_param (FGHandle1, 'continuous_grabbing', 'disable')
* 
get_framegrabber_param (FGHandle1, 'ring_buffer_last_index', LastFrame1)
get_framegrabber_param (FGHandle1, 'ring_buffer_current_index', CurrentFrame1)
* 
stop ()
* 
set_framegrabber_param (FGHandle1, 'walk_ring_buffer', 'enable')
ObjectCount := LastFrame1-CurrentFrame1
if (ObjectCount < 0)
    ObjectCount := NumBuffers-CurrentFrame1+LastFrame1
endif
for i := 1 to ObjectCount by 1
    grab_image (Image111, FGHandle1)
    dev_set_window (WindowHandle1)
    dev_display (Image111)
    stop ()
endfor
* 
stop ()
* 
close_framegrabber (FGHandle1)