glTF Directional Light Coordinate Space Guide

This article provides an overview of the coordinate space and directional rules governing directional light nodes in the glTF (GL Transmission Format) standard. It details the default emission vector within the node's local coordinate space as defined by the KHR_lights_punctual extension, explains how glTF's right-handed system applies to light orientation, and outlines how scene hierarchy transforms determine the final world-space direction.

Local Coordinate Space and Emission Direction

In glTF, light sources are defined using the official KHR_lights_punctual extension. Within a directional light node, the light orientation is defined in the node's local coordinate space.

By specification, a directional light emits light along the negative Z-axis ([0.0, 0.0, -1.0]) of its local coordinate frame. It illuminates objects facing toward the positive Z direction relative to the light node.

glTF's Coordinate System Conventions

glTF uses a right-handed Cartesian coordinate system with the following axis definitions:

  • +X points to the right.
  • +Y points up.
  • +Z points out of the screen toward the viewer.

Because directional lights emit along the local -Z axis, an unrotated directional light node points directly "into" the screen, away from the default viewer perspective.

Transforming to World Space

A directional light does not carry absolute world-space directional coordinates inside its extension definition. Instead, its global orientation is derived from the scene graph hierarchy:

  1. Local Node Transforms: The light node can define rotation (quaternions), scale, and translation (TRS properties), or a combined 4x4 local matrix.
  2. Hierarchy Evaluation: To obtain the world-space direction, the initial local forward vector [0.0, 0.0, -1.0] is multiplied by the rotation component of the node's cumulative global transformation matrix (the product of all ancestor node transformations up to the root).

When implementing glTF directional lights in a rendering engine, extract the upper-left 3x3 rotation portion of the node's world transform matrix and apply it to the vector (0, 0, -1) to determine the final light trajectory in world space.