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

5 Encoding of fields

--- X3D separator bar ---

cube5.1 Introduction

5.1.1 Table of contents

Table 5.1 — Table of contents

5.1 Introduction
5.1.1 Table of contents
5.1.2 Description
5.2 SFBool and MFBool
5.3 SFColor and MFColor
5.4 SFColorRGBA and MFColorRGBA
5.5 SFDouble and MFDouble
5.6 SFFloat and MFFloat
5.7 SFImage
5.8 SFInt32 and MFInt32
5.9 SFNode and MFNode
5.10 SFRotation and MFRotation
5.11 SFString and MFString
5.12 SFTime and MFTime
5.13 SFVec2d and MFVec2d
5.14 SFVec2f and MFVec2f
5.15 SFVec3d and MFVec3d
5.16 SFVec3f and MFVec3f

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 "/>

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

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

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

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

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

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

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

cube 5.9 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 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"/>

cube 5.10 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>

cube 5.11 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;"' />

cube 5.12 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.

cube 5.13 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"/>

cube 5.14 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"/>

cube 5.15 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.

cube 5.16 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.

--- X3D separator bar ---