BabylonJS/Babylon.js · critical · Error

Missing codebook in SOG version 2 scales data.

Error message

Missing codebook in SOG version 2 scales data.

What it means

ParseSogDatas decodes SOG (Sparse Occupancy Grid / splat) scales by indexing a codebook palette (data.scales.codebook) when the meta.json declares format version 2. This error means the version field says 2 (codebook-quantized encoding) but the scales entry in meta.json has no codebook array, so the uint8 indices in the scales image cannot be mapped to real scale values. The library throws rather than silently producing garbage scale values.

Source

Thrown at packages/dev/loaders/src/SPLAT/sog.pure.ts:187

    // --- Positions
    for (let i = 0; i < splatCount; i++) {
        const index = i * 4;
        for (let j = 0; j < 3; j++) {
            const meansMin = data.means.mins[j];
            const meansMax = data.means.maxs[j];
            const meansup = meansu[index + j];
            const meanslow = meansl[index + j];
            const q = (meansup << 8) | meanslow;
            const n = Scalar.Lerp(meansMin, meansMax, q / 65535);
            position[i * 8 + j] = unlog(n);
        }
    }

    // --- Scales
    const scales = imageDataArrays[2].bits;
    if (data.version === 2) {
        if (!data.scales.codebook) {
            throw new Error("Missing codebook in SOG version 2 scales data.");
        }
        for (let i = 0; i < splatCount; i++) {
            const index = i * 4;
            for (let j = 0; j < 3; j++) {
                const sc = data.scales.codebook[scales[index + j]];
                const sce = Math.exp(sc);
                scale[i * 8 + 3 + j] = sce;
            }
        }
    } else {
        if (!Array.isArray(data.scales.mins) || !Array.isArray(data.scales.maxs)) {
            throw new Error("Missing arrays in SOG scales data.");
        }

        for (let i = 0; i < splatCount; i++) {
            const index = i * 4;
            for (let j = 0; j < 3; j++) {
                const sc = scales[index + j];

View on GitHub (pinned to 0592b347b8)

Solutions

  1. Regenerate meta.json with a SOG v2 encoder so data.scales.codebook is populated.
  2. If the asset is actually v1, remove version: 2 (or set version: 1) from meta.json so the mins/maxs path is used instead.
  3. Validate meta.json before parsing: if version === 2, check Array.isArray(data.scales.codebook) before calling ParseSogMeta.

Example fix

// before (meta.json)
{ "version": 2, "scales": { "shape": [...], "dtype": "uint8", "files": ["scales.webp"] } }
// after
{ "version": 2, "scales": { "shape": [...], "dtype": "uint8", "files": ["scales.webp"], "codebook": [0.01, 0.015, ...] } }
Defensive patterns

Strategy: validation

Validate before calling

function validateV2Scales(meta) {
  if (meta.version === 2 && !Array.isArray(meta.scales?.codebook)) {
    throw new Error('v2 SOG asset: meta.scales.codebook is required');
  }
}
// call validateV2Scales(meta) before ParseSogMeta(meta, rootUrl, scene)

Type guard

function hasScalesCodebook(meta) {
  return meta.version !== 2 || Array.isArray(meta.scales?.codebook);
}

Try / catch

try {
  await ParseSogMeta(metaOrFiles, rootUrl, scene);
} catch (e) {
  if (e.message.includes('Missing codebook')) {
    // asset metadata incompatible with declared version: re-export or fix meta.json
  }
  throw e;
}

Prevention

When it happens

Trigger: Calling ParseSogMeta (or ParseSogMetaAsTextures) with a meta.json where version: 2 while data.scales lacks the codebook property — typically because the meta.json was hand-edited, produced by an encoder targeting SOG v1, or the codebook key was dropped when transcribing/transforming the metadata.

Common situations: Mixing SOG v1 and v2 assets (v1 meta has mins/maxs, v2 requires codebook); an asset pipeline upgrade that bumped version to 2 without regenerating meta.json; custom tooling that strips unknown fields from meta.json; loading a partially-uploaded SOG bundle where meta.json is from one version and images from another.

Related errors

AI-assisted analysis of BabylonJS/Babylon.js@0592b347b8 (2026-08-30). Data as JSON: /api/errors/0c81eeef5eef0b57. Report an issue: GitHub.