@aura3d/assets 1.3.3 → 1.4.1

package/src/GLTFAutoFit.ts

@@ -1,133 +0,0 @@
-import type { CameraFrameBounds } from "@aura3d/rendering";
-
-/**
- * Up-axis of the source asset. Most glTF assets are Y-up (spec default), but
- * many catalog exports (CAD/Blender Z-up pipelines) ship Z-up geometry.
- */
-export type GLTFUpAxis = "y" | "z";
-
-export interface AutoFitTransform {
-  /** Uniform scale to apply so the model reaches the target height. */
-  readonly scale: number;
-  /**
-   * Translation (post-scale) that recenters the model horizontally and places
-   * its lowest point ("feet") at y = 0.
-   */
-  readonly translation: readonly [number, number, number];
-  /**
-   * Quaternion (x, y, z, w) that rotates source up-axis to Y-up, applied before
-   * scale/translation. Identity `[0, 0, 0, 1]` when no correction is needed.
-   */
-  readonly rotation: readonly [number, number, number, number];
-  /** The up-axis correction that was applied (`"none"` when already Y-up). */
-  readonly upAxisCorrection: "none" | "z-to-y";
-  /** The largest source extent, useful for diagnostics/logging. */
-  readonly sourceExtent: number;
-  /** The resulting model height after the transform is applied. */
-  readonly fittedHeight: number;
-}
-
-export interface AutoFitOptions {
-  /** Target height (in world units) the model should occupy. Default 1.6. */
-  readonly targetHeight?: number;
-  /**
-   * Source up-axis. When omitted, the loader keeps the asset as-authored
-   * (`"y"`); pass `"z"` for Z-up catalog exports to rotate them upright.
-   */
-  readonly upAxis?: GLTFUpAxis;
-  /**
-   * Recenter the model on the ground plane (feet at y = 0, centered in X/Z).
-   * Default `true`. When `false`, only scale (and optional rotation) is returned.
-   */
-  readonly recenter?: boolean;
-}
-
-const IDENTITY_ROTATION = [0, 0, 0, 1] as const;
-// Quaternion for -90deg about X, which maps Z-up geometry to Y-up.
-const Z_TO_Y_ROTATION = [-Math.SQRT1_2, 0, 0, Math.SQRT1_2] as const;
-const DEFAULT_TARGET_HEIGHT = 1.6;
-const MIN_EXTENT_EPSILON = 1e-6;
-
-/**
- * Compute a fit-to-height transform for a loaded glTF scene's bounds.
- *
- * Catalog models vary wildly in scale and orientation: one Sketchfab export had
- * an extent of ~1821 units while a Kenney prop is ~1 unit, and Z-up CAD exports
- * arrive lying on their side. This helper returns a single uniform scale +
- * translation (and optional up-axis rotation) so any model fits a target height
- * with its feet on the ground plane, independent of the renderer.
- *
- * The returned transform is meant to be applied in order: rotation, then scale,
- * then translation.
- */
-export function computeAutoFitTransform(
-  bounds: CameraFrameBounds,
-  options: AutoFitOptions = {}
-): AutoFitTransform {
-  const targetHeight = options.targetHeight ?? DEFAULT_TARGET_HEIGHT;
-  if (!Number.isFinite(targetHeight) || targetHeight <= 0) {
-    throw new Error("computeAutoFitTransform targetHeight must be a positive finite number.");
-  }
-  const recenter = options.recenter ?? true;
-  const upAxisCorrection = options.upAxis === "z" ? "z-to-y" : "none";
-  const rotation = upAxisCorrection === "z-to-y" ? Z_TO_Y_ROTATION : IDENTITY_ROTATION;
-
-  // Reorient the AABB into the post-rotation (Y-up) frame before measuring height.
-  const oriented = upAxisCorrection === "z-to-y" ? rotateBoundsZtoY(bounds) : bounds;
-
-  const size: readonly [number, number, number] = [
-    Math.max(0, oriented.max[0] - oriented.min[0]),
-    Math.max(0, oriented.max[1] - oriented.min[1]),
-    Math.max(0, oriented.max[2] - oriented.min[2])
-  ];
-  const sourceExtent = Math.max(size[0], size[1], size[2]);
-  const height = size[1];
-  const scale = height > MIN_EXTENT_EPSILON ? targetHeight / height : 1;
-
-  let translation: readonly [number, number, number] = [0, 0, 0];
-  if (recenter) {
-    const centerX = (oriented.min[0] + oriented.max[0]) / 2;
-    const centerZ = (oriented.min[2] + oriented.max[2]) / 2;
-    const floorY = oriented.min[1];
-    translation = [-centerX * scale, -floorY * scale, -centerZ * scale];
-  }
-
-  return {
-    scale,
-    translation,
-    rotation,
-    upAxisCorrection,
-    sourceExtent,
-    fittedHeight: height * scale
-  };
-}
-
-/**
- * Convenience wrapper that reads `.bounds` off an object (e.g. a
- * `GLTFRenderResources` instance) and computes the fit transform.
- */
-export function autoFitGLTFScene(
-  scene: { readonly bounds: CameraFrameBounds },
-  options: AutoFitOptions = {}
-): AutoFitTransform {
-  return computeAutoFitTransform(scene.bounds, options);
-}
-
-/**
- * Rotate an axis-aligned bounding box by the Z-up -> Y-up correction. Because the
- * rotation is axis-aligned (-90deg about X), this maps each source axis to a
- * destination axis exactly: x -> x, y -> z, z -> -y.
- */
-function rotateBoundsZtoY(bounds: CameraFrameBounds): CameraFrameBounds {
-  const xs = [bounds.min[0], bounds.max[0]];
-  const ys = [bounds.min[1], bounds.max[1]];
-  const zs = [bounds.min[2], bounds.max[2]];
-  // mapped axes: newX = x, newY = z, newZ = -y
-  const newX = xs;
-  const newY = zs;
-  const newZ = ys.map((value) => -value);
-  return {
-    min: [Math.min(...newX), Math.min(...newY), Math.min(...newZ)],
-    max: [Math.max(...newX), Math.max(...newY), Math.max(...newZ)]
-  };
-}

package/src/GLTFCompressionDecoders.ts

@@ -1,190 +0,0 @@
-import type {
-  GLTFDracoDecodeDescriptor,
-  GLTFDracoDecodedPrimitive,
-  GLTFDracoDecoder,
-  GLTFMeshoptDecodeDescriptor,
-  GLTFMeshoptDecoder
-} from "./GLTFLoader";
-
-export interface GLTFMeshoptDecoderModule {
-  readonly ready?: PromiseLike<void>;
-  decodeGltfBuffer(
-    target: Uint8Array,
-    count: number,
-    size: number,
-    source: Uint8Array,
-    mode: GLTFMeshoptDecodeDescriptor["mode"],
-    filter?: GLTFMeshoptDecodeDescriptor["filter"]
-  ): void;
-}
-
-export interface GLTFDracoStatus {
-  ok(): boolean;
-  error_msg(): string;
-}
-
-export interface GLTFDracoDecoderBuffer {
-  Init(data: Uint8Array, byteLength: number): void;
-}
-
-export interface GLTFDracoMesh {
-  num_points(): number;
-  num_faces(): number;
-}
-
-export interface GLTFDracoAttribute {
-  num_components(): number;
-}
-
-export interface GLTFDracoNumericArray {
-  size(): number;
-  GetValue(index: number): number;
-}
-
-export interface GLTFDracoDecoderInstance {
-  GetEncodedGeometryType(buffer: GLTFDracoDecoderBuffer): number;
-  DecodeBufferToMesh(buffer: GLTFDracoDecoderBuffer, mesh: GLTFDracoMesh): GLTFDracoStatus;
-  GetAttributeByUniqueId(mesh: GLTFDracoMesh, uniqueId: number): GLTFDracoAttribute | null;
-  GetAttributeFloatForAllPoints(mesh: GLTFDracoMesh, attribute: GLTFDracoAttribute, out: GLTFDracoNumericArray): boolean;
-  GetFaceFromMesh(mesh: GLTFDracoMesh, faceIndex: number, out: GLTFDracoNumericArray): boolean;
-}
-
-export interface GLTFDracoDecoderModule {
-  readonly TRIANGULAR_MESH: number;
-  readonly Decoder: new () => GLTFDracoDecoderInstance;
-  readonly DecoderBuffer: new () => GLTFDracoDecoderBuffer;
-  readonly Mesh: new () => GLTFDracoMesh;
-  readonly DracoFloat32Array: new () => GLTFDracoNumericArray;
-  readonly DracoInt32Array: new () => GLTFDracoNumericArray;
-  destroy?(object: unknown): void;
-}
-
-export function createMeshoptDecoder(module: GLTFMeshoptDecoderModule): GLTFMeshoptDecoder {
-  return async (source, descriptor) => {
-    if (module.ready) {
-      await module.ready;
-    }
-    const target = new Uint8Array(descriptor.count * descriptor.byteStride);
-    module.decodeGltfBuffer(
-      target,
-      descriptor.count,
-      descriptor.byteStride,
-      source,
-      descriptor.mode,
-      descriptor.filter
-    );
-    return target;
-  };
-}
-
-export function createDracoDecoder(module: GLTFDracoDecoderModule): GLTFDracoDecoder {
-  return (source, descriptor) => {
-    const allocated: unknown[] = [];
-    const decoder = track(new module.Decoder(), allocated);
-    const buffer = track(new module.DecoderBuffer(), allocated);
-    const mesh = track(new module.Mesh(), allocated);
-
-    try {
-      buffer.Init(source, source.byteLength);
-      const geometryType = decoder.GetEncodedGeometryType(buffer);
-      if (geometryType !== module.TRIANGULAR_MESH) {
-        throw new Error(`glTF Draco primitive ${descriptorLabel(descriptor)} must decode to a triangular mesh`);
-      }
-
-      const status = decoder.DecodeBufferToMesh(buffer, mesh);
-      if (!status.ok()) {
-        throw new Error(`glTF Draco primitive ${descriptorLabel(descriptor)} decode failed: ${status.error_msg()}`);
-      }
-
-      return {
-        attributes: decodeDracoAttributes(module, decoder, mesh, descriptor, allocated),
-        indices: decodeDracoIndices(module, decoder, mesh, descriptor, allocated)
-      };
-    } finally {
-      destroyAllocated(module, allocated);
-    }
-  };
-}
-
-function decodeDracoAttributes(
-  module: GLTFDracoDecoderModule,
-  decoder: GLTFDracoDecoderInstance,
-  mesh: GLTFDracoMesh,
-  descriptor: GLTFDracoDecodeDescriptor,
-  allocated: unknown[]
-): GLTFDracoDecodedPrimitive["attributes"] {
-  const pointCount = mesh.num_points();
-  const attributes: Record<string, number[][]> = {};
-
-  for (const [semantic, uniqueId] of Object.entries(descriptor.attributes)) {
-    const attribute = decoder.GetAttributeByUniqueId(mesh, uniqueId);
-    if (!attribute) {
-      throw new Error(`glTF Draco primitive ${descriptorLabel(descriptor)} is missing decoded attribute ${semantic} unique id ${uniqueId}`);
-    }
-
-    const componentCount = attribute.num_components();
-    if (!Number.isInteger(componentCount) || componentCount <= 0) {
-      throw new Error(`glTF Draco primitive ${descriptorLabel(descriptor)} decoded attribute ${semantic} has invalid component count ${componentCount}`);
-    }
-
-    const values = track(new module.DracoFloat32Array(), allocated);
-    if (!decoder.GetAttributeFloatForAllPoints(mesh, attribute, values)) {
-      throw new Error(`glTF Draco primitive ${descriptorLabel(descriptor)} failed to read decoded attribute ${semantic}`);
-    }
-    if (values.size() !== pointCount * componentCount) {
-      throw new Error(`glTF Draco primitive ${descriptorLabel(descriptor)} decoded attribute ${semantic} has ${values.size()} values but expected ${pointCount * componentCount}`);
-    }
-
-    const rows: number[][] = [];
-    for (let pointIndex = 0; pointIndex < pointCount; pointIndex += 1) {
-      const row: number[] = [];
-      for (let componentIndex = 0; componentIndex < componentCount; componentIndex += 1) {
-        row.push(values.GetValue(pointIndex * componentCount + componentIndex));
-      }
-      rows.push(row);
-    }
-    attributes[semantic] = rows;
-  }
-
-  return attributes;
-}
-
-function decodeDracoIndices(
-  module: GLTFDracoDecoderModule,
-  decoder: GLTFDracoDecoderInstance,
-  mesh: GLTFDracoMesh,
-  descriptor: GLTFDracoDecodeDescriptor,
-  allocated: unknown[]
-): number[] | undefined {
-  const faceCount = mesh.num_faces();
-  if (faceCount === 0) return undefined;
-
-  const face = track(new module.DracoInt32Array(), allocated);
-  const indices: number[] = [];
-  for (let faceIndex = 0; faceIndex < faceCount; faceIndex += 1) {
-    if (!decoder.GetFaceFromMesh(mesh, faceIndex, face)) {
-      throw new Error(`glTF Draco primitive ${descriptorLabel(descriptor)} failed to read decoded face ${faceIndex}`);
-    }
-    if (face.size() !== 3) {
-      throw new Error(`glTF Draco primitive ${descriptorLabel(descriptor)} decoded face ${faceIndex} has ${face.size()} indices but expected 3`);
-    }
-    indices.push(face.GetValue(0), face.GetValue(1), face.GetValue(2));
-  }
-  return indices;
-}
-
-function track<T>(value: T, allocated: unknown[]): T {
-  allocated.push(value);
-  return value;
-}
-
-function destroyAllocated(module: GLTFDracoDecoderModule, allocated: unknown[]): void {
-  if (!module.destroy) return;
-  for (let index = allocated.length - 1; index >= 0; index -= 1) {
-    module.destroy(allocated[index]);
-  }
-}
-
-function descriptorLabel(descriptor: GLTFDracoDecodeDescriptor): string {
-  return `${descriptor.meshIndex}/${descriptor.primitiveIndex}`;
-}

package/src/GLTFExtensionSupport.ts

@@ -1,138 +0,0 @@
-export type GLTFExtensionSupportFamily =
-  | "texture"
-  | "geometry"
-  | "material"
-  | "animation"
-  | "scene"
-  | "compression";
-
-export type GLTFExtensionSupportStatus =
-  | "runtime-supported"
-  | "decoder-required"
-  | "parsed-with-limits"
-  | "diagnostic-only"
-  | "unsupported";
-
-export interface GLTFExtensionSupportEntry {
-  readonly name: string;
-  readonly family: GLTFExtensionSupportFamily;
-  readonly status: GLTFExtensionSupportStatus;
-  readonly requiredAccepted: boolean;
-  readonly publicApi: readonly string[];
-  readonly decoder?: "draco" | "meshopt" | "ktx2-basis";
-  readonly knownLimits: readonly string[];
-}
-
-export interface GLTFExtensionSupportEvaluation {
-  readonly schemaVersion: "gltf-extension-support";
-  readonly requested: readonly GLTFExtensionSupportEntry[];
-  readonly supported: readonly GLTFExtensionSupportEntry[];
-  readonly runtimeSupported: readonly GLTFExtensionSupportEntry[];
-  readonly parsedWithLimits: readonly GLTFExtensionSupportEntry[];
-  readonly diagnosticOnly: readonly GLTFExtensionSupportEntry[];
-  readonly unsupportedUsed: readonly string[];
-  readonly unsupportedRequired: readonly string[];
-  readonly notAcceptedUsed: readonly string[];
-  readonly decoderRequired: readonly GLTFExtensionSupportEntry[];
-}
-
-export const GLTF_EXTENSION_SUPPORT_MATRIX: readonly GLTFExtensionSupportEntry[] = [
-  entry("EXT_texture_avif", "texture", "runtime-supported", ["GLTFLoader"], []),
-  entry("EXT_texture_webp", "texture", "runtime-supported", ["GLTFLoader"], []),
-  entry("KHR_texture_basisu", "compression", "decoder-required", ["GLTFLoader", "createGLTFRenderResources", "transcodeKTX2BasisTexture"], ["Requires loaders.gl Basis/KTX2 transcoder modules at render-resource creation time."], "ktx2-basis"),
-  entry("KHR_texture_transform", "texture", "runtime-supported", ["GLTFLoader", "TexturedPBRMaterial"], []),
-  entry("KHR_mesh_quantization", "geometry", "runtime-supported", ["GLTFLoader"], []),
-  entry("KHR_draco_mesh_compression", "compression", "decoder-required", ["GLTFLoader", "createDracoDecoder"], ["Requires an injected Draco decoder module."], "draco"),
-  entry("EXT_meshopt_compression", "compression", "decoder-required", ["GLTFLoader", "createMeshoptDecoder"], ["Requires an injected meshoptimizer decoder module."], "meshopt"),
-  entry("KHR_meshopt_compression", "compression", "decoder-required", ["GLTFLoader", "createMeshoptDecoder"], ["Requires an injected meshoptimizer decoder module."], "meshopt"),
-  entry("EXT_mesh_gpu_instancing", "geometry", "runtime-supported", ["GLTFLoader", "Renderable.instanceTransforms", "ProductionWebGL2Renderer"], ["Supports TRS instance attributes; custom per-instance material attributes remain out of scope."]),
-  entry("KHR_lights_punctual", "scene", "runtime-supported", ["GLTFLoader", "Scene", "ProductionWebGL2Renderer"], []),
-  entry("KHR_materials_unlit", "material", "runtime-supported", ["GLTFLoader", "UnlitMaterial"], []),
-  entry("KHR_materials_emissive_strength", "material", "runtime-supported", ["GLTFLoader", "TexturedPBRMaterial"], []),
-  entry("KHR_materials_clearcoat", "material", "parsed-with-limits", ["GLTFLoader", "TexturedPBRMaterial"], ["Clearcoat factors/textures are mapped; full reference BRDF parity still requires visual corpus acceptance."]),
-  entry("KHR_materials_transmission", "material", "parsed-with-limits", ["GLTFLoader", "TexturedPBRMaterial"], ["Transmission is mapped to the current WebGL2 fallback path; screen-space/refraction parity remains blocked."]),
-  entry("KHR_materials_diffuse_transmission", "material", "parsed-with-limits", ["GLTFLoader", "TexturedPBRMaterial"], ["Diffuse transmission factors/textures are mapped; full reference energy parity remains blocked."]),
-  entry("KHR_materials_volume", "material", "parsed-with-limits", ["GLTFLoader", "TexturedPBRMaterial"], ["Volume attenuation/thickness are mapped for fallback rendering, not full volumetric path tracing."]),
-  entry("KHR_materials_ior", "material", "runtime-supported", ["GLTFLoader", "TexturedPBRMaterial"], []),
-  entry("KHR_materials_specular", "material", "parsed-with-limits", ["GLTFLoader", "TexturedPBRMaterial"], ["Specular factors/textures are mapped; full reference BRDF parity still requires visual corpus acceptance."]),
-  entry("KHR_materials_sheen", "material", "parsed-with-limits", ["GLTFLoader", "TexturedPBRMaterial"], ["Sheen factors/textures are mapped; cloth reference parity remains blocked."]),
-  entry("KHR_materials_anisotropy", "material", "parsed-with-limits", ["GLTFLoader", "TexturedPBRMaterial"], ["Anisotropy factors/textures are mapped; tangent-space visual parity remains under review."]),
-  entry("KHR_materials_iridescence", "material", "parsed-with-limits", ["GLTFLoader", "TexturedPBRMaterial"], ["Iridescence factors/textures are mapped; thin-film reference parity remains under review."]),
-  entry("KHR_materials_dispersion", "material", "parsed-with-limits", ["GLTFLoader", "TexturedPBRMaterial"], ["Dispersion factor is preserved for material fallback; spectral dispersion rendering remains blocked."]),
-  entry("KHR_materials_pbrSpecularGlossiness", "material", "parsed-with-limits", ["GLTFLoader", "TexturedPBRMaterial"], ["Spec/gloss assets are converted into the current metallic-roughness runtime contract."]),
-  entry("KHR_materials_variants", "material", "parsed-with-limits", ["GLTFLoader"], ["Variant mappings are loaded; authoring/persistence workflow parity remains blocked."]),
-  entry("KHR_animation_pointer", "animation", "diagnostic-only", ["GLTFLoader"], ["Optional animation pointer channels are reported as unsupported tracks unless promoted into runtime targets."])
-];
-
-export const GLTF_SUPPORTED_EXTENSION_NAMES = GLTF_EXTENSION_SUPPORT_MATRIX
-  .filter((extension) => extension.status !== "diagnostic-only" && extension.status !== "unsupported")
-  .map((extension) => extension.name);
-
-export const GLTF_RUNTIME_SUPPORTED_EXTENSION_NAMES = extensionNamesByStatus("runtime-supported");
-export const GLTF_DECODER_REQUIRED_EXTENSION_NAMES = extensionNamesByStatus("decoder-required");
-export const GLTF_PARSED_WITH_LIMITS_EXTENSION_NAMES = extensionNamesByStatus("parsed-with-limits");
-export const GLTF_DIAGNOSTIC_ONLY_EXTENSION_NAMES = extensionNamesByStatus("diagnostic-only");
-export const GLTF_REQUIRED_ACCEPTED_EXTENSION_NAMES = GLTF_EXTENSION_SUPPORT_MATRIX
-  .filter((extension) => extension.requiredAccepted)
-  .map((extension) => extension.name);
-
-export function getGLTFExtensionSupport(name: string): GLTFExtensionSupportEntry {
-  return GLTF_EXTENSION_SUPPORT_MATRIX.find((entry) => entry.name === name)
-    ?? {
-      name,
-      family: "scene",
-      status: "unsupported",
-      requiredAccepted: false,
-      publicApi: [],
-      knownLimits: ["No A3D loader/runtime support is registered for this extension."]
-    };
-}
-
-export function evaluateGLTFExtensionSupport(
-  extensionsUsed: readonly string[] = [],
-  extensionsRequired: readonly string[] = []
-): GLTFExtensionSupportEvaluation {
-  const requested = [...new Set([...extensionsUsed, ...extensionsRequired])].sort();
-  const requestedEntries = requested.map((name) => getGLTFExtensionSupport(name));
-  const supported = requestedEntries.filter((entry) => entry.status !== "unsupported");
-  const unsupportedUsed = extensionsUsed.filter((name) => getGLTFExtensionSupport(name).status === "unsupported").sort();
-  const unsupportedRequired = extensionsRequired.filter((name) => !getGLTFExtensionSupport(name).requiredAccepted).sort();
-  const notAcceptedUsed = extensionsUsed.filter((name) => !getGLTFExtensionSupport(name).requiredAccepted).sort();
-  return {
-    schemaVersion: "gltf-extension-support",
-    requested: requestedEntries,
-    supported,
-    runtimeSupported: supported.filter((entry) => entry.status === "runtime-supported"),
-    parsedWithLimits: supported.filter((entry) => entry.status === "parsed-with-limits"),
-    diagnosticOnly: supported.filter((entry) => entry.status === "diagnostic-only"),
-    unsupportedUsed,
-    unsupportedRequired,
-    notAcceptedUsed,
-    decoderRequired: supported.filter((entry) => entry.status === "decoder-required")
-  };
-}
-
-function extensionNamesByStatus(status: GLTFExtensionSupportStatus): readonly string[] {
-  return GLTF_EXTENSION_SUPPORT_MATRIX
-    .filter((extension) => extension.status === status)
-    .map((extension) => extension.name);
-}
-
-function entry(
-  name: string,
-  family: GLTFExtensionSupportFamily,
-  status: Exclude<GLTFExtensionSupportStatus, "unsupported">,
-  publicApi: readonly string[],
-  knownLimits: readonly string[],
-  decoder?: GLTFExtensionSupportEntry["decoder"]
-): GLTFExtensionSupportEntry {
-  return {
-    name,
-    family,
-    status,
-    requiredAccepted: status !== "diagnostic-only",
-    publicApi,
-    ...(decoder === undefined ? {} : { decoder }),
-    knownLimits
-  };
-}