Extensible 3D (X3D)
Part 1: Extensible Markup Language (XML) encoding

5 Encoding of fields

5.1 Introduction

5.1.1 Topics

Table 5.1 lists the topics for this clause.

5.1.2 Description

This clause describes the syntax of field data type values.

There are two general classes of fields: fields that contain a single value (where 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 quotations and separated by whitespace. If the field has zero values, only the quotes are written. The last value may optionally be followed by whitespace.

EXAMPLE 1 All of the following are valid for a multiple-valued MFColor field color in the ColorNode containing a single color triplet:

<Color color="1 1 1"/>
<Color color="1 1 1,"/>
<Color color="1 1 1 0 0 0"/>
<Color color="1 1 1, 0 0 0, "/>

Within MF arrays, commas may only be used as whitespace between values of individual base datatypes. Further, an integral number of tuple values must be provided for 2-tuple, 3-tuple and 4-tuple datatypes.

EXAMPLE 2 The following MFColor values are erroneous:

<Color DEF="failsValidation1" color="1, 1, 1, 0, 0, 0"/>
<Color DEF="failsValidation2" color="1 1 1, 0 0 "/>

5.2 SFBool and MFBool

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. Lower-case strings for true and false are used in order to maximize interoperability with other XML languages.

EXAMPLE

<NavigationInfo headlight="false"/>

includes an SFBool field, headlight, defined as having 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. 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

<ColorNode color="1.0 0. 0.0, 0 1 0, 0 0 1"/>

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

5.4 SFColorRGBA and MFColorRGBA

The SFColorRGBA field specifies one RGBA (red-green-blue-alpha) colour 4-tuple. MFColorRGBA specifies zero or more RGBA 4-tuples. 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

<ColorRGBANode color="1.0 0. 0.0 0.5, 0 1 0 0.5, 0 0 1 0.5"/>

is an MFColorRGBA field, color, containing the three partially transparent primary colours red, green, blue.

5.5 SFDouble and MFDouble

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

EXAMPLE

<NurbsCurve knot="1000.123456789, 200.123456789, 300.123456789"/>

is an MFDouble field, knot, containing three high-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).

EXAMPLE

<ElevationGrid creaseAngle="0.785"/>

is an SFFloat field, creaseAngle, containing a single floating point value.

5.7 SFImage

The SFImage field specifies a single uncompressed 2-dimensional pixel image. 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 1

myImage <width> <height> <num components> <pixels 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 2

<PixelTexture DEF="greyscaleImage" image="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 3

<PixelTexture image="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.

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 fields are encoded as an integer in decimal or hexadecimal (beginning with '0x') format.

EXAMPLE

<IndexedLineSet coordIndex="0 1 -1"> <Coordinate point="1 2 3, 3 2 1"/> </IndexedLineSet>

The IndexedLineSet in this example contains an MFInt32 field, coordIndex, containing three integer values.

5.9 SFMatrix3d and MFMatrix3d

The SFMatrix3d field specifies a 3×3 matrix of double precision float elements. An MFMatrix3d field specifies zero or more 3×3 double precision matrices. Each SFMatrix3d field 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 Two SFMatrix3d values form the following MFMatrix3d array:

5.10 SFMatrix3f and MFMatrix3f

The SFMatrix3d field specifies a 3×3 matrix of single precision float values. An MFMatrix3d field specifies zero or more 3×3 single precision matrices. Each SFMatrix3d field 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 second row of the matrix. The last three single precision floating point numbers represent the bottom row of the matrix.

EXAMPLE Two SFMatrix3f values form the following MFMatrix3f array:

5.11 SFMatrix4d and MFMatrix4d

The SFMatrix3d field specifies a 4×4 matrix of double precision float elements. An MFMatrix3d field specifies zero or more 4×4 double precision matrices. Each SFMatrix3d field 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 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 Two SFMatrix4d values form the following MFMatrix4d array:

5.12 SFMatrix4f and MFMatrix4f

The SFMatrix3d field specifies a 4×4 matrix of single precision float values. An MFMatrix3d field specifies zero or more 4×4 single precision matrices. Each SFMatrix3d field 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 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 Two SFMatrix4f values form the following MFMatrix4f array:

5.13 SFNode and MFNode

The SFNode field specifies a single X3D node. The MFNode field specifies an array of zero or more nodes.

EXAMPLE 1 The following illustrates initialization of a user-defined prototype field, named PositioningNodes, having type MFNode:

<fieldValue name="PositioningNodes">
<Transform USE="someTransformInstance"/>
<GeoLocation DEF="defaultGeoLocationInstance"/>
<ESPDUTransform USE="someEspduTransformInstance"/>
</fieldValue>

Definition of an SFNode field may contain the USE name of a previously defined node for initialization.

EXAMPLE 2

<field name="provideNode1" type="SFNode" value="someTransformInstance"/>

Definition of an SFNode field may contain the keyword NULL as the initialization value to indicate that it is empty. NULL may be overridden as a DEF name earlier in the scene, however.

EXAMPLE 3 Assuming that no node instance has a DEF="NULL", the following two definitions are equivalent:

<field name="provideNullNode2" type="SFNode"/>
<field name="provideNullNode2" type="SFNode" value="NULL"/>

5.14 SFRotation and MFRotation

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 π/4 radians rotation of a Box about the Y axis is:

<Transform rotation="0.0 1.0 0.0 0.785">
<Shape>
<Box/>
</Shape>
</Transform>

5.15 SFString and MFString

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

NOTE The construct

"string3"

is not a valid instance of an MFString. Such an MFString would be properly specified as

'"string3"'

EXAMPLE 1 A node with an MFString:

<NavigationInfo type='"WALK" "ANY"' />

Any characters (including linefeeds and '#') may appear within the quotes. Special characters as defined by XML (e.g., apostrophe and double quotes) are specified using the XML character entity encodings (see 2.[XML]).

EXAMPLE 2 Two instances of the double quote are contained in the following SFString field string:

<Text string='"He said, \&quot;Immel did it!\&quot;"' />

5.16 SFTime and MFTime

The SFTime field specifies a single time value. The MFTime field specifies zero or more time values. A time value is encoded as a double-precision floating point number in ISO C floating point format (see ISO/IEC 9899).

EXAMPLE

<TimeSensor cycleInterval="5.0"/>

is an SFTime field, cycleInterval, representing a time of 5.0 seconds for the interval of the TimeSensor node.

5.17 SFVec2d and MFVec2d

The SFVec2d field specifies a two-dimensional (2D) high-precision vector. An MFVec2d field specifies zero or more 2D high-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

<field name="corners"
type="MFVec2d"
value="42.89978899 666.000123, 84.97778978 933.70941"/>

5.18 SFVec2f and MFVec2f

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

<TextureCoordinate point="0.25 0.25 0.8 0.8"/>

5.19 SFVec3d and MFVec3d

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

EXAMPLE

<GeoOrigin geoCoords="1000.123456789 100.123456789 100.123456789"/>

is an SFVec3d field, geoCoords, defining a high-precision vector value.

5.20 SFVec3f and MFVec3f

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

<Coordinate point="1.0 2.24 3.4, 3 2 1, 4.5 1.2 5.745"/>

is an SFVec3f field, point, defining three 3D vectors.

5.21 SFVec4d and MFVec4d

The SFVec4d field specifies a four-dimensional (4D) double precision vector (or a three-dimensional homogeneous 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

<field name="point="br>        type="MFVec4d"
       value="1.000000000001 42 666.35357878 0.5748998763,
              7 94 0.100000000007 1.11111111111"/>

is an MFVec4d field, point, defining a double precision vector value.

5.22 SFVec4f and MFVec4f

The SFVec4f field specifies a four-dimensional (4D) single precision vector (or a three-dimensional homogeneous 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.

EXAMPLEp>

<field name="point="
type="MFVec4f"
value="1 42 666 13.5, 7 -94.7 0 3.678"/>

is an MFVec4d field, point, defining a single precision vector value.