Skip to content

open_framegrabberOpenFramegrabberOpenFramegrabberopen_framegrabberT_open_framegrabber🔗

Short description🔗

open_framegrabberOpenFramegrabberOpenFramegrabberopen_framegrabberT_open_framegrabber — Open and configure an image acquisition device.

Signature🔗

open_framegrabber( string Name, extent.x HorizontalResolution, extent.y VerticalResolution, rectangle.extent.x ImageWidth, rectangle.extent.y ImageHeight, rectangle.origin.y StartRow, rectangle.origin.x StartColumn, string Field, integer BitsPerChannel, string ColorSpace, string Generic, string ExternalTrigger, string CameraType, string Device, integer Port, integer LineIn, out framegrabber AcqHandle )void OpenFramegrabber( const HTuple& Name, const HTuple& HorizontalResolution, const HTuple& VerticalResolution, const HTuple& ImageWidth, const HTuple& ImageHeight, const HTuple& StartRow, const HTuple& StartColumn, const HTuple& Field, const HTuple& BitsPerChannel, const HTuple& ColorSpace, const HTuple& Generic, const HTuple& ExternalTrigger, const HTuple& CameraType, const HTuple& Device, const HTuple& Port, const HTuple& LineIn, HTuple* AcqHandle )static void HOperatorSet.OpenFramegrabber( HTuple name, HTuple horizontalResolution, HTuple verticalResolution, HTuple imageWidth, HTuple imageHeight, HTuple startRow, HTuple startColumn, HTuple field, HTuple bitsPerChannel, HTuple colorSpace, HTuple generic, HTuple externalTrigger, HTuple cameraType, HTuple device, HTuple port, HTuple lineIn, out HTuple acqHandle )def open_framegrabber( name: str, horizontal_resolution: int, vertical_resolution: int, image_width: int, image_height: int, start_row: int, start_column: int, field: str, bits_per_channel: MaybeSequence[int], color_space: MaybeSequence[str], generic: MaybeSequence[Union[str, float, int]], external_trigger: str, camera_type: MaybeSequence[str], device: MaybeSequence[str], port: MaybeSequence[int], line_in: MaybeSequence[int] ) -> HHandle

Herror T_open_framegrabber( const Htuple Name, const Htuple HorizontalResolution, const Htuple VerticalResolution, const Htuple ImageWidth, const Htuple ImageHeight, const Htuple StartRow, const Htuple StartColumn, const Htuple Field, const Htuple BitsPerChannel, const Htuple ColorSpace, const Htuple Generic, const Htuple ExternalTrigger, const Htuple CameraType, const Htuple Device, const Htuple Port, const Htuple LineIn, Htuple* AcqHandle )

void HFramegrabber::HFramegrabber( const HString& Name, Hlong HorizontalResolution, Hlong VerticalResolution, Hlong ImageWidth, Hlong ImageHeight, Hlong StartRow, Hlong StartColumn, const HString& Field, const HTuple& BitsPerChannel, const HTuple& ColorSpace, const HTuple& Generic, const HString& ExternalTrigger, const HTuple& CameraType, const HTuple& Device, const HTuple& Port, const HTuple& LineIn )

void HFramegrabber::HFramegrabber( const HString& Name, Hlong HorizontalResolution, Hlong VerticalResolution, Hlong ImageWidth, Hlong ImageHeight, Hlong StartRow, Hlong StartColumn, const HString& Field, Hlong BitsPerChannel, const HString& ColorSpace, double Generic, const HString& ExternalTrigger, const HString& CameraType, const HString& Device, Hlong Port, Hlong LineIn )

void HFramegrabber::HFramegrabber( const char* Name, Hlong HorizontalResolution, Hlong VerticalResolution, Hlong ImageWidth, Hlong ImageHeight, Hlong StartRow, Hlong StartColumn, const char* Field, Hlong BitsPerChannel, const char* ColorSpace, double Generic, const char* ExternalTrigger, const char* CameraType, const char* Device, Hlong Port, Hlong LineIn )

void HFramegrabber::HFramegrabber( const wchar_t* Name, Hlong HorizontalResolution, Hlong VerticalResolution, Hlong ImageWidth, Hlong ImageHeight, Hlong StartRow, Hlong StartColumn, const wchar_t* Field, Hlong BitsPerChannel, const wchar_t* ColorSpace, double Generic, const wchar_t* ExternalTrigger, const wchar_t* CameraType, const wchar_t* Device, Hlong Port, Hlong LineIn ) (Windows only)

public HFramegrabber( string name, int horizontalResolution, int verticalResolution, int imageWidth, int imageHeight, int startRow, int startColumn, string field, HTuple bitsPerChannel, HTuple colorSpace, HTuple generic, string externalTrigger, HTuple cameraType, HTuple device, HTuple port, HTuple lineIn )

public HFramegrabber( string name, int horizontalResolution, int verticalResolution, int imageWidth, int imageHeight, int startRow, int startColumn, string field, int bitsPerChannel, string colorSpace, double generic, string externalTrigger, string cameraType, string device, int port, int lineIn )

void HFramegrabber::OpenFramegrabber( const HString& Name, Hlong HorizontalResolution, Hlong VerticalResolution, Hlong ImageWidth, Hlong ImageHeight, Hlong StartRow, Hlong StartColumn, const HString& Field, const HTuple& BitsPerChannel, const HTuple& ColorSpace, const HTuple& Generic, const HString& ExternalTrigger, const HTuple& CameraType, const HTuple& Device, const HTuple& Port, const HTuple& LineIn )

void HFramegrabber::OpenFramegrabber( const HString& Name, Hlong HorizontalResolution, Hlong VerticalResolution, Hlong ImageWidth, Hlong ImageHeight, Hlong StartRow, Hlong StartColumn, const HString& Field, Hlong BitsPerChannel, const HString& ColorSpace, double Generic, const HString& ExternalTrigger, const HString& CameraType, const HString& Device, Hlong Port, Hlong LineIn )

void HFramegrabber::OpenFramegrabber( const char* Name, Hlong HorizontalResolution, Hlong VerticalResolution, Hlong ImageWidth, Hlong ImageHeight, Hlong StartRow, Hlong StartColumn, const char* Field, Hlong BitsPerChannel, const char* ColorSpace, double Generic, const char* ExternalTrigger, const char* CameraType, const char* Device, Hlong Port, Hlong LineIn )

void HFramegrabber::OpenFramegrabber( const wchar_t* Name, Hlong HorizontalResolution, Hlong VerticalResolution, Hlong ImageWidth, Hlong ImageHeight, Hlong StartRow, Hlong StartColumn, const wchar_t* Field, Hlong BitsPerChannel, const wchar_t* ColorSpace, double Generic, const wchar_t* ExternalTrigger, const wchar_t* CameraType, const wchar_t* Device, Hlong Port, Hlong LineIn ) (Windows only)

void HFramegrabber.OpenFramegrabber( string name, int horizontalResolution, int verticalResolution, int imageWidth, int imageHeight, int startRow, int startColumn, string field, HTuple bitsPerChannel, HTuple colorSpace, HTuple generic, string externalTrigger, HTuple cameraType, HTuple device, HTuple port, HTuple lineIn )

void HFramegrabber.OpenFramegrabber( string name, int horizontalResolution, int verticalResolution, int imageWidth, int imageHeight, int startRow, int startColumn, string field, int bitsPerChannel, string colorSpace, double generic, string externalTrigger, string cameraType, string device, int port, int lineIn )

Description🔗

The operator open_framegrabberOpenFramegrabber opens and configures the chosen image acquisition device. During this process, the connection to the image acquisition device is tested, the image acquisition device is locked for other processes, and, if necessary, memory is reserved for the data buffers. The actual image grabbing is done via the operators grab_imageGrabImage, grab_dataGrabData, grab_image_asyncGrabImageAsync, or grab_data_asyncGrabDataAsync. If the image acquisition device is not needed anymore, it should be closed via the operator close_framegrabberCloseFramegrabber, releasing it for other processes. Some image acquisition devices allow to open several instances of the same image acquisition device class.

For all parameters image acquisition device-specific default values can be chosen explicitly (see the parameter description below). Additional information for a specific image acquisition device is available via info_framegrabberInfoFramegrabber. A comprehensive documentation of all image acquisition device-specific parameters can be found in the corresponding interface documentation in the directory doc/html/reference/acquisition.

The meaning of the particular parameters is as follows:

The operator open_framegrabberOpenFramegrabber returns a handle (AcqHandleacqHandleacq_handle) to the opened image acquisition device.

Attention🔗

Due to the multitude of supported image acquisition devices, open_framegrabberOpenFramegrabber contains a large number of parameters. However, not all parameters are needed for a specific image acquisition device.

For a multithreaded application, info_framegrabberInfoFramegrabber, open_framegrabberOpenFramegrabber, and close_framegrabberCloseFramegrabber are executed exclusively. Thus, they block the concurrent execution of each other, but run in parallel with all non-exclusive operators outside of this group.

On Windows Systems, error dialog boxes from the operating system can occur when dependency modules of the interface are not found, e.g., the according SDK was not installed. The occurrence of the error boxes can be controlled by setting Windows’ Error Mode. Please refer to the description of SetErrorMode within the Windows MSDN documentation.

Execution information🔗

Execution information

  • Multithreading type: reentrant (runs in parallel with non-exclusive operators).

  • Multithreading scope: global (may be called from any thread).

  • Processed without parallelization.

This operator returns a handle. Note that the state of an instance of this handle type may be changed by specific operators even though the handle is used as an input parameter by those operators.

Parameters🔗

Namenamename (input_control) string → (string)HTuple (HString)HTuple (string)strHtuple (char*)

HALCON image acquisition interface name, i.e., name of the corresponding DLL (Windows) or shared library (Linux).

Default: 'File'"File"
Suggested values: 'ABS', 'ADLINK', 'AlkUSB3', 'Andor', 'BitFlow', 'Crevis', 'DahengCAM', 'DirectFile', 'DirectShow', 'Ensenso-NxLib', 'File', 'FocalSpecLCI', 'GenICamTL', 'GigEVision2', 'GingaDG', 'Ginga++', 'GStreamer', 'heliCamC3', 'KeyenceLJ', 'KeyenceVJ', 'LinX', 'LPS36', 'LuCam', 'MatrixVisionAcquire', 'MediaFoundation', 'Metavision', 'MILLite', 'MultiCam', 'O3D3xx', 'Opteon', 'PhoXi', 'PixeLINK', 'RealSense', 'SaperaLT', 'Sentech', 'SICK-3DCamera', 'SICK-ScanningRuler', 'SiliconSoftware', 'TWAIN', 'uEye', 'USB3Vision', 'Video4Linux2', 'VRmUsbCam'"ABS", "ADLINK", "AlkUSB3", "Andor", "BitFlow", "Crevis", "DahengCAM", "DirectFile", "DirectShow", "Ensenso-NxLib", "File", "FocalSpecLCI", "GenICamTL", "GigEVision2", "GingaDG", "Ginga++", "GStreamer", "heliCamC3", "KeyenceLJ", "KeyenceVJ", "LinX", "LPS36", "LuCam", "MatrixVisionAcquire", "MediaFoundation", "Metavision", "MILLite", "MultiCam", "O3D3xx", "Opteon", "PhoXi", "PixeLINK", "RealSense", "SaperaLT", "Sentech", "SICK-3DCamera", "SICK-ScanningRuler", "SiliconSoftware", "TWAIN", "uEye", "USB3Vision", "Video4Linux2", "VRmUsbCam"

HorizontalResolutionhorizontalResolutionhorizontal_resolution (input_control) extent.x → (integer)HTuple (Hlong)HTuple (int / long)intHtuple (Hlong)

Desired horizontal resolution of image acquisition interface (absolute value or 11 for full resolution, 22 for half resolution, or 44 for quarter resolution).

Default: 11
Suggested values: 1, 2, 4, 1600, 1280, 768, 640, 384, 320, 192, 160, -11, 2, 4, 1600, 1280, 768, 640, 384, 320, 192, 160, -1

VerticalResolutionverticalResolutionvertical_resolution (input_control) extent.y → (integer)HTuple (Hlong)HTuple (int / long)intHtuple (Hlong)

Desired vertical resolution of image acquisition interface (absolute value or 11 for full resolution, 22 for half resolution, or 44 for quarter resolution).

Default: 11
Suggested values: 1, 2, 4, 1200, 1024, 576, 480, 288, 240, 144, 120, -11, 2, 4, 1200, 1024, 576, 480, 288, 240, 144, 120, -1

ImageWidthimageWidthimage_width (input_control) rectangle.extent.x → (integer)HTuple (Hlong)HTuple (int / long)intHtuple (Hlong)

Width of desired image part (absolute value or 00 for HorizontalResolutionhorizontalResolutionhorizontal_resolution - 2*StartColumnstartColumnstart_column).

Default: 00
Suggested values: 0, -10, -1

ImageHeightimageHeightimage_height (input_control) rectangle.extent.y → (integer)HTuple (Hlong)HTuple (int / long)intHtuple (Hlong)

Height of desired image part (absolute value or 00 for VerticalResolutionverticalResolutionvertical_resolution - 2*StartRowstartRowstart_row).

Default: 00
Suggested values: 0, -10, -1

StartRowstartRowstart_row (input_control) rectangle.origin.y → (integer)HTuple (Hlong)HTuple (int / long)intHtuple (Hlong)

Line number of upper left corner of desired image part (or border height if ImageHeightimageHeightimage_height = 00).

Default: 00
Suggested values: 0, -10, -1

StartColumnstartColumnstart_column (input_control) rectangle.origin.x → (integer)HTuple (Hlong)HTuple (int / long)intHtuple (Hlong)

Column number of upper left corner of desired image part (or border width if ImageWidthimageWidthimage_width = 00).

Default: 00
Suggested values: 0, -10, -1

Fieldfieldfield (input_control) string → (string)HTuple (HString)HTuple (string)strHtuple (char*)

Desired half image or full image.

Default: 'default'"default"
Suggested values: 'first', 'second', 'next', 'interlaced', 'progressive', 'default'"first", "second", "next", "interlaced", "progressive", "default"

BitsPerChannelbitsPerChannelbits_per_channel (input_control) integer(-array) → (integer)HTuple (Hlong)HTuple (int / long)MaybeSequence[int]Htuple (Hlong)

Number of transferred bits per pixel and image channel (-1: device-specific default value).

Default: -1-1
Suggested values: 5, 8, 10, 12, 14, 16, -15, 8, 10, 12, 14, 16, -1

ColorSpacecolorSpacecolor_space (input_control) string(-array) → (string)HTuple (HString)HTuple (string)MaybeSequence[str]Htuple (char*)

Output color format of the grabbed images, typically 'gray'"gray" or 'raw'"raw" for single-channel or 'rgb'"rgb" or 'yuv'"yuv" for three-channel images ('default'"default": device-specific default value).

Default: 'default'"default"
Suggested values: 'gray', 'raw', 'rgb', 'yuv', 'default'"gray", "raw", "rgb", "yuv", "default"

Genericgenericgeneric (input_control) string(-array) → (real / string / integer)HTuple (double / HString / Hlong)HTuple (double / string / int / long)MaybeSequence[Union[str, float, int]]Htuple (double / char* / Hlong)

Generic parameter with device-specific meaning.

Default: -1-1

ExternalTriggerexternalTriggerexternal_trigger (input_control) string → (string)HTuple (HString)HTuple (string)strHtuple (char*)

External triggering.

Default: 'default'"default"
List of values: 'default', 'false', 'true'"default", "false", "true"

CameraTypecameraTypecamera_type (input_control) string(-array) → (string)HTuple (HString)HTuple (string)MaybeSequence[str]Htuple (char*)

Type of used camera ('default'"default": device-specific default value).

Default: 'default'"default"
Suggested values: 'ntsc', 'pal', 'auto', 'default'"ntsc", "pal", "auto", "default"

Devicedevicedevice (input_control) string(-array) → (string)HTuple (HString)HTuple (string)MaybeSequence[str]Htuple (char*)

Device the image acquisition device is connected to ('default'"default": device-specific default value).

Default: 'default'"default"
Suggested values: '-1', '0', '1', '2', '3', 'default'"-1", "0", "1", "2", "3", "default"

Portportport (input_control) integer(-array) → (integer)HTuple (Hlong)HTuple (int / long)MaybeSequence[int]Htuple (Hlong)

Port the image acquisition device is connected to (-1-1: device-specific default value).

Default: -1-1
Suggested values: 0, 1, 2, 3, -10, 1, 2, 3, -1

LineInlineInline_in (input_control) integer(-array) → (integer)HTuple (Hlong)HTuple (int / long)MaybeSequence[int]Htuple (Hlong)

Camera input line of multiplexer (-1-1: device-specific default value).

Default: -1-1
Suggested values: 1, 2, 3, 4, -11, 2, 3, 4, -1

AcqHandleacqHandleacq_handle (output_control) framegrabber → (handle)HTuple (HHandle)HFramegrabber, HTuple (IntPtr)HHandleHtuple (handle)

Handle of the opened image acquisition device.

Example🔗

(HDevelop)

* Select a suitable image acquisition interface name AcqName
info_framegrabber(AcqName,'port',Information,Values)
* Open image acquisition device using the default settings, see
* documentation of the actually used interface for more details
open_framegrabber(AcqName,1,1,0,0,0,0,'default',-1,'default',-1.0, \
                  'default','default','default',-1,-1,AcqHandle)
grab_image(Image,AcqHandle)
close_framegrabber(AcqHandle)

Result🔗

If the parameter values are correct and the desired image acquisition device could be opened, open_framegrabberOpenFramegrabber returns the value 2 (H_MSG_TRUE). Otherwise an exception is raised.

Combinations with other operators🔗

Combinations

Possible predecessors

info_framegrabberInfoFramegrabber

Possible successors

grab_imageGrabImage, grab_dataGrabData, grab_image_startGrabImageStart, grab_image_asyncGrabImageAsync, grab_data_asyncGrabDataAsync, set_framegrabber_paramSetFramegrabberParam, set_framegrabber_callbackSetFramegrabberCallback

See also

info_framegrabberInfoFramegrabber, close_framegrabberCloseFramegrabber, grab_imageGrabImage

Module🔗

Foundation