]> X3D XML encoding 4.0 draft - ISO/IEC 19776-1:202x - 5 Encoding of fields

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

Validation of individual values can be performed using XML Document Type Definition (DTD) (also known as DOCTYPE), X3D XML Schema, X3D Regular Expressions (regexes) X3DREGEX, X3D Schematron, SCHEMATRON.1, SCHEMATRON.2, and X3DSCHEMATRON.

NOTE The precise expressive power for each of these validation tools can vary.

XML DTD/DOCTYPE validation can confirm well-formed XML, correct spelling of element and attribute names, legal parent-child node relationships, and correct enumeration values,
XML Schema validation can additionally validate correctness of most attribute values, including floating-point values,
X3D Regular Expressions (regexes) can detect malformed floating-point values and incorrect counts of values in SFVec/MFVec and SFMatrix/MFMatrix numeric arrays,
X3D Schematron validation provides a wide range of rules that check for ordering and logical consistency of values (e.g. a DEF node appearing before corresponding USE nodes).

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. Comma characters that are used as whitespace within an SFColor value will fail XML validation. Comma characters that are used as whitespace between SFColor values in an MFColor array will pass XML validation.

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. Comma characters that are used as whitespace within an SFColorRGBA value will fail XML validation. Comma characters that are used as whitespace between SFColorRGBA values in an MFColorRGBA array will pass XML validation.

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. SFDouble and MFDouble values 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. SFFloat and MFFloat values 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 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 width×height hexadecimal or integer values representing the pixels in the image, separated by whitespace. Comma characters that are used as whitespace within an SFImage value will fail XML validation.

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. Comma characters that are used as whitespace within an SFMatrix3d value will fail XML validation. Comma characters that are used as whitespace between SFMatrix3d values in an MFMatrix3d array will pass XML validation.

EXAMPLE Two SFMatrix3d values form the following MFMatrix3d array:

5.10 SFMatrix3f and MFMatrix3f

The SFMatrix3f field specifies a 3×3 matrix of single-precision float values. An MFMatrix3f field specifies zero or more 3×3 single-precision matrices. Each SFMatrix3f 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. Comma characters that are used as whitespace within an SFMatrix3f value will fail XML validation. Comma characters that are used as whitespace between SFMatrix3f values in an MFMatrix3f array will pass XML validation.

EXAMPLE Two SFMatrix3f values form the following MFMatrix3f array:

5.11 SFMatrix4d and MFMatrix4d

The SFMatrix4d field specifies a 4×4 matrix of double-precision float elements. An MFMatrix4d field specifies zero or more 4×4 double-precision matrices. Each SFMatrix4d 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. Comma characters that are used as whitespace within an SFMatrix4d value will fail XML validation. Comma characters that are used as whitespace between SFMatrix4d values in an MFMatrix4d array will pass XML validation.

EXAMPLE Two SFMatrix4d values form the following MFMatrix4d array:

5.12 SFMatrix4f and MFMatrix4f

The SFMatrix4f field specifies a 4×4 matrix of single-precision float values. An MFMatrix4f field specifies zero or more 4×4 single-precision matrices. Each SFMatrix4f 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. Comma characters that are used as whitespace within an SFMatrix4f value will fail XML validation. Comma characters that are used as whitespace between SFMatrix4f values in an MFMatrix4f array will pass XML validation.

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. However, care is recommended nevertheless since NULL may be overridden as a DEF name earlier in the scene.

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. Comma characters that are used as whitespace within an SFRotation value will fail XML validation. Comma characters that are used as whitespace between SFRotation values in an MFRotation array will pass XML validation.

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 that are further subject to XML encoding rules (see I10646 Universal Coded Character Set (UCS) and XML).

SFString specifies a single string encoded as a sequence of UTF-8 octets. SFString attributes shall be enclosed in either single quotes or double quotes ( e.g., value='string' or value="string").

EXAMPLE 1 A node with an SFString attribute:

<WorldInfo title='MyModel.x3d'/>
<WorldInfo title="MyModel.x3d"/>

An MFString attribute is a sequence of zero or more SFString values. As with any XML attribute, each MFString attribute is similarly enclosed by single quotes or double quotes in the XML encoding. The delimiters for the overall MFString XML attribute shall match. The XML delimiter for the MFString attribute shall be different from the delimiter for the contained SFString values. Each pair of quoted SFString values within an MFString is separated by whitespace. It is recommended that when the interior SFString delimiters are double quotes, typically the exterior XML delimiters are single quotes.

EXAMPLE 2 A node with an MFString attribute containing two SFString values, where each of the individual SFString values are surrounded by double quotes:

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

Any characters (including linefeeds and '#') are allowed to appear within SFString values. Special characters as defined by XML ( e.g., apostrophe and quotation mark), or any other individual character, can be individually replaced by any of the various XML character entity encodings (see XML).

Literal quotation-mark characters included as part of SFString content are preceded by a backslash character (e.g. \"). Similarly, literal backslash characters included as part of SFString content are preceded by a backslash character.

EXAMPLE 3 Two instances of a literal quotation mark are contained in the following MFString field string, which delimits a single SFString, which in turn contains two literal quotation marks within the string content, which are each escaped for proper parsing by using a backslash character (i.e. \").

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

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

This example displays the following text when rendered:

He said, "Immel did it!"

An MFString field that contains only a single SFString value is a special case that can optionally be represented without requiring the usual exterior quotation marks found surrounding an SFString value. Thus the second entry in the following example is equivalent to EXAMPLE 3.

EXAMPLE 4 Nodes with MFString attribute containing a single unquoted SFString:

<Text string='Who did it?'/>

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

Similar to HTML and other XML string values, individual SFString values can have numerous equivalent variations by substituting character entities for individual characters (see I10646 Universal Coded Character Set (UCS) and XML). Each character entity substitution can be expressed in decimal form, hexadecimal form, or as an abbreviation (if predefined). EXAMPLE 5 shows a number of equivalent examples in tabular form, with several cases having many more equivalent representations possible.

EXAMPLE 5 X3D XML syntax examples:

	Examples with equivalent values	Resulting text
5a	`<-- escaped character entities for single quotation mark -->` `\"` `\"` `\"` `\"`	"
5b	`<-- SFString examples including quotation-mark characters -->` `<WorldInfo title='\"MyModel.x3d\"'/>` `<WorldInfo title='\"MyModel.x3d\"'/>` `<WorldInfo title='\"MyModel.x3d\"'/>` `<WorldInfo title='\"MyModel.x3d\"'/>`	"MyModel.x3d"
5c	`<-- MFString examples containing single SFString -->` `<Text string='"Hello world!"'/>` `<Text string='Hello world!'/>` `<Text string="Hello world!"/>`	Hello world!
5d	`<-- MFString examples showing character entities for quotes -->` `<Text string=' "Hello" "World" '/>` `<Text string=' "Hello" "World" '/>` `<Text string=" "Hello" "World" "/>` `<Text string=" &Hello" "World" "/>` `<Text string=" "Hello" "World" "/>`	Hello World
5e	`<-- EXAMPLE 3 and alternatives -->` `<Text string='"He said, \"Immel did it!\""'/>` `<Text string='"He said, \"Immel did it!\""'/>` `<Text string='"He said, \"Immel did it!\""'/>` `<Text string='"He said, \"Immel did it!\""'/>` `<Text string='"He said, \"Immel did it!\""'/>` `<Text string='"He said, \"Immel did it!\""'/>` `<Text string='"He said, \"Immel did it!\""'/>` `<-- EXAMPLE 4 and alternatives -->` `<Text string='He said, \"Immel did it!\"'/>` `<Text string='He said, \"Immel did it!\"'/>` `<Text string='He said, \"Immel did it!\"'/>` `<Text string='He said, \"Immel did it!\"'/>` `<Text string='He said, \"Immel did it!\"'/>` (plus numerous additional permutations and variations)	He said, "Immel did it!"
5f	`<-- SFString as empty string, i.e. default value -->` `<WorldInfo/>` `<WorldInfo title=''/>` `<WorldInfo title=""/>`	(no text)
5g	`<-- MFString as empty list, i.e. default value -->` `<Text/>` `<Text string=''/>` `<Text string=""/>`	(no text)
5h	`<-- MFString contains single empty SFString -->` `<Text string='""'/>`	(no text)

NOTE 1. A quotation mark character (i.e. ") can be replaced by a character entity (\" or \" or \") within an MFString attribute that is itself delimited by quotation mark characters, since such an attribute meets the requirements for well-formed XML.

NOTE 2. SFString content containing a quotation mark that is not preceded by a backslash \ escape character results in an incorrectly formed SFString value.

As shown above, EXAMPLE 5 illustrates a number of correctly formed examples that have multiple possible representations. To clearly illustrate common errors, EXAMPLE 6 below shows a number of similar but invalid SFString and MFString expressions. These examples each fail to follow XML attribute-quoting rules described in NOTE 1, fail to escape X3D backslash prerequisites for literal quotation marks described in NOTE 2, or fail to meet XML and X3D rules simultaneously.

EXAMPLE 6 Common errors:

6a. erroneous SFString: <WorldInfo DEF="NotWellFormedXML1" title=" \"MyModel.x3d\" "/>

6b. erroneous MFString: <Text DEF="NotWellFormedXML2" string=" "Hello" "World" "/>

6c. erroneous SFString: <WorldInfo DEF="IncorrectX3dQuotes1" title=' "MyModel.x3d" '/>

6d. erroneous MFString: <Text DEF="IncorrectX3dQuotes2" string=' He said "Immel did it." '/>

6e. erroneous MFString: <NavigationInfo DEF="IncorrectX3dQuotes3" type=" 'WALK' 'ANY' "/>

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

where cycleInterval is an SFTime field representing a time of 5.0 seconds for the duration period 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 and MFVec2d values are encoded as a pair of ISO C floating point values (see ISO/IEC 9899) separated by whitespace. Comma characters that are used as whitespace within an SFVec2d value will fail XML validation. Comma characters that are used as whitespace between SFVec2d values in an MFVec2d array will pass XML validation.

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 and MFVec2f values are encoded as a pair of ISO C floating point values (see ISO/IEC 9899) separated by whitespace. Comma characters that are used as whitespace within an SFVec2f value will fail XML validation. Comma characters that are used as whitespace between SFVec2f values in an MFVec2f array will pass XML validation.

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 and MFVec3d values are encoded as three ISO C floating point values (see ISO/IEC 9899) separated by whitespace. Comma characters that are used as whitespace within an SFVec3d value will fail XML validation. Comma characters that are used as whitespace between SFVec3d values in an MFVec3d array will pass XML validation.

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 and MFVec3f values are encoded as three ISO C floating point values (see ISO/IEC 9899) separated by whitespace. Comma characters that are used as whitespace within an SFVec3f value will fail XML validation. Comma characters that are used as whitespace between SFVec3f values in an MFVec3f array will pass XML validation.

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 and MFVec4d values are encoded as four ISO C floating point values (see ISO/IEC 9899) separated by whitespace. Comma characters that are used as whitespace within an SFVec4d value will fail XML validation. Comma characters that are used as whitespace between SFVec4d values in an MFVec4d array will pass XML validation.

EXAMPLE

<field name="point"
       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 and MFVec4f values are encoded as four ISO C floating point values (see ISO/IEC 9899) separated by whitespace. Comma characters that are used as whitespace within an SFVec4f value will fail XML validation. Comma characters that are used as whitespace between SFVec4f values in an MFVec4f array will pass XML validation.

EXAMPLE

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