Skip to content

3D engine that AI agents drive

10.3 KB
Raw Blame
// Rewrites the parts of a glTF document that common Sketchfab files get wrong, so that they load instead of throwing.
// parseGltf imports this module only when a file needs it, so it adds nothing to a scene that loads a clean file.

const SPECULAR_GLOSSINESS = 'KHR_materials_pbrSpecularGlossiness';

/** Paths (as arrays of keys) to every texture reference of a material that reads the given UV set. */
function collectTextureKeys(value, uvSet, path = [], found = []) {
  if (!value || typeof value !== 'object') return found;
  for (const [key, child] of Object.entries(value)) {
    if (!child || typeof child !== 'object') continue;
    const isTextureReference = Number.isInteger(child.index) && (child.texCoord ?? 0) === uvSet;
    if (isTextureReference) found.push([...path, key]);
    else collectTextureKeys(child, uvSet, [...path, key], found);
  }
  return found;
}

function referenceAt(root, path) {
  return path.reduce((node, key) => node[key], root);
}

/**
 * KHR_materials_pbrSpecularGlossiness to metallic-roughness, the way Blender's importer approximates it: the diffuse
 * color becomes the base color, the surface is dielectric, and roughness is 1 minus the glossiness factor. The specular
 * color and the specularGlossinessTexture are dropped, because reading them needs a pass over the image pixels.
 */
function convertSpecularGlossiness(document, warnings) {
  const converted = [];
  document.materials?.forEach((material, index) => {
    const specularGlossiness = material?.extensions?.[SPECULAR_GLOSSINESS];
    if (!specularGlossiness) return;
    const pbr = { metallicFactor: 0, roughnessFactor: 1 - (specularGlossiness.glossinessFactor ?? 1) };
    if (specularGlossiness.diffuseFactor) pbr.baseColorFactor = specularGlossiness.diffuseFactor;
    if (specularGlossiness.diffuseTexture) pbr.baseColorTexture = specularGlossiness.diffuseTexture;
    material.pbrMetallicRoughness = pbr;
    delete material.extensions[SPECULAR_GLOSSINESS];
    if (!Object.keys(material.extensions).length) delete material.extensions;
    const dropped = specularGlossiness.specularGlossinessTexture ? ' and its specularGlossinessTexture' : '';
    converted.push(`${material.name ?? `material ${index}`}${dropped}`);
  });
  if (!converted.length) return;
  document.extensionsUsed = document.extensionsUsed?.filter(name => name !== SPECULAR_GLOSSINESS);
  document.extensionsRequired = document.extensionsRequired?.filter(name => name !== SPECULAR_GLOSSINESS);
  warnings.push(`${SPECULAR_GLOSSINESS} converted to metallic-roughness (diffuse color as base color, metallic 0, roughness 1 - glossiness, specular color not read) in ${converted.join(', ')}.`);
}

// The shader samples these slots with the second UV set as they are; the path tracer and the light bake read only the
// first set, so the other maps of an all-TEXCOORD_1 material still move to it.
const SECOND_SET_SLOTS = new Set(['normalTexture', 'metallicRoughnessTexture', 'occlusionTexture', 'emissiveTexture']);

/** True when the texture reference carries a KHR_texture_transform that moves the UVs (an identity transform does not). */
function hasUvTransform(reference) {
  const transform = reference.extensions?.KHR_texture_transform;
  if (!transform) return false;
  const { offset = [0, 0], rotation = 0, scale = [1, 1] } = transform;
  return JSON.stringify([offset, rotation, scale]) !== JSON.stringify([[0, 0], 0, [1, 1]]);
}

/**
 * Maps can read TEXCOORD_1 themselves, but the path tracer and the light bake read only the first set, and Crucible bakes
 * a KHR_texture_transform into the UVs of one set only. When every map of the material reads TEXCOORD_1 (Blender writes
 * this for a material whose only UV map is the second one) and one is a base color or layer map or carries a transform,
 * the primitives get that set as TEXCOORD_0 and the maps move with it. When the material also has maps on TEXCOORD_0,
 * only a map on TEXCOORD_1 with a transform is dropped; the others keep reading their own set.
 */
function moveSecondSetTextures(document, warnings) {
  const movedMaterials = new Set();
  const movedNames = [];
  const droppedNames = [];
  document.materials?.forEach((material, index) => {
    const secondSet = collectTextureKeys(material, 1);
    const transformed = secondSet.filter(path => hasUvTransform(referenceAt(material, path)));
    const needsFirstSet = secondSet.some(path => !SECOND_SET_SLOTS.has(path.at(-1))) || transformed.length > 0;
    if (!needsFirstSet) return;
    const name = material.name ?? `material ${index}`;
    if (collectTextureKeys(material, 0).length === 0) {
      for (const path of secondSet) {
        const reference = referenceAt(material, path);
        delete reference.texCoord;
        // A KHR_texture_transform texCoord override of 1 would otherwise contradict the promoted set.
        if (reference.extensions?.KHR_texture_transform) delete reference.extensions.KHR_texture_transform.texCoord;
      }
      movedMaterials.add(index);
      movedNames.push(name);
      return;
    }
    for (const path of transformed) {
      delete referenceAt(material, path.slice(0, -1))[path.at(-1)];
      droppedNames.push(`${path.at(-1)} of ${name}`);
    }
  });
  for (const mesh of document.meshes ?? []) {
    for (const primitive of mesh.primitives ?? []) {
      if (!movedMaterials.has(primitive.material) || !primitive.attributes) continue;
      const secondSetAccessor = primitive.attributes.TEXCOORD_1;
      delete primitive.attributes.TEXCOORD_1;
      if (secondSetAccessor === undefined) delete primitive.attributes.TEXCOORD_0;
      else primitive.attributes.TEXCOORD_0 = secondSetAccessor;
    }
  }
  if (movedNames.length) warnings.push(`Read the textures of ${movedNames.join(', ')} from TEXCOORD_1 as the first UV set, because the path tracer, the light bake and a KHR_texture_transform read only the first set.`);
  if (droppedNames.length) warnings.push(`Dropped ${droppedNames.join(', ')}: a KHR_texture_transform on TEXCOORD_1 cannot be baked beside maps on TEXCOORD_0.`);
}

/**
 * A primitive without the UV set a texture reads cannot sample it. Such a primitive gets its own copy of the material
 * without those textures, and the original stays for the primitives that do have UVs.
 */
function dropTexturesWithoutUvs(document, warnings) {
  const copiesByKey = new Map();
  const dropped = new Set();
  const missingAttributes = new Set();
  const materialNames = new Set();
  for (const mesh of document.meshes ?? []) {
    for (const primitive of mesh.primitives ?? []) {
      const material = document.materials?.[primitive.material];
      if (!material) continue;
      const missingSets = [0, 1].filter(uvSet => primitive.attributes?.[`TEXCOORD_${uvSet}`] === undefined);
      const paths = missingSets.flatMap(uvSet => collectTextureKeys(material, uvSet));
      if (!paths.length) continue;
      const key = `${primitive.material}:${missingSets.join()}`;
      if (!copiesByKey.has(key)) {
        const copy = structuredClone(material);
        for (const path of paths) {
          delete referenceAt(copy, path.slice(0, -1))[path.at(-1)];
          dropped.add(path.at(-1));
        }
        document.materials.push(copy);
        copiesByKey.set(key, document.materials.length - 1);
      }
      for (const uvSet of missingSets) missingAttributes.add(`TEXCOORD_${uvSet}`);
      materialNames.add(material.name ?? `material ${primitive.material}`);
      primitive.material = copiesByKey.get(key);
    }
  }
  if (!dropped.size) return;
  warnings.push(`Dropped ${[...dropped].sort().join(', ')} from primitives without ${[...missingAttributes].sort().join(' or ')}, which cannot sample a texture (material ${[...materialNames].sort().join(', ')}).`);
}

/** Paths to every texture reference whose texCoord the test refuses: a negative number, or a set above the two Crucible reads. */
function collectTexCoordKeys(value, isUnreadable, path = [], found = []) {
  if (!value || typeof value !== 'object') return found;
  for (const [key, child] of Object.entries(value)) {
    if (!child || typeof child !== 'object') continue;
    if (Number.isInteger(child.index) && typeof child.texCoord === 'number' && isUnreadable(child.texCoord)) found.push([...path, key]);
    else collectTexCoordKeys(child, isUnreadable, [...path, key], found);
  }
  return found;
}

/**
 * Blender writes texCoord -1 for a map on a primitive that has no UVs, and some exporters write a roughness of 2. The
 * spec forbids both, and three.js draws the file anyway: the map is skipped and the factor is clamped. This does the same
 * and says so, so one bad value does not refuse the whole file.
 */
function repairOutOfSpecMaterialValues(document, warnings) {
  const droppedNames = [];
  const clampedNames = [];
  const highSetNames = [];
  document.materials?.forEach((material, index) => {
    if (!material || typeof material !== 'object') return;
    const name = material.name ?? `material ${index}`;
    for (const path of collectTexCoordKeys(material, texCoord => texCoord < 0)) {
      delete referenceAt(material, path.slice(0, -1))[path.at(-1)];
      droppedNames.push(`${path.at(-1)} of ${name}`);
    }
    for (const path of collectTexCoordKeys(material, texCoord => texCoord > 1)) {
      delete referenceAt(material, path.slice(0, -1))[path.at(-1)];
      highSetNames.push(`${path.at(-1)} of ${name}`);
    }
    const pbr = material.pbrMetallicRoughness;
    if (!pbr || typeof pbr !== 'object') return;
    for (const field of ['metallicFactor', 'roughnessFactor']) {
      const value = pbr[field];
      if (!Number.isFinite(value) || (value >= 0 && value <= 1)) continue;
      pbr[field] = Math.min(1, Math.max(0, value));
      clampedNames.push(`${field} ${value} of ${name}`);
    }
  });
  if (droppedNames.length) warnings.push(`Dropped ${droppedNames.join(', ')}: a negative texCoord names no UV set.`);
  if (highSetNames.length) warnings.push(`Dropped ${highSetNames.join(', ')}: Crucible reads only TEXCOORD_0 and TEXCOORD_1, and the texCoord names a later set.`);
  if (clampedNames.length) warnings.push(`Clamped ${clampedNames.join(', ')} to 0..1.`);
}

/** Rewrites the document in place and returns the warnings that tell the caller what changed. */
export function applyGltfFallbacks(document) {
  const warnings = [];
  repairOutOfSpecMaterialValues(document, warnings);
  convertSpecularGlossiness(document, warnings);
  moveSecondSetTextures(document, warnings);
  dropTexturesWithoutUvs(document, warnings);
  return warnings;
}