Extensible 3D (X3D)

Part 1: Architecture and base components

5 Field type reference

This clause describes the syntax and general semantics of *fields, *the
elemental data types used by X3D to define the properties of nodes. Nodes are
composed of fields whose types are defined in this clause. For more information
on nodes, see 4.4.2 Object model.

There are two general classes of field types: field types that contain a single
value (where a value may be a single number, a vector, or even an image), and
field types that contain an ordered list of multiple values. Single-valued field
types have names that begin with ** SF. **Multiple-valued field types
have names that begin with

Table 5.1 provides links to the major topics in this clause.

The SFBool field specifies a single Boolean value. The MFBool field specifies multiple Boolean values. Each Boolean value represents either TRUE or FALSE. How these values are represented is encoding dependent.

The initial value of an uninitialized SFBool field is FALSE. The initial value of an uninitialized MFBool field is the empty list.

The SFColor field specifies one RGB (red-green-blue) colour triple. MFColor specifies zero or more RGB triples. Each colour is written to the X3D file as an RGB triple of floating point numbers in the range 0.0 to 1.0.

The initial value of an uninitialized SFColor field is (0 0 0). The initial value of an uninitialized MFColor field is the empty list.

The SFColorRGBA field specifies one RGBA (red-green-blue-alpha) colour quadruple that includes alpha (opacity) information. MFColorRGBA specifies zero or more RGBA quadruples. Each colour is written to the X3D file as an RGBA quadruple of floating point numbers in the range 0.0 to 1.0. Alpha values range from 0.0 (fully transparent) to 1.0 (fully opaque).

The initial value of an uninitialized SFColorRGBA field is (0 0 0 0). The initial value of an uninitialized MFColorRGBA field is the empty list.

The SFDouble field specifies one double-precision floating point number. MFDouble specifies zero or more double-precision floating point numbers. SFDouble and MFDouble are represented in the X3D file as specified in the respective encoding.

Implementation of these fields is targeted at the double precision floating point capabilities of processors. However, it is allowable to implement this field using fixed point numbering provided at least 14 decimal digits of precision are maintained and that exponents have range of at least [-12, 12] for both positive and negative numbers.

The initial value of an uninitialized SFDouble field is 0.0. The initial value of an MFDouble field is the empty list.

The SFFloat field specifies one single-precision floating point number. MFFloat specifies zero or more single-precision floating point numbers. SFFloats and MFFloats are represented in the X3D file as specified in the respective encoding.

Implementation of these fields is targeted at the single precision floating point capabilities of processors. However, it is allowable to implement this field using fixed point numbering provided at least six decimal digits of precision are maintained and that exponents have range of at least [-12, 12] for both positive and negative numbers.

The initial value of an uninitialized SFFloat field is 0.0. The initial value of an MFFloat field is the empty list.

The SFImage field specifies a single uncompressed 2-dimensional pixel image. SFImage fields contain 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. MFImage fields contain zero or more SFImage fields. Each image in an MFImage field may contain different values for the width, height, and number of components in the image and hence may have a different number of hexadecimal or integer 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 each 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.

The initial value of an SFImage outputOnly field is (0 0 0). The initial value of an MFImage field is the empty list.

The SFInt32 field specifies one 32-bit integer. The MFInt32 field specifies zero or more 32-bit integers. SFInt32 and MFInt32 fields are signed integers.

The initial value of an uninitialized SFInt32 field is 0. The initial value of an MFInt32 field is the empty list.

The SFNode field specifies an X3D node. The MFNode field specifies zero or more nodes.

The initial value of an uninitialized SFNode field is NULL. The initial value of an MFNode field is the empty list.

The SFRotation field specifies one arbitrary rotation. The MFRotation field specifies zero or more arbitrary rotations. An SFRotation is written to the X3D file as four floating point values. The allowable form for a floating point number is defined in the specific encoding. The first three values specify a normalized rotation axis vector about which the rotation takes place. The fourth value specifies the amount of right-handed rotation about that axis in radians.

The 3x3 matrix representation of a rotation (x y z a) is

[ tx^{2}+c txy+sz txz-sy txy-sz ty^{2}+c tyz+sx txz+sy tyz-sx tz^{2}+c ] where c = cos(a), s = sin(a), and t = 1-c

The initial value of an uninitialized SFRotation field is (0 0 1 0). The initial value of an MFRotation field is the empty list.

The SFString and MFString fields contain strings encoded with the UTF-8 universal character set (see 2.[I16046-1]). SFString specifies a single string. The MFString specifies zero or more strings. Strings are specified as a sequence of UTF-8 octets.

Any characters (including linefeeds and '#') may appear within the string.

The initial value of an uninitialized SFString outputOnly field is the empty string. The initial value of an MFString field is the empty list.

Characters in 2.[I10646-1] are encoded in multiple octets. Code space is divided into four units, as follows:

+-------------+-------------+-----------+------------+ | Group-octet | Plane-octet | Row-octet | Cell-octet | +-------------+-------------+-----------+------------+

2.[I10646-1] allows two basic forms for characters:

- UCS-2 (Universal Coded Character Set-2). This form is also known as the Basic Multilingual Plane (BMP). Characters are encoded in the lower two octets (row and cell).
- UCS-4 (Universal Coded Character Set-4). Characters are encoded in the full four octets.

In addition, two transformation formats (UCS Transformation Format or UTF) are accepted: UTF-8 and UTF-16. Each represents the nature of the transformation: 8-bit or 16-bit. UTF-8 and UTF-16 are referenced in 2.[I10646-1].

UTF-8 maintains transparency for all ASCII code values (0...127). It allows ASCII text (0x0..0x7F) to appear without any changes and encodes all characters from 0x80.. 0x7FFFFFFF into a series of six or fewer bytes.

If the most significant bit of the first character is 0, the remaining seven bits are interpreted as an ASCII character. Otherwise, the number of leading 1 bits indicates the number of bytes following. There is always a zero bit between the count bits and any data.

The first byte is one of the following. The X indicates bits available to encode the character:

0XXXXXXX only one byte 0..0x7F (ASCII) 110XXXXX two bytes Maximum character value is 0x7FF 1110XXXX three bytes Maximum character value is 0xFFFF 11110XXX four bytes Maximum character value is 0x1FFFFF 111110XX five bytes Maximum character value is 0x3FFFFFF 1111110X six bytes Maximum character value is 0x7FFFFFFF

All following bytes have the format 10XXXXXX.

As a two byte example, the symbol for a registered trade mark ®, encoded as 0x00AE in UCS-2 of ISO 10646-1, has the following two byte encoding in UTF-8: 0xC2, 0xAE.

The SFTime field specifies a single time value. The MFTime field specifies zero or more time values. Time values are specified as a double-precision floating point number. The allowable form for a double precision floating point number is defined in the specific encoding. Time values are specified as the number of seconds from a specific time origin. Typically, SFTime fields represent the number of seconds since Jan 1, 1970, 00:00:00 GMT.

The initial value of an uninitialized SFTime field is -1. The initial value of an MFTime field is the empty list.

The SFVec2d field specifies a two-dimensional (2D) vector. An MFVec2d field specifies zero or more 2D vectors. SFVec2d's and MFVec2d's are represented as a pair of double-precision floating point values (see 5.4 SFDouble). The allowable form for a double-precision floating point number is defined in the specific encoding.

The initial value of an uninitialized SFVec2d field is (0 0). The initial value of an MFVec2d field is the empty list.

The SFVec2f field specifies a two-dimensional (2D) vector. An MFVec2f field specifies zero or more 2D vectors. SFVec2f's and MFVec2f's are represented as a pair of single-precision floating point values. The allowable form for a single-precision floating point number is defined in the specific encoding.

The initial value of an uninitialized SFVec2f field is (0 0). The initial value of an MFVec2f field is the empty list.

The SFVec3d field or event specifies a three-dimensional (3D) vector. An MFVec3d field or event specifies zero or more 3D vectors. SFVec3d's and MFVec3d's are represented as a 3-tuple of double-precision floating point values (see 5.4 SFDouble). The allowable form for a double-precision floating point number is defined in the specific encoding.

The initial value of an uninitialized SFVec3d field is (0 0 0). The initial value of an MFVec3d field is the empty list.

The SFVec3f field or event specifies a three-dimensional (3D) vector. An MFVec3f field or event specifies zero or more 3D vectors. SFVec3f's and MFVec3f's are represented as a pair of single-precision floating point values. The allowable form for a single-precision floating point number is defined in the specific encoding.

The initial value of an uninitialized SFVec3f field is (0 0 0). The initial value of an MFVec3f field is the empty list.