BabylonJS/Babylon.js · critical · Error

SOG texture contains ${splatTexelCount} texels, but metadata

Error message

SOG texture contains ${splatTexelCount} texels, but metadata references ${splatCount} splats.

What it means

ParseSogMetaAsTextures validates that the decoded means texture has at least as many texels (width * height) as the splat count declared in metadata (data.count or means.shape[0]). This error means the means_l webp image is too small for the declared splat count, so splats beyond the texel capacity would read undefined data. The message includes both numbers to aid diagnosis.

Source

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

        gpuTextures = gpu;
        meansL = CreateSogTextureFromImage(scene, images[0]);
        meansU = CreateSogTextureFromImage(scene, images[1]);
        meansWidth = images[0].width;
        meansHeight = images[0].height;
    } else {
        const [meansTex, gpu] = await Promise.all([Promise.all(data.means.files.map(loadGpuTextureAsync)), Promise.all(gpuFiles.map(loadGpuTextureAsync))]);
        gpuTextures = gpu;
        meansL = meansTex[0];
        meansU = meansTex[1];
        const size = (meansL as Texture).getSize();
        meansWidth = size.width;
        meansHeight = size.height;
    }

    const splatCount = data.count ?? data.means.shape[0];
    const splatTexelCount = meansWidth * meansHeight;
    if (splatTexelCount < splatCount) {
        throw new Error(`SOG texture contains ${splatTexelCount} texels, but metadata references ${splatCount} splats.`);
    }

    const scales = gpuTextures[0];
    const quats = gpuTextures[1];
    const sh0 = gpuTextures[2];

    let shCentroids: RawTexture | undefined;
    let shLabels: RawTexture | undefined;
    let shCoeffCount = 0;
    let shDegree = 0;

    if (data.shN && gpuTextures.length >= 5) {
        shCentroids = gpuTextures[3];
        shLabels = gpuTextures[4];

        shCoeffCount = data.shN.bands ? (data.shN.bands + 1) ** 2 - 1 : data.shN.shape[1] / 3;
        shDegree = data.shN.bands ?? Math.round(Math.sqrt(shCoeffCount + 1) - 1);
    }

View on GitHub (pinned to 0592b347b8)

Solutions

Ensure all SOG files come from the same export: re-download/re-extract the complete bundle so meta.json matches the means images.
Fix data.count (or means.shape[0]) in meta.json so it is <= meansWidth * meansHeight of the actual means_l image.
Re-export the asset with the SOG encoder so means image dimensions match the splat count.
Verify the asset pipeline does not re-encode/resize the webp data images.

Example fix

// before (meta.json references 250000 splats but image is 512x256 = 131072 texels)
"count": 250000
// after (match count to the actual means texture capacity, or re-export)
"count": 131072

Defensive patterns

Strategy: validation

Validate before calling

function validateSplatCapacity(meta, meansImage) {
  const splatCount = meta.count ?? meta.means.shape[0];
  const texels = meansImage.width * meansImage.height;
  if (texels < splatCount) {
    throw new Error(`means texture has ${texels} texels but meta declares ${splatCount} splats`);
  }
}

Type guard

function hasSufficientMeansCapacity(meta, meansImage) {
  const splatCount = meta.count ?? meta.means.shape[0];
  return meansImage.width * meansImage.height >= splatCount;
}

Try / catch

try {
  return await ParseSogMetaAsTextures(metaOrFiles, rootUrl, scene);
} catch (e) {
  if (e.message.startsWith('SOG texture contains')) {
    // meta.json and means image are from different assets or the image was resized:
    // re-download the complete bundle or fix count/shape in meta.json
  }
  throw e;
}

Prevention

Never serve SOG webp data images through re-encoding/resizing image CDNs — they are raw data.
Verify splatCount (count ?? means.shape[0]) fits within the means image dimensions during asset QA.
Keep meta.json and images from one export together via a manifest/hash; never mix bundles.
Log image dimensions alongside splat count when SOG loading fails for easier diagnosis.

When it happens

Trigger: Loading a SOG bundle where meta.json's count/means.shape[0] exceeds meansWidth*meansHeight — typically a meta.json from a different asset paired with mismatched means webp images, an encoder that wrote a wrong shape/count, or the means image being replaced/downscaled by an image pipeline.

Common situations: Mixing files from two SOG assets during manual re-bundling; CDN/asset optimization re-encoding or resizing the webp images; hand-edited meta.json with an incorrect count; partial uploads pairing an old meta.json with new images.

Related errors

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