Welcome to the Viewpoint XML Reference Guide, your best resource for learning how to use Viewpoint MTX code. A published Viewpoint scene comprises an .mtx file, which contains MTX code that describes the attributes and behavior of the scene, including rich media file streaming. MTX code is based on XML (eXtensible Markup Language), a flexible, easily compressed, industry-standard data format, easily read by humans and machines.

Get started by reviewing the following features of this reference guide:

• MTX Code Overview -- Explains MTX code concepts, structure, and syntax rules
• Tag Navigation -- Use the links in the left navigation bar to browse the code hierarchy by scene element.
• Search -- Enter a key word or an exact code element in the provided search field to find individual entries corresponding to the search subject.

For information relating to XML, see www.xml.com. For information on how to author Viewpoint rich media and ZoomView content, see the documentation section.

Viewpoint MTX Code Overview

Viewpoint MTX code describes the attributes of your Viewpoint scene and streams files, such as .swf and .mts files, into the scene. Use any of the following methods to generate, publish, and edit MTX code:

• Edit and publish MTX code in an external .mtx file via scene assembly applications, such as Viewpoint Scene Builder
• Write and edit MTX code in an external .mtx file via an XML or text editor, such as UltraEdit
• Embed MTX code directly into the scene .html page
• Dynamically generate MTX code via JavaScript

The following information explains the MTX key code concepts, how to structure your code, and the supported code syntax.

MTX Code Concepts

To understand Viewpoint MTX code, it is important to understand some of the key concepts of the code, such as object instances, scene properties, and code hierarches.

Instances

An instance is a generalized container for an object. An instance typically holds one object and its parts, but can hold other sets of display elements, also, such as multiple objects, some subset of object parts, or a duplicate reference to a previously defined part, as described below.

If a model has two or more identical components, they can be referenced as instances of the same object.

Properties

Nearly every scene attribute defined in the .mtx file has a corresponding property that either matches the exact spelling of the attribute or is a truncated match of the attribute comprising four characters. By design, most properties can be set to manipulate the scene from its original state. Properties can be set through the MTX tags listed in the scene .mtx file. They can also be set using a scripting language, such as JavaScript.

You set a property by accessing the property's corresponding value type. This value type describes how the property acts and how it can be set to modify the Viewpoint scene. For example, a Boolean property type can be set to turn on or off depending on how you design the scene. The following table lists and describes all MTX property value types.

Animators

Scene animators modify a scene over time. Animators can be applied to three scene elements:

• Instances – An instance (that is, an object, a group of objects, or the parts that make up an object) can move, rotate, or zoom. Also, it can change size, opacity, and other aspects of the material applied to it (such as the color or texture), and can apply animation to scene background and foreground textures not applied to an instance.
• Camera – This is the vantage point from which the scene is viewed by the user. The camera can change location, zoom in or out, or rotate around objects in the scene.
• Action Triggers – An animator can trigger external files, events, or other animators to download into the scene.

Interactors and Events

Interactors are the elements of a Viewpoint scene used to catch system, user, or scene events to trigger an action. In a Viewpoint scene, these events can include:

• User Interactions – These include clicking, pointing, and dragging objects in the scene.
• State-Triggered Events – The scene author can define actions that set certain states in a Viewpoint scene (for example, a user click might change an object's state to "Clicked"). In turn, the actions that occur based on the new state might differ from the actions that occur in the previous state.
• Time-Triggered Events – These events happen after a specific number of seconds (for example, a message displays after five seconds if no one clicks the scene).
• Scene Events – These are events triggered within the Viewpoint scene, such as an event generated when a file finishes downloading to the user's computer.
• JavaScript and ActionScript Events – Events sent from the web page with JavaScript, or from an embedded Flash movie with ActionScript can be handled by the Viewpoint interactor system.

Hierarchies

Hierarchies are parent-child relationships that allow certain attributes to be inherited by a child component from its parent. Within a hierarchy, each child has a parent, and can have children of its own. Each of those children, in turn, can have children, and so on.

XML is hierarchical in nature, and .mtx files take advantage of this hierarchical structure to determine how things happen in the scene. The .mtx file supports nested hierarchies for three groups of information:

• Display Hierarchy – Includes an object itself and its related textures, other materials, and related hot spots.
• Animation Hierarchy – Includes actions and other scene animators that modify the scene over time.
• Interaction Hierarchy – Includes interactors, which modify scene elements based on events that occur.

Hierarchies make it possible for you to apply a command to an individual element, or to a group of elements (a parent and its children). Hierarchies can be leveraged in scene animation, including Flash and video asset files, and interactor systems, as well as 3D objects.

MTX Code Structure

The .mtx file contains global information about the entire scene and the camera (the vantage point from which the scene is viewed) and other information, such as the scene properties that define the particular aspects of the scene, such as 3D objects (instances), interactors, and animators.

Since Viewpoint Media Player parses scene .mtx files from top to bottom, the order of the tags within the .mtx file is important. A scene element that refers to another scene element must ALWAYS follow the referenced element. For example, to trigger an action in your scene, such as an animation, via some specified user interaction, in the MTX code the action declaration must preceed the interactor declaration.

While a scene can contain only a subset of the MTX code structure illustrated in the following graphic, the order of these listed elements ensures the greatest content flexibility

IMPORTANT! Currently, Viewpoint publishing tools and exporters from 3D modeling applications output MTX code that is slightly different than represented in this graphic. In most cases, the published code from these tools functions as expected. However, for some content to work, such as content using interactive Flash or SVG, you must rearrange your code as illustrated here. For best results for all types of content, structure your MTX code as illustrated.

As illustrated above, for best results, a Viewpoint .mtx file should be organized in this order:

1. The .mtx file begins with a file header. The rest of the file describes the scene itself, denoted by the MTSScene tag.
2. After the header, all global tags about the scene and camera follow. Scene parameters are listed with an MTSSceneParms tag and camera parameters are declared with MTSCamera.
3. Actions, defined with MTSAction tags, MUST precede the interactors which call them.
4. Objects are described next with MTSInstance tags.
5. Scene animators are declared with MTSTimeElem tags. The MTSTimeElem tag also loads the binary .mts file and any externally referenced files.
6. Lastly, the .mtx file ends with scene interactors, which relate to objects and are defined with MTSInteractor tags.

MTX Code Syntax

The basic building blocks of XML script are elements (or nodes), attributes, and values. "Tag" is a general term that can be used for elements and attributes.

• Element – A tag that is a container for subelements and attributes. It represents a category of functionality for a Viewpoint scene. For example, the MTSSceneParms element contains global settings for a scene, such as whether object shadows are on or off. The MTSInstance element contains the settings for a specific instance of geometry.
• Subelement – This is an element contained within a parent element. For example, within MTSInstance, the Transform subelement contains attributes controlling the position, scale, and other characteristics for the instance of geometry.
• Attribute – Attributes flesh out the details of an element or subelement. For instance, OrbitDist is an attribute of the element MTSCamera and sets how far the camera is from the scene center.
• Property – Properties are distinguished from attributes only in certain cases. In general, properties have names that match their corresponding attribute names in length and case. There are cases, though, where property names are four characters long and all lowercase.
• Value – This is the setting of the attribute. In MTX code, a value can indicate whether the scene attribute is on or off. Or, it might determine the intensity, position, color, or some other quality of the attribute.

In the following example, the MTSInstance element is made up of a starting tag (<MTSInstance>), attributes (Name and AntiAlias), values (indicated here by "value"), and a closing tag for the element (</MTSInstance>):

Simple tags like this one can also close themselves:

Simple vs. Complex Elements

There are two broad categories of XML tags: "simple" tags, which assign a single value to a particular attribute, and "complex" tags, which can have multiple attributes. This MTSTextureMap element is simple:

Some elements, such as MTSInstance, can have multiple subelements associated with them, some of which have their own subelements. These are called complex elements. In the following example, MTSCamera is a complex tag with one level of nested subelements:

DOM Syntax

Viewpoint Media Player supports Document Object Model (DOM) syntax as the means of accessing and setting MTX properties in a scene. In the words of the W3C web consortium responsible for the conception of the DOM and its further evolution, "W3C's Document Object Model (DOM) is a standard Application Programming Interface (API) to the structure of documents; it aims to make it easy for programmers to access components and to delete, add, or edit their content, attributes, and style.

Syntax Conventions

At its most simple, the DOM is simply a way of navigating hierarchies or declaring ownership, both using the period (".") as separator. In hierarchies, one could think of the "." as being shorthand for "is the parent of":

Or, regarding ownership, you could think of it as being shorthand for "has the property":

Or both, assuming there are no conflicts with the naming of properties and instances:

Currently, the DOM syntax employs the "." to distinguish object hierarchy relationships, objects from object names, object names from property names, and property names from subproperty names. It also harmonizes Viewpoint content authoring syntax with all other DOM syntax available in JavaScript, C++, Flash ActionScript, and so forth. Also, the double colons syntax convention ("::") can distinguish object names from property names, though this convention is being phased out of the Viewpoint Media Player DOM syntax support and should only be used to declare function calls, which are explained under "Functions" below, and for referencing the Propagate property.

For more information on DOM syntax, refer to http://www.w3.org/DOM/, or to a reference for any language that uses it, like Java, JavaScript or ActionScript.

Properties of Properties (Subproperties)

A major advantage of DOM syntax is that it allows greater access to Viewpoint scene information. For example, MTSInstance objects have a property called Geometry, which corresponds to the MTSGeometry tag in MTX code. The Geometry property has properties of its own, including Vertices. Here, we access the Vertices property of the Geometry property of the MTSInstance named cube:

Subproperties of Property Value Types

The basic property value types, such as Point3d, Point2d, Quaternion, and Rect, also have subproperties. For example, the MTSInstance property Translation has the following sub-properties: x, y, and z. Therefore, to modify only an object's x translation value, specify the following path:

The following table presents the subproperties of the basic property value types:

Array Properties

Some properties do not correspond to one value but to a set of indexed values. These property types are called array properties. For example, the MTSGeometry property, Vertices, is an array property. The Vertices array property accesses all vertex coordinates of a geometry. Each vertex has 3D coordinates (value type: Point3d); the Vertices property is an array of the Point3d value type.

Functions

Objects have properties and functions that can be accessed using a DOM path. An object function is a specific action that a specific object knows how to execute. Unlike properties, functions do not store a state of the object, but instead trigger an action on the object. Currently, very few objects execute these built-in functions.

All Viewpoint functions are called via the VETDispatchCall element, which names the function derived from the MTSBaseComponent element. Normally, you use functions in actions. As noted above, contrary to the normal DOM syntax convention, function calls are declared using the double-colon syntax (::) instead of the period (.):