interfaces mvtec

Interface Documentation

Image Acquisition Interface for VRmagic Imaging Devices

Interface: VRmUsbCam
Revision: 13.0.1
Date: 2016-10-28
HALCON Version: 13.0

General

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.

System Requirements

  • Intel compatible PC with Windows 7 (32-bit) or newer that is also supported by the vendor-specific SDK, also WoW64 (using 32-bit HALCON on 64-bit Windows).
  • 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 hAcqVRmUsbCamxl.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

  • No support for images with 10 bit per pixel.

Parameters for info_framegrabber

Parameter Value List Type Kind Description
'bits_per_channel' 8 integer pre-defined Values for bits per channel.
'camera_type' 'default' string pre-defined Returns the values for the camera type.
'color_space' ['default', 'gray', 'rgb'] string pre-defined Values for color space.
'defaults' [1, 1, 0, 0, 0, 0, 'default', 8, 'default', -1.0, 'false', 'default', 'default', -1, -1] mixed pre-defined Default values for open_framegrabber.
'device' ['<device>', 'default'] string dynamic List of available device numbers.
'external_trigger' ['false', 'true'] string pre-defined Values for the external trigger.
'field' [] Unused.
'general' [] string pre-defined Information about the HALCON VRmUsbCam interface.
'generic' [] Unused.
'horizontal_resolution' [] Unsupported query!
'image_height' [] Unsupported query.
'image_width' [] Unsupported query.
'info_boards' ['device:<device> camera_type:<source_format>'] string dynamic A list of the available devices.
'parameters' ['<parameters>'] string pre-defined Pre-defined parameters of the HALCON interface.
'parameters_readonly' ['<parameters>'] string pre-defined Pre-defined read-only parameters of the HALCON interface.
'parameters_writeonly' ['<parameters>'] string pre-defined Pre-defined write-only parameters of the HALCON interface.
'port' [] Unused.
'revision' '<revision>' string pre-defined Revision number of the VRmUsbCam interface.
'start_column' [] Unsupported query.
'start_row' [] Unsupported query.
'vertical_resolution' [] Unsupported query!

Parameters for open_framegrabber

Parameter Values Default Type Description
Name 'VRmUsbCam' string Name of the HALCON interface.
HorizontalResolution --- Ignored.
VerticalResolution --- Ignored.
ImageWidth 0 0 integer Width of the desired image part ('0' stands for the complete image).
ImageHeight 0 0 integer Height of the desired image part ('0' stands for the complete image).
StartRow 0 0 integer Row coordinate of the upper left pixel within the desired image part.
StartColumn 0 0 integer Column coordinate of the upper left pixel within the desired image part.
Field --- Ignored.
BitsPerChannel 8 8 integer Number of significant bits per channel. Currently, only 8 bit images are supported.
ColorSpace 'default', 'gray', 'rgb' 'default' string Desired color space of the resulting HALCON image. 'default' means to adapt the camera setting.
Generic --- -1 Ignored.
ExternalTrigger 'false', 'true' 'false' string Status of the external trigger.
CameraType '<source_format>', 'default' 'default' string Desired camera source format.
Device '<device>', 'default' 'default' string Unique device string of the desired camera as returned by info_framegrabber(..., 'info_boards', ...). 'default' searches for the first unused camera.
Port --- -1 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', ...).
Parameter Values Default Type Description
'do_delete_config' <config_id> integer 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> integer 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> integer Saves the configuration to the specified device.
'do_show_property_page' [<left, top, width, height>] integer Shows the settings dialog (property page) of the device (params: (opt.) window position and size).
'image_height' <height> integer Height of the desired image part ('0' stands for the complete image).
'image_width' <width> integer Width of the desired image part ('0' stands for the complete image).

Parameters for get_framegrabber_param

There may exist additional read-only parameters with the following postfixes:
  • '_description': These parameters provide the tool-tip of the corresponding parameter as a string.
  • '_range': These parameters provide the minimum, maximum, step width, and default values for the corresponding integer or float parameter as a tuple with 4 elements, e.g., get_framegrabber_param(.., 'Shutter_range', ..) will return the output tuple [min, max, step, default].
  • '_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'].

All these postfixed parameter names are not returned when calling info_framegrabber(.., 'parameters', ..) and are used to enable the easy parameterization via a generic graphical user interface, particularly the HDevelop Image Acquisition Assistant.

Parameter Values Default Type Kind Description
'available_param_descriptions' ['<descriptions>'] string pre-defined 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>'] string dynamic The list contains the names of all available parameters.
'bits_per_channel' 8 8 integer pre-defined Number of bits per channel of the resulting HALCON image. In case of -1 the current bit depth of the camera is used. By specifying a value greater than 8 the grabbed images are delivered as uint2 images.
'camera_type' '<source_format>' 'default' string pre-defined Current camera type.
'color_space' 'gray', 'rgb' 'default' string pre-defined Desired color space and thus the number of image channels of the resulting HALCON image.
'device' '<device_id>' 'default' string dynamic Current device ID.
'external_trigger' 'false', 'true' 'false' string pre-defined Status of the external trigger.
'field' '<default>' 'default' string pre-defined The value is not used, so a default value is returned.
'generic' <default> -1 integer pre-defined The value is not used, so a default value is returned.
'grab_async_mode' 'freerunning', 'freerunning_sequential', 'triggered_internal' string dynamic Device grab mode to use when asynchronous grabbing is selected.
'horizontal_resolution' <resolution> 1 integer pre-defined Current value of horizontal resolution.
'image_available' 0, 1 integer dynamic 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. Note that this parameter is especially useful in combination with external triggering.
'image_height' <height> 0 integer pre-defined Height of the desired image part ('0' stands for the complete image).
'image_width' <width> 0 integer pre-defined Width of the desired image part ('0' stands for the complete image).
'ip_address' '<ip_address>' string dynamic The IP address in case of Ethernet-based intelligent devices, otherwise an empty string.
'line_in' <default> -1 integer pre-defined The value is not used, so a default value is returned.
'name' 'VRmUsbCam' string pre-defined Name of the HALCON interface.
'port' <default> -1 integer pre-defined The value is not used, so a default value is returned.
'revision' '<revision>' string pre-defined Revision number of the VRmUsbCam interface.
'start_column' <column> 0 integer pre-defined Returns the current start column of the HALCON image.
'start_row' <row> 0 integer pre-defined Returns the current start row of the HALCON image.
'vertical_resolution' <resolution> 1 integer pre-defined Current value of vertical resolution.
'vrmusbcam_api_version' '<version>' string dynamic Version of VRmUsbCam API this acquisition interface is built for.
'vrmusbcam_version' '<string>' string dynamic Version of underlying VRmUsbCam API runtime.

Operator set_framegrabber_lut

Not supported by this interface.

Operator get_framegrabber_lut

Not supported by this interface.

Operator set_framegrabber_callback

Not supported by this interface.

Operator get_framegrabber_callback

Not supported by this interface.

Operator grab_image_start

Starts a new asynchronous grab. See also grab_image_start.

Operator grab_image

grab_image starts a new synchronous grab. See also grab_image. Note that the interface converts the image from the device to the desired image format specified by the parameters 'image_width', 'image_height', 'start_row', 'start_column', 'bits_per_channel', and 'color_space'.

Operator grab_image_async

grab_image_async returns an image and starts the next asynchronous grab. See also grab_image_async. Note that the interface converts the image from the device to the desired image format specified by the parameters 'image_width', 'image_height', 'start_row', 'start_column', 'bits_per_channel', and 'color_space'.

Operator grab_data

Not supported by this interface.

Operator grab_data_async

Not supported by this interface.

Operator close_framegrabber

This operator closes the device. See also close_framegrabber.

HDevelop Examples

For this interface there are the following examples available:
  • vrmusbcam_2cameras - Shows concurrent grabbing from two connected cameras.
  • vrmusbcam_crop - Example for grabbing images with image cropping.
  • vrmusbcam.hdev - Performance evaluation.
  • vrmusbcam_parameters.hdev - Lists all parameters of a device.
  • vrmusbcam_simple.hdev - A simple example to show the usage of the interface.
  • vrmusbcam_trigger.hdev - Grabbing of images with usage of an external trigger.

Release Notes

  • Revision 13.0.1 (Oct 28, 2016):
    • HALCON 13 version of the interface.
  • Revision 6.0 (Oct 31, 2014):
    • HALCON 12 version of the interface.
  • Revision 5.0 (May 15, 2012):
    • HALCON 11 version of the interface (included in HALCON 11 DVD).
  • Revision 4.1 (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 4.0 (Dec 1, 2008):
    • HALCON 9.0 version of the interface (included in HALCON 9.0 DVD).
  • Revision 3.1 (Jul 23, 2008):
    • Bug fix 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.