open_framegrabber

Herror ::open_framegrabber ( const HTuple &Name, const HTuple &FGWidth, const HTuple &FGHeight, const HTuple &Width, const HTuple &Height, const HTuple &StartRow, const HTuple &StartColumn, const HTuple &Field, const HTuple &Bits, const HTuple &ColorSpace, const HTuple &Gain, const HTuple &ExternalTrigger, const HTuple &Generic, const HTuple &Device, const HTuple &Port, const HTuple &LineIn, long *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:

FGWidth,FGHeight             Desired resolution of frame grabber.
Width,Height                 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.
Bits                         Desired resolution of color and/or 
                             grayvalues (typically 8 or 24 bits).
ColorSpace                   Desired color space (mostly 'rgb') for
                             colored images.
Gain                         Amplification factor for the video
                             amplifier.
ExternalTrigger              Activation of external triggering (if
                             available).
Generic                      Generic parameter (string
                             type) with frame grabber specific
                             meaning, which can be inquired via
                             ::info_framegrabber.
Device                       Device name of the frame grabber card.
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 `->` HTuple.char *
HALCON frame grabber interface, i.e. name of the corresponding DLL (WindowsNT) or shared library (UNIX).
Default value: 'VirtualFG'
Suggested values: 'BitFlow', 'DFG-BW1', 'DFG-LC', 'DT315x', 'FlashBus', 'GINGA', 'HTwain', 'IDS', 'Inspecta2', 'MatrixVision', 'Meteor', 'PCEye', 'PicPort', 'PX', 'PXC', 'Ramses1', 'Raven', 'RoadRunner', 'VideoPort', 'VirtualFG'

`FGWidth` (input_control)	extent.x `->` HTuple.long
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

`FGHeight` (input_control)	extent.y `->` HTuple.long
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

`Width` (input_control)	rectangle.extent.x `->` HTuple.long
Width of desired image part (0: `FGWidth` - 2`StartColumn`).*
Default value: 0

`Height` (input_control)	rectangle.extent.y `->` HTuple.long
Height of desired image part (0: `FGHeight` - 2`StartRow`).*
Default value: 0

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

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

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

`Bits` (input_control)	integer `->` HTuple.long
Number of bits per pixel (-1: frame grabber specific default value).
Default value: -1
Suggested values: 8, 16, 24, -1

`ColorSpace` (input_control)	string `->` HTuple.char *
The desired color space of colored images ('default': frame grabber specific default value, mostly 'rgb').
Default value: 'default'
Suggested values: 'rgb', 'yuv', 'gray', 'default'

`Gain` (input_control)	real `->` HTuple.double
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 `->` HTuple.char *
External triggering.
Default value: 'default'
List of values: 'true', 'false', 'default'

`Generic` (input_control)	string `->` HTuple.char *
Generic parameter (frame grabber specific) ('default': frame grabber specific default value).
Default value: 'default'
Suggested values: 'NTSC', 'PAL', 'SECAM', 'AUTO', 'default'

`Device` (input_control)	string `->` HTuple.char *
Device the frame grabber is linked to ('default': frame grabber specific default value).
Default value: 'default'
Suggested values: 'default'

`Port` (input_control)	integer `->` HTuple.long
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 `->` HTuple.long
Camera input line of multiplexer.
Default value: 1
Suggested values: 1, 2, 3, 4

`FGHandle` (output_control)	framegrabber `->` long *
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 H_MSG_TRUE. Otherwise an exception handling is raised.

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