Extensible 3D (X3D) encodings

Part 2: Classic VRML encoding

5 Encoding of fields

Table 5.1 lists the topics in this clause.

Table 5.1 — Topics in this clause

This clause describes the syntax of *field* data type values.

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**.

Multiple-valued fields are written as an ordered list of values enclosed in square brackets and separated by whitespace. If the 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.

EXAMPLE 1 All of the following are valid for a multiple-valued
MFInt32 field named *foo* containing the single integer value 1:

** foo 1
foo [1,]
foo [ 1 ]**

A floating point number may be specified either as an integer or with a decimal point and may also include an exponent portion.

EXAMPLE 2 All of the following are validly expressed floating point values:

** foo 0
foo 0.0
foo **

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

EXAMPLE

**fooBool FALSE**

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

The SFColor field specifies one RGB (red-green-blue) colour triple. MFColor specifies zero or more RGB triples. 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.

EXAMPLE

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.

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.

EXAMPLE

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.

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

EXAMPLE

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

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

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).

EXAMPLE

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

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

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 width×height hexadecimal or
integer values representing the pixels in the image, separated by whitespace:

EXAMPLE

**fooImage <width> <height> <num components> <pixel values>**

Pixel values are limited to 256 levels of intensity (i.e., 0-255 decimal or 0x00-0xFF hexadecimal). A one-component image specifies one-byte hexadecimal or integer values representing the intensity of the image. For example, 0xFF is full intensity in hexadecimal (255 in decimal), 0x00 is no intensity (0 in decimal). A two-component image specifies the intensity in the first (high) byte and the alpha opacity in the second (low) byte. Pixels in a three-component image specify the red component in the first (high) byte, followed by the green and blue components (e.g., 0xFF0000 is red, 0x00FF00 is green, 0x0000FF is blue). Four-component images specify the alpha opacity byte after red/green/blue (e.g., 0x0000FF80 is semi-transparent blue). A value of 0x00 is completely transparent, 0xFF is completely opaque. Note that alpha equals (1.0 - transparency), if alpha and transparency range from 0.0 to 1.0.

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.

EXAMPLE

**fooImage 1 2 1 0xFF 0x00**

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.

EXAMPLE

**fooImage 2 4 3 0xFF0000 0xFF00 0 0 0 0 0xFFFFFF 0xFFFF00 # red green black white yellow**

is a 2 pixel wide by 4 pixel high RGB image, 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.

EXAMPLE

**fooImages [1 2 1 0xFF 0x00, 1 2 1 0x40 0xC0]**

specifies two images the first of which is a 1 pixel wide by 2 pixels
high one-component (*i.e.*, greyscale) image 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.

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

EXAMPLE

**fooInt32 [ 17, -0xE20, -518820 ]**

is an MFInt32 field containing three values.

The SFMatrix3d field specifies a 3×3 matrix of double-precision floating point numbers. MFMatrix3d specifies zero or more 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.

EXAMPLE

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 ]

The SFMatrix3f field specifies a 3×3 matrix of single-precision floating point numbers. MFMatrix3f specifies zero or more 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.

EXAMPLE

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 ]

The SFMatrix4d field specifies a 4×4 matrix of double-precision floating point numbers. MFMatrix4d specifies zero or more 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.

EXAMPLE

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]

The SFMatrix4f field specifies a 4×4 matrix of single-precision floating point numbers. MFMatrix4f specifies zero or more 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.

EXAMPLE

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 ]

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

EXAMPLE The following illustrates valid syntax for an MFNode field,
*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 that it is empty.

The SFRotation field specifies one arbitrary 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.

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

**fooRot 0.0 1.0 0.0 3.14159265**

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 forming two backslashes.

EXAMPLE

**
fooString [ "One, Two, Three", "He said, \"Immel did it!\"" ]**

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.

EXAMPLE

**fooTime 0.0**

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

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

EXAMPLE

**fooVec2d [ 42.89978899 666.000123, 7 94.1 ]**

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

EXAMPLE

**fooVec2f [ 42 666, 7 94 ]**

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

EXAMPLE

**fooVec3d [ 1.000000000001 42 666.35357878, 7 94 0.100000000007 ]**

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

EXAMPLE

**fooVec3f [ 1 42 666, 7 94 0 ]**

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

EXAMPLE

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

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

EXAMPLE

**fooVec3f [ 1 42 666 -43.8, 7 94 0 0.0001 ]**