Skip to content

Scene DOM Paths

Jump to bottom Edit New page
Ben Heasly edited this page Jul 26, 2013 · 43 revisions

RenderTooblox3 defines a syntax called "Scene DOM Paths", which facilitates working with XML files. RenderTooblox3 works with a few kinds of XML file:

PBRT-XML files are used by RenderToolbox3's ColladaToPBRT() utility. They are an intermediate between Collada parent scene files and PBRT-native plain text files.

XML is nice because it allows RenderToolbox3 to read and write file data through a convenient Document Object Model, aka DOM, instead of reading and writing plain text. Scene DOM Paths specify which parts of an XML file the DOM should access.

Scene DOM paths may be used in mappings files, in inside Mitsuba-path and PBRT-path blocks. See Mappings File Format and Mappings Syntax.

Overview of XML Structure

XML files use a structured syntax based on elements and attributes.

Elements give XML files a tree-like structure: every element has a parent, and some elements have children. All elements have a string name, and some elements have a string value.

Attributes are attached to elements, and describe them. Each attribute is attached to one element, and an element may have any number of attributes. All attributes have a string name and a string value.

Here is an XML example, taken from a Collada parent scene file:

      <node id="Camera" type="NODE">
        <translate sid="location">0 0 5</translate>
        <rotate sid="rotationZ">0 0 1 0</rotate>
        <rotate sid="rotationY">0 1 0 0</rotate>
        <rotate sid="rotationX">1 0 0 0</rotate>
        <scale sid="scale">1 1 1</scale>
        <instance_camera url="#Camera-camera"/>
      </node>

In this example there are 7 elements. Their names are node, translate, rotate, scale, and instance_camera. The node element is the parent of all the other elements. The rest are child elements.

The node element has two attributes, named id and type, with values Camera and NODE. Each child element has one attribute, named sid or url.

Note that 3 of the child elements have the same name, rotate. But you can tell them apart by looking at the value of the sid attribute.

For more about XML, see the W3Schools tutorial.

Sample Scene DOM Path

Scene DOM Paths are also based on elements and attributes. Each Scene DOM Path starts with the unique identifier a parent element, descends through names of child elements, and ends with the name of an element or attribute.

The following Scene DOM Path could be used with the XML example above. It specifies the x-rotation value of the Camera:

Camera:rotate|sid=rotationX

This path has 2 parts:

  • Camera means, "Start with the element whose id attribute has the value Camera".
  • :rotate|sid=rotationX means, "Descend through a child element whose name is rotate, and whose sid attribute has the value rotationX".

Following the path would lead to the x-rotation value, 1 0 0 0.

Read on for more about the Scene DOM Path syntax.

Scene DOM Path Syntax

Scene DOM Paths are made of parts. Parts contain the name of an element or attribute. Some parts also contain operators, which determine how to interpret the element or attribute name.

Parts can be combined into paths in 2 ways: as concatenated strings, or as elements of a Matlab cell array of strings. For example, the following Scene DOM Paths are equivalent:

% string form
myPath = 'Camera:rotate|sid=rotationX';

% cell array of strings form
myPath = {'Camera', ':rotate|sid=rotationX'};

This wiki page generally uses the string form.

Parent Element id

The first part of a path must contain the unique identifier of an element. The unique identifier corresponds to the value of an element's id attribute. Not all elements have an id. Those that do are usually intuitive parts of a scene, like the camera, lights, shapes, and materials.

A simple path to an element with the id value "myCamera" would look like this:

myCamera

Subsequent path parts must begin with an operator, followed by the name of an element or attribute.

Child Elements, :

The : operator specifies child elements. For example, a camera may have several child elements that describe spatial transformations. A path to the camera's scale transformation might look like this:

myCamera:scale

The : operator may appear multiple times in a path.

Attributes, .

The . operator specifies attributes of an element. For example a spatial transformation might have a sub-identifier that distinguishes it from similar transformations. A path to the sid sub-identifier of the camera's rotate transformation might look like this:

myCamera:rotate.sid

The . operator must appear in the the last part of a path.

Child Elements with Check Values, | and =

The | and = operators check the behavior of the : operator. For example, it might be necessary to disambiguate several child elements that share the name "rotate", by using the value of a sub-identifier attribute. A path to the "rotateX" transformation of camera might look like this:

myCamera:rotate|sid=rotateX

In this example, "sid" would be a check-name, and "rotateX" would be a check-value.

The | and = operators may appear multiple times in a path. They should not be flanked by spaces.

Element or Attribute Name, $

The $ operator specifies the name of an element or attribute, as opposed to its value. This allows elements and attributes to be renamed. A path to the name of a camera translate element might look like this:

myCamera:translate$

This path would point to the element name, "translate". If this path were used to rename the element, for example changing "translate" to "scale", then the original path would be invalidated. The new path to the same element would be:

myCamera:scale

The $ operator works with attributes as well as elements. A path to the name of the sid attribute of a camera's rotate element might look like this:

myCamera:rotate|sid=rotateX.sid$

This would point to the string name "sid".

The $ operator must appear in the the last part of a path.

Long Scene DOM Path

A longer path could point to a child element after disambiguating multiple intermediate elements, with different names, based on different attributes. For example, the following path points to the value of an object reference, buried deep within a real Collada scene file:

Sphere-mesh:mesh:polylist|material=SphereMaterial:input|semantic=VERTEX.source

This path has 5 parts:

  • Sphere-mesh means, "Start with the element identified as Sphere-mesh".
  • :mesh means, "Descend into the actual mesh data contained inside Sphere-mesh".
  • :polylist|material=SphereMaterial means, "Descend into the particular polygon list of a material called SphereMaterial".
  • :input|semantic=VERTEX means, "Descend into the particular part of the polygon list that contains VERTEX positions (as opposed to NORMAL vectors)".
  • .source means, "Get the value of the source attribute of the VERTEX positions".

Following this path would lead to a reference, indicating where to find actual numerical data.

RenderToolbox3 uses Scene DOM Paths like this internally. Users probably don't need to worry about such long paths or data indirection.

Add a custom footer
Add a custom sidebar
Clone this wiki locally