Extensible 3D (X3D) encodings
Part 5: JSON encoding

5 Encoding of fields

--- X3D separator bar ---

cube 5.1 Introduction and topics

5.1.1 Introduction

This clause specifies the JSON syntax for the encoding of each field type defined in 5 Field type reference in ISO/IEC 19775-1.

5.1.2 Topics

Table 5.1 lists the topics in this clause.

Table 5.1 — Topics

5.1.3 Description

This clause describes the syntax of field data type values.

There are two general classes of fields: fields that contain a single value (where, for example, 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.

In this JSON encoding, however, this general class distinction is unsuitable. A single-value field such as SFVec3f requires three values. These three values are encoded as an array, in an identical manner to an SFFloat field with three values. In comparison, an MFVec3f field with three values, which in abstract terms can be considered to be a three by three two-dimensional array, is encoded in JSON as a one-dimensional nine element array.

Fields that may have multiple values are written as an ordered list of values enclosed in square brackets with a comma separator between values. The last value shall not be followed by a comma. Whitespace may appear anywhere, except within a single value.

If a field that may have multiple values has zero values, only the square brackets ("[ ]") are written. The brackets shall be included, even if it has only a single value.

EXAMPLE 1  An MFInt32 field named foo containing the single integer value 1 shall be encoded as shown below. Additional whitespace is also permitted.

  "foo": [1]

A floating point number may be specified either as an integer or with a decimal point and may also include an exponent portion.

EXAMPLE 2  All of the following are validly expressed floating point values:

  "foo": 0
  "foo": 0.0
  "foo": 1.35e20

EXAMPLE 3  All of the following floating point values that are incorrectly expressed. JSON does not permit leading zeroes or plus signs, or trailing decimal points.

  "foo": 025
  "foo": 3.
  "foo": +1.35e20

cube 5.2 SFBool and MFBool

The SFBool field specifies a single boolean value encoded as either the JSON value true or false. MFBool specifies an array of zero or more SFBool values.

EXAMPLES

  "fooSFBool": false

  "fooMFBool": [ false,true , false]

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 encoded as an RGB triple of JSON numbers in the range 0.0 to 1.0.

EXAMPLES

  "fooSFColor": [1.0,0.0,0.0]

  "fooMFColor": [1,0,0,0,1,0,0,0,1]

The first example is an SFColor field, fooSFColor, containing the primary colour red. The second example is an MFColor field, fooMFColor, containing each of the three primary colours red, green, and blue.

cube 5.4 SFColorRGBA and MFColorRGBA

The SFColorRGBA field specifies one RGB (red-green-blue) colour triple and one alpha (opacity) value. MFColorRGBA specifies zero or more SFColorRGBA values. Each colour is encoded as an RGBA 4-tuple of JSON numbers in the range 0.0 to 1.0.

EXAMPLES

  "fooSFColorRGBA": [1,0,0,1]

  "fooMFColorRGBA": [1.0,0.0,0.0,1.0,0,1,0,1,0,0,1,1.0]

The fist example is an SFColorRGBA field, fooSFColorRGBA, containing the primary colour red with complete opacity. The second example is an MFColorRGBA field, fooMFColorRGBA, containing each of the three primary colours red, green, and blue with complete opacity.

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. SFDoubles and MFDoubles are encoded as JSON numbers.

EXAMPLES

  "fooSFDouble": -6.3502487E-2

  "fooMFDouble": [ 3.1415926, 12.5666666666e-12, .000176989898 ]

The first example is an SFDouble field, fooSFDouble, containing a single JSON number value. The second example is an MFDouble field, fooMFDouble, containing three JSON number values.

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 encoded as JSON numbers.

EXAMPLES

  "fooSFFloat": -3

  "fooMFFloat": [ 3.1415926, 12.5e-3, 0.0001 ]

The first example is an SFFloat field, fooSFFloat, containing a single JSON number value. The second example is an MFFloat field, fooMFFloat, containing three JSON number values.

cube 5.7 SFImage and MFImage

The SFImage field specifies a single uncompressed 2-dimensional pixel image. MFImage specifies zero or more SFImage values. SFImage fields are encoded as three integers representing the width, height and number of components in the image, followed by width×height integer decimal values representing the pixels in the image.

EXAMPLES

  "fooSFImage": [<width>,<height>,<num components>,<pixel values>]

Individual component values are limited to 256 levels of intensity (i.e., 0 to 255) with 0 representing no intensity and 255 representing full intensity. The individual component intensities for each pixel are combined into a single integer pixel value. Table 5.2 lists the formulae for calculating the pixel values for images with different numbers of components. The pixel values shall always be encoded as decimal integers.

Table 5.2 — Formulae for combining component intensities into a single pixel value

Number of components Component types Formula
1 intensity intensity
2 intensity, opacity (intensity×256)+opacity
3 red, green, blue (red×65,536)+(green×256)+blue
4 red, green, blue, opacity (red×16,777,216)+(green×65,536)+(blue×256)+opacity

A one-component image specifies a single decimal integer value representing the intensity of the image. For example, 255 is full intensity, 0 is no intensity. A two-component image specifies the intensity and combines it with the opacity. Pixels in a three-component image specify the red, green and blue components. Four-component images specify the opacity in addition to the red/green/blue. For opacity a component value of 0 is completely transparent, and a value of 255 is completely opaque.

Each pixel is read as a single unsigned number. Pixels are specified from left to right, bottom to top. The first decimal value is the lower left pixel and the last value is the upper right pixel.

EXAMPLE

  "fooSFImage": [1,2,1,255,0]

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.

EXAMPLE

  "fooSFImage": [2,4,3,16711680,65280,0,0,0,0,16777215,16776960]

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.

EXAMPLE

  "fooMFImage": [1,2,1,255,0,1,2,1,64,192]

specifies two images the first of which is a 1 pixel wide by 2 pixels high one-component (i.e., greyscale) image as in the first example while the second image is also a 1 pixel wide by 2 pixels high one-component (i.e., greyscale) image with the bottom pixel dark grey and the top pixel light grey.

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 encoded as JSON integer numbers in decimal format.

EXAMPLES

  "fooSFInt32": -547

  "fooMFInt32": [ 17, -148, -518820]

The first example is an SFInt32 field, fooSFInt32, containing a single integer. The second example is an MFInt32 field, fooMFInt32, containing three integer values.

NOTE: JSON does not have a native integer type. While numeric expressions such as 2.55E2 and -1E8 are integers and valid JSON numbers they will be rejected as invalid by the JSON Schema described in Annex A because the schema applies the restriction that an integer can only contain an optional leading minus sign and any number of decimal digits.

cube 5.9 SFMatrix3d and MFMatrix3d

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 SFMatrix3d is encoded as nine JSON numbers separated by commas. The first three numbers represent the top row of the matrix. The second three numbers represent second row of the matrix. The last three numbers represent the bottom row of the matrix.

EXAMPLES

  "fooSFMatrix3d": [1.5968734,0.7658987778666,0,0.4387899877,1,0,0,0,1]

  "fooMFMatrix3d": [1.5968734,0.7658987778666,0,0.4387899877,1,0,0,0,1,
                    2.7338246644,0.5,0,4.389222333,2.5,0,0,0,1]

cube 5.10 SFMatrix3f and MFMatrix3f

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 SFMatrix3f is encoded as nine JSON numbers separated by commas. The first three numbers represent the top row of the matrix. The second three numbers represent the second row of the matrix. The last three numbers represent the bottom row of the matrix.

EXAMPLES

  "fooSFMatrix3f": [3.05,43.89,0,77.89,54.32,0,-3.5,2.78,1]

  "fooMFMatrix3f": [3.05,43.89,0,77.89,54.32,0,-3.5,2.78,1,
                    89.777,33.486,0,3222.2,1,17.0,4.0,-3.9,0.5]

cube 5.11 SFMatrix4d and MFMatrix4d

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 SFMatrix4d is encoded as sixteen JSON numbers separated by commas. The first four numbers represent the top row of the matrix. The second four numbers represent the second row of the matrix. The third four numbers represent the third row of the matrix. The last four numbers represent the bottom row of the matrix.

EXAMPLES

  "fooSFMatrix4d": [1.5968734,0.7658987778666,0,0.4387899877,
                    1,0,0,0,
                    36.31896667,0.5,-13.4879906634,0,
                    0,0,0,1]

  "fooMFMatrix4d": [1.5968734,0.7658987778666,0,0.4387899877,
                    1,0,0,0,
                    36.31896667,0.5,-13.4879906634,0,
                    0,0,0,1,

                    2.7338246644,0.5,0,4.389222333,
                    2.5,0,0,0,
                    987.883,-0.5432,3289.77,1,
                    -43.5,43.5,-10,1]

cube 5.12 SFMatrix4f and MFMatrix4f

The SFMatrix4f field specifies a 4×4 matrix of single-precision floating point numbers. MFMatrix4f specifies zero or more 4×4 matrices of single-precision floating point numbers. Each SFMatrix4f is encoded as sixteen JSON numbers separated by commas. The first four numbers represent the top row of the matrix. The second four numbers represent the second row of the matrix. The third four numbers represent the third row of the matrix. The last four numbers represent the bottom row of the matrix.

EXAMPLES

  "fooSFMatrix4f": [3.05,43.89,0,77.89,
                    54.32,0,-3.5,2.78,
                    1.43,-0.0000776,2.1,1,
                    -0.5,0.5,2.9987,13.34]

  "fooMFMatrix4f": [3.05,43.89,0,77.89,
                    54.32,0,-3.5,2.78,
                    1.43,-0.0000776,2.1,1,
                    -0.5,0.5,2.9987,13.34,

                    89.777,33.486,0,3222.2,
                    1,17.0,4.0,-3.9,
                    -33.3333,17.6689,0.5,1,
                    1,1,-3,1.115]

cube 5.13 SFNode and MFNode

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

EXAMPLE The following illustrates valid syntax for an SFNode field, fooSFNode, containing a single Box node:

  "fooSFNode": {
    "Box": {
    }
  }

EXAMPLE The following illustrates valid syntax for an MFNode field, fooMFNode, defining three nodes:

  "fooMFNode": [
    { "Box": {
        "@DEF": "CUBE"
      }
    },
    { "Transform": {
        "@translation": [1,0,0]
      }
    },
    { "Box": {
        "@USE": "CUBE"
      }
    }
  ]

cube 5.14 SFRotation and MFRotation

The SFRotation field specifies one arbitrary rotation. The MFRotation field specifies zero or more arbitrary rotations. An SFRotation is encoded as four JSON numbers separated by commas.

EXAMPLE  An SFRotation containing a PI radians rotation about the Y axis is:

  "fooSFRot": [0.0,1.0,0.0,3.14159265]

EXAMPLE  An MFRotation containing two rotations is:

  "fooMFRot": [0.0,1.0,0.0,3.14159265,
               1,0,0,1.57079633]

cube 5.15 SFString and MFString

The SFString and MFString fields contain JSON strings. SFString specifies a single string. The MFString specifies zero or more strings. JSON strings are encoded as a sequence of Unicode code points enclosed in double quotes ("), (e.g., "string").

Any Unicode character may appear within the quotation marks except for the characters that shall be escaped: double quote ("), reverse solidus (\) and control characters. There are several two-character escape sequences as follows:

In addition, any code point may be represented as a hexadecimal number, as defined by ISO/IEC 10646. If the code point is in the Basic Multiligual Plane (BMP) then it may be represented by the six character sequence: a reverse solidus, followed by the lower case u, followed by four hexadecimal digits the encode the code point. Either upper or lower case may be used for the hexadecimal digits A-F/a-f. So, for example, a string containing only a single reverse solidus character may be encoded as "\u005c".

The following four cases all produce the same result:

To escape a code point that is not in the BMP, the character is represented as a twelve character sequence, encoding the UTF-16 surrogate pair. So, for example, a string containing only the G clef character (U+1D11E) may be encoded as "\uD834\uDD1E"

EXAMPLES

  "fooSFString": "One string"

  "fooMFString": ["One, Two, Three", "He said, \"Immel did it!\""]

cube 5.16 SFTime and MFTime

The SFTime field specifies a single time value. The MFTime field specifies zero or more time values. Time values are encoded as JSON numbers. As stated in ISO/IEC 19775-1, each SFTime field represents the number of seconds since Jan 1, 1970, 00:00:00 GMT.

EXAMPLES

  "fooSFTime": 0.0

  "fooMFTime": [0.0, 1.0]

In the first example fooSFTime is an SFTime field, representing a time of 0.0 seconds. In the second example fooMFTime is an MFTime field with two time values.

cube 5.17 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. Each vector is encoded as a pair of JSON numbers separated by a comma.

EXAMPLES

  "fooSFVec2d": [ 42.89978899,666.000123 ]

  "fooMFVec2d": [ 42.89978899,666.000123,7,94.1 ]

cube 5.18 SFVec2f and MFVec2f

The SFVec2f field specifies a two-dimensional (2D) single-precision vector. An MFVec2f field specifies zero or more 2D single-precision vectors. Each vector is encoded as a pair JSON numbers separated by a comma.

single-precision

EXAMPLES

  "fooSFVec2f": [ 42.9, 666 ]

  "fooMFVec2f": [ 42.9, 666, 7, 94.1 ]

cube 5.19 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. Each vector is encoded as three JSON numbers separated by commas.

EXAMPLES

  "fooSFVec3d": [ 1.000000000001,42,666.35357878 ]

  "fooMFVec3d": [ 1.000000000001,42,666.35357878,7,94,0.100000000007 ]

cube 5.20 SFVec3f and MFVec3f

The SFVec3f field specifies a three-dimensional (3D) single-precision vector. An MFVec3f field specifies zero or more 3D single-precision vectors. Each vector is encoded as three JSON numbers separated by commas.

EXAMPLES

  "fooSFVec3f": [ 1,42,666 ]

  "fooMFVec3f": [ 1,42,666,7,94,0 ]

cube 5.21 SFVec4d and MFVec4d

The SFVec4d field specifies a four-dimensional (4D) double-precision vector. An MFVec4d field specifies zero or more 4D double-precision vectors. Each vector is encoded as four JSON numbers separated by commas.

EXAMPLES

  "fooSFVec4d": [ 1.000000000001,42,666.35357878,32.6 ]

  "fooMFVec4d": [ 1.000000000001,42,666.35357878,32.6, 7,94,0.100000000007,143.998 ]

cube 5.22 SFVec4f and MFVec4f

The SFVec4f field specifies a four-dimensional (4D) single-precision vector. An MFVec4f field specifies zero or more 4D single-precision vectors. Each vector is encoded as four JSON numbers separated by commas.

EXAMPLES

  "fooSFVec4f": [ 1,42,666,-43.8 ]

  "fooMFVec4f": [ 1,42,666,-43.8, 7,94,0,0.0001 ]

--- X3D separator bar ---