Extensible 3D (X3D)
Part 3: Binary encoding

5 Encoding of fields

--- X3D separator bar ---

cube5.1 Introduction

5.1.1 Topics

Table 5.1 — Topics in this clause

5.1 Introduction
  5.1.1 Topics
  5.1.2 Description

5.2 Field encoder for Fast-InfoSet usage
  5.2.1 Introduction
  5.2.2 Boolean encoder
  5.2.3 CDATA encoder
  5.2.4 Double encoder
  5.2.5 Float encoder
  5.2.6 Integer encoder

5.3 Compression techniques
  5.3.1 zlib compression
 

5.4 X3D-specific floating point encoders
  5.4.1 Quantized float array encoder
  5.4.2 zlib float array encoder
  5.4.3 Quantized zlib float array encoder
  5.4.4 Quantized double array encoder
  5.4.5 zlib double array encoder
 

5.5 X3D-specific integer encoders
  5.5.1 Range integer array encoder
  5.5.2 Delta zLib integer array encoder

5.6 Encoding of X3D fields
  5.6.1 SFBool and MFBool
  5.6.2 SFColorAndMFColor
  5.6.3 SFColorRGBA and MFColorRGBA
  5.6.4 SFDouble and MFDouble
  5.6.5 SFFloat and MFFloat
  5.6.6 SFImage
  5.6.7 SFInt32 and MFInt32
  5.6.8 SFNode and MFNode
  5.6.9 SFRotation and MFRotation
  5.6.10 SFString and MFString
  5.6.11 SFTime and MFTime
  5.6.12 SFVec2d and MFVec2d
  5.6.13 SFVec2f and MFVec2f
  5.6.14 SFVec3d and MFVec3d
  5.6.15 SFVec3f and MFVec3f

5.1.2 Description

This clause describes the syntax of field data type values.

Field values follow the syntax for fields defined in 5 Encoding of Fields of part 1 of ISO/IEC 19776. These field values are then encoded using FastInfoSet rules as defined in part 1 of ISO/IEC 24824. Specific rules for each field type will follow. In general, SFNode and MFNode are encoded using Element rules, FI 7.3.1. and other field types are encoded using the Attribute rules in FI 7.4.

Each field specifies what method it has used to write its values. This allows the X3D Binary encoding to use type specific knowledge to further compress a field. Encoders are expected to pick the right methods to meet the users expectations for parsing speed verses file size.

The usage of encoding algorithms not specified in this part of ISO/IEC 19776 or in part 1 of ISO/IEC 24824 is invalid. A conformant implementation need only support these algorithms to parse an X3D binary encoded file.

All field values shall end on a byte boundary.

cube 5.2 Field encoder for Fast-InfoSet usage

5.2.1 Introduction

By default all field values are written in String form. part 1 of ISO/IEC 24824 allows the specification of encoders to write values in a compact binary form. This subclause defines the encoders available for compressing X3D content. Only encoders defined in this clause or in part 1 of ISO/IEC 24824 may be used for compressing X3D content. All X3D encoders defined in this document will provide a unique URI to be used in the Encoding Algorithms table of the document serialization. If an encoder is used, this URI shall be added to the 8.3 Encoding Algorithm Table.

Fast-InfoSet defines a set of native encoders to help speed parsing and decrease file size for commonly used constructs. When possible, these encoders are used for handling X3D field types. This subclause specifies the encoders used along with a brief description of their function. See part 1 of ISO/IEC 24824 for a detailed discussion of each encoder, including the exact definition of what is written to a stream.

All encoders defined by part 1 of ISO/IEC 24824 are lossless.

5.2.2 Boolean encoder

This encoder handles boolean values. It can handle single values or a list of booleans separated by spaces. This encoder is named "boolean" and is defined in 10.7 of Part 1 of ISO/IEC 24824.

5.2.3 CDATA encoder

This encoder handles blocks of character data. This encoder is named "cdata" and is defined in 10.11 of Part 1 of ISO/IEC 24824.

5.2.4 Double encoder

This encoder handles double values. It can handle single values or a list of doubles separated by spaces. This encoder it is named "double" and  is defined in 10.9 of Part 1 of ISO/IEC 24824.

5.2.5 Float encoder

This encoder handles float values. It can handle single values or a list of floats separated by spaces. This encoder is named "float" and is defined in 10.8 of Part 1 of ISO/IEC 24824.

5.2.6 Integer encoder

This encoder handles integer values. It can handle single values or a list of integers separated by spaces. This encoder is named "int" and is defined in 10.9 of Part 1 of ISO/IEC 24824.

cube 5.3 Compression techniques

5.3.1 zlib

zlib compression is used for several encoders. zlib works by detecting common patterns in a stream and outputing short-hand tags for these patterns.

Implementations should reuse or reimplement the zlib library specified in 2.[ZLIB].

5.4 X3D-specific floating point encoders

5.4.1 Quantized float array encoder

This encoder takes an array of float values and encodes them as a quantized form of the single-precision floating point numbers specified in IEC 60559. A custom value is selected for the exponent, mantissa and sign bits typically used to encode floats. The bias of 127 is still used. These values are written to the stream first before the data. The number of exponent bits is encoded using 3 bits, giving a range of 1-8, 0 exponent bits cannot be used. The number of mantissa bits is encoded using 5 bits. 1 bit is used for the sign bit. When a number uses 0 sign bits it is assumed to be positive. The last bits will be used for data. Data will follow the float description using the extra 7 bits of the second byte for storage. Extra bits need to byte align the data will be 0 padded.

The number of floats written can be determined by:

NumFloats = floor((numBytes × 8 - 11) / (exponent + mantissa + sign));

This technique is a lossy encoder.

The URI for identifying this encoder is:

"encoder://web3d.org/QuantizedFloatArrayEncoder"

EXAMPLE

value to encode: "0.42 -1 0.1972"
parameters: exponent = 4 bits, mantissa = 4 bits, sign = 1 bits

resultant bits:

byte Octet(s) Description
1 100 00100 Exponent(4) written in 3 bits, Mantissa(4) 5 bits
2 1 0110101 Sign(0) 1 bit. Start of 0.42
3 10 100000 End of 0.42, start of -1
4 000 01011 End of -1, start of 0.1972
5 0010 0000 End of 0.1972, 4 bits of padding

5.4.2 zlib float array encoder

This encoder uses the zlib library (see 2.[ZLIB]) to find patterns in float values.

The array of floats is feed to the zlib library unmodified.

This technique is a lossless encoder.

The URI for identifying this encoder is:

"encoder://web3d.org/zlibFloatArrayEncoder"

5.4.3 Quantized zlib float array encoder

This encoder takes an array of float values and encodes them as a quantized form of the single precision floating point numbers defined in IEC 60559. A custom value is selected for the exponent, mantissa and sign bits typically used to encode floats. The bias of 127 is still used. These values are written to the stream first before the data. The number of exponent bits is encoded using 3 bits, giving a range of 1-8, 0 exponent bits cannot be used. The number of mantissa bits is encoded using 5 bits. 1 bit is used for the sign bit. When a number uses 0 sign bits it is assumed to be positive. The last bits will be used for data. Data will follow the float description using the extra 7 bits of the second byte for storage. Extra bits need to byte align the data will be 0 padded.

These values are then encoded using the zlib library.

This technique is a lossy encoder.

The URI for identifying this encoder is:

"encoder://web3d.org/QuantizedzlibFloatArrayEncoder"

5.4.4 Quantized double array encoder

This encoder takes an array of double values and encodes them as a quantized form of the double precision floating point numbers defined in IEC 60559. A custom value is selected for the exponent, mantissa and sign bits typically used to encode floats. The bias of 1023 is still used. These values are written to the stream first before the data. The number of exponent bits is encoded using 4 bits, giving a range of 0-15. The number of mantissa bits is encoded using 6 bits. 1 bit is used for the sign bit. When a number uses 0 sign bits it is assumed to be positive. The last bits will be used for data. Data will follow the float description using the extra 7 bits of the second byte for storage. Extra bits need to byte align the data will be 0 padded.

The number of doubles written can be determined by:

NumDoubles = floor((numBytes × 8 - 11) / (exponent + mantissa + sign));

This technique is a lossy encoder.

The URI for identifying this encoder is:

"encoder://web3d.org/QuantizedDoubleArrayEncoder"

5.4.5 zlib double array encoder

This encoder use the zlib algorithm to find patterns in double values.

This technique is a lossless encoder.

cube 5.5 X3D-specific integer encoders

5.5.1 Range integer array encoder

This encoder takes an array of integer values and encodes them in the least number of bits required to express the range of integers encoded. This is accomplished by determing the range of the integers present. All values are then shifted to a positive value (called shift). Each integer is written using the number of bits required to encode the range of integer values present.

The number of integers written can be determined by:

length / numBits per Integer

This technique is a lossless encoder.

The URI for identifying this encoder is:

"encoder://web3d.org/RangeIntArrayEncoder"

5.5.2 Delta zlib integer array encoder

This encoder takes an array of integer values, calculates delta values and then encodes them using the zlib library. Span is how many values to skip between deltas. The first Span values are the original values, the rest are deltas. The following array: 0,1,2,-1,3,4,5,-1,6,9,8,-1 with a span of 4 would generate the following deltas: 0,1,2,-1,3,3,3,0,3,5,3,0

The span is written out using 8 bits. The array of deltas is then compressed using the zlib library.

This technique is a lossless encoder.

The URI for identifying this encoder is:

"encoder://web3d.org/DeltazlibIntArrayEncoder"

cube 5.6 Encoding of X3D fields

5.6.1 SFBool and MFBool

SFBool and MFBool values are encoded using the "boolean" algorithm as defined in 10.7 of Part 1 of ISO/IEC 24824.

5.6.2 SFColor and MFColor

The SFColor field specifies one RGB (red-green-blue) colour triple. MFColor specifies zero or more RGB triples.

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.

SFColor and MFColor fields can be encoded using lossy and lossless techniques.

Values can be losslessly encoded using these encoders:

  1. Fast-InfoSet “float” encoder (see part 1 of ISO/IEC 24824) or
  2. zlib float array encoder.

Values can be lossy encoded using these encoders:

  1. Quantized float array,
  2. Quantized zlib float array

5.6.3 SFColorRGBA and MFColorRGBA

The SFColorRGBA field specifies one RGBA (red-green-blue-alpha) colour 4-tuple. MFColorRGBA specifies zero or more RGBA 4-tuples.

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.

SFColorRGBA and MFColorRGBA fields can be encoded using lossy and lossless techniques.

Values can be losslessly encoded using these encoders:

  1. Fast-InfoSet “float” encoder (see part 1 of ISO/IEC 24824) or
  2. zlib float array encoder.

Values can be lossy encoded using these encoders:

  1. Quantized float array,
  2. Quantized zlib float array

5.6.4 SFDouble and MFDouble

The SFDouble field specifies one double-precision floating point number. MFDouble specifies zero or more double-precision floating point numbers.

EXAMPLE

<NurbsCurve knot="1000.123456789, 200.123456789, 300.123456789"/>

is an MFDouble field, knot, containing three double-precision floating point values.

SFDouble and MFDouble fields can be encoded using lossy and lossless techniques.

Values can be losslessly encoded using these encoders:

  1. FastInfoSet “double” encoder (see part 1 of ISO/IEC 24824) or
  2. zlib Double Array Encoder.

Values can be lossy encoded using these encoders:

  1. Quantized double array,
  2. Quantized zlib double array

5.6.5 SFFloat and MFFloat

The SFFloat field specifies one single-precision floating point number. MFFloat specifies zero or more single-precision floating point numbers.

EXAMPLE

<ElevationGrid creaseAngle="0.785"/>

is an SFFloat field, creaseAngle, containing a single floating point value.

SFFloat and MFFloat fields can be encoded using lossy and lossless techniques.

Values can be losslessly encoded using these encoders:

  1. Fast-InfoSet “float” encoder (see part 1 of ISO/IEC 24824) or
  2. zlib float array encoder.

Values can be lossy encoded using these encoders:

  1. Quantized float array,
  2. Quantized zlib float array

5.6.6 SFImage

The SFImage field specifies a single uncompressed two-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.

SFImage values can be losslessly encoded using these encoders:
  1. Range integer array or
  2. Delta zlib integer array.

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

SFInt32 fields shall be encoded using the Fast-InfoSet “int” encoder (see 10.9 of part 1 of ISO/IEC 24824).

MFInt32 fields can only be encoded using lossless techniques.

MFInt32 values can be losslessly encoded using any of these encoders:

  1. Fast-InfoSet “int” encoder  (see 10.9 of part 1 of ISO/IEC 24824),
  2. Range integer array, or
  3. Delta zlib integer array.

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

Nodes are handled by the generic Fast-InfoSet rules for dealing with Elements as specified in 7.3 of part 1 of ISO/IEC 24824. No special encoders are defined.

5.6.9 SFRotation and MFRotation

The SFRotation field specifies one arbitrary rotation. The MFRotation field specifies zero or more arbitrary rotations.

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>

SFRotation and MFRotation fields can be encoded using lossy and lossless techniques.

Values can be losslessly encoded using these encoders:

  1. Fast-InfoSet “float” encoder (see part 1 of ISO/IEC 24824) or
  2. zlib float array encoder.

Values can be lossy encoded using these encoders:

  1. Quantized float array,
  2. Quantized zlib float array

5.6.10 SFString and MFString

The SFString and MFString fields contain strings formatted with the UTF-8 universal character set (see ISO/IEC 10646-1). 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"').

NOTE  The construct

"string3"

is not a valid instance of an MFString. Such an MFString would be properly specified as

'"string3"'

EXAMPLE 1  A node with an 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 (see 2.[XML]).

EXAMPLE 2  Two instances of the double quote are contained in the following SFString field string:

<Text string='"He said, &quot;Immel did it!&quot;"' />

SFString values are encoded directly as a string as specified in part 1of ISO/IEC 24824. No encoders are used.

MFString values are encoded directly as a string using the canonical form for MFStrings. No encoders are used.

5.6.11 SFTime and MFTime

The SFTime field specifies a single time value. The MFTime field specifies zero or more time values.

EXAMPLE

<TimeSensor cycleInterval="5.0"/>

is an SFTime field, cycleInterval, representing a time of 5.0 seconds for the interval of the TimeSensor node.

SFTime and MFTime fields shall be encoded using the FastInfoSet “double” encoder (see part 1of ISO/IEC 24824).

Lossy encoders are not allowed due to the sensitive nature of time values to the simulation model.

5.6.12 SFVec2d and MFVec2d

The SFVec2d field specifies a two-dimensional (2D) double-precision vector. An MFVec2d field specifies zero or more 2D double-precision vectors.

EXAMPLE

<field name="corners"
       type="MFVec2d"
       value="42.89978899 666.000123, 84.97778978 933.70941"/>

SFVec2d and MFVec2d fields can be encoded using lossy and lossless techniques.

Values can be losslessly encoded using these encoders:

  1. FastInfoSet “double” encoder (see part 1 of ISO/IEC 24824) or
  2. zlib Double Array Encoder.

Values can be lossy encoded using these encoders:

  1. Quantized double array, or
  2. Quantized zlib double array

5.6.13 SFVec2f and MFVec2f

The SFVec2f field specifies a two-dimensional (2D) vector. An MFVec2f field specifies zero or more 2D vectors.

EXAMPLE

<TextureCoordinate point="0.25 0.25 0.8 0.8"/>

SFVec2f and MFVec2f fields can be encoded using lossy and lossless techniques.

Values can be losslessly encoded using these encoders:

  1. Fast-InfoSet “float” encoder (see part 1 of ISO/IEC 24824) or
  2. zlib float array encoder.

Values can be lossy encoded using these encoders:

  1. Quantized float array or
  2. Quantized zlib float array

5.6.14 SFVec3d and MFVec3d

The SFVec3d field specifies a three-dimensional (3D) double-precision vector. An MFVec3d field specifies zero or more 3D double-precision vectors.

EXAMPLE

<GeoOrigin geoCoords="1000.123456789, 100.123456789, 100.123456789"/>

is an SFVec3d field, geoCoords, defining a high-precision vector value.

SFVec3d and MFVec3d fields can be encoded using lossy and lossless techniques.

SFVec2d and MFVec2d fields can be encoded using lossy and lossless techniques.

Values can be losslessly encoded using these encoders:

  1. FastInfoSet “double” encoder or
  2. zlib Double Array Encoder.

Values can be lossy encoded using these encoders:

  1. Quantized double array,
  2. Quantized zlib double array

5.6.15 SFVec3f and MFVec3f

The SFVec3f field specifies a three-dimensional (3D) vector. An MFVec3f field specifies zero or more 3D vectors.

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.

SFVec3f and MFVec3f fields can be encoded using lossy and lossless techniques.

Values can be losslessly encoded using these encoders:

  1. Fast-InfoSet “float” encoder (see part 1 of ISO/IEC 24824) or
  2. zlib float array encoder.

Values can be lossy encoded using these encoders:

  1. Quantized float array,
  2. Quantized zlib float array

--- X3D separator bar ---