How to Define a 4x4 Matrix in a glTF Node

In glTF (GL Transmission Format), node transformations can be defined either by individual translation, rotation, and scale (TRS) properties or by a single 4x4 transformation matrix. Replacing separate TRS vectors with a unified matrix property simplifies scene structures by combining complex affine transforms into a single array, directly aligning with graphics API conventions. This guide explains how to define a 4x4 matrix within a glTF node, detailing array ordering, syntax requirements, and operational constraints.

The matrix Property Syntax

To use a 4x4 matrix instead of individual TRS properties, add the matrix key directly to the node object within the nodes array. The value must be an array of 16 floating-point numbers.

{
  "nodes": [
    {
      "name": "TransformedNode",
      "matrix": [
        1.0, 0.0, 0.0, 0.0,
        0.0, 1.0, 0.0, 0.0,
        0.0, 0.0, 1.0, 0.0,
        2.5, 4.0, 0.0, 1.0
      ],
      "mesh": 0
    }
  ]
}

Column-Major Ordering

The glTF specification mandates that matrix elements are stored in column-major order, which matches standard OpenGL and WebGL conventions.

When mapping the 16-element array to a standard \(4 \times 4\) mathematical matrix, the indices correspond as follows:

\[ \begin{bmatrix} m[0] & m[4] & m[8] & m[12] \\ m[1] & m[5] & m[9] & m[13] \\ m[2] & m[6] & m[10] & m[14] \\ m[3] & m[7] & m[11] & m[15] \end{bmatrix} \]

In this layout:

• Indices 0–2, 4–6, and 8–10 define the upper-left \(3 \times 3\) submatrix controlling rotation and scale.
• Indices 12, 13, and 14 define the translation vector along the X, Y, and Z axes (\(T_x\), \(T_y\), \(T_z\)).
• Indices 3, 7, 11, and 15 form the projection row and must be 0.0, 0.0, 0.0, 1.0 for valid affine transformations.

Specification Constraints and Rules

1. Mutual Exclusivity: A glTF node must define either the matrix property or any of the translation, rotation, and scale properties. Defining both on the same node violates the glTF specification.
2. Identity Default: If omitted, the default transformation is the \(4 \times 4\) identity matrix: [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1].
3. Affine Transforms Only: The matrix must be invertible and must represent a valid rigid or affine transform. Skew and non-uniform scaling can be represented, but perspective projections are invalid for node hierarchies.
4. Animation Limitations: glTF animation channels can only target individual translation, rotation, scale, and weights properties. If a node needs to be animated, it must use TRS properties rather than a matrix.