Extensible 3D (X3D)
Part 1: Architecture and base components

5 Field type reference

--- X3D separator bar ---

cube 5.1 General

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 MF. Multiple-valued fields are written as an ordered list of values. If the field has zero values, the value is empty but still represented.

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

Table 5.1 — Topics in this clause

--- X3D separator bar ---

cube 5.2 SFBool and MFBool

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.

--- X3D separator bar ---

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

--- X3D separator bar ---

cube 5.4 SFColorRGBA and MFColorRGBA

The SFColorRGBA field specifies one RGBA (red-green-blue-alpha) colour quadruple that includes alpha (transparency) 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.

--- X3D separator bar ---

cube 5.5 SFDouble and MFDouble

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.

--- X3D separator bar ---

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

--- X3D separator bar ---

cube 5.7 SFImage and MFImage

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.

--- X3D separator bar ---

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

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

--- X3D separator bar ---

cube 5.9 SFNode and MFNode

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.

--- X3D separator bar ---

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

    [ tx2+c    txy+sz    txz-sy
      txy-sz   ty2+c     tyz+sx
      txz+sy   tyz-sx    tz2+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.

--- X3D separator bar ---

cube 5.11 SFString and MFString

The SFString and MFString fields contain strings encoded with the UTF-8 universal character set (see 2.[UTF8]). 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.

--- X3D separator bar ---

cube 5.12 SFTime and MFTime

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.

--- X3D separator bar ---

cube 5.13 SFVec2d and MFVec2d

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.

--- X3D separator bar ---

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

--- X3D separator bar ---

cube 5.15 SFVec3d and MFVec3d

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.

--- X3D separator bar ---

cube 5.16 SFVec3f and MFVec3f

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.

--- X3D separator bar ---