HALCON 7.1 Frame Grabber Interface for DirectShow
This page provides the documentation about the HALCON frame grabber interface HFGDirectShow.dll for the Microsoft DirectShow application programming interface. Registered customers can download the latest revision of this interface from the MVTec WWW server.
Revision: 2.10
System Requirements
- Intel compatible PC with Windows 2000 / XP and DirectX 8.1 or later installed. You can check your installed DirectX version by running the dxdiag diagnosis program. Note that the HALCON DirectShow interface does not run under Windows NT 4.0.
- A WDM compatible capture device and a successfully installed WDM driver for that device.
-
HALCON frame grabber interface HFGDirectShow.dll or
parHFGDirectShow.dll, respectively.
If you have properly installed the interface, this DLL should reside in bin\i586-nt4 (32 bit Windows) or bin\x64-xp (64 bit Windows) within the HALCON base directory %HALCONROOT% you have chosen during the installation of HALCON. You don't need to register this DLL manually. Instead, upon the first call to open_framegrabber() the DLL performs the necessary steps itself. However, note that it causes no error if the registration fails (e.g., because the application does not have sufficient rights to write to the registry). Thus it is possible to use parHFGDirectShow.dll with HFGDirectShow.dll still registered, or vice versa, which might cause serious crashes! You can use the operator set_system('do_low_error', 'true') to show warnings in case the registration fails.
Features
- Multiple capture devices.
- Synchronous and asynchronous grabbing.
- External trigger.
- Realtime grabbing (e.g., 30 frames per second for NTSC).
- Software control of a variety of camera parameters.
Limitations
- Only RGB8, RGB555, RGB565, RGB24, RGB32, Y800, UYVY, Y411, and Y41P video subtypes supported (see below for the usage for FOURCC codes), see also Microsoft DirectShow documentation: Video Subtypes.
- Image scaling and cropping not supported.
- No LUTs.
- grab_region and grab_region_async not supported.
Description
Parameters for open_framegrabber():
| Name | 'DirectShow' | The name of the HALCON frame grabber interface. | |||
| HorizontalResolution | --- | Ignored. | |||
| VerticalResolution | --- | Ignored. | |||
| ImageWidth | --- | Ignored. | |||
| ImageHeight | --- | Ignored. | |||
| StartRow | --- | Ignored. | |||
| StartColumn | --- | Ignored. | |||
| Field | --- | Ignored. | |||
| BitsPerChannel | --- | Ignored. | |||
| ColorSpace | 'gray', 'rgb' | Specify the desired color space and thus the number of image channels of the resulting HALCON image. Note that specifying 'gray' does not influence the used media type of the camera, i.e., the conversion from RGB to gray-value images is done in the HALCON DirectShow interface. Default: 'rgb'. | |||
| Gain | --- | Ignored. | |||
| ExternalTrigger | 'true', 'false' | Activate/deactivate external triggering. | |||
| CameraType | '[video norm] type (widthxheight)', 'default' |
The desired video format as it should be returned by
info_framegrabber(...,'camera_type',...),
e.g., 'NTSC RGB24 (640x480)'. video norm can be one of
the following: 'PAL', 'NTSC'. Omit video norm, if the device
does not support analog video. type can be one of the
following: RGB8, RGB555, RGB565, RGB24, RGB32, Y800, UYVY, Y411, or
Y41P.
width and height specify the desired image dimensions.
Alternatively, you can pass 'default'. Then the first generally
acceptable video format that the capture device proposes is
chosen. Note that when the video source (i.e., the capture device) and the video destination (i.e., the HALCON DirectShow interface) do not agree on a video format, DirectShow automatically tries to establish a connection via a transformation filter (e.g., a codec). This behavior is blocked by the HALCON DirectShow interface for all camera types but 'default'! Default: 'default'. Additionally, type can also be a four-character code (FOURCC). In that case, the output data of the capture device is decoded by a suitable codec, which, of course, has to be installed properly (see also Microsoft DirectShow documentation: Working with Codecs). Attention: MVTec does by no means encourage the use of FOURCC video formats, and also does not guarantee that the HALCON DirectShow interface works correctly with all FOURCC video formats. Please note that FOURCC video formats are not returned by info_framegrabber(...,'camera_type',...). To obtain the available FOURCC video formats you have to use, e.g., the Microsoft amcap.exe example application. |
|||
| Device | '0', '1', '2', ..., '9', 'name' | The number of the capture device (passed as a string!). Alternatively, you can pass the name of the capture device as it is returned by info_framegrabber(...,'info_boards',...). Default: '0'. | |||
| Port | number | The Port parameter specifies the number of the capture device's output pin as it is returned by get_framegrabber_param(...,'available_pins',...). If you pass -1, the system automatically selects a suitable pin. Default: -1. | |||
| LineIn | --- | Ignored. | |||
Parameters for set_framegrabber_param():
Note that most of the following parameters (and also the valid parameter values!) depend on the capabilities of the used capture device and/or connected camera.
Many parameters (like 'brightness' and 'white_balance') can be set by either a valid integer value or by specifying one of the following strings:
- 'auto' means that the device/camera controls the value automatically by itself
- 'off' disables the specified property
- 'on' enables the specified property
| 'backlight_compensation' | 'off', 'on' | Backlight compensation. If the capture device does not support backlight compensation, H_ERR_FGPARAM is returned (or an empty tuple in the corresponding call to get_framegrabber_param, respectively). | |||
| 'brightness' | min ... max (long), 'auto' | Brightness. 'auto' indicates that the brightness is adjusted automatically. If the capture device does not support brightness adjustment, H_ERR_FGPARAM is returned (or an empty tuple in the corresponding call to get_framegrabber_param, respectively). | |||
| 'color_enable' | 'off', 'on' | Color enable. If the capture device does not support color enable, H_ERR_FGPARAM is returned (or an empty tuple in the corresponding call to get_framegrabber_param, respectively). | |||
| 'connector' | number | Physical connector. If the capture device does not support physical connectors, H_ERR_FGPARAM is returned (or an empty tuple in the corresponding call to get_framegrabber_param, respectively). A list of the available physical connectors can be obtained by calling get_framegrabber_param(...,'available_connectors',...). | |||
| 'contrast' | min ... max (long), 'auto' | Contrast. 'auto' indicates that the contrast is adjusted automatically. If the capture device does not support contrast adjustment, H_ERR_FGPARAM is returned (or an empty tuple in the corresponding call to get_framegrabber_param, respectively). | |||
| 'do_force_trigger' | --- | Forces an event trigger from the application, when using the external triger. This might be useful for testing purposes. | |||
| 'do_open_dialog' | dialog | Opens a dialog (property page) provided by the capture device. If the capture device does not support the specified (or any) dialog, H_ERR_FGPARAM is returned. A list of the available dialogs can be obtained by calling get_framegrabber_param(...,'available_dialogs',...). | |||
| 'do_stop_grabbing' | --- | Stops the continuous grabbing of images. Note that stopping of grabbing inevitably results in the termination of the capture thread (and restarting grabbing in creating a new one respectively), which is a rather time consuming operation and might slow down your application considerably! | |||
| 'exposure' | min ... max (long), 'auto' | Exposure time. 'auto' indicates that the exposure time is adjusted automatically. If the capture device does not support the setting of the exposure time, H_ERR_FGPARAM is returned (or an empty tuple in the corresponding call to get_framegrabber_param, respectively). | |||
| 'external_trigger' | 'true', 'false' | Activate/deactivate external triggering. | |||
| 'flip_horizontal' | 'false','true' | Horizontal image flipping. If the capture device does not support horizontal flipping, H_ERR_FGPARAM is returned (or an empty tuple in the corresponding call to get_framegrabber_param, respectively). | |||
| 'flip_vertical' | 'false','true' | Vertical image flipping. If the capture device does not support vertical flipping, H_ERR_FGPARAM is returned (or an empty tuple in the corresponding call to get_framegrabber_param, respectively). | |||
| 'focus' | min ... max (long), 'auto' | Focus. 'auto' indicates that the focus is adjusted automatically. If the capture device does not support focus adjustment, H_ERR_FGPARAM is returned (or an empty tuple in the corresponding call to get_framegrabber_param, respectively). | |||
| 'frame_rate' | 0.0 ... 60.0 (float) | Desired frame rate in frames per second (as a float value!). A list of available frame rates can be obtained by calling get_framegrabber_param(...,'available_frame_rates',...). Default: 15.0. | |||
| 'grab_timeout' | msec | Specify the desired timeout (milliseconds passed as an integer) for aborting a pending grab. Default: 5000. | |||
| 'gamma' | min ... max (long), 'auto' | Gamma. 'auto' indicates that the gamma is adjusted automatically. If the capture device does not support gamma adjustment, H_ERR_FGPARAM is returned (or an empty tuple in the corresponding call to get_framegrabber_param, respectively). | |||
| 'hue' | min ... max (long), 'auto' | Hue. 'auto' indicates that the hue is adjusted automatically. If the capture device does not support hue adjustment, H_ERR_FGPARAM is returned (or an empty tuple in the corresponding call to get_framegrabber_param, respectively). | |||
| 'iris' | min ... max (long), 'auto' | Iris. 'auto' indicates that the iris is adjusted automatically. If the capture device does not support iris adjustment, H_ERR_FGPARAM is returned (or an empty tuple in the corresponding call to get_framegrabber_param, respectively). | |||
| 'pan' | min ... max (long), 'auto' | Pan. 'auto' indicates that the pan setting is adjusted automatically. If the capture device does not support pan setting, H_ERR_FGPARAM is returned (or an empty tuple in the corresponding call to get_framegrabber_param, respectively). | |||
| 'roll' | min ... max (long), 'auto' | Roll. 'auto' indicates that the roll setting is adjusted automatically. If the capture device does not support roll setting, H_ERR_FGPARAM is returned (or an empty tuple in the corresponding call to get_framegrabber_param, respectively). | |||
| 'saturation' | min ... max (long), 'auto' | Saturation. 'auto' indicates that the saturation is adjusted automatically. If the capture device does not support saturation adjustment, H_ERR_FGPARAM is returned (or an empty tuple in the corresponding call to get_framegrabber_param, respectively). | |||
| 'sharpness' | min ... max (long), 'auto' | Sharpness. 'auto' indicates that the sharpness is adjusted automatically. If the capture device does not support sharpness adjustment, H_ERR_FGPARAM is returned (or an empty tuple in the corresponding call to get_framegrabber_param, respectively). | |||
| 'tilt' | min ... max (long), 'auto' | Tilt. 'auto' indicates that the tilt setting is adjusted automatically. If the capture device does not support tilt setting, H_ERR_FGPARAM is returned (or an empty tuple in the corresponding call to get_framegrabber_param, respectively). | |||
| 'video_gain' | min ... max (long), 'auto' | Gain. 'auto' indicates that the gain is adjusted automatically. If the capture device does not support gain adjustment, H_ERR_FGPARAM is returned (or an empty tuple in the corresponding call to get_framegrabber_param, respectively). | |||
| 'white_balance' | min ... max (long), 'auto' | White balance. 'auto' indicates that the white balance is adjusted automatically. If the capture device does not support white balance adjustment, H_ERR_FGPARAM is returned (or an empty tuple in the corresponding call to get_framegrabber_param, respectively). | |||
| 'zoom' | min ... max (long), 'auto' | Zoom. 'auto' indicates that the zoom setting is adjusted automatically. If the capture device does not support zoom setting, H_ERR_FGPARAM is returned (or an empty tuple in the corresponding call to get_framegrabber_param, respectively). | |||
Parameters for get_framegrabber_param():
Additional parameters supported by get_framegrabber_param only. Note that all parameters supported by set_framegrabber_param can also be accessed by get_framegrabber_param.
| 'available_connectors' | [connector_type_1, connector_type_2,...] | Types of the physical connectors of the device. | |||
| 'available_dialogs' | [dialog_1, dialog_2,...] | Dialogs (property pages) provided by the device. | |||
| 'available_frame_rates' | [frame_rate_1, frame_rate_2,...] | Currently available frame rates in frames per second (as float values!). This list will be empty, if the current device does not support the setting of frame rates. | |||
| 'available_pin_names' | [pin_name_1, pin_name_2,...] | Names of the connectable pins of the source filter. Note that only pins will be displayed which deliver video data. | |||
| 'available_pins' | [pin_index_1, pin_index_2,...] | Indices of the connectable pins of the source filter (as to be passed to Port in open_framegrabber). Note that only pins will be displayed which deliver video data. | |||
| 'backlight_compensation_range' | ['off', 'on', default (string)] | Possible range for backlight compensation. If backlight compensation is activated by default, default is 'on', otherwise 'off'. If the capture device does not support backlight compensation, an empty tuple is returned. | |||
| 'brightness_range' | [min (long), max (long), step (long), default (long), <'auto'>] | Possible range for brightness. If the capture device supports automatic brightness adjustment, the return tuple has 'auto' as its fifth element, otherwise it contains only four elements. If the capture device does not support brightness adjustment, an empty tuple is returned. | |||
| 'color_enable_range' | ['off', 'on', default (string)] | Possible range for color enable. If color is enabled by default, default is 'on', otherwise 'off'. If the capture device does not support color enable/disable, an empty tuple is returned. | |||
| 'contrast_range' | [min (long), max (long), step (long), default (long), <'auto'>] | Possible range for contrast. If the capture device supports automatic contrast adjustment, the return tuple has 'auto' as its fifth element, otherwise it contains only four elements. If the capture device does not support contrast adjustment, an empty tuple is returned. | |||
| 'exposure_range' | [min (long), max (long), step (long), default (long), <'auto'>] | Possible range for exposure. If the capture device supports automatic exposure time adjustment, the return tuple has 'auto' as its fifth element, otherwise it contains only four elements. If the capture device does not support exposure time adjustment, an empty tuple is returned. | |||
| 'external_trigger_range' | ['false', 'true', 'false'] | Possible range for external triggering. If the capture device does not support external triggering, an empty tuple is returned. | |||
| 'flip_horizontal_range' | ['false', 'true', 'false'] | Possible range for horizontal flipping. If the capture device does not support horizontal flipping, an empty tuple is returned. | |||
| 'flip_vertical_range' | ['false', 'true', 'false'] | Possible range for vertical flipping. If the capture device does not support vertical flipping, an empty tuple is returned. | |||
| 'focus_range' | [min (long), max (long), step (long), default (long), <'auto'>] | Possible range for focus. If the capture device supports automatic focus adjustment, the return tuple has 'auto' as its fifth element, otherwise it contains only four elements. If the capture device does not support focus adjustment, an empty tuple is returned. | |||
| 'gamma_range' | [min (long), max (long), step (long), default (long), <'auto'>] | Possible range for gamma. If the capture device supports automatic gamma adjustment, the return tuple has 'auto' as its fifth element, otherwise it contains only four elements. If the capture device does not support gamma adjustment, an empty tuple is returned. | |||
| 'hue_range' | [min (long), max (long), step (long), default (long), <'auto'>] | Possible range for hue. If the capture device supports automatic hue adjustment, the return tuple has 'auto' as its fifth element, otherwise it contains only four elements. If the capture device does not support hue adjustment, an empty tuple is returned. | |||
| 'iris_range' | [min (long), max (long), step (long), default (long), <'auto'>] | Possible range for iris. If the capture device supports automatic iris adjustment, the return tuple has 'auto' as its fifth element, otherwise it contains only four elements. If the capture device does not support iris adjustment, an empty tuple is returned. | |||
| 'pan_range' | [min (long), max (long), step (long), default (long), <'auto'>] | Possible range for pan. If the capture device supports automatic pan adjustment, the return tuple has 'auto' as its fifth element, otherwise it contains only four elements. If the capture device does not support pan adjustment, an empty tuple is returned. | |||
| 'revision' | revision | The revision number of the HALCON DirectShow interface. | |||
| 'roll_range' | [min (long), max (long), step (long), default (long), <'auto'>] | Possible range for roll. If the capture device supports automatic roll adjustment, the return tuple has 'auto' as its fifth element, otherwise it contains only four elements. If the capture device does not support roll adjustment, an empty tuple is returned. | |||
| 'saturation_range' | [min (long), max (long), step (long), default (long), <'auto'>] | Possible range for saturation. If the capture device supports automatic saturation adjustment, the return tuple has 'auto' as its fifth element, otherwise it contains only four elements. If the capture device does not support saturation adjustment, an empty tuple is returned. | |||
| 'sharpness_range' | [min (long), max (long), step (long), default (long), <'auto'>] | Possible range for sharpness. If the capture device supports automatic sharpness adjustment, the return tuple has 'auto' as its fifth element, otherwise it contains only four elements. If the capture device does not support sharpness adjustment, an empty tuple is returned. | |||
| 'tilt_range' | [min (long), max (long), step (long), default (long), <'auto'>] | Possible range for tilt. If the capture device supports automatic tilt adjustment, the return tuple has 'auto' as its fifth element, otherwise it contains only four elements. If the capture device does not support tilt adjustment, an empty tuple is returned. | |||
| 'video_gain_range' | [min (long), max (long), step (long), default (long), <'auto'>] | Possible range for gain. If the capture device supports automatic gain adjustment, the return tuple has 'auto' as its fifth element, otherwise it contains only four elements. If the capture device does not support gain adjustment, an empty tuple is returned. | |||
| 'white_balance_range' | [min (long), max (long), step (long), default (long), <'auto'>] | Possible range for white balance. If the capture device supports automatic white balance adjustment, the return tuple has 'auto' as its fifth element, otherwise it contains only four elements. If the capture device does not support white balance adjustment, an empty tuple is returned. | |||
| 'zoom_range' | [min (long), max (long), step (long), default (long), <'auto'>] | Possible range for zoom. If the capture device supports automatic zoom adjustment, the return tuple has 'auto' as its fifth element, otherwise it contains only four elements. If the capture device does not support zoom adjustment, an empty tuple is returned. | |||
Release Notes
-
Revision 2.10 (Aug 3, 2007):
- Bugfix in open_framegrabber.
- Ignore Leutron Vision Video Capture and VfW driver to prevent conflicts with using the HALCON Leutron interface simultaneously.
-
Revision 2.9 (Jan 17, 2006):
- Bugfix in info_framegrabber(...,'camera_type',...).
- Allow usage of FOURCC codes for the CameraType parameter in open_framegrabber.
-
Revision 2.8 (Sep 9, 2005):
- 64 bit Windows version available.
- Manual registration of HFGDirectShow.dll or parHFGDirectShow.dll no longer necessary.
- Bugfix in info_framegrabber(...,'camera_type',...).
-
Revision 2.7 (Jul 27, 2005):
- HALCON 7.1 version of the interface (included in HALCON 7.1 CD).
- Speed-up for acquisition of RGB images (avoiding cache alignment failures when converting the interleaved image data into HALCON image objects).
-
Revision 2.6 (Jul 19, 2004):
- Parallel version available.
-
Revision 2.5 (Jul 7, 2004):
- Extension to allow top-down bitmaps for RGB8, RGB15, RGB16, RGB24, and RGB32 video subtypes.
- Bugfix: Faulty reference count corrected.
-
Revision 2.4 (Dec 3, 2003):
- Bugfix in set_framegrabber_param.
-
Revision 2.3 (Sep 15, 2003):
- HALCON 7.0 version of the interface (included in HALCON 7.0 CD).
- New video subtypes UYVY, Y411, and Y41P supported.
- New parameters 'available_dialogs' and 'do_open_dialog' for using the property pages provided by a capture device.
- Extension to allow setting of parameters for capture devices that change their settings only if the source filter is not connected.
-
Revision 2.2 (May 23, 2003):
- Extension to allow enabling the external trigger for capture devices that change the IAMVideoControl interface settings only if the source filter is not yet connected.
-
Revision 2.1 (Dec 4, 2002):
- New video subtype Y800 supported.
- New parameters 'external_trigger', 'external_trigger_range' and 'do_force_trigger' for external triggering.
- New parameters 'connector', and 'available_connectors' for video input selection.
- New parameters 'pan', 'tilt', 'roll', 'zoom', 'exposure', 'iris', 'focus', 'pan_range', 'tilt_range', 'roll_range', 'zoom_range', 'exposure_range', 'iris_range', and 'focus_range' for further control of the camera.
- New parameters 'flip_horizontal', 'flip_vertical', 'flip_horizontal_range' and 'flip_vertical_range' for image flipping.
-
Revision 2.0 (Sep 30, 2002):
- First official release.
