Configuring video capture in ARToolKit Professional
From ARToolworks support library
Main Page > ARToolKit Professional > Configuring video capture in ARToolKit Professional
About libARvideo's configuration options
ARToolKit Professional includes libARvideo, a cross-platform library which captures video from a variety of different sources. In general, most users of ARToolKit Professional who have a single webcam attached to their system will never delve into the workings of this library. However, the module or modules inside this library generally allow for a degree of configuration to control parameters of the capture sources with which they interface.
This section of the manual details some of the configuration options available with libARvideo.
How to change the video configuration in your program, or in an ARToolKit Professional example
Setting the configuration at run-time
Video configurations are passed to libARvideo in a standard way; as a c-string containing text. What to put in the contents of the string depends on your capture source.
The contents of the string are different for different capture sources because although libARvideo presents a standard API for passing video to other code (e.g. libAR, libARgsub_lite and libARgsub), there is custom code inside libARvideo for each capture source (e.g. QuickTime, DirectShow, libdc1394). The capture sources generally implement a variety of different approaches to video stream acquisition. So, the configuration parameters are different depending on the underlying capture module being used.
The simplest way to specify the video configuration (without recompiling the example applications) is to create an environment variable "ARTOOLKIT_4_CONFIG" with the video configuration you wish to use. See Setting an environment variable for more information on how to set environment variables.
Setting the configuration programmatically
Video configuration can also be passed to libARvideo programmatically (as the sole parameter to the arVideoOpen() call). When no string (NULL) or an empty string ("") is passed, libARvideo looks for an environment variable "ARTOOLKIT_4_CONFIG" (as mentioned above) for the string. If this environment variable is not found, the video module will use a default configuration.
In most of the ARToolKit Professional examples, the video config is specified in a string named "vconf". Do a search in your source editor for "vconf" to see this. So in most of the examples, editing the vconf string in the sourcecode will change the video configuration being used.
Of course, editing sourcecode requires recompiling for the changes to stick, so a few of the examples accept a command-line parameter and use this as vconf. You can look at the sourcecode to see if a given example does so.
Available capture sources and switching between them
There is one standard configuration option (which is new to ARToolKit Professional, and not found in any version of ARToolKit v2.x). Where more than one capture source has been compiled into libARvideo on a given platform, this option allows switching between the options.
This table lists the capture sources available on each platform. (N.B. if you have a binary release of ARToolKit Professional, not all of these capture sources may have been compiled into your copy):
| Platform | Capture source (descriptive name) | Constant required in <AR/config.h> for this source to be compiled into libARvideo | video config string to select this capture source | Avail.: (1) | Unavail.: (2) |
|---|---|---|---|---|---|
| All | Dummy input | AR_INPUT_DUMMY | -device=Dummy | 4.0.0 | |
| Linux | Video4Linux | AR_INPUT_V4L | -device=LinuxV4L | 4.0.0 | |
| Linux | GStreamer | AR_INPUT_GSTREAMER | -device=GStreamer | 4.3.2 | |
| Linux | libdc1394 | AR_INPUT_1394CAM | -device=Linux1394Cam | 4.0.0 | |
| Mac OS X, Windows | QuickTime® (enhanced) | AR_INPUT_QUICKTIME | -device=QUICKTIME | 4.3.0 | |
| Windows | DirectShow® | AR_INPUT_WINDOWS_DIRECTSHOW | -device=WinDS | 4.0.0644 | 4.0.065,4.1.x |
| Windows | DSVideoLib | AR_INPUT_WINDOWS_DSVIDEOLIB | -device=WinDSVL | 4.1.0 | |
| Windows | DragonFly FlyCapture® | AR_INPUT_WINDOWS_DRAGONFLY | -device=WinDF | 4.0.0644 | 4.0.065 |
| Mac OS X | QuickTime® | AR_INPUT_QUICKTIME_OLD | -device=QUICKTIME_OLD | 4.0.0 | |
| Windows | HDCam64 | AR_INPUT_WINDOWS_HDCAM | -device=WinHD | 4.0.0644 | 4.0.065 |
| Linux | libdv | AR_INPUT_DV | -device=LinuxDV | 4.0.0 | 4.1.x, 4.3.x |
| SGI Irix | SGI video input | AR_INPUT_SGI | -device=SGI | 4.0.0 | 4.1.x, 4.3.x |
(1): First version of ARToolKit Professional in which this capture source became available. (2):Version(s) of ARToolKit Professional in which this source is/was unavailable or unusable.
Video configuration options
Notes on the tables below
- Items inside square brackets ("[" and "]") are optional modifications to parameters, e.g. an option listed below as "-[no]foo" means that option "-foo" activates some option "foo", and option "-nofoo" deactivates it.
- Items separated by a vertical bar ("|") are mutually-exclusive options. Use only one.
- Items in italic typeface are placeholders, which you should replace. E.g. N indicates an integer number should be inserted.
AR_VIDEO_DEVICE_DUMMY
| video config string | usage notes | Default value | Avail.: (1) | Unavail.: (2) |
|---|---|---|---|---|
| -device=Dummy | Select this device for use. | 4.0.0 | ||
| -width=N | Specify the width of the returned image. | 640 | 4.0.0 | |
| -height=N | Specify the height of the returned image. | 480 | 4.0.0 |
AR_VIDEO_DEVICE_V4L
| video config string | usage notes | Default value | Avail.: (1) | Unavail.: (2) |
|---|---|---|---|---|
| -device=LinuxV4L | Select this device for use. | 4.0.0 | ||
| -width=N | Specify the width of the returned image. | 640 | 4.0.0 | |
| -height=N | Specify the height of the returned image. | 480 | 4.0.0 | |
| -contrast=N | specifies contrast. (0.0 <-> 1.0) | 4.0.0 | ||
| -brightness=N | specifies brightness. (0.0 <-> 1.0) | 4.0.0 | ||
| -color=N | specifies color. (0.0 <-> 1.0) | 4.0.0 | ||
| -hue=N | specifies hue. (0.0 <-> 1.0) | 4.0.0 | ||
| -whiteness=N | specifies whiteness. (0.0 <-> 1.0) | 4.0.0 | ||
| -channel=N | specifies source channel. | 3 | 4.0.0 | |
| -dev=filepath | specifies device file. | /dev/video0 | 4.0.0 | |
| -mode=[PAL|NTSC|SECAM] | specifies TV signal mode. | NTSC | 4.0.0 | |
| -format=[BGR|BGRA] | specifies pixel format. | BGR | 4.0.0 |
AR_VIDEO_DEVICE_DV
AR_VIDEO_DEVICE_1394CAM
| video config string | usage notes | Default value | Avail.: (1) | Unavail.: (2) |
|---|---|---|---|---|
| -device=Linux1394Cam | Select this device for use. | 4.0.0 | ||
| -port=N | specifies a FireWire adaptor port (-1: Any). | 0 | 4.0.0 | |
| -euid=N | specifies EUID of a FireWire camera (-1: Any). | 0 | 4.0.0 | |
| -mode=[320x240_YUV422 | 640x480_YUV422 | 640x480_RGB | 640x480_YUV411 | 640x480_YUV411_HALF | 640x480_MONO | 640x480_MONO_COLOR | 640x480_MONO_COLOR2 | 640x480_MONO_COLOR3 | 640x480_MONO_COLOR_HALF | 640x480_MONO_COLOR_HALF2 | 640x480_MONO_COLOR_HALF3 | 1024x768_MONO | 1024x768_MONO_COLOR] | specifies input image format. | Depends on camera selected during execution of configure. | 4.0.0 | |
| -rate=N | specifies desired framerate of a FireWire camera. (1.875, 3.75, 7.5, 15, 30, 60) | 30 | 4.0.0 | |
| -reset | resets camera to factory default settings. This is required for DFK21AF04 when it has been connected. | 4.0.0 |
AR_VIDEO_DEVICE_SGI
AR_VIDEO_DEVICE_WINDOWS_DIRECTSHOW
Extra help on building this video capture module can be found on the page Building libARvideo using DirectShow.
| video config string | usage notes | Default value | Avail.: (1) | Unavail.: (2) |
|---|---|---|---|---|
| -device=WinDS | Select this device for use. | 4.0.0644 | 4.0.065 | |
| -showDialog | Request that the WDM capture PIN (configuration sheet) be shown to the user when the video stream is opened. | -showDialog (only if no config string is supplied). | 4.0.0644 | 4.0.065 |
| -showDeviceList | Do not actually open the device, but instead dump a list of device numbers and device names to the standard output. The format of the dump is up to 2 decimal digits (beginning with '1' for the first device), followed by a colon and a space, and the remaining characters before the new line constituting the device name, as known to WDM. | 4.0.0644 | 4.0.065 | |
| -devNum=n | Open device n, rather than the default device. | 1 | 4.0.0644 | 4.0.065 |
| -flipH | Flip camera image horizontally. | 4.0.0644 | 4.0.065 | |
| -flipV | Flip camera image vertically. | -flipV (only if no config string is supplied). | 4.0.0644 | 4.0.065 |
AR_VIDEO_DEVICE_WINDOWS_DRAGONFLY
AR_VIDEO_DEVICE_WINDOWS_HDCAM
AR_VIDEO_DEVICE_QUICKTIME
Extra help on building this video capture module can be found on the page Building libARvideo using QuickTime.
The QuickTime video plugin can operate in two modes.
- In the first mode (the default), it acquires live video from a video capture source via QuickTime's video grabber. (Note that QuickTime for Windows does not come with a video digitizer component, and a third party component (e.g. WinVDIG [1] must be installed.)
- In the second mode, specified by passing a video configure parameter "-movie=pathnameOrURL", the plugin can open any valid QuickTime resource, including movies from disk, or movies streamed via http, rtsp or ftp protocols.
QuickTime video input from VDIG
| video config string | usage notes | Default value | Avail.: (1) | Unavail.: (2) |
|---|---|---|---|---|
| -device=QUICKTIME | Select this device for use. | 4.3.0 | ||
| -[no]dialog | Don't display video settings dialog. | -dialog | 4.3.0 | |
| -[no]standarddialog | Don't remove unnecessary panels from video settings dialog. | -nostandarddialog | 4.3.0 | |
| -width=w | Scale camera native image to width w. | 640 | 4.3.0 | |
| -height=h | Scale camera native image to height h. | 480 | 4.3.0 | |
| -[no]fps | Overlay camera frame counter on image. | -nofps | 4.3.0 | |
| -grabber=n | With multiple QuickTime video grabber components installed,
use component n (default n=1). N.B. It is NOT necessary to use this option if you have installed more than one video input device (e.g. two cameras) as the default QuickTime grabber can manage multiple video channels. | 1 | 4.3.0 | |
| -pixelformat=cccc | Return images with pixels in format cccc, where cccc is either a
numeric pixel format number or a valid 4-character-code for a pixel format. The following numeric values are supported: 24 (24-bit RGB), 32 (32-bit ARGB), 40 (8-bit grey) The following 4-character-codes are supported: BGRA, RGBA, ABGR, 24BG, 2vuy, yuvs. (See http://developer.apple.com/quicktime/icefloe/dispatch020.html.) | Depends on platform; default for Mac OS X is 32 (i.e. ARGB), default for Windows is BGRA. | 4.3.0 | |
| -[no]fliph | Flip camera image horizontally. | -nofliph | 4.3.0 | |
| -[no]flipv | Flip camera image vertically. | -noflipv | 4.3.0 | |
| -[no]singlebuffer | Use single buffering of captured video instead of triple-buffering. | -nosinglebuffer | 4.3.0 |
