{"record":{"id":"0f84691c86542ba5","repo":"BabylonJS/Babylon.js","slug":"missing-codebook-in-sog-version-2-sh0-data","errorCode":null,"errorMessage":"Missing codebook in SOG version 2 sh0 data.","messagePattern":"Missing codebook in SOG version 2 sh0 data\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"critical","filePath":"packages/dev/loaders/src/SPLAT/sog.pure.ts","lineNumber":217,"sourceCode":"            throw new Error(\"Missing arrays in SOG scales data.\");\r\n        }\r\n\r\n        for (let i = 0; i < splatCount; i++) {\r\n            const index = i * 4;\r\n            for (let j = 0; j < 3; j++) {\r\n                const sc = scales[index + j];\r\n                const lsc = Scalar.Lerp(data.scales.mins[j], data.scales.maxs[j], sc / 255);\r\n                const lsce = Math.exp(lsc);\r\n                scale[i * 8 + 3 + j] = lsce;\r\n            }\r\n        }\r\n    }\r\n\r\n    // --- Colors/SH0\r\n    const colors = imageDataArrays[4].bits;\r\n    if (data.version === 2) {\r\n        if (!data.sh0.codebook) {\r\n            throw new Error(\"Missing codebook in SOG version 2 sh0 data.\");\r\n        }\r\n        for (let i = 0; i < splatCount; i++) {\r\n            const index = i * 4;\r\n            for (let j = 0; j < 3; j++) {\r\n                const component = 0.5 + data.sh0.codebook[colors[index + j]] * SH_C0;\r\n                rgba[i * 32 + 24 + j] = Math.max(0, Math.min(255, Math.round(255 * component)));\r\n            }\r\n            rgba[i * 32 + 24 + 3] = colors[index + 3];\r\n        }\r\n    } else {\r\n        if (!Array.isArray(data.sh0.mins) || !Array.isArray(data.sh0.maxs)) {\r\n            throw new Error(\"Missing arrays in SOG sh0 data.\");\r\n        }\r\n        for (let i = 0; i < splatCount; i++) {\r\n            const index = i * 4;\r\n            for (let j = 0; j < 4; j++) {\r\n                const colorsMin = data.sh0.mins[j];\r\n                const colorsMax = data.sh0.maxs[j];\r","sourceCodeStart":199,"sourceCodeEnd":235,"githubUrl":"https://github.com/BabylonJS/Babylon.js/blob/0592b347b8a4ee0236089ea86a749cacfdb266d8/packages/dev/loaders/src/SPLAT/sog.pure.ts#L199-L235","documentation":"For SOG version 2, base colors (SH0) are stored as palette indices into data.sh0.codebook; the decoder maps each byte through the codebook before applying the SH_C0 basis. This error means meta.json declares version 2 but the sh0 entry has no codebook, so color bytes cannot be decoded. The library throws instead of rendering wrong colors.","triggerScenarios":"ParseSogMeta with meta.json where version: 2 and data.sh0 has no codebook array — e.g. meta.json generated by a v1 encoder, hand-edited, or the sh0 codebook omitted during metadata transformation.","commonSituations":"Version mismatch between meta.json and the asset generator; converting assets between SOG versions with a script that drops codebook fields; third-party SOG files that claim v2 but follow v1 metadata layout.","solutions":["Regenerate meta.json with a proper SOG v2 encoder so sh0.codebook (256 entries) is present.","If the asset is actually v1, set version to 1/omit it so the mins/maxs path decodes sh0.","Pre-validate: if version === 2, require Array.isArray(data.sh0.codebook) before parsing."],"exampleFix":"// before\n\"sh0\": { \"shape\": [100000, 4], \"dtype\": \"uint8\", \"files\": [\"sh0.webp\"] }\n// after\n\"sh0\": { \"shape\": [100000, 4], \"dtype\": \"uint8\", \"files\": [\"sh0.webp\"], \"codebook\": [-0.53, -0.51, ...] }","handlingStrategy":"validation","validationCode":"function validateV2Sh0(meta) {\n  if (meta.version === 2 && !Array.isArray(meta.sh0?.codebook)) {\n    throw new Error('v2 SOG asset: meta.sh0.codebook is required');\n  }\n}","typeGuard":"function hasSh0Codebook(meta) {\n  return meta.version !== 2 || Array.isArray(meta.sh0?.codebook);\n}","tryCatchPattern":"try {\n  await ParseSogMeta(metaOrFiles, rootUrl, scene);\n} catch (e) {\n  if (e.message.includes('sh0')) {\n    // sh0 codebook missing: re-export asset or correct the version field\n  }\n  throw e;\n}","preventionTips":["Run a schema check on meta.json (version + per-attribute requirements) as a build step for SOG assets.","Never bump the version field without regenerating the data files and metadata together.","Test-load every SOG asset in CI with the same loader version used in production."],"tags":["sog","gaussian-splatting","codebook","sh0","asset-validation"],"backgroundTag":"missing-codebook-in-quantized-data","analyzedSha":"0592b347b8a4ee0236089ea86a749cacfdb266d8","analyzedAt":"2026-08-30T15:11:20.442Z","schemaVersion":2},"datasetVersion":"2026-08-31T09:17:48.483Z"}