glTF Spherical Harmonics Irradiance Parameters

In glTF 2.0, diffuse irradiance from environment maps is typically encoded using spherical harmonics within image-based lighting (IBL) extensions. This article outlines the specific extensions, parameter formats, coefficient counts, and mathematical conventions used to store and evaluate diffuse irradiance via spherical harmonics in glTF assets.

The Extension: EXT_lights_image_based

Diffuse irradiance via spherical harmonics is primarily standardized in the EXT_lights_image_based glTF extension. This extension defines environment lights for image-based lighting and uses spherical harmonics (SH) to represent the low-frequency diffuse irradiance of an environment instead of requiring a separate, pre-filtered cubemap.

The Parameter: irradianceCoefficients

Inside an image-based light definition, the spherical harmonics data is stored in the irradianceCoefficients property.

The structure of irradianceCoefficients is defined as follows:

  • Type: A two-dimensional array of floating-point numbers with dimensions [9][3].
  • Data Count: 9 vectors, each containing 3 values representing the RGB channels, yielding 27 floating-point values in total.
  • Color Space: Linear RGB.
{
  "extensions": {
    "EXT_lights_image_based": {
      "lights": [
        {
          "rotation": [0.0, 0.0, 0.0, 1.0],
          "intensity": 1.0,
          "irradianceCoefficients": [
            [0.28, 0.35, 0.39],
            [0.07, 0.12, 0.17],
            [-0.01, -0.01, -0.01],
            [-0.05, -0.07, -0.09],
            [-0.02, -0.02, -0.02],
            [0.01, 0.01, 0.02],
            [-0.05, -0.06, -0.07],
            [-0.01, -0.01, -0.02],
            [0.02, 0.03, 0.04]
          ]
        }
      ]
    }
  }
}

Spherical Harmonics Order and Layout

The 9 RGB vectors represent a second-order (\(l = 2\)) spherical harmonic expansion, encompassing degrees \(l = 0, 1, 2\):

  • Band 0 (\(l = 0\)): 1 coefficient (\(m = 0\)), capturing ambient (constant) light.
  • Band 1 (\(l = 1\)): 3 coefficients (\(m = -1, 0, 1\)), capturing directional gradients along the coordinate axes.
  • Band 2 (\(l = 2\)): 5 coefficients (\(m = -2, -1, 0, 1, 2\)), capturing quadratic variations.

The standard indexing follows the canonical ordering:

  1. \(L_{0,0}\)
  2. \(L_{1,-1}\)
  3. \(L_{1,0}\)
  4. \(L_{1,1}\)
  5. \(L_{2,-2}\)
  6. \(L_{2,-1}\)
  7. \(L_{2,0}\)
  8. \(L_{2,1}\)
  9. \(L_{2,2}\)

Pre-Scaling and Mathematical Formulation

The coefficients in irradianceCoefficients follow the formulation established by Ravi Ramamoorthi and Pat Hanrahan ("An Efficient Representation for Irradiance Environment Maps").

The coefficients represent the incident radiance already convolved with the cosine lobe (\(\max(N \cdot L, 0)\)) required for Lambertian diffuse reflection. In typical runtime implementations, the reconstructed diffuse irradiance \(E(N)\) for a given surface normal \(N = (x, y, z)\) is evaluated directly using the basis polynomials without requiring runtime numerical integration:

\[E(N) = c_1 L_{2,0} (3z^2 - 1) + c_2 L_{2,2} (x^2 - y^2) + c_3 L_{2,1} z x + c_4 L_{2,-1} y z + c_5 L_{2,-2} x y + c_6 L_{1,0} z + c_7 L_{1,1} x + c_8 L_{1,-1} y + c_9 L_{0,0}\]

Depending on the exporter toolchain, constants associated with spherical harmonics basis functions (\(\hat{A}_l\) and \(Y_{lm}\)) are often pre-multiplied directly into the stored coefficients to minimize shader instruction counts during runtime evaluation.