open_framegrabber

open_framegrabber ( : : Name, HorizontalResolution, VerticalResolution, ImageWidth, ImageHeight, StartRow, StartColumn, Field, BitsPerChannel, ColorSpace, Gain, ExternalTrigger, CameraType, Device, Port, LineIn : FGHandle )

Open and configure a frame grabber.

The operator open_framegrabber opens and configures the chosen frame grabber. During this process the connection to the frame grabber is tested, the frame grabber is (normally) locked for other processes, and if necessary memory is reserved as data buffer. The image is actually grabbed via the operators grab_image, grab_region, grab_image_async, or grab_region_async. If the frame grabber is not needed anymore, it should be closed via the operator close_framegrabber, releasing it for other processes. This automatically happens when a frame grabber is reopened. Some frame grabbers allow to open several instances of the same frame grabber class (up to 5).

For some parameters frame grabber specific default values can be chosen explicitly (see the parameter description below). Additional information for a specific frame grabber is available via info_framegrabber. Please check also the directory doc/html/manuals for files describing selected frame grabbers.

The meaning of the particular parameters is as follows:

HorizontalResolution,VerticalResolution
                             Desired resolution of frame grabber.
ImageWidth,ImageHeight       Size of the image area to be returned 
                             by grab_image etc.
StartRow,StartColumn         Upper left corner of the desired image area.
Field                        Desired half image ('first', 'second', or 
                             'next') or selection of a full image.
BitsPerChannel               Number of bits, which are transferred from the 
                             frame grabber board per pixel and image channel 
                             (typically 5, 8, 10, 12, or 16 Bits).
ColorSpace                   Specify to grab single-channel ('gray') 
                             or three-channel images ('rgb', 'yuv', ...). 
Gain                         Amplification factor for the video
                             amplifier (if available).
ExternalTrigger              Activation of external triggering (if
                             available).
CameraType                   Frame grabber specific parameter (string
                             type) to specify the type of the used camera, 
                             which can be inquired via
                             info_framegrabber.
Device                       Device name of the frame grabber board.
Port                         Port of the frame grabber the video signal
                             is connected to.
LineIn                       Camera input line of multiplexer (if
                             available).

The operator open_framegrabber returns a handle (FGHandle) to the opened frame grabber.

Attention

Due to the multitude of supported frame grabbers a large number of parameters is necessary for the operator open_framegrabber. However, not all parameters are needed for a specific frame grabber.

Parameters

`Name` (input_control)	string `->` string
HALCON frame grabber interface, i.e. name of the corresponding DLL (Windows) or shared library (UNIX).
Default value: 'File'
Suggested values: 'Barracuda', 'Bcam1394', 'BitFlow', 'CCi4', 'DFG-BW', 'DFG-LC', 'DirectShow', 'DqVll', 'DT315x', 'DT3162', 'File', 'Fire-i', 'FirePackage', 'FlashBus', 'FlashBusMX', 'Ginga', 'Ginga++', 'IDS', 'Inspecta', 'MatrixVision', 'MultiCam', 'Opteon', 'p3i2', 'p3i4', 'PCEye', 'PicPort', 'PicPortPro', 'PicProdigy', 'PX', 'PXC', 'PXD', 'PXR', 'Ramses1', 'TWAIN', 'uEye'

`HorizontalResolution` (input_control)	extent.x `->` integer
Desired horizontal resolution of frame grabber (1: full resolution, 2: half resolution, 4: quarter resolution).
Default value: 1
Suggested values: 1, 2, 4, 768, 720, 640, 384, 320, 192, 160

`VerticalResolution` (input_control)	extent.y `->` integer
Desired vertical resolution of frame grabber (1: full resolution, 2: half resolution, 4: quarter resolution).
Default value: 1
Suggested values: 1, 2, 4, 576, 480, 288, 240, 144, 120

`ImageWidth` (input_control)	rectangle.extent.x `->` integer
Width of desired image part (0: `HorizontalResolution` - 2`StartColumn`).*
Default value: 0
Suggested values: -1, 0

`ImageHeight` (input_control)	rectangle.extent.y `->` integer
Height of desired image part (0: `VerticalResolution` - 2`StartRow`).*
Default value: 0
Suggested values: -1, 0

`StartRow` (input_control)	rectangle.origin.y `->` integer
Line number of upper left corner of desired image part, for `ImageHeight` = 0: Height of a border.
Default value: 0
Suggested values: -1, 0

`StartColumn` (input_control)	rectangle.origin.x `->` integer
Column number of upper left corner of desired image part, for `ImageWidth` = 0: Width of a border.
Default value: 0
Suggested values: -1, 0

`Field` (input_control)	string `->` string
Desired half image or for full image.
Default value: 'default'
Suggested values: 'first', 'second', 'next', 'interlaced', 'progressive', 'default'

`BitsPerChannel` (input_control)	integer(-array) `->` integer
Number of transferred bits per pixel and image channel (-1: frame grabber specific default value).
Default value: -1
Suggested values: 5, 8, 10, 12, 16, -1

`ColorSpace` (input_control)	string(-array) `->` string
Specify to grab single-channel ('gray') or three-channel ('rgb', 'yuv', ...) images ('default': frame grabber specific default value, mostly 'rgb').
Default value: 'default'
Suggested values: 'gray', 'rgb', 'yuv', 'default'

`Gain` (input_control)	real `->` real
Amplification factor for video amplifier (-1.0: frame grabber specific default value).
Default value: -1.0
Suggested values: 0.25, 0.5, 0.75, 1.0, -1.0

`ExternalTrigger` (input_control)	string `->` string
External triggering.
Default value: 'default'
List of values: 'true', 'false', 'default'

`CameraType` (input_control)	string(-array) `->` string
Type of used camera (frame grabber specific) ('default': frame grabber specific default value).
Default value: 'default'
Suggested values: 'ntsc', 'pal', 'auto', 'default'

`Device` (input_control)	string(-array) `->` string
Device the frame grabber is linked to ('default': frame grabber specific default value).
Default value: 'default'
Suggested values: '-1', '0', '1', '2', '3', 'default'

`Port` (input_control)	integer(-array) `->` integer
Port of the frame grabber the video signal is linked to (-1: frame grabber specific default value).
Default value: -1
Suggested values: 0, 1, 2, 3, -1

`LineIn` (input_control)	integer(-array) `->` integer
Camera input line of multiplexer.
Default value: -1
Suggested values: 1, 2, 3, 4, -1

`FGHandle` (output_control)	framegrabber `->` integer
Handle of the opened frame grabber.

Example

// Select a suitable frame grabber FgName
info_framegrabber(FgName,'ports',Information,Val)
// Choose the port P and the input line L your camera is connected to
open_framegrabber(FgName,1,1,0,0,0,0,'default',-1,'default',-1.0,
                  'default','default','default',P,L,FgHandle)
grab_image(Img,FgHandle) 
close_framegrabber(FgHandle)

Result

If the parameter values are correct and the desired frame grabber is available at call time, open_framegrabber returns the value 2 (H_MSG_TRUE). Otherwise an exception handling is raised.

Parallelization Information

open_framegrabber is local and processed completely exclusively without parallelization.

Possible Predecessors

info_framegrabber

Possible Successors

grab_image, grab_region, grab_image_start, grab_image_async, grab_region_async, set_framegrabber_param

Module

Image / region / XLD management