Extensible 3D (X3D)
Part 1: Architecture and base components
5 Field type reference
5.1 GeneralThis 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.
Table 5.1 provides links to the major topics in this clause.
5.2 Abstract field typesThere 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.
X3DArrayField is the abstract field type from which all field types that can contain multiple values are derived. All fields derived from X3DArrayField have names beginning with MF (multiple-valued field). MFxxxx MF fields may zero or more values, each of which shall be of the type indicated by the corresponding SFxxxx field type. It is illegal for any MFxxxx field to mix values of different SFxxxx field types.
EXAMPLE MFString is a field type that can contain zero or more character strings.
X3DField is the abstract field type from which all single values field types are derived. All fields directly derived from X3DField have names beginning with SF (single-valued field). SFxxxx fields may only contain a single value of the type indicated by the name of the field type.
EXAMPLE SFBool is a field type that can contain a single Boolean value.
5.3 Field typesThe 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 default value of an uninitialized SFBool field is FALSE. The default 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 default value of an uninitialized SFColor field is (0 0 0). The default 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 default value of an uninitialized SFColorRGBA field is (0 0 0 0). The default 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 default value of an uninitialized SFDouble field is 0.0. The default 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 default value of an uninitialized SFFloat field is 0.0. The default 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 default value of an uninitialized SFImage outputOnly field is (0 0 0). The default 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 default value of an uninitialized SFInt32 field is 0. The default value of an MFInt32 field is the empty list.
The SFMatrix3d field specifies a 3×3 matrix of double-precision floating point numbers. MFMatrix3d specifies zero or more 3×3 matrices of double-precision floating point numbers. Each floating point number is represented in the X3D file as specified in the respective encoding.
SFMatrix3d matrices are organized in row-major fashion. The first row of the matrix stores information for the x dimension, and the second for the y dimension. Since these data types are commonly used for transformation matrices, translation values are stored in the third row.
The default value of an uninitialized SFMatrix3d field is the identity matrix [1 0 0 0 1 0 0 0 1]. The default value of an uninitialized MFMatrix3d field is the empty list.
The SFMatrix3f field specifies a 3×3 matrix of single-precision floating point numbers. MFMatrix3f specifies zero or more 3×3 matrices of single-precision floating point numbers. Each floating point number is represented in the X3D file as specified in the respective encoding.
SFMatrix3f matrices are organized in row-major fashion. The first row of the matrix stores information for the x dimension, and the second for the y dimension. Since these data types are commonly used for transformation matrices, translation values are stored in the third row.
The default value of an uninitialized SFMatrix3f field is the identity matrix [1 0 0 0 1 0 0 0 1]. The default value of an uninitialized MFMatrix3f field is the empty list.
The SFMatrix4d field specifies a 4×4 matrix of double-precision floating point numbers. MFMatrix4d specifies zero or more 4×4 matrices of double-precision floating point numbers. Each floating point number is represented in the X3D file as specified in the respective encoding.
SFMatrix4d matrices are organized in row-major fashion. The first row of the matrix stores information for the x dimension, the second for the y dimension, and the third for the z dimension. Since these data types are commonly used for transformation matrices, translation values are stored in the fourth row.
The default value of an uninitialized SFMatrix4d field is the identity matrix [1 0 0 0 0 1 0 0 0 0 1 0 0 0 0 1]. The default value of an uninitialized MFMatrix4d field is the empty list.
The SFMatrix4f field specifies a 4x4 matrix of single-precision floating point numbers. MFMatrix4f specifies zero or more 4x4 matrices of single-precision floating point numbers. Each floating point number is represented in the X3D file as specified in the respective encoding.
SFMatrix4f matrices are organized in row-major fashion. The first row of the matrix stores information for the x dimension, the second for the y dimension, and the third for the z dimension. Since these data types are commonly used for transformation matrices, translation values are stored in the fourth row.
The default value of an uninitialized SFMatrix4f field is the identity matrix [1 0 0 0 0 1 0 0 0 0 1 0 0 0 0 1]. The default value of an uninitialized MFMatrix4f field is the empty list.
The SFNode field specifies an X3D node. The MFNode field specifies zero or more nodes.
The default value of an uninitialized SFNode field is NULL. The default 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 angle base units.
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 default value of an uninitialized SFRotation field is (0 0 1 0). The default 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 ISO/IEC 10646). 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 default value of an uninitialized SFString outputOnly field is the empty string. The default value of an MFString field is the empty list.
Characters in ISO/IEC 10646 are encoded in multiple octets. Code space is divided into four units, as follows:
+-------------+-------------+-----------+------------+ | Group-octet | Plane-octet | Row-octet | Cell-octet | +-------------+-------------+-----------+------------+
ISO/IEC 10646 allows two basic forms for characters:
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 ISO/IEC 10646.
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, 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.
When an SFTime value represents a time-interval duration, negative values are not allowed. See 8.2.2 Time origin for further details.
The default value of an uninitialized SFTime field is -1. The default 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.3.4 SFDouble and MFDouble). The allowable form for a double-precision floating point number is defined in the specific encoding.
The default value of an uninitialized SFVec2d field is (0 0). The default 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 (see 5.3.5 SFFloat and MFFloat). The allowable form for a single-precision floating point number is defined in the specific encoding.
The default value of an uninitialized SFVec2f field is (0 0). The default 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.3.4 SFDouble and MFDouble). The allowable form for a double-precision floating point number is defined in the specific encoding.
The default value of an uninitialized SFVec3d field is (0 0 0). The default 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 3-tuple of single-precision floating point values (see 5.3.5 SFFloat and MFFloat). The allowable form for a single-precision floating point number is defined in the specific encoding.
The default value of an uninitialized SFVec3f field is (0 0 0). The default value of an MFVec3f field is the empty list.
The SFVec4d field or event specifies a three-dimensional (3D) homogeneous vector. An MFVec4d field or event specifies zero or more 3D homogeneous vectors. SFVec4d's and MFVec4d's are represented as a 4-tuple of double-precision floating point values (see 5.3.4 SFDouble and MFDouble). The allowable form for a double-precision floating point number is defined in the specific encoding.
The default value of an uninitialized SFVec4d field is (0 0 0 1). The default value of an MFVec4d field is the empty list.
The SFVec4f field or event specifies a three-dimensional (3D) homogeneous vector. An MFVec4f field or event specifies zero or more 3D homogeneous vectors. SFVec4f's and MFVec4f's are represented as a 4-tuple of single-precision floating point values (see 5.3.5 SFFloat and MFFloat). The allowable form for a single-precision floating point number is defined in the specific encoding.
The default value of an uninitialized SFVec4f field is (0 0 0 1). The default value of an MFVec4f field is the empty list.