X3D Classic VRML encoding 4.0 draft — ISO/IEC 19776-2:202x

Extensible 3D (X3D) encodings
Part 2: Classic VRML encoding

5 Encoding of fields

5.1 Introduction

5.1.1 Topics

5.1.2 Description

There are two general classes of fields: fields that contain a single value (where, for example, a value may be a single number, a vector, or even an image), and fields that contain an ordered list of multiple values. Single-valued fields have names that begin with SF. Multiple-valued fields have names that begin with MF.

Single-valued fields (SF types) are written as a list of one or more values, depending on the type. For example, an SFVec3f type is a three-tuple array of three single-precision floating-point values. No square brackets ("[ ]") are written around single-valued field types.

A floating-point number may be specified either as an integer or with a decimal point, and may also include an exponent portion. Single-precision and double-precision floating-point values have the same syntax.

   transparency foo 0
   transparency foo 0.0
   transparency foo 0.
   transparency foo 0.e20 1.e20

Multiple-valued fields are written as an ordered list of values enclosed in square brackets and separated by whitespace. If the MF field has zero values, only the square brackets ("[ ]") are written. The last value may optionally be followed by whitespace. If the field has exactly one value, the brackets may be omitted.

For an example MetadataInteger node, all All of the following representations are valid for a multiple-valued MFInt32 field named value, foo which is an ordered list of length 1 containing the single integer value 1.

5.2 SFBool and MFBool

The SFBool field type specifies a single boolean value encoded as either the string TRUE or the string FALSE. The MFBool field type specifies zero or more SFBool string values.

TimeSensor { enabled FALSE }

MetadataBoolean { value [ TRUE FALSE TRUE FALSE ] }

For these two node instances, enabled is an SFBool field defining a FALSE value, and value is an MFBool field defining an ordered list of SFBool values.

fooBool FALSE

is an SFBool field, fooBool, defining a FALSE value.

5.3 SFColor and MFColor

The SFColor field specifies one RGB (red-green-blue) colour triple. MFColor specifies zero or more RGB triples (i.e. zero or more SFColor values). Each colour is encoded as an RGB triple of floating-point numbers in ISO C floating-point format (see ISO/IEC 9899) in the range 0.0 to 1.0.

Material { diffuseColor 0.1 0.6 0.8 }

Color { color [ 1 0 0, 0.0 1.0 0.0, 0 0 1 ] }

For these two node instances, diffuseColor is an SFColor field defining a single RGB value, and color is an MFColor field defining an ordered list of SFColor values.

fooColor [ 1.0 0. 0.0, 0 1 0, 0 0 1 ]

is an MFColor field, fooColor, containing the three primary colours red, green, and blue.

5.4 SFColorRGBA and MFColorRGBA

The SFColorRGBA field specifies one RGB (red-green-blue) colour triple and one alpha (opacity) value. MFColorRGBA specifies zero or more SFColorRGBA values. Each colour is encoded as an RGBA 4-tuple of floating-point numbers in ISO C floating-point format (see ISO/IEC 9899) in the range 0.0 to 1.0.

TextureProperties { borderColor 0.1 0.6 0.8 0.5 }

ColorRGBA { color [ 1 0 0 0.5, 0.0 1.0 0.0 0.5, 0 0 1 0.5 ] }

For these two node instances, borderColor is an SFColorRGBA field defining a single RGBA value, and color is an MFColorRGBA field defining an ordered list of SFColorRGBA values.

fooColor [ 1.0 0. 0.0 1.0, 0 1 0 1, 0 0 1 1 ]

is an MFColorRGBA field, fooColor, containing the three primary colours red, green, and blue with complete opacity.

5.5 SFDouble and MFDouble

The SFDouble field specifies one double-precision floating-point number. MFDouble specifies zero or more double-precision floating-point numbers. SFDouble and MFDouble values SFDoubles and MFDoubles are encoded as ISO C floating-point format (see ISO/IEC 9899).

GeoElevationGrid { xSpacing 0.3047999995 zSpacing 0.3047999995 }

MetadataDouble { value [ 0 1.0 2.718281828459045 3.141592653589793 ] }

For these two node instances, xSpacing and zSpacing are SFDouble fields each defining one double-precision value, and value is an MFDouble field defining an ordered list of SFDouble values.

fooDouble [ 3.1415926, 12.5666666666e-12, .000176989898 ]

is an MFDouble field, fooDouble, containing three double-precision floating-point values.

5.6 SFFloat and MFFloat

The SFFloat field specifies one single-precision floating-point number. MFFloat specifies zero or more single-precision floating-point numbers. SFFloats and MFFloats are encoded as ISO C floating-point format (see ISO/IEC 9899).

PointLight { radius 30.48 }

MetadataFloat { value [ 0 1.0 2.718281828 3.1415926535 ] }

For these two node instances, radius is an SFFloat field defining one single-precision value, and value is an MFFloat field defining an ordered list of SFFloat values.

fooFloat [ 3.1415926, 12.5e-3, .0001 ]

is an MFFloat field, fooFloat, containing three floating-point values.

5.7 SFImage and MFImage

The SFImage field specifies a single uncompressed 2-dimensional pixel image. MFImage specifies zero or more SFImage values.

SFImage fields are encoded as three integers representing the width, height and number of components in the image, followed by a sequence of width×height hexadecimal (or integer) values representing the pixels in the image, each separated by whitespace:

Pixels are specified from left to right, bottom to top. The first hexadecimal value is the lower left pixel and the last value is the upper right pixel. Pixel values are limited to 256 levels of intensity (i.e., 0-255 decimal or 0x00-0xFF hexadecimal). Editors note, for readability and clarity: first sentence was moved here verbatim from below, then bullet points inserted.

Each pixel is read as a single unsigned number. For example, a 3-component pixel with value 0x0000FF may also be written as 0xFF (hexadecimal) or 255 (decimal). Pixels are specified from left to right, bottom to top. The first hexadecimal value is the lower left pixel and the last value is the upper right pixel.

is a 1 pixel wide by 2 pixel high one-component (i.e., greyscale) image, with the bottom pixel white and the top pixel black.

PixelTexture { image fooImage 2 4 3 0xFF0000 , 0xFF00 , 0 , 0 , 0 , 0 , 0xFFFFFF , 0xFFFF00
# 2x4x3 with one red, one green, four black, one white, and one yellow pixels
}

is a 2 pixel wide by 4 pixel high RGB image, containing 3-component RGB values, for an expected total of 8 RGB color values that follow. (For convenience and clarity in this Classic VRML encoding example, optional whitespace commas have been placed between each of the pixel values above.) These values define with the bottom-left pixel red, the bottom-right pixel green, the two middle rows of pixels black, the top-left pixel white, and the top-right pixel yellow.

Script {
inputOutput MFImage imagePair fooImages [1 2 1 0xFF 0x00, 1 2 1 0x40 0xC0]
url [ "ImagePairComparison.js" ]
}

The imagePair field declaration includes an initialization value that specifies two images. The first image the first of which is a 1 pixel wide by 2 pixels high one-component (i.e., greyscale) image, as shown in Example 8. The as in the first example. while the second image is also a 1 pixel wide by 2 pixels high one-component (i.e., greyscale) image with the bottom pixel dark grey and the top pixel light grey.

5.8 SFInt32 and MFInt32

The SFInt32 field specifies one 32-bit integer. The MFInt32 field specifies zero or more 32-bit integers. SFInt32 and MFInt32 values fields are encoded as an integer in decimal or hexadecimal (beginning with '0x') format.

IntegerTrigger { triggerValue 17 }

MetadataInteger { value [ 0 1 2 3 4 ] }

For these two node instances, triggerValue is an SFInt32 field defining one integer value, and value is an MFInt32 field defining an ordered list of SFInt32 values.

fooInt32 [ 17, -0xE20, -518820 ]

is an MFInt32 field containing three values.

5.9 SFMatrix3d and MFMatrix3d

The SFMatrix3d field specifies a 3×3 matrix of double-precision floating point numbers. MFMatrix3d specifies zero or more SFMatrix3d values. 3×3 matrices of double-precision floating-point numbers. Each SFMatrix3d is encoded as nine ISO C double-precision floating-point values (see ISO/IEC 9899) separated by whitespace. The first three double-precision floating-point numbers represent the top row of the matrix. The second three double-precision floating-point numbers represent second row of the matrix. The last three double-precision floating-point numbers represent the bottom row of the matrix.

DEF Script9a Script {
inputOutput SFMatrix3d field9a 1 0 0 0 1 0 0 0 1 # Editors note: no square brackets around SF fields, matching grammar
}

DEF Script9b Script {
inputOutput MFMatrix3d field9b fooMatrix3d [ 1.5968734 0.7658987778666 0 0.4387899877 1 0 0 0 1,
2.7338246644 0.5 0 4.389222333 2.5 0 0 0 1 ]
}

For these two node instances, field9a is an SFMatrix3d field defining one 3x3 matrix value, and field9b is an MFMatrix3d field defining an ordered list of SFMatrix3d values.

fooMatrix3d [ 1.5968734 0.7658987778666 0 0.4387899877 1 0 0 0 1,
2.7338246644 0.5 0 4.389222333 2.5 0 0 0 1 ]

5.10 SFMatrix3f and MFMatrix3f

The SFMatrix3f field specifies a 3×3 matrix of single-precision floating point numbers. MFMatrix3f specifies zero or more SFMatrix3f values. 3×3 matrices of single-precision floating-point numbers. Each SFMatrix3f is encoded as nine ISO C single-precision floating-point values (see ISO/IEC 9899) separated by whitespace. The first three single-precision floating-point numbers represent the top row of the matrix. The second three single-precision floating-point numbers represent the second row of the matrix. The last three single-precision floating-point numbers represent the bottom row of the matrix.

RigidBody {
inertia 1 0 0 0 1 0 0 0 1 # Editors note: no square brackets around SF fields, matching grammar
}

DEF Script10b Script {
    inputOutput MFMatrix3f field10b fooMatrix3d
              [ 1.5968734 0.7658987778666 0 0.4387899877 1 0 0 0 1,
              2.7338246644 0.5 0 4.389222333 2.5 0 0 0 1 ]
}

For these two node instances, inertia is an SFMatrix3f field defining one 3x3 matrix value, and field10b is an MFMatrix3f field defining an ordered list of SFMatrix3f values.

fooMatrix3f [ 3.05 43.89 0 77.89 54.32 0 -3.5 2.78 1,
89.777 33.486 0 3222.2 1 17.0 4.0 -3.9 0.5 ]

5.11 SFMatrix4d and MFMatrix4d

The SFMatrix4d field specifies a 4×4 matrix of double-precision floating point numbers. MFMatrix4d specifies zero or more SFMatrix4d values. 4×4 matrices of double-precision floating-point numbers. Each SFMatrix4d is encoded as sixteen ISO C double-precision floating-point values (see ISO/IEC 9899) separated by whitespace. The first four double-precision floating-point numbers represent the top row of the matrix. The second four double-precision floating-point numbers represent the second row of the matrix. The third four double-precision floating-point numbers represent the third row of the matrix. The last four double-precision floating point numbers represent the bottom row of the matrix.

DEF Script11a Script {
inputOutput SFMatri4d field11a 1 0 0 0 0 1 0 0 0 0 1 0 0 0 0 1 # Editors note: no square brackets around SF fields, matching grammar
}

DEF Script11b Script {
    inputOutput MFMatrix4d field11b fooMatrix3d
            [ 1.5968734 0.7658987778666 0 0.4387899877
              1 0 0 0
              36.31896667 0.5 -13.4879906634 0
              0 0 0 1,

              2.7338246644 0.5 0 4.389222333
              2.5 0 0 0
              987.883 -0.5432 3289.77 1
              -43.5 43.5 -10 1 ]
}

For these two node instances, field11a is an SFMatrix4d field defining one 4×4 matrix value, and field11b is an MFMatrix4d field defining an ordered list of SFMatrix4d values.

fooMatrix3d [ 1.5968734 0.7658987778666 0 0.4387899877
              1 0 0 0
              36.31896667 0.5 -13.4879906634 0
              0 0 0 1,

              2.7338246644 0.5 0 4.389222333
              2.5 0 0 0
              987.883 -0.5432 3289.77 1
              -43.5 43.5 -10 1]

5.12 SFMatrix4f and MFMatrix4f

The SFMatrix4f field specifies a 4×4 matrix of single-precision floating point numbers. MFMatrix4f specifies zero or more SFMatrix4f values. 4×4 matrices of single-precision floating-point numbers. Each SFMatrix4f is encoded as sixteen ISO C single-precision floating-point values (see ISO/IEC 9899) separated by whitespace. The first four single-precision floating-point numbers represent the top row of the matrix. The second four single-precision floating-point numbers represent the second row of the matrix. The third four single-precision floating-point numbers represent the third row of the matrix. The last four single-precision floating point numbers represent the bottom row of the matrix.

TextureTransformMatrix3D {
matrix 1 0 0 0 0 1 0 0 0 0 1 0 0 0 0 1 # Editors note: no square brackets around SF fields, matching grammar
}

DEF Script12b Script {
    inputOutput MFMatrix4f field12b fooMatrix3d
             [ 3.05 43.89 0 77.89
              54.32 0 -3.5 2.78
              14.322210443 -0.00007788666 2.1 1
              -0.5 0.5 2.9987799 13.34,

              89.777 33.486 0 3222.2
              1 17.0 4.0 -3.9
              -33.3333 17.6689 0.5 1
              1 1 -3 1.115 ]
}

For these two node instances, matrix is an SFMatrix4f field defining one 4x4 matrix value, and field12b is an MFMatrix4f field defining an ordered list of SFMatrix4f values.

fooMatrix3f [ 3.05 43.89 0 77.89
              54.32 0 -3.5 2.78
              14.322210443 -0.00007788666 2.1 1
              -0.5 0.5 2.9987799 13.34,

              89.777 33.486 0 3222.2
              1 17.0 4.0 -3.9
              -33.3333 17.6689 0.5 1
              1 1 -3 1.115 ]

5.13 SFNode and MFNode

The SFNode field specifies an X3D a VRML node. The MFNode field specifies zero or more nodes.

Shape {
    appearance Appearance {
        material Material { diffuseColor 0 0 1 }
    }
}

The preceding scene-graph excerpt illustrates illustrates valid syntax for two SFNode fields, namely appearance and material.

EXAMPLE 2

Group {
    children fooNode [
          DEF CUBE Shape { geometry Box { } }
          Transform {
              translation 1 0 0
              children [ USE CUBE ]
          }
          USE SOME_OTHER_NODE
     ]
}

The preceding scene-graph excerpt illustrates valid syntax for an MFNode field, children, of which the first instance contains multiple nodes, and the second instance contains a single USE node.

fooNode, defining four nodes:
fooNode [ Transform { translation 1 0 0 }
          DEF CUBE Box { }
          USE CUBE
          USE SOME_OTHER_NODE ]

The SFNode field may contain the keyword NULL to indicate when that it is empty.

5.14 SFRotation and MFRotation

The SFRotation field specifies one arbitrary axis-angle rotation. The MFRotation field specifies zero or more arbitrary rotations. An SFRotation is encoded as four ISO C floating-point values (see ISO/IEC 9899) separated by whitespace.

Transform {
    rotation 0 1 0 1.5708
    children [
        Inline {
            url ["HelloWorld.x3dv" ]
        }
    ]
}

OrientationInterpolator {
key [ 0 0.33 0.67 1 ]
keyValue [ 0 1 0 0, 0 1 0 1.047, 0 1 0 2.096, 0 1 0 3.14159 ]
}

For these two node instances, rotation is an SFRotation field defining one axis-angle rotation value, and keyValue is an MFRotation field defining an ordered list of SFRotation values.

An SFRotation containing a PI radians rotation about the Y axis is:

fooRot 0.0 1.0 0.0 3.14159265

5.15 SFString and MFString

The SFString and MFString fields contain strings formatted with the UTF-8 universal character set (see ISO 10646). SFString specifies a single string. The MFString specifies zero or more strings. Strings are encoded as a sequence of UTF-8 octets enclosed in double quotes (e.g., "string").

Any characters (including linefeeds and '#') may appear within the quotes. A double quote character within the string is preceded with a backslash. A backslash character within the string is also preceded with a backslash, thereby forming two backslashes.

WorldInfo { title "Hello World" }

Text { string fooString [ "One, Two, Three", "He said, \"Immel did it!\"" ] }

For these two node instances, title is an SFString field defining a single-line string value, and the Text node's string field is an MFString field defining an ordered list of SFString values.

5.16 SFTime and MFTime

The SFTime field specifies a single time value. The MFTime field specifies zero or more time values. Time values are encoded as a double-precision floating point number in ISO C floating-point format (see ISO/IEC 9899). As stated in ISO/IEC 19775-1, each SFTime field represents the number of seconds since Jan 1, 1970, 00:00:00 GMT.

TimeSensor { cycleInterval 5.0 }

DEF Script19 Script {
inputOutput MFTime field19 [ 0 1 2 4.0 8.0 16.0 ]
}

For these two node instances, cycleInterval is an SFTime field defining one double-precision time value, and field19 is an MFTime field defining an ordered list of SFTime values.

fooTime 0.0

is an SFTime field, fooTime, representing a time of 0.0 seconds.

5.17 SFVec2d and MFVec2d

The SFVec2d field specifies a two-dimensional (2D) double-precision vector. An MFVec2d field specifies zero or more 2D double-precision vectors. SFVec2d and MFVec2d values SFVec2d's and MFVec2d's are encoded as a pair of ISO C floating-point values (see ISO/IEC 9899) separated by whitespace.

DEF Script17 Script {
inputOutput SFVec2d field17 0.0 0.0 # Editors note: no square brackets around SF fields, matching grammar
}

NurbsCurve2D { controlPoint [ 42.89978899 666.000123, 7 94.1 ] }

For the first node instance, field17 is a SFVec2d fields defining a double-precision 2-tuple value. For the NurbsCurve2D node instance, controlPoint is an MFVec2d field defining an ordered list of SFVec2d values.

5.18 SFVec2f and MFVec2f

The SFVec2f field specifies a two-dimensional (2D) vector. An MFVec2f field specifies zero or more 2D vectors. SFVec2f and MFVec2f values SFVec2f's and MFVec2f's are encoded as a pair of ISO C floating-point values (see ISO/IEC 9899) separated by whitespace.

PlaneSensor { minPosition -1 -1 maxPosition 1 1 }

Extrusion {
crossSection [ -1 -1, -1 1, 1 1, 1 -1 ]
scale [ 0.8 0.8, 1.2 1.2 ]
}

For the PlaneSensor node instance, minPosition and minPosition are SFVec2f fields each defining a single-precision 2-tuple value. For the Extrusion node instance, crossSection and scale are MFVec2f fields each defining an ordered list of SFVec2f values.

5.19 SFVec3d and MFVec3d

The SFVec3d field specifies a three-dimensional (3D) double-precision vector. An MFVec3d field specifies zero or more 3D double-precision vectors. SFVec3d and MFVec3d values SFVec3d's and MFVec3d's are encoded as three ISO C floating-point values (see ISO/IEC 9899) separated by whitespace.

GeoOrigin { geoCoords 0.0 0.0 0.0 }

GeoPositionInterpolator { keyValue [
51.5122 -0.065 10000000, 48.865 2.35 10000000,
40.6698 -73.943849 10000000, 51.5122 -0.065 10000000 ]
}

For these two node instances, geoCoords is an SFVec3d field defining one double-precision three-tuple value, and keyValue is an MFVec3d field defining an ordered list of SFVec3d values.

5.20 SFVec3f and MFVec3f

The SFVec3f field specifies a three-dimensional (3D) vector. An MFVec3f field specifies zero or more 3D vectors. SFVec3f and MFVec3f values SFVec3f's and MFVec3f's are encoded as three ISO C floating-point values (see ISO/IEC 9899) separated by whitespace.

Transform { translation 0 0 -1 }

PositionInterpolator { keyValue [ 0 0 0, 0 2 0, 0 3 0, 0 4 0 ] }

For these two node instances, translation is an SFVec3f field defining one single-precision three-tuple value, and keyValue is an MFVec3f field defining an ordered list of SFVec3f values.

5.21 SFVec4d and MFVec4d

The SFVec4d field specifies a four-dimensional (4D) double-precision vector. An MFVec4d field specifies zero or more 4D double-precision vectors. SFVec4d and MFVec4d values SFVec4d's and MFVec4d's are encoded as four ISO C floating-point values (see ISO/IEC 9899) separated by whitespace.

DEF Script21a Script {
inputOutput SFVec4d field21a 1.000000000001 42 666.35357878 32.6 # Editors note: no square brackets around SF fields, matching grammar
}

DEF Script21b Script {
inputOutput MFVec4d field21b [ 1.000000000001 42 666.35357878 32.6, 7 94 0.100000000007 143.998 ]
}

For these two node instances, field21a is an SFVec4d field defining one double-precision time value, and field21b is an MFVec4d field defining an ordered list of SFVec4d values.

fooVec3d [ 1.000000000001 42 666.35357878 32.6, 7 94 0.100000000007 143.998 ]

5.22 SFVec4f and MFVec4f

The SFVec4f field specifies a four-dimensional (4D) single-precision vector. An MFVec4f field specifies zero or more 4D single-precision vectors. SFVec4f and MFVec4f values SFVec4f's and MFVec4f's are encoded as four C floating-point values (see ISO/IEC 9899) separated by whitespace.

DEF Script22 Script {
inputOutput SFVec4f field22 1 42 666 -43.8 # Editors note: no square brackets around SF fields, matching grammar
}

NurbsTextureCoordinate { controlPoint [ 1 42 666 -43.8, 7 94 0 0.0001 ] }

For these two node instances, field22 is an SFVec4f field defining one single-precision 4-tuple value, and controlPoint is an MFVec4f field defining an ordered list of SFVec4f values.