How TRS Properties Are Serialized in glTF Nodes

In the glTF (GL Transmission Format) 2.0 specification, a node's spatial transform can be represented either as a single 4x4 affine transformation matrix or decomposed into separate Translation, Rotation, and Scale (TRS) properties. This article provides a technical overview of how TRS values are serialized within glTF JSON structures, outlining the schema definitions, data types, default values, and the mathematical order of operations used to compute the final local transformation matrix.

Node Structure and Mutual Exclusivity

Inside a glTF file, the nodes array contains individual node objects. A node defines its local transform using either the matrix property or a combination of TRS properties (translation, rotation, scale). According to the glTF specification, a node must not define both a matrix and any TRS property simultaneously; they are mutually exclusive.

If any TRS property is omitted from a node, it assumes its mathematical identity default.

{
  "nodes": [
    {
      "name": "SampleNode",
      "translation": [1.0, 2.0, 0.0],
      "rotation": [0.0, 0.0, 0.0, 1.0],
      "scale": [1.0, 1.0, 1.0]
    }
  ]
}

Translation Serialization

The translation property specifies the linear displacement of the node along the local X, Y, and Z axes.

  • Type: Array of three floating-point numbers (number[3]).
  • Format: [x, y, z]
  • Default Value: [0.0, 0.0, 0.0]
  • Units: Meters, aligned with glTF’s standard right-handed Cartesian coordinate system where +Y is up, +X is right, and +Z points forward toward the viewer.

Rotation Serialization

The rotation property specifies the node's orientation using a unit quaternion. Using quaternions avoids gimbal lock and ensures smooth spherical linear interpolation (slerp) during animations.

  • Type: Array of four floating-point numbers (number[4]).
  • Format: [x, y, z, w], where x, y, and z represent the vector component, and w represents the scalar component.
  • Default Value: [0.0, 0.0, 0.0, 1.0] (representing no rotation).
  • Constraints: Values must be normalized to represent a valid unit quaternion, such that \(x^2 + y^2 + z^2 + w^2 \approx 1\).

Scale Serialization

The scale property defines non-uniform or uniform scaling factors applied along the node's local coordinate axes.

  • Type: Array of three floating-point numbers (number[3]).
  • Format: [x, y, z]
  • Default Value: [1.0, 1.0, 1.0]
  • Behavior: A value of 1.0 maintains the original mesh dimensions, values greater than 1.0 expand the geometry, and values between 0.0 and 1.0 compress it. Negative scaling values are valid but invert mesh winding order and surface normals.

Matrix Reconstruction Order

When a glTF runtime reconstructs the local 4x4 transformation matrix (\(M\)) from serialized TRS properties, operations must be evaluated in a strictly defined order: Scale first, followed by Rotation, and then Translation.

In matrix multiplication terms, this corresponds to:

\[M = T \times R \times S\]

Where:

  • \(T\) is the translation matrix generated from translation.
  • \(R\) is the rotation matrix generated from the rotation quaternion.
  • \(S\) is the scale matrix generated from scale.

This sequence ensures that scaling does not distort the translation vector and that rotation operates on properly scaled local geometry before the object is positioned in space.