VR World Description File Format

All XML elements of the VR World description have the namespace "http://www.anyma.ch/mexx/vrbuild". All string values are case sensitive.

If you aren't familiar with the internal structure of QTVR Movies, I strongly suggest you have a look at Apple's QuickTime VR documentation before using vrbuild, primarily Inside QuickTime VR.

A general note of caution: vrbuild doesn't do elaborate validity checking of the description file. Errors in the file might cause the program to stop without explanation or to silently produce unexpected results.

vr-world

The vr-world element is the root element of the description file.

Attributes:

width, height (optional)

Specify the default width and height of the resulting QTVR Movie in pixels. The default is 640 x 480.

Child Nodes:

node (one or more)

Defines a node of the VR world.

node

The node element defines one node of the QTVR Movie.

Attributes:

type

The only node type which is currently supported is "pano", which defines a Panorama node.

support object nodes

id

A string which uniquely identifies this node. This string will be used in other parts of the file to identify this node (eg. hotspot target node). It won't be visible in the final QTVR Movie (except if you don't specify a name, see below).

name (optional)

A string which will be stored in the output movie as the node name. If omitted, it defaults to the value of the id attribute.

Child Nodes:

image (one)

Specifies the image data for the current node.

support multiple image children for low-res tracks

hotspots (none or one)

Defines the hotspots in this node.

Additionally, for type="pano":

geometry (one)

Specifies the geometry of the Panorama. Currently only cubic Panorama nodes are supported.

geometry

This element specifies the geometric parameters of a Panorama node.

Attributes:

type

Currently only cubic Panorama nodes are supported, which have a geometry type of "cubic"

support cylindrical panoramas and custom cubes

image

The image element defines a link to image data which is to be inserted into a Video Track of the output movie.

Attributes:

type

Indicates the kind of image data source (eg. a separate image file for each frame or a part of a track of another movie). Currently the only supported value for this attribute is "separate-images", which indicates that each frame to insert is stored in a separate image file.

support other movies as sources

codec (optional)

The codec to use to encode the data in the output movie. Note that this is not the source file format, but the target codec to use. The source format is detected automatically. The default is the same codec as the source data.

quality (optional)

The quality hint to pass to the encoding codec. You can specify an integer value from 0 (lowest) to 1024 (lossless) in decimal notation, or hexadecimal by prefixing the value with "0x". Alternatively, you can use one of "min", "low", "normal", "high", "max", or "lossless". Depending on the codec, some values might not be appropriate (eg. lossless), or the value might be completely ignored. The default is copied from the source data.

depth (optional)

The target color depth. Should be "1", "2", "4", "8", "16", "24" or "32" for color images or "34", "36" or "40" for 2-bit, 4-bit, or 8-bit grayscale. The default is taken from the source image.

Additionally, for type="separate-images":

href

The URL of the source data. Can be relative (to the description file's containing folder). Currently only "file:" URLs are supported. The file name of each individual frame is constructed by inserting the frame number, starting at 1, just before the first period character of the specified source file name. No padding or leading zeroes are added to the frame number.
Example: if the value of href is "image.png" and six frames are to be imported, these frames are loaded from files called "image1.png", "image2.png", "image3.png", "image4.png", "image5.png" and "image6.png"

More flexibility for file name generation, eg. allow "%i" sequence

hotspots

The hotspots element regroups information about the hotspots of a node.

Child Nodes:

image (one)

Specifies the image data for the Hotspot Image Track. You should use a 8-bits lossless codec for hotspot image data.

hotspot (none or more)

Each hotspot child specifies one hotspot for this node.

hotspot

The hotspot element defines a hotspot in a node.

Attributes:

type

Specify the type of hotspot. Currently, the values "link" and "url" are supported. Link hotspots link to another node in the same movie, while URL hotspots link to external resources.

color-index (need this or ref-frame, ref-x and ref-y)

The color index in the source image data which corresponds to this hotspot. Alternatively, you can specify a reference point in the source data to fetch the color index from, using the ref-frame, ref-x, and ref-y attributes.

ref-frame (need this, ref-x and ref-y, or color-index)

The frame to get the hotspot's color index from.

ref-x (need this, ref-frame and ref-y, or color-index)

The x coordinate in the specified frame to get the hotspot's color index from. This should be between 0.0 and 1.0, where 0.0 is the left edge of the image and 1.0 is the right edge.

ref-y (need this, ref-frame and ref-x, or color-index)

The y coordinate in the specified frame to get the hotspot's color index from. This should be between 0.0 and 1.0, where 0.0 is the top edge of the image and 1.0 is the bottom edge.

Additionally, for type="link":

target

The ID of the target node, as specified in its id attribute.

from-pan (optional)

The hotspot's preferred source pan value. See the QuickTime VR documentation about Link Hotspots for more info.

from-tilt (optional)

The hotspot's preferred source tilt value. See the QuickTime VR documentation about Link Hotspots for more info.

from-fov (optional)

The hotspot's preferred source field of view value. See the QuickTime VR documentation about Link Hotspots for more info.

to-pan (optional)

The hotspot's destination pan value. See the QuickTime VR documentation about Link Hotspots for more info.

to-tilt (optional)

The hotspot's destination tilt value. See the QuickTime VR documentation about Link Hotspots for more info.

from-fov (optional)

The hotspot's destination field of view value. See the QuickTime VR documentation about Link Hotspots for more info.

Additionally, for type="url":

target

The target URL. May be relative (to the output movie verify)