8.2 X3D Nodes

The following nodes are currently supported in the X2D/X3D viewer. These nodes are analogous to VRML nodes, and much of the information here is directly from the VRML specifications. For more information, see the VRML specifications.

Appearance
Box
Color
Coordinate
DirectionalLight
IndexedFaceSet
Material
Normal
Shape
Sphere
Transform
Viewpoint

8.2.1  Appearance

<Appearance>
  <Material>...</Material>
</Apperance>

The Appearance node specifies the visual properties of a geometry. An Appearance element can contain one Material node. If no Material node is given, then, lighting is off (all lights are ignored during rendering of the object that references this Appearance) and the unlit object colour is (1, 1, 1). Details of the lighting model are in 4.14, Lighting model of the VRML specs.

8.2.2  Box

<Box size="2.0 2.0 2.0"/>

The Box node specifies a rectangular parallelepiped box centered at (0, 0, 0) in the local coordinate system and aligned with the local coordinate axes. By default, the box measures 2 units in each dimension, from -1 to +1. The size attribute specifies the extents of the box along the X-, Y-, and Z-axes respectively and each component value shall be greater than zero.

8.2.3  Color

<Color color="0.2 0.2 0.2, 0.4 0.4 0.4"/>

This node defines a set of RGB or RGBA colors to be used in the fields of another node. The color attribute can contain an arbitrary amount of colors, each of which are comma delmiited.

Color nodes are only used to specify multiple colours for a single geometric shape, such as colours for the faces or vertices of an IndexedFaceSet. A Material node is used to specify the overall material parameters of lit geometry. If both a Material node and a Color node are specified for a geometric shape, the colours shall replace the diffuse component of the material.

8.2.4  Coordinate

<Coordinate point="0 0 0, 1 0 0, 1 0 -1, 0.5 1 0"/>

This node defines a set of 3D coordinates to be used in the coord field of vertex-based geometry nodes including IndexedFaceSet, IndexedLineSet, and PointSet.

8.2.5  DirectionalLight

<DirectionalLight ambientIndensity="0.0"
                  color="1 1 1"
                  direction="0 0 -1"
                  intensity="1.0"
                  on="true"/>

The DirectionalLight node defines a directional light source that illuminates along rays parallel to a given 3-dimensional vector. A description of the ambientIntensity, color, intensity, and on fields is in 4.6.6, Light sources of the VRML specs.

The direction field specifies the direction vector of the illumination emanating from the light source in the local coordinate system. Light is emitted along parallel rays from an infinite distance away. A directional light source illuminates only the objects in its enclosing parent group. The light may illuminate everything within this coordinate system, including all children and descendants of its parent group. The accumulated transformations of the parent nodes affect the light.

8.2.6  IndexedFaceSet

<IndexedFaceSet ccw="true"
                colorIndex="0, 1, 0, -1, 0, 2, 0, -1"
                colorPerVertex="true"
                convex="true"
                coordIndex="0, 1, 3, -1, 0, 2, 3, -1"
                creaseAngle="0.0"
                normalIndex="0, 1, 3, -1, 0, 2, 3, -1"
                normalPerVertex="true"
                solid="true>
  <Color color="0.2 0.2 0.2, 0.4 0.4 0.4, 0.6 0.6 0.6"/>
  <Coordinate point="0 0 0, 1 0 0, 1 0 -1, 0.5 1 0"/>
  <Normal vector="0 0 1, 0 0 1, 0 0 1, 0 0 1"/>
</IndexedFaceSet>

The IndexedFaceSet node represents a 3D shape formed by constructing faces (polygons) from points listed in the Coordinate element. The Coordinate node that defines the 3D vertices referenced by the coordIndex field. IndexedFaceSet uses the indices in its coordIndex attribute to specify the polygonal faces by indexing into the coordinates in the Coordinate node. An index of "-1" indicates that the current face has ended and the next one begins. The last face may be (but does not have to be) followed by a "-1" index. If the greatest index in the coordIndex field is N, the Coordinate node shall contain N+1 coordinates (indexed as 0 to N). Each face of the IndexedFaceSet shall have:

  1. at least three non-coincident vertices;
  2. vertices that define a planar polygon;
  3. vertices that define a non-self-intersecting polygon.

Otherwise, The results are undefined.

The IndexedFaceSet node is specified in the local coordinate system and is affected by the transformations of its ancestors.

Descriptions of the coord, normal, and texCoord fields are provided in the Coordinate, Normal, and TextureCoordinate nodes, respectively.

Details on lighting equations and the interaction between color field, normal field, textures, materials, and geometries are provided in 4.14, Lighting model.

If a Color element is present, its colors are applied to the vertices or faces of the IndexedFaceSet as follows:

  1. If colorPerVertex is FALSE, colours are applied to each face, as follows:
    1. If the colorIndex field is not empty, then one colour is used for each face of the IndexedFaceSet. There shall be at least as many indices in the colorIndex field as there are faces in the IndexedFaceSet. If the greatest index in the colorIndex field is N, then there shall be N+1 colours in the Color node. The colorIndex field shall not contain any negative entries.
    2. If the colorIndex field is empty, then the colours in the Color node are applied to each face of the IndexedFaceSet in order. There shall be at least as many colours in the Color node as there are faces.
  2. If colorPerVertex is TRUE, colours are applied to each vertex, as follows:
    1. If the colorIndex field is not empty, then colours are applied to each vertex of the IndexedFaceSet in exactly the same manner that the coordIndex field is used to choose coordinates for each vertex from the Coordinate node. The colorIndex field shall contain at least as many indices as the coordIndex field, and shall contain end-of-face markers (-1) in exactly the same places as the coordIndex field. If the greatest index in the colorIndex field is N, then there shall be N+1 colours in the Color node.
    2. If the colorIndex field is empty, then the coordIndex field is used to choose colours from the Color node. If the greatest index in the coordIndex field is N, then there shall be N+1 colours in the Color node.

If the Color element is not present, the geometry shall be rendered normally using the Material and texture defined in the Appearance node (see 4.14, Lighting model, for details).

If the Normal element is present, its normals are applied to the vertices or faces of the IndexedFaceSet in a manner exactly equivalent to that described above for applying colours to vertices/faces (where normalPerVertex corresponds to colorPerVertex and normalIndex corresponds to colorIndex). If the Normal element is not present, the browser shall automatically generate normals, using creaseAngle to determine if and how normals are smoothed across shared vertices (see 4.6.3.5, Crease angle field).

8.2.7  Material

<Material ambientIntensity="0.2"
          diffuseColor="0.8 0.8 0.8"
          emissiveColor="0.0 0.0 0.0"
          shininess="0.2"
          specularColor="0.0 0.0 0.0"
          transparency="0.0"/>

The Material node specifies surface material properties for associated geometry nodes and is used by the VRML lighting equations during rendering. Subclause 4.14, Lighting model, contains a detailed description of the VRML lighting model equations.

All of the fields in the Material node range from 0.0 to 1.0.

The fields in the Material node determine how light reflects off an object to create colour:

  1. The ambientIntensity field specifies how much ambient light from light sources this surface shall reflect. Ambient light is omnidirectional and depends only on the number of light sources, not their positions with respect to the surface. Ambient colour is calculated as ambientIntensity × diffuseColor.
  2. The diffuseColor field reflects all VRML light sources depending on the angle of the surface with respect to the light source. The more directly the surface faces the light, the more diffuse light reflects.
  3. The emissiveColor field models "glowing" objects. This can be useful for displaying pre-lit models (where the light energy of the room is computed explicitly), or for displaying scientific data.
  4. The specularColor and shininess fields determine the specular highlights (e.g., the shiny spots on an apple). When the angle from the light to the surface is close to the angle from the surface to the viewer, the specularColor is added to the diffuse and ambient colour calculations. Lower shininess values produce soft glows, while higher values result in sharper, smaller highlights.
  5. The transparency field specifies how "clear" an object is, with 1.0 being completely transparent, and 0.0 completely opaque.

8.2.8  Normal

<Normal vector="0 0 1, 0 0 1, 0 0 1, 0 0 1"/>

This node defines a set of 3D surface normal vectors to be used in the vector field of some geometry nodes (e.g., IndexedFaceSet and ElevationGrid). This node contains one multiple-valued field that contains the normal vectors. Normals shall be of unit length.

8.2.9  Shape

<Shape>
  <Appearance>...</Appearance>
  <Geometry>...</Geometry>
</Shape>

The Shape node has two elements, Appearance and a geometry node, which are used to create rendered objects in the world. The Appearance node specifies the visual attributes (e.g., material and texture) to be applied to the geometry. The specified geometry node (Box, Sphere, IndexedFaceSet) is rendered with the specified appearance nodes applied.

If there is no geometry element, the object is not drawn.

8.2.10  Sphere

<Sphere radius="1.0"/>

The Sphere node specifies a sphere centered at (0, 0, 0) in the local coordinate system. The radius attribute specifies the radius of the sphere and shall be greater than zero.

8.2.11  Transform

<Transform center="0 0 0"
           rotation="0 0 1 0"
           scale="1 1 1"
           scaleOrientation="0 0 1 0"
           translation="0 0 0">
  <Child/>
  <Child/>
  ...
</Transform>

The Transform node is a grouping node that defines a coordinate system for its children that is relative to the coordinate systems of its ancestors. See 4.4.4, Transformation hierarchy, and 4.4.5, Standard units and coordinate system, for a description of coordinate systems and transformations.

The translation, rotation, scale, scaleOrientation and center fields define a geometric 3D transformation consisting of (in order):

  1. a (possibly) non-uniform scale about an arbitrary point;
  2. a rotation about an arbitrary point and axis;
  3. a translation.

The center field specifies a translation offset from the origin of the local coordinate system (0,0,0). The rotation field specifies a rotation of the coordinate system. The scale field specifies a non-uniform scale of the coordinate system. scale values shall be greater than zero. The scaleOrientation specifies a rotation of the coordinate system before the scale (to specify scales in arbitrary orientations). The scaleOrientation applies only to the scale operation. The translation field specifies a translation to the coordinate system.

Given a 3-dimensional point P and Transform node, P is transformed into point P' in its parent's coordinate system by a series of intermediate transformations. In matrix transformation notation, where C (center), SR (scaleOrientation), T (translation), R (rotation), and S (scale) are the equivalent transformation matrices,

    P' = T × C × R × SR × S × -SR × -C × P

8.2.12  Viewpoint

<Viewpoint fieldOfView="0.785398"
           orientation="0 0 1 0"
           position="0 0 10"
           description=""/>

The Viewpoint node defines a specific location in the local coordinate system from which the user may view the scene.

The position and orientation fields of the Viewpoint node specify relative locations in the local coordinate system. Position is relative to the coordinate system's origin (0,0,0), while orientation specifies a rotation relative to the default orientation. In the default position and orientation, the viewer is on the Z-axis looking down the -Z-axis toward the origin with +X to the right and +Y straight up. Viewpoint nodes are affected by the transformation hierarchy.

The fieldOfView field specifies a preferred minimum viewing angle from this viewpoint in radians. A small field of view roughly corresponds to a telephoto lens; a large field of view roughly corresponds to a wide-angle lens. The field of view shall be greater than zero and smaller than PI. The value of fieldOfView represents the minimum viewing angle in any direction axis perpendicular to the view. For example, a browser with a rectangular viewing projection shall have the following relationship:

      display width    tan(FOVhorizontal/2)
      ------------------ = ---------------------------
      display height   tan(FOVvertical/2)

where the smaller of display width or display height determines which angle equals the fieldOfView (the larger angle is computed using the relationship described above). The larger angle shall not exceed PI and may force the smaller angle to be less than fieldOfView in order to sustain the aspect ratio.

The description field specifies a textual description of the Viewpoint node. This may be used by browser-specific user interfaces. If a Viewpoint's description field is empty it is recommended that the browser not present this Viewpoint in its browser-specific user interface.