HALCON 9.0 Image Acquisition Interface for DirectShow

This page provides the documentation about the HALCON DirectShow image acqusition interface for the Microsoft DirectShow application programming interface. Registered customers can download the latest revision of this interface from the MVTec WWW server.

Revision: 4.2

System Requirements

• Intel compatible PC with Windows 2000/XP/Vista/7 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 image acqusistion interface hAcqDirectShow.dll or hAcqDirectShowxl.dll, respectively.
  If you have properly installed the interface, this DLL should reside in bin\%HALCONARCH% 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 hAcqDirectShowxl.dll with hAcqDirectShow.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_data and grab_data_async not supported.

Description

Parameters for open_framegrabber():

	Name		'DirectShow'		The name of the HALCON image acquisition 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'.
	Generic		---		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).
	'disconnect_graph'		'true', 'false'		Activate/deactivate automatic disconnection of the filter graph when setting camera parameters. By default (i.e. upon opening of the capture device) the filter graph is disconnected before setting camera parameters, and reconnected immedeatly afterwards. To speed up the execution of set_framegrabber_param this behaviour can be switched off by setting 'disconnect_graph' to 'false'. Note, however, that numerous capture devices do not allow the setting of camera parameters while the filter graph is still connected. The behaviour of such devices is not predictable and might range from simply ignoring the new settings to crashes of your application! Use 'disconnect_graph' only with greatest care!
	'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. Furthermore, corresponding to the parameters supported by set_framegrabber_param, there may exist additional read-only parameters with the following postfixes:

• '_description': These parameters provide the tooltip of the corresponding parameter as a string.
• '_range': These parameters provide the minimum, maximum, stepwidth, and default values for the corresponding integer or float parameter as a tuple with 4 elements, e.g., get_framegrabber_param(..,'exposure_range',..) will return the output tuple [min,max,step,default]. Optionally, this tuple can also contain additional valid string values like 'auto' or 'manual'.
• '_values': These parameters provide the valid value list for the corresponding parameter as a tuple, e.g., get_framegrabber_param(..,'volatile_values',..) will return the output tuple ['enable','disable'].

	'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.
	'revision'		revision		The revision number of the HALCON DirectShow interface.

Release Notes

• Revision 4.2 (Aug 20, 2010):
  • In certain cases the image buffer size was calculated too large by a factor of 8. This bug has been fixed.
• Revision 4.1 (Jan 22, 2010):
  • Skipped query of the actual connector settings.
  • Adapted order within the device initialization to ensure a valid crossbar instance.
• Revision 4.0 (Dec 1, 2008):
  • HALCON 9.0 version of the interface (included in HALCON 9.0 DVD).
• Revision 3.3 (Apr 22, 2008):
  • Added read-only parameters with postfix '_description', '_range', and '_values' to enable the easy parameterization via a generic graphical user interface.
• Revision 3.2 (Aug 3, 2007):
  • Ignore Leutron Vision Video Capture and VfW driver to prevent conflicts with using the HALCON Leutron interface simultaneously.
• Revision 3.1 (Jun 29, 2007):
  • Bugfix in the internal memory allocation.
• Revision 3.0 (May 15, 2007):
  • HALCON 8.0 version of the interface (included in HALCON 8.0 DVD).
• Revision 2.10 (Jun 29, 2006):
  • Bugfix in open_framegrabber.
  • New parameter 'disconnect_graph' for faster setting of parameters.
• 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 hAcqDirectShow.dll or parhAcqDirectShow.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.