HALCON 8.0 Image Acquisition Interface for VRmagic Imaging Devices

This page provides the documentation of the HALCON VRmUsbCam interface for the imaging devices from VRmagic. Registered customers can download the latest revision of this interface from the MVTec WWW server.

Revision: 3.2

System Requirements

• Intel compatible PC with Windows 2000/XP/Vista/7, or Windows x64 Editions via WOW64.
• Successfully installed VRmUsbCam driver vrmusb.sys (VRmUsbCam SDK version 3.13 or higher).
  If you do not have this driver version, please contact VRmagic or the vendor from which you bought the camera.
• HALCON image acquisition interface hAcqVRmUsbCam.dll or parhAcqVRmUsbCam.dll, respectively.
  If you have properly installed the interface, both DLLs should reside in bin\%HALCONARCH% within the HALCON base directory %HALCONROOT% you have chosen during the installation of HALCON.

Features

• Multiple cameras.
• Synchronous and asynchronous grabbing.
• Cropping of image parts.
• Generic access to all camera-specific parameters.
• External trigger.

Limitations

• grab_data and grab_data_async not supported.
• No LUTs.
• No support for 10 bpp images.

Description

Parameters for open_framegrabber():

	Name		'VRmUsbCam'		The name of the HALCON image acquisition interface.
	HorizontalResolution		---		Ignored.
	VerticalResolution		---		Ignored.
	ImageWidth		0		The width of the desired image part ('0' stands for the complete image). Default: 0.
	ImageHeight		0		The height of the desired image part ('0' stands for the complete image). Default: 0.
	StartRow		0		The row coordinate of the upper left pixel within the desired image part ('0' obviously results in delivering the complete image). Default: 0.
	StartColumn		0		The column coordinate of the upper left pixel within the desired image part ('0' obviously results in delivering the complete image). Default: 0.
	Field		---		Ignored.
	BitsPerChannel		8		The number of significant bits per channel. Currently, only 8 bpp images are supported. Default: 8.
	ColorSpace		'default', 'gray', 'rgb'		Sets the desired color space of the resulting HALCON image. 'default' means to adapt the camera setting. Default: 'default'.
	Generic		---		Ignored.
	ExternalTrigger		'true', 'false'		Activate/deactivate external triggering. Default: 'false'.
	CameraType		'source_format', 'default'		This parameter is used to specify the desired camera source format. Default: 'default'.
	Device		'device', 'default'		The unique device string of the desired camera as returned by info_framegrabber('VRmUsbCam','info_boards',...). Default: 'default' (searches for the first unused camera).
	Port		---		Ignored.
	LineIn		---		Ignored.

Parameters for set_framegrabber_param():

Note that most parameters of this interface are generic, i.e., all actually available parameters for a specific camera can be queried directly from the camera by calling get_framegrabber_param(...,'available_param_names',...).

	'do_delete_config'		config_id		Deletes the configuration from the specified device.
	'do_enable_logging'		---		Switches on internal VRmUsbCam logging to \"vrmusbcam.log\".
	'do_force_trigger'		---		Simulates external trigger (only in triggered modes).
	'do_hide_property_page'		---		Hides the settings dialog (property page) of the device if currently showed.
	'do_load_config_from'		config_id		Loads the configuration from the specified device.
	'do_reload_config'		---		Reloads the current configuration from the device.
	'do_save_config'		---		Saves the current configuration to the device.
	'do_save_config_to'		config_id		Saves the configuration to the specified device.
	'do_show_property_page'		[left,top,width,height]		Shows the settings dialog (property page) of the device (params: (opt.) window position and size).
	'image_height'		height		Dynamically change the current image height of the grabbed image.
	'image_width'		width		Dynamically change the current image width of the grabbed image.

Parameters for get_framegrabber_param():

Additional parameters supported by get_framegrabber_param only. Note that all parameters supported by set_framegrabber_param except the ones with prefix 'do_' 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_param_descriptions'		descriptions		Returns a list containing additional information about all parameters. The order of the entries is equal to the order of the parameter names returned by 'available_param_names'.
	'available_param_names'		parameters		Returns a list containing the names of all available parameters.
	'grab_async_mode'		'freerunning', 'freerunning_sequential', 'triggered_internal'		Device grab mode to use when async grabbing is selected.
	'image_available'		0, 1		Returns the status of the last asynchronous grab command. The value 1 means that the image is already acquired and thus can be fetched by grab_image_async without delay.
	'ip_address'		string		Returns the IP address in case of Ethernet-based intelligent devices, otherwise an empty string.
	'vrmusbcam_api_version'		string		Version of VRmUsbCam API this acquisition interface is built for.
	'vrmusbcam_version'		string		Returns the version of underlying VRmUsbCam API runtime.
	'revision'		revision		The revision number of the HALCON VRmUsbCam interface.

Release Notes

• Revision 3.2 (Aug 20, 2010):
  • Adapted to VRmUsbCam SDK version 3.13.
  • Fixed bug in grab_image_start: Depending on the state of the interface, sometimes the first image was dropped.
  • Added read-only parameter 'ip_address'.
  • Added support of "triggered internal" mode for asynchronous grabbing.
  • HALCON 10 version of the interface (included in HALCON 10 DVD).
• Revision 3.1 (Jul 23, 2008):
  • Bugfix in grab_image_start to avoid unnecessary re-initializing of the acquisition engine. As a result from this, the interactive parameterization via the HDevelop Image Acquisition Assistant reacts significantly faster.
  • In contrast to the documentation, the parameter 'image_available' erroneously returned the string 'true'/'false' instead of the integer 0/1. This bug has been fixed. The example program vrmusbcam_2cameras.dev has been adapted accordingly.
• Revision 3.0 (Apr 22, 2008):
  • First official release.