Chapter 4: Field and Event Reference -- The Annotated VRML97 Reference Manual

TECHNICAL NOTE: There are some "missing" MF field types. For example, there is an SFBool field type but no MFBool type. Only the field types used by the 54 nodes in the specification are defined. The practical, immediate benefits of making implementations a little bit smaller were judged to be more important than the intangible benefits of having a more symmetric design or the possible future benefits to language extensions defined using EXTERNPROTO.

The design of the field types is not as conceptually "clean" as it could be. The problem is that some of the field types define only the syntax or structure of the values they contain, while others define both the syntax and the semantics of the values they contain. For example, an SFVec3f field can contain any triple of floating point numbers, regardless of how they are used. An SFColor field is syntactically identical to an SFVec3f field, but it implies something about the semantics of the numbers in the field—they must be between 0.0 and 1.0, and they represent RGB intensities. The field types would be more consistent if either there was no SFColor field type or if the SFVec3f field type was replaced with field types with specific uses--perhaps SFPosition (for a point in space) and SFUnitVector (for a unit vector such as a polygon normal).

It isn't clear which design would be better--one with fewer field types that define only the structure of the fields or one with more field types that define the semantics of the fields. The mix of both found in the current specification works pretty well in practice.

TIP: Each component (R, G, B) of a color is expressed in VRML as a floating point number (0.0 to 1.0), but most VRML implementations will convert them internally into, at most, 256 discrete levels. So writing out colors with more than three significant digits of precision just makes your VRML files unnecessarily large. Users will not be able to distinguish between color (.005199, .12345, 0) and color (.005, .123, 0).

TIP: Legal values for single-precision floating point values range from 1.0e38 to -1.0e38, with more than seven significant decimal digits of accuracy. Seven digits of accuracy means you can model something 10 km big with about plus or minus 1-mm accuracy. Usually you won't need such high accuracy and you can make your VRML files much smaller by writing out floating point values with less precision.

TIP: The SFImage field is used only by the PixelTexture node and is meant to be used only for small images or images that are algorithmically generated by a Script node. For larger images it is generally much better to use ImageTexture nodes and store the images in PNG, JPEG, or GIF files, since those file formats can compress the images, making them much faster to transmit across the network.

TIP: SFNode and MFNode are used whenever a node needs to include the definition of another node in order to define itself. The syntax of SFNode and MFNode is identical to standard VRML file syntax—you simply specify the node definition as the field value.

The most common use of SFNode/MFNode is in grouping nodes that contain children nodes. For example, the Group node has an exposed MFNode field named children. This field contains a list of node definitions that represent the child nodes that the Group encapsulates. Remember that node definitions may contain DEF names or USE instantiations. In the following file excerpt, the Group node specifies five children nodes in the children field. Note that the last two children are specified through the USE syntax:

    ... 
    DEF S1 Shape { geometry Sphere {} } 
    Group { 
      children [                   # an MFNode exposedField 
        Shape { geometry Cone {} } # first child 
        Shape { geometry Box {} }  # second child 
        DEF T1 Transform { ... }   # third child (named) 
        USE S1 # fourth child (instance of S1) 
        USE T1 # fifth child (instance of T1) 
      ] 
    }

TIP: Be careful. One rotation has multiple equivalent representations in the axis-plus-angle form chosen by VRML to represent rotations. Zero rotations can be especially troublesome; (1, 0, 0, 0) and (0, 1, 0, 0) are equivalent (and are equivalent to any rotation of the form (x, y, z, 0)). Similarly, a rotation (x, y, z, angle) is equivalent to the rotation (-x, -y, -z, -angle).

This means that you must not assume that the particular values you choose for the axis and angle to represent a rotation will be preserved by a browser. For example, a browser may read in an SFRotation value of (1, 0, 0, 0), but may write the value back out (or return it to a Script node) as (0, 0, 1, 0). They are equivalent rotations, but if you were expecting to get exactly the same axis and angle, you will be surprised.

Also note that these fields cannot store multiple rotations about an axis, for exactly the same reason: A rotation (x, y, z, angle) is the same as (x, y, z, i×2×angle), for any positive or negative integer i.

TECHNICAL NOTE: It might have been better to name these fields SF/MFOrientation, because they really represent a "final" orientation of something and do not imply anything about how it might have been rotated to get to that orientation. A common VRML 1.0 extension was a Rotor node that used an SFRotation field to define how the object should rotate. A very common error was to use a zero rotation angle about a desired rotation axis to define the rotation. Browsers that stored rotations internally as quaternions or matrices would immediately convert the SFRotation into their internal representation and lose the desired rotation axis. The end result was a rotation about (usually) the z-axis and a very frustrated user.

If you are writing extension nodes or Scripts that truly require a rotation axis and a rotation angle, do not use an SFRotation field. Instead, store the axis in an SFVec3f field and store the angle in an SFFloat field. The Rotor node would have worked perfectly if the desired rotation axis was specified as an SFVec3f field.

TECHNICAL NOTE: Time must be written as double-precision values to represent absolute times accurately that are 20 years past the time origin. About 800 million seconds have elapsed since 1970, so an accuracy of one part in 800 million (about 1e-9) is required to represent absolute times in the present with one-second accuracy--beyond the seven digit accuracy given by single-precision floating points.

Chapter 4 Field and Event Reference

4.1 Introduction

4.1.1 Description

4.2 SFBool

4.3 SFColor and MFColor

4.4 SFFloat and MFFloat

4.5 SFImage

4.6 SFInt32 and MFInt32

4.7 SFNode and MFNode

4.8 SFRotation and MFRotation

4.9 SFString and MFString

4.10 SFTime

4.11 SFVec2f and MFVec2f

4.12 SFVec3f and MFVec3f