-
Notifications
You must be signed in to change notification settings - Fork 29
ARToolKit v5 video module configuration reference
ARToolKit includes libARvideo, a cross-platform library which captures video from a variety of different sources. In general, most users of ARToolKit 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.
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 ARTOOLKIT5_VCONF with the video configuration you wish to use.
Some of the ARToolKit utilities (including calib_camera, calib_stereo and check_id) accept video configuration(s) as command-line parameters. The desired configuration is passed after a parameter "--vconf" (or --vconfL or --vconfR for calib_stereo). Note that if the video configuration string includes spaces, it must be quoted to prevent the shell passing it as multiple parameters.
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 "ARTOOLKIT5_VCONF" (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 examples, the video configuration 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 source code will change the video configuration being used.
Of course, editing source code requires recompiling for the changes to take effect, so a few of the examples accept a command-line parameter and use this as vconf. You can look at the source code to see if a given example does so.
ARToolKit for Unity allows you to specify video configuration separately for each supported platform directly in the Unity Editor.
Where more than one capture source has been compiled into libARvideo on a given platform, you are allowed to switch between the options.
This table lists the capture sources available on each platform. Note: If you have a binary release of ARToolKit, 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 | ARVIDEO_INPUT_DUMMY | -module=Dummy | 4.0.0 | |
| Mac OS X, Windows, Linux | JPEG image input | ARVIDEO_INPUT_IMAGE | -module=Image | 4.6.2 | |
| Linux | Video4Linux | ARVIDEO_INPUT_V4L2 | -module=V4L2 | 4.0.0 | |
| Linux | GStreamer | ARVIDEO_INPUT_GSTREAMER | -module=GStreamer | 4.3.2 | |
| Linux | libdc1394 | ARVIDEO_INPUT_1394CAM | -module=1394 | 4.0.0 | |
| macOS, iOS | AVFoundation video input | ARVIDEO_INPUT_AVFOUNDATION | -module=AVFoundation | 4.4.3 (iOS release 1.0) | |
| Android | Android video input | ARVIDEO_INPUT_ANDROID | -module=Android | 5.3 | |
| Windows | Media Foundation | ARVIDEO_INPUT_WINDOWS_MEDIA_FOUNDATION | -module=WinMF | 5.1.5 | |
| Windows Store (Windows 8.1 and Windows Phone 8.1) | Windows Media Capture | ARVIDEO_INPUT_WINDOWS_MEDIA_CAPTURE | -module=WinMC | 5.1.7 |
(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.
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.
| video config string | usage notes | Default value | Avail.: (1) | Unavail.: (2) |
|---|---|---|---|---|
| -module=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 | |
| -bufferpow2 | Requests that images are returned in a buffer which has power-of-two dimensions. | Buffers are same size as image. | 4.4.3 | |
| -format=X | Return images with pixels in format X, where X is one of the following format tokens: BGRA, RGBA, RGBA_5551, RGBA_4444, y420 | BGRA |
| video config string | usage notes | Default value | Avail.: (1) | Unavail.: (2) |
|---|---|---|---|---|
| -module=Image | Select this device for use. | 4.6.2 | ||
| -width=N | Specify the width of the returned image. | Width of first JPEG in image list. | 4.6.2 | |
| -height=N | Specify the height of the returned image. | Height of first JPEG in image list. | 4.6.2 | |
| -bufferpow2 | Requests that images are returned in a buffer which has power-of-two dimensions. | Buffer of same size as first JPEG in image list. | 4.6.2 | |
| -format=X | Return images with pixels in format X, where X is one of the following format tokens: RGB, RGBA, MONO. Note that where the format requires a conversion from the native JPEG format (usually RGB) to anything other than MONO, there is a performance penalty imposed by the conversion. ARToolKit can natively handle RGB, RGBA and MONO JPEG formats, however in some circumstances, displaying RGB format images may have a performance penalty compared to RGBA format images because of data alignment issues. Benchmarking is recommended if performance is of concern. | RGB for RGB-format JPEGs, RGBA for RGBA-format JPEGs, or MONO for monochrome JPEGs. | 4.6.2 | |
| -[no]loop | In loop mode, after reading last image, the next read will return the first image. In noloop mode, no after reading the last image, no further images will be returned. May be used multiple times; later invocations will override earlier. | -noloop | 4.6.2 | |
| -image=pathname | ||||
| -image="pathname with spaces" | Specifies image to be read from file. Pathname is relative to the current working directory, or an absolute pathname in the system-native format. May be used an arbitrary number of times in a single config. string. | 4.6.2 |
| video config string | usage notes | Default value | Avail.: (1) | Unavail.: (2) |
|---|---|---|---|---|
| -module=V4L2 | 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 |
Extra help on building this video capture module can be found on the page Building libARvideo.
| video config string | usage notes | Default value | Avail.: (1) | Unavail.: (2) |
|---|---|---|---|---|
| -module=1394 | 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 | 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 |
| video config string | usage notes | Default value | Avail.: (1) | Unavail.: (2) |
|---|---|---|---|---|
| -module=GStreamer | Select this device for use. | 4.3.2 | ||
| remainder of config string | Specifies a configuration string following the gst-launch syntax. See more at GStreamer Configuration. | 4.3.2 |
The AVFoundation video plugin is available on Apple macOS and iOS devices including Mac, iPhone, iPad, and iPod Touch devices. It can operate in either two modes; either acquiring live video from a camera on the device, or playing a pre-recorded video file stored in the app's bundle resource directory.
| video config string | usage notes | Default value | Avail.: (1) | Unavail.: (2) |
|---|---|---|---|---|
| -module=AVFoundation | Select this device for use. | 4.4.3 (release 1.0) | ||
| -format=X | Return images with pixels in format X, where X is one of the following format tokens: 420v, 420f, BGRA, RGBA, RGBA_5551, RGBA_4444 | 420f (ARToolKit v5.0 and later.), BGRA (ARToolKit version pre-5.0) | 4.4.3 (release 1.0) | |
| -preset=X | Specify use of camera settings preset X, where X is one of: cif, 480p, 720p, 1080p, low, medium, high, photo. (N.B.:480p=640x480, i.e. 4:3 aspect ratio, 720p=1280x720 and 1080p=1920x1080 i.e. 16:9 aspect ratio). | medium | 4.5.1 (release 2.0) | |
| -position=X | Choose between rear/back and front-mounted camera (where available). Allowable values for X include: rear, back, front. (N.B.:rear is a synonym for back). | rear | 4.5.1 (release 2.0) | |
| -[no]flipv | Flip the incoming image from the camera vertically. On front mounted-cameras, this option is on by default (but can be overridden by specifying -noflipv). Flipping the video vertically matches the orientation of the video image (when displayed on the screen of the device) to the physical orientation of the device. | noflipv (on rear camera). flipv (on front camera) | 4.5.4 (release 3.0) | |
| -[no]fliph | Flip the incoming image from the camera horizontally. | nofliph | 4.6.6 (release 16) | |
| -width=w | Crop native camera image width to w. | camera native image width for given preset (see above.) | 4.4.3 (release 1.0) | 4.5.0- |
| -height=h | Crop native camera image height to h. | camera native image height for given preset (see above.) | 4.4.3 (release 1.0) | 4.5.0- |
| -bufferpow2 | Requests that images are returned in a buffer which has power-of-two dimensions. | camera native image size for given preset (see below.) | 4.4.3 (release 1.0) | 4.5.0- |
| video config string | usage notes | Default value | Avail.: (1) | Unavail.: (2) |
|---|---|---|---|---|
| -module=AVFoundation | Select this device for use. | 4.5.5 (release 4.0) | ||
| -movie=pathname or -movie="pathname" | Specifies that video should be acquired from a movie resource. This can be any valid movie file resource that iOS can open, but typically MPEG-4 (h.264 video with optional AAC audio). The pathname is relative to the resources directory of the app bundle. If the pathname contains spaces, it must be surrounded with double quotes ("). e.g. -movie="My great sample.mov". | 4.5.5 (release 4.0) | ||
| -[no]1to1 | N.B. CURRENTLY IGNORED. Do not fit the movie to the window or buffer size, but instead display it at its original size (1 to 1 scaling). | -no1to1 | 4.5.5 (release 4.0) | |
| -[no]fill | N.B. CURRENTLY IGNORED. Rather than fitting the movie into the window so that all the movie is visible, scale it so that it completely fills the window or buffer. The movie's aspect ratio will be maintained, and this may result in some of the movie being clipped at the top and bottom or left and right. | -nofill | 4.5.5 (release 4.0) | |
| -[no]stretch | N.B. CURRENTLY IGNORED. Rather than fitting the movie into the window so that all the movie is visible, scale it so that it completely fills the window or buffer. The movie's aspect ratio will be stretched if necessary so that no pixels are clipped. | -stretch | 4.5.5 (release 4.0) | |
| -[no]loop | Request that the movie loop continuously. | -loop | 4.5.5 (release 4.0) | |
| -[no]mute | Set movie audio volume to 0. | -nomute | 4.5.5 (release 4.0) | |
| -[no]pause | Open movie in paused state. A call to arVideoCapStart() would be required to unpause the movie. | -pause | 4.5.5 (release 4.0) | |
| -width=w | Scale movie native frame to width w. | Width of movie frame. | 4.5.5 (release 4.0) | |
| -height=h | Scale movie native frame to height h. | Height of movie frame. | 4.5.5 (release 4.0) | |
| -[no]fliph | N.B. CURRENTLY IGNORED. Flip movie frame horizontally. | -nofliph | 4.5.5 (release 4.0) | |
| -[no]flipv | Flip movie frame vertically. | -noflipv | 4.5.5 (release 4.0) | |
| -pixelformat=cccc | Ignored unless -offscreen is also passed, requests return of movie frames 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 values are supported: 32, BGRA, RGBA, ABGR, 24, 24BG, 2vuy, yuvs. (See http://developer.apple.com/quicktime/icefloe/dispatch020.html) | BGRA | 4.5.5 (release 4.0) |
| video config string | usage notes | Default value | Avail.: (1) | Unavail.: (2) |
|---|---|---|---|---|
| -module=WinMF | Select this device for use. | 5.1.5 | ||
| -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. | -noShowDeviceList | 5.1.5 | |
| -noShowDeviceList | Override a previous -showDeviceList option | -noShowDeviceList | 5.1.5 | |
| -devNum=n | Open device n, rather than the default device. E.g. if two cameras are connected, use -devNum=2 to access the second camera. | 1 | 5.1.5 | |
| -format=X | Return images with pixels in format X, where X is one of: BGRA, BGR, NV12/420f, 2vuy/UYVY, yuvs/YUY2, RGB_565, RGBA_5551. The most reliable format is BGRA, due to support within Media Foundation for conversion from YUV-colour spaces to RGB colour space. Other formats must be supported natively on the device in order for the request to succeed. | Default pixel format. | 5.1.5 | |
| -width=w | Request video format of width w pixels | Default frame width | 5.1.5 | |
| -height=h | Request video format of height h pixels | Default frame height | 5.1.5 | |
| -flipV | Flip image vertically. | -noFlipV | 5.1.5 | |
| -noFlipV | Override a previous -flipV option and do not flip image vertically. | -noFlipV | 5.1.5 | |
| -showFormats | Dump the full list of native formats to the console. This is helpful in determining device capabilities. | -noShowFormats | 5.1.5 | |
| -noShowFormats | Override a previous -showFormats option | -noShowFormats | 5.1.5 |
| video config string | usage notes | Default value | Avail.: (1) | Unavail.: (2) |
|---|---|---|---|---|
| -module=WinMC | Select this device for use. | 5.1.7 | ||
| -position=X | Choose between rear/back and front-mounted (where available). Other options include cameras mounted on left, right, top or bottom edges of the device. Allowable values for X include: rear, back, front, left, right, top, bottom, default. (N.B.:rear is a synonym for back). | default | 5.1.7 | |
| -devNum=n | Open device n, rather than the default device. E.g. if two cameras are connected, use -devNum=2 to access the second camera. If this option is combined with the -position option, then it will choose the n'th device at the preferred position. E.g. to choose the second of two rear cameras, you could use -position=rear -devNum=2. | 1 | 5.1.7 | |
| -format=X | Return images with pixels in format X, where X is one of: BGRA, BGR, NV12/420f, 2vuy/UYVY, yuvs/YUY2, RGB_565, RGBA_5551. The most reliable format is BGRA, due to support within Windows Media Capture for conversion from YUV-colour spaces to RGB colour space. Other formats must be supported natively on the device in order for the request to succeed. | Default pixel format. | 5.1.7 | |
| -width=w | Request video format of width w pixels | Default frame height | 5.1.7 | |
| -height=h | Request video format of height h pixels | Default frame height | 5.1.7 | |
| -flipV | Flip image vertically. | -noFlipV | 5.1.7 | |
| -noFlipV | Override a previous -flipV option and do not flip image vertically. | -noFlipV | 5.1.7 |