Extensible 3D (X3D)
Part 1: Extensible Markup Language (XML) encoding
5 Encoding of fields
Table 5.1 — Table of contents
5.1.1 Table of contents
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.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
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. For example, 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. For example, 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 "/>
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. For example:
includes an SFBool field, headlight, defined as having 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 2.[ISOC]) in the range 0.0 to 1.0. For 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.
The SFColorRGBA field specifies one RGBA (red-green-blue-alpha) colour
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
in the range 0.0 to 1.0. For 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.
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 2.[ISOC]). For example:
<NurbsCurve knot="1000.123456789, 200.123456789, 300.123456789"/>
is an MFDouble field, knot, containing three high-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 2.[ISOC]). For example:
is an SFFloat field, creaseAngle, containing a single floating point value.
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:
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.
<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.
As another example:
<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.
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. For example:
<IndexedLineSet coordIndex="0 1 -1"> <Coordinate point="1 2 3, 3 2 1"/> </IndexedLineSet>
is an MFInt32 field, colorIndex, containing three integer values.
The SFNode field specifies a single X3D node. The MFNode field specifies an array of zero or more nodes.
The following example 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. For example:
<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. For example, assuming that no node instance has a DEF="NULL" then the following two definitions are equivalent:
<field name="provideNode2" type="SFNode"/> <field name="provideNode3" type="SFNode" value="NULL"/> <field name="provideNullNode4" type="SFNode"></field>
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 2.[ISOC]) separated by whitespace. For example, an SFRotation containing a PI/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>
The SFString and MFString fields contain strings formatted with the UTF-8
universal character set (see
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"'). An example node with a 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. For example, two instances of the double quote are contained in the following SFString field, string:
<Text string='"He said, "Immel did it!""' />
An MFString with a single value can be encoded in a shorthand form without an enclosing single quote. This case can be detected by inspecting the first character. If it is not a single quote, the single string will be wrapped by double quotes. An example using this shorthand:
<NavigationInfo type="WALK" />
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 2.[ISOC]). For example:
is an SFTime field, cycleInterval, representing a time of 5.0 seconds for the interval of the TimeSensor node.
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 2.[ISOC]) separated by whitespace. For example:
<field name="corners" type="MFVec2d" value="42.89978899 666.000123, 84.97778978 933.70941"/>
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 2.[ISOC]) separated by whitespace. For example:
<TextureCoordinate point="0.25 0.25 0.8 0.8"/>
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 2.[ISOC]) separated by whitespace. For example:
<GeoOrigin geoCoords="1000.123456789, 100.123456789, 100.123456789"/>
is an SFVec3d field, geoCoords, defining a high-precision vector value.
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 2.[ISOC]) separated by whitespace. For 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.