@downdraft/engine 0.0.0 → 0.1.1

package/libraries/models/src/threemf.ts

@@ -0,0 +1,201 @@
+// ============================================================================
+// threemf.ts — 3D Manufacturing Format (.3mf) parser
+//
+// 3MF is an OPC zip container: 3D/3dmodel.model holds XML with <object>
+// resources (mesh vertices + triangles), <basematerials> colors, and a
+// <build> list of items with optional 4×3 transforms. This parses the core
+// mesh spec — slices, beam lattices, and production-extension items are
+// skipped with warnings.
+// ============================================================================
+
+import { strFromU8, unzipSync } from "fflate";
+import { assertCount, MAX_FACE_COUNT, MAX_VERTEX_COUNT } from "@downdraft/engine";
+import type { MaterialData, MeshData, ModelData } from "./types";
+
+function parseTransform(s: string): number[] | null {
+  // 4×3 row-major: m00 m01 m02 m10 m11 m12 m20 m21 m22 m30 m31 m32
+  const v = s.trim().split(/\s+/).map(Number);
+  if (v.length !== 12 || v.some((x) => !Number.isFinite(x))) return null;
+  return v;
+}
+
+function applyTransform(p: [number, number, number], t: number[]): [number, number, number] {
+  const [x, y, z] = p;
+  return [
+    x * t[0] + y * t[3] + z * t[6] + t[9],
+    x * t[1] + y * t[4] + z * t[7] + t[10],
+    x * t[2] + y * t[5] + z * t[8] + t[11],
+  ];
+}
+
+function parseColor(s: string): [number, number, number, number] {
+  const h = s.replace("#", "");
+  const n = parseInt(h.length === 6 ? h + "FF" : h, 16);
+  return [((n >>> 24) & 255) / 255, ((n >>> 16) & 255) / 255, ((n >>> 8) & 255) / 255, (n & 255) / 255];
+}
+
+export function parse3MF(data: ArrayBuffer, name: string): ModelData {
+  let files: Record<string, Uint8Array>;
+  try {
+    files = unzipSync(new Uint8Array(data));
+  } catch {
+    throw new Error("3MF: not a valid zip container");
+  }
+  const modelPath = Object.keys(files).find((k) => /(^|\/)3d\/[^/]*\.model$/i.test(k))
+    ?? Object.keys(files).find((k) => /\.model$/i.test(k));
+  if (!modelPath) throw new Error("3MF: no 3D/*.model part found");
+  const xml = strFromU8(files[modelPath]);
+  const warnings: string[] = [];
+
+  // ── basematerials: <basematerials id="N"><base name=".." displaycolor="#RRGGBBAA"/></basematerials>
+  const materials: MaterialData[] = [];
+  const baseMatGroups = new Map<number, number[]>(); // basematerials id → material indices
+  const bmRe = /<basematerials\s+id="(\d+)"[^>]*>([\s\S]*?)<\/basematerials>/gi;
+  let bm: RegExpExecArray | null;
+  while ((bm = bmRe.exec(xml))) {
+    const gid = parseInt(bm[1], 10);
+    const idxs: number[] = [];
+    const baseRe = /<base\s+[^>]*displaycolor="([^"]+)"[^>]*\/>/gi;
+    let b: RegExpExecArray | null;
+    while ((b = baseRe.exec(bm[2]))) {
+      idxs.push(materials.length);
+      const nameM = /name="([^"]*)"/.exec(b[0]);
+      materials.push({
+        name: nameM?.[1] || `mat${materials.length}`,
+        baseColor: parseColor(b[1]),
+        metallic: 0,
+        roughness: 0.9,
+      });
+    }
+    baseMatGroups.set(gid, idxs);
+  }
+
+  // ── objects: <object id="N" ...><mesh><vertices>..</vertices><triangles>..</triangles></mesh></object>
+  interface Obj { verts: number[][]; tris: { v: [number, number, number]; pid?: number; p1?: number; p2?: number; p3?: number }[]; pid?: number; pindex?: number }
+  const objects = new Map<number, Obj>();
+  const objRe = /<object\s+([^>]*)>([\s\S]*?)<\/object>/gi;
+  let om: RegExpExecArray | null;
+  while ((om = objRe.exec(xml))) {
+    const attrs = om[1];
+    const id = parseInt(/id="(\d+)"/.exec(attrs)?.[1] ?? "-1", 10);
+    if (id < 0) continue;
+    const type = /type="([^"]+)"/.exec(attrs)?.[1] ?? "model";
+    if (type !== "model") { warnings.push(`object ${id} type "${type}" skipped`); continue; }
+    const pid = /pid="(\d+)"/.exec(attrs)?.[1];
+    const pindex = /pindex="(\d+)"/.exec(attrs)?.[1];
+    const obj: Obj = { verts: [], tris: [], pid: pid ? parseInt(pid, 10) : undefined, pindex: pindex ? parseInt(pindex, 10) : undefined };
+
+    const body = om[2];
+    const vRe = /<vertex\s+([^>]*)\/>/gi;
+    let vm: RegExpExecArray | null;
+    while ((vm = vRe.exec(body))) {
+      const a = vm[1];
+      obj.verts.push([
+        parseFloat(/x="([^"]+)"/.exec(a)?.[1] ?? "0"),
+        parseFloat(/y="([^"]+)"/.exec(a)?.[1] ?? "0"),
+        parseFloat(/z="([^"]+)"/.exec(a)?.[1] ?? "0"),
+      ]);
+    }
+    const tRe = /<triangle\s+([^>]*)\/>/gi;
+    let tm: RegExpExecArray | null;
+    while ((tm = tRe.exec(body))) {
+      const a = tm[1];
+      const num = (k: string) => { const m2 = new RegExp(`${k}="(\\d+)"`).exec(a); return m2 ? parseInt(m2[1], 10) : undefined; };
+      obj.tris.push({
+        v: [num("v1") ?? 0, num("v2") ?? 0, num("v3") ?? 0],
+        pid: num("pid"), p1: num("p1"), p2: num("p2"), p3: num("p3"),
+      });
+    }
+    objects.set(id, obj);
+  }
+
+  if (objects.size === 0) throw new Error("3MF: no model objects found");
+
+  // ── build items (transforms); fall back to all objects when <build> is absent
+  const items: { id: number; t: number[] | null }[] = [];
+  const buildRe = /<item\s+([^>]*)\/>/gi;
+  let im: RegExpExecArray | null;
+  while ((im = buildRe.exec(xml))) {
+    const a = im[1];
+    const oid = parseInt(/objectid="(\d+)"/.exec(a)?.[1] ?? "-1", 10);
+    const t = /transform="([^"]+)"/.exec(a)?.[1];
+    if (oid >= 0 && objects.has(oid)) items.push({ id: oid, t: t ? parseTransform(t) : null });
+  }
+  if (items.length === 0) for (const id of objects.keys()) items.push({ id, t: null });
+
+  // ── emit: one mesh per (item × material-group) — a triangle's pid picks the
+  // basematerials group; per-vertex p1/p2/p3 index into it. We bake the common
+  // case (uniform material per triangle) into materialIndex.
+  const meshes: MeshData[] = [];
+  const positions: number[] = [];
+
+  items.forEach((item) => {
+    const obj = objects.get(item.id)!;
+    // Group triangles by resolved material index (-1 = none).
+    const byMat = new Map<number, number[]>();
+    const triMat = (t: Obj["tris"][number]): number => {
+      const gid = t.pid ?? obj.pid;
+      if (gid === undefined) return -1;
+      const group = baseMatGroups.get(gid);
+      if (!group || group.length === 0) return -1;
+      const p = t.p1 ?? obj.pindex ?? 0;
+      return group[Math.min(p, group.length - 1)] ?? -1;
+    };
+    obj.tris.forEach((t) => {
+      const mi = triMat(t);
+      let arr = byMat.get(mi);
+      if (!arr) { arr = []; byMat.set(mi, arr); }
+      arr.push(t.v[0], t.v[1], t.v[2]);
+    });
+
+    for (const [mi, triIdx] of byMat.entries()) {
+      // Remap: local vertex list per material mesh.
+      const local = new Map<number, number>();
+      const indexArr: number[] = [];
+      const startPos = positions.length / 3;
+      triIdx.forEach((gv) => {
+        let li = local.get(gv);
+        if (li === undefined) {
+          li = positions.length / 3 - startPos;
+          const p = obj.verts[gv] ?? [0, 0, 0];
+          const w = item.t ? applyTransform(p as [number, number, number], item.t) : p;
+          positions.push(w[0], w[1], w[2]);
+          local.set(gv, li);
+        }
+        indexArr.push(li);
+      });
+      const vCount = positions.length / 3 - startPos;
+      if (vCount === 0 || indexArr.length === 0) continue;
+      const verts = new Float32Array(vCount * 6);
+      for (let v = 0; v < vCount; v++) {
+        verts[v * 6] = positions[(startPos + v) * 3];
+        verts[v * 6 + 1] = positions[(startPos + v) * 3 + 1];
+        verts[v * 6 + 2] = positions[(startPos + v) * 3 + 2];
+      }
+      const mesh: MeshData = {
+        vertices: verts,
+        indices: indexArr.length > 65535 ? new Uint32Array(indexArr) : new Uint16Array(indexArr),
+        vertexCount: vCount,
+        indexCount: indexArr.length,
+        uvs: null,
+        colors: null,
+      };
+      if (mi >= 0) mesh.materialIndex = mi;
+      meshes.push(mesh);
+    }
+  });
+
+  if (meshes.length === 0) throw new Error("3MF: objects contain no triangles");
+  const totalVerts = meshes.reduce((s, m) => s + m.vertexCount, 0);
+  assertCount("3mf vertices", totalVerts, MAX_VERTEX_COUNT);
+  assertCount("3mf triangles", meshes.reduce((s, m) => s + m.indexCount / 3, 0), MAX_FACE_COUNT);
+
+  const model: ModelData = {
+    meshes,
+    name,
+    format: "3mf",
+    materials: materials.length > 0 ? materials : undefined,
+  };
+  if (warnings.length > 0) model.warnings = warnings;
+  return model;
+}

package/libraries/models/src/types.ts

@@ -0,0 +1,188 @@
+export interface MorphTargetData {
+  name: string;
+  deltaPositions: Float32Array;
+  deltaNormals?: Float32Array;
+}
+
+export interface MeshData {
+  vertices: Float32Array;
+  indices: Uint16Array | Uint32Array;
+  vertexCount: number;
+  indexCount: number;
+  uvs: Float32Array | null;
+  colors: Float32Array | null;
+  materialIndex?: number;
+  joints?: Uint8Array | Uint16Array | Uint32Array; // 4 bone indices per vertex
+  weights?: Float32Array; // 4 bone weights per vertex (normalized)
+  morphTargets?: MorphTargetData[];
+  morphTargetNames?: string[];
+  /** KHR_materials_variants: per-primitive variant → material mappings. */
+  variantMappings?: { variant: number; material: number }[];
+}
+
+export interface TextureTransform {
+  offset: [number, number];
+  rotation: number;
+  scale: [number, number];
+  texCoord?: number;
+}
+
+export interface MaterialData {
+  name: string;
+  baseColor: [number, number, number, number];
+  metallic: number;
+  roughness: number;
+  textureUri?: string;
+  textureData?: ArrayBuffer | null;
+  normalTextureUri?: string;
+  /** Embedded normal texture data (from bufferView). */
+  normalTextureData?: ArrayBuffer | null;
+  emissiveColor?: [number, number, number];
+  /** KHR_texture_transform applied to the baseColor texture (UV transform). */
+  textureTransform?: TextureTransform;
+  /** KHR_texture_transform for the normal texture, if present. */
+  normalTextureTransform?: TextureTransform;
+  /** KHR_texture_transform for the emissive texture, if present. */
+  emissiveTextureTransform?: TextureTransform;
+}
+
+export interface AnimationChannel {
+  targetNode: string;
+  path: "translation" | "rotation" | "scale" | "weights";
+  keyframeTimes: Float32Array;
+  keyframeValues: Float32Array;
+  interpolation: "LINEAR" | "STEP" | "CUBICSPLINE";
+}
+
+export interface AnimationEvent {
+  time: number;
+  type: string;
+  payload?: Record<string, unknown>;
+}
+
+export interface AnimationData {
+  name: string;
+  duration: number;
+  channels: AnimationChannel[];
+  sourceRestRotations?: Map<string, [number, number, number, number]>;
+  sourcePreRotations?: Map<string, [number, number, number, number]>;
+  /** Source-node rest translations (Lcl Translation) keyed by node name —
+   *  used by retargeting to compute rest bone directions. */
+  sourceRestTranslations?: Map<string, [number, number, number]>;
+}
+
+export interface ModelNode {
+  name: string;
+  children?: number[];
+  /** Index of the primary mesh for this node (first material split). */
+  mesh?: number;
+  /** All mesh indices owned by this node, including multi-material splits.
+   *  For single-material nodes this is `[mesh]`. For multi-material FBX
+   *  geometries (split into one MeshData per material), this contains every
+   *  split so renderers can draw the full geometry. Undefined when the node
+   *  has no mesh. */
+  meshes?: number[];
+  translation?: [number, number, number];
+  rotation?: [number, number, number, number];
+  scale?: [number, number, number];
+  nodeIndex?: number;
+  /** KHR_lights_punctual: index into ModelData.lights. */
+  lightIndex?: number;
+}
+
+export interface BoneData {
+  name: string;
+  nodeIndex: number;
+  parentIndex: number;
+  inverseBindMatrix: Float32Array; // 16 floats (mat4, column-major)
+  restTranslation: [number, number, number];
+  restRotation: [number, number, number, number];
+  restScale: [number, number, number];
+  /** For root bones (parentIndex < 0) with non-bone ancestors in the FBX
+   *  hierarchy, this is the composed world transform of those ancestors.
+   *  Applied in computeSkinMatrices so the root bone's world matrix matches
+   *  the TransformLink. Undefined when no non-bone ancestors exist. */
+  rootAncestorMatrix?: Float32Array;
+}
+
+export interface SkinData {
+  bones: BoneData[];
+  boneNameToIndex: Map<string, number>;
+  /**
+   * The 4×4 normalization transform (column-major) that was applied to mesh
+   * vertices during normalization. The animator must conjugate skin matrices
+   * with this (T * skinMatrix * T^-1) so that skinned vertices, which were
+   * transformed by T, are mapped to the correct normalized world positions.
+   * Identity (or undefined) when no normalization was applied or the model
+   * has no skin.
+   */
+  normalizationMatrix?: Float32Array;
+  /** Native up-axis of the skeleton's bone space (the space rest transforms
+   *  and animation tracks live in, before normalizationMatrix conjugation).
+   *  Retargeting must convert source-space deltas into this space. Defaults
+   *  to "z" when absent for backward compatibility with rigs authored before
+   *  this field existed. */
+  skeletonUpAxis?: "y" | "z";
+}
+
+export interface PunctualLightData {
+  type: "directional" | "point" | "spot";
+  color?: [number, number, number];
+  intensity?: number;
+  range?: number;
+  spot?: {
+    innerConeAngle: number;
+    outerConeAngle: number;
+  };
+}
+
+export interface ModelData {
+  meshes: MeshData[];
+  name: string;
+  format: ModelFormat;
+  materials?: MaterialData[];
+  animations?: AnimationData[];
+  nodes?: ModelNode[];
+  skin?: SkinData;
+  morphTargetNames?: string[];
+  /** KHR_materials_variants: variant names indexed by variant id. */
+  materialVariants?: string[];
+  /** KHR_lights_punctual: lights referenced by nodes via lightIndex. */
+  lights?: PunctualLightData[];
+  /** Non-fatal warnings collected during parsing (e.g. skipped primitives). */
+  warnings?: string[];
+  /** Source asset's up-axis as detected by the parser. "y" or "z". Engine is Y-up. */
+  sourceUpAxis?: "y" | "z";
+  /** Source asset's unit system as detected by the parser. Engine uses meters. */
+  sourceUnits?: "meters" | "centimeters" | "inches" | "millimeters" | "units";
+  /** FBX raw UnitScaleFactor (units per centimeter). Used for precise unit conversion. */
+  sourceUnitScaleFactor?: number;
+  /** Computed axis-aligned bounding box of all meshes (min/max corners). */
+  bounds?: { min: [number, number, number]; max: [number, number, number] };
+  /** Normalization warnings (e.g. auto-fit triggered, extreme scale detected). */
+  normalizationWarnings?: string[];
+}
+
+export function getMaterialVariant(model: ModelData, name: string): number {
+  if (!model.materialVariants) return -1;
+  return model.materialVariants.indexOf(name);
+}
+
+export type ModelFormat = "obj" | "gltf" | "glb" | "fbx" | "dae" | "stl" | "ply" | "3ds" | "off" | "vtk" | "dxf" | "3mf";
+
+export function detectFormat(filename: string): ModelFormat | null {
+  const lower = filename.toLowerCase();
+  if (lower.endsWith(".obj")) return "obj";
+  if (lower.endsWith(".gltf")) return "gltf";
+  if (lower.endsWith(".glb")) return "glb";
+  if (lower.endsWith(".fbx")) return "fbx";
+  if (lower.endsWith(".dae")) return "dae";
+  if (lower.endsWith(".stl")) return "stl";
+  if (lower.endsWith(".ply")) return "ply";
+  if (lower.endsWith(".3ds")) return "3ds";
+  if (lower.endsWith(".off")) return "off";
+  if (lower.endsWith(".vtk")) return "vtk";
+  if (lower.endsWith(".dxf")) return "dxf";
+  if (lower.endsWith(".3mf")) return "3mf";
+  return null;
+}

package/libraries/models/src/vtk.ts

@@ -0,0 +1,218 @@
+// ============================================================================
+// vtk.ts — VTK legacy format (.vtk) parser, ASCII POLYDATA
+//
+// Supports the classic serial format: POINTS, POLYGONS/LINES/VERTICES plus
+// POINT_DATA attributes (NORMALS, TEXTURE_COORDINATES, COLOR_SCALARS,
+// SCALARS+LOOKUP_TABLE). Binary legacy files and STRUCTURED/UNSTRUCTURED/
+// FIELD datasets are reported as warnings — the modern XML VTK family
+// (.vtp/.vtu/.vti) is a different container entirely.
+// ============================================================================
+
+import { assertCount, MAX_FACE_COUNT, MAX_VERTEX_COUNT } from "@downdraft/engine";
+import type { MeshData, ModelData } from "./types";
+
+export function parseVTK(data: ArrayBuffer, name: string): ModelData {
+  const text = new TextDecoder().decode(data);
+  const lines = text.split("\n");
+  const warnings: string[] = [];
+
+  if (!lines[0]?.startsWith("# vtk DataFile")) {
+    throw new Error("VTK: not a legacy vtk file");
+  }
+  const encoding = (lines[2] ?? "").trim().toUpperCase();
+  if (encoding === "BINARY") {
+    throw new Error("VTK: binary legacy files are not supported (ASCII only)");
+  }
+  const datasetLine = (lines[3] ?? "").trim().toUpperCase();
+  const dataset = datasetLine.replace(/^DATASET\s+/, "");
+  if (dataset !== "POLYDATA") {
+    warnings.push(`VTK dataset ${dataset} — only POLYDATA geometry is loaded`);
+    if (dataset !== "UNSTRUCTURED_GRID") {
+      throw new Error(`VTK: unsupported dataset ${dataset}`);
+    }
+  }
+
+  // Tokenize the body after the DATASET line — VTK ASCII is whitespace-
+  // separated with keywords interleaved.
+  const body = lines.slice(4).join("\n");
+  const tokens = body.split(/\s+/).filter((t) => t.length > 0);
+  let ti = 0;
+
+  const positions: number[] = [];
+  const indices: number[] = [];
+  const normals: number[] = [];
+  const uvs: number[] = [];
+  const colors: number[] = [];
+  let pointDataCount = 0;
+  let colorComps = 0;
+  let scalarLookup: { name: string; table: Float32Array; scalarName: string; values: Float32Array } | null = null;
+  let pendingScalars: { name: string; values: Float32Array } | null = null;
+  const pendingCells: number[][] = [];
+
+  // VTK cell type → surface triangles (vertex order per the VTK spec).
+  const tri = (c: number[], ...ts: number[]) => {
+    for (let i = 0; i + 2 < ts.length; i += 3) indices.push(c[ts[i]], c[ts[i + 1]], c[ts[i + 2]]);
+  };
+  function emitCell(type: number, c: number[]): void {
+    switch (type) {
+      case 5: tri(c, 0, 1, 2); break; // TRIANGLE
+      case 9: tri(c, 0, 1, 2, 0, 2, 3); break; // QUAD
+      case 10: tri(c, 0, 1, 2, 0, 1, 3, 0, 2, 3, 1, 2, 3); break; // TETRA
+      case 12: // HEXAHEDRON
+        tri(c, 0, 1, 2, 0, 2, 3, 4, 6, 5, 4, 7, 6, 0, 4, 5, 0, 5, 1,
+               1, 5, 6, 1, 6, 2, 2, 6, 7, 2, 7, 3, 3, 7, 4, 3, 4, 0);
+        break;
+      case 13: // WEDGE
+        tri(c, 0, 1, 2, 3, 5, 4, 0, 3, 4, 0, 4, 1, 1, 4, 5, 1, 5, 2, 2, 5, 3, 2, 3, 0);
+        break;
+      case 14: // PYRAMID
+        tri(c, 0, 1, 2, 0, 2, 3, 0, 1, 4, 1, 2, 4, 2, 3, 4, 3, 0, 4);
+        break;
+      default: break; // vertex/line/unknown cells aren't meshes
+    }
+  }
+
+  while (ti < tokens.length) {
+    const kw = tokens[ti++].toUpperCase();
+    if (kw === "POINTS") {
+      const n = parseInt(tokens[ti++], 10);
+      ti++; // datatype token
+      assertCount("vtk points", n, MAX_VERTEX_COUNT);
+      for (let i = 0; i < n * 3; i++) positions.push(parseFloat(tokens[ti++]));
+    } else if (kw === "POLYGONS" || kw === "TRIANGLE_STRIPS") {
+      const n = parseInt(tokens[ti++], 10);
+      ti++; // total index count
+      assertCount("vtk polygons", n, MAX_FACE_COUNT);
+      if (kw === "POLYGONS") {
+        for (let i = 0; i < n; i++) {
+          const k = parseInt(tokens[ti++], 10);
+          const face: number[] = [];
+          for (let j = 0; j < k; j++) face.push(parseInt(tokens[ti++], 10));
+          for (let j = 1; j < k - 1; j++) {
+            indices.push(face[0], face[j], face[j + 1]);
+          }
+        }
+      } else {
+        // Triangle strips → triangle list.
+        for (let i = 0; i < n; i++) {
+          const k = parseInt(tokens[ti++], 10);
+          const strip: number[] = [];
+          for (let j = 0; j < k; j++) strip.push(parseInt(tokens[ti++], 10));
+          for (let j = 0; j + 2 < k; j++) {
+            if (j % 2 === 0) indices.push(strip[j], strip[j + 1], strip[j + 2]);
+            else indices.push(strip[j + 1], strip[j], strip[j + 2]);
+          }
+        }
+      }
+    } else if (kw === "VERTICES" || kw === "LINES") {
+      // Point/line cells — not renderable as triangles; skip.
+      const n = parseInt(tokens[ti++], 10);
+      const total = parseInt(tokens[ti++], 10);
+      ti += total;
+      if (n > 0) warnings.push(`VTK ${kw.toLowerCase()} skipped (points/lines aren't meshes)`);
+    } else if (kw === "CELLS") {
+      // UNSTRUCTURED_GRID cell connectivity — collect raw index lists;
+      // CELL_TYPES (next section) decides how each becomes triangles.
+      const n = parseInt(tokens[ti++], 10);
+      ti++; // total index count
+      assertCount("vtk cells", n, MAX_FACE_COUNT);
+      for (let i = 0; i < n; i++) {
+        const k = parseInt(tokens[ti++], 10);
+        const cell: number[] = [];
+        for (let j = 0; j < k; j++) cell.push(parseInt(tokens[ti++], 10));
+        pendingCells.push(cell);
+      }
+    } else if (kw === "CELL_TYPES") {
+      const n = parseInt(tokens[ti++], 10);
+      for (let i = 0; i < n; i++) {
+        const type = parseInt(tokens[ti++], 10);
+        const cell = pendingCells[i] ?? [];
+        emitCell(type, cell);
+      }
+      pendingCells.length = 0;
+    } else if (kw === "POINT_DATA" || kw === "CELL_DATA") {
+      pointDataCount = parseInt(tokens[ti++], 10);
+      if (kw === "CELL_DATA") break; // cell attributes don't map to vertices
+    } else if (kw === "NORMALS") {
+      ti++; // name
+      ti++; // datatype
+      for (let i = 0; i < pointDataCount * 3; i++) normals.push(parseFloat(tokens[ti++]));
+    } else if (kw === "TEXTURE_COORDINATES") {
+      ti++; // name
+      const dim = parseInt(tokens[ti++], 10);
+      ti++; // datatype
+      for (let i = 0; i < pointDataCount; i++) {
+        uvs.push(parseFloat(tokens[ti++]));
+        uvs.push(dim >= 2 ? parseFloat(tokens[ti++]) : 0);
+        if (dim >= 3) ti++;
+      }
+    } else if (kw === "COLOR_SCALARS") {
+      ti++; // name
+      colorComps = parseInt(tokens[ti++], 10);
+      for (let i = 0; i < pointDataCount; i++) {
+        const c = [0, 0, 0, 1];
+        for (let j = 0; j < colorComps; j++) c[j] = parseFloat(tokens[ti++]);
+        colors.push(c[0], c[1], c[2], c[3]);
+      }
+    } else if (kw === "SCALARS") {
+      const scalarName = tokens[ti++];
+      ti++; // datatype
+      if (tokens[ti] === "1") ti++; // optional numComp
+      // Next keyword is usually LOOKUP_TABLE
+      if (tokens[ti]?.toUpperCase() === "LOOKUP_TABLE") {
+        ti++;
+        const tableName = tokens[ti++];
+        pendingScalars = { name: scalarName, values: new Float32Array(pointDataCount) };
+        for (let i = 0; i < pointDataCount; i++) pendingScalars.values[i] = parseFloat(tokens[ti++]);
+        scalarLookup = { name: tableName, table: new Float32Array(0), scalarName, values: pendingScalars.values };
+      } else {
+        for (let i = 0; i < pointDataCount; i++) ti++;
+      }
+    } else if (kw === "LOOKUP_TABLE") {
+      ti++; // name
+      const n = parseInt(tokens[ti++], 10);
+      const table = new Float32Array(n * 4);
+      for (let i = 0; i < n * 4; i++) table[i] = parseFloat(tokens[ti++]);
+      if (scalarLookup && pendingScalars) {
+        scalarLookup.table = table;
+        // Apply table: scalar value [0,1] → rgba
+        for (let i = 0; i < pointDataCount; i++) {
+          const t = Math.max(0, Math.min(1, pendingScalars.values[i]));
+          const idx = Math.min(n - 1, Math.floor(t * (n - 1) + 0.5)) * 4;
+          colors.push(table[idx], table[idx + 1], table[idx + 2], table[idx + 3]);
+        }
+      }
+    } else {
+      // Unknown keyword — stop scanning; trailing sections (VECTORS,
+      // TENSORS, FIELD) are skipped to avoid misreading counts.
+      break;
+    }
+  }
+
+  const vertexCount = positions.length / 3;
+  if (vertexCount === 0) throw new Error("VTK: no POINTS section");
+
+  const hasNormals = normals.length === vertexCount * 3;
+  const vertices = new Float32Array(vertexCount * 6);
+  for (let i = 0; i < vertexCount; i++) {
+    vertices[i * 6] = positions[i * 3];
+    vertices[i * 6 + 1] = positions[i * 3 + 1];
+    vertices[i * 6 + 2] = positions[i * 3 + 2];
+    vertices[i * 6 + 3] = hasNormals ? normals[i * 3] : 0;
+    vertices[i * 6 + 4] = hasNormals ? normals[i * 3 + 1] : 0;
+    vertices[i * 6 + 5] = hasNormals ? normals[i * 3 + 2] : 0;
+  }
+
+  const mesh: MeshData = {
+    vertices,
+    indices: indices.length > 65535 ? new Uint32Array(indices) : new Uint16Array(indices),
+    vertexCount,
+    indexCount: indices.length,
+    uvs: uvs.length === vertexCount * 2 ? new Float32Array(uvs) : null,
+    colors: colors.length === vertexCount * 4 ? new Float32Array(colors) : null,
+  };
+
+  const model: ModelData = { meshes: [mesh], name, format: "vtk" };
+  if (warnings.length > 0) model.warnings = warnings;
+  return model;
+}

package/libraries/models/test-fixtures/fbx/LICENSE-notice.txt

@@ -0,0 +1,24 @@
+FBX test fixtures (m01-m16) are from the BabylonJS/Assets repository:
+https://github.com/BabylonJS/Assets/tree/master/meshes/fbx/loaderTests
+
+License: MIT (https://github.com/BabylonJS/Assets/blob/master/LICENSE.md)
+
+Copyright (c) 2014-2024 Babylon.js contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/libraries/models/test-fixtures/fbx/README.md

@@ -0,0 +1,46 @@
+# FBX loader visual-test models
+
+A deterministic suite of small FBX files exercising the Babylon.js FBX loader's feature surface.
+Each file is authored programmatically (binary FBX, v7500) and validated against the real Autodesk
+FBX SDK, so it opens correctly in Maya as well as the Babylon loader.
+
+Generator (not in this repo): `babylon-fbx/tools/fbx-test-generator`.
+
+`fbxVisualTests.js` is the scene-creation script for the Babylon.js visual-regression suite: it loads
+each model here, frames it with the validated per-model camera + a neutral light rig, renders
+single-sided, and pins animations to a deterministic frame. The Babylon.js FBX loader PR references
+its functions via the visualization `config.json` (`scriptToRun` + `functionToCall`). NOTE: fbx2gltf
+drops FBX skeletal animation, so the SDK/Maya-proxy render of `m12_skeletal_anim` shows the rest pose
+(straight); the Babylon loader (and real Maya, when scrubbed) shows the bend.
+
+## Conventions / expectations
+- **Single-sided**: meshes are wound so the outward face is front-facing. Render with backface
+  culling on; a regression that flips winding/normals will show backfaces (inside-out).
+- **Axis**: M16 includes genuinely Z-up and Y-up authorings. The Babylon loader converts both to the
+  engine's Y-up space, so all three M16 files load identically. (Maya does NOT convert on import, so
+  the Z-up file looks rotated there — that is the proof it is genuinely Z-up.)
+- **Cameras/lights** (M15): FBX cameras look down local +X, lights down local -Z; both are aimed at
+  the subject. View M15 through its own perspective camera.
+
+## Models
+| File | Exercises | Expected |
+| --- | --- | --- |
+| m01_cube_phong | basic mesh, Phong material, per-face normals/UVs | lit cube |
+| m02_geo_ngons | n-gon triangulation (tri/quad/hex/concave arrow), vertex colors | flat panel of colored polygons (enable vertex-color display in Maya) |
+| m03_normals | smooth vs flat (hard-edged) shading on two spheres | left smooth, right faceted; no pole holes |
+| m04_material_properties | Lambert/Phong, specular, emissive, ambient, opacity | row of spheres with distinct shading |
+| m05_textures | texture slots: diffuse, normal (debossed F), emissive, opacity (holes), external sidecar | row of textured quads (needs `m05_external_diffuse.png`) |
+| m06_uv_transform | per-texture UV translation + scaling | tiled/offset checker on a plane |
+| m07_multimaterial | per-polygon material indices → submesh splitting | cube with 3 colored face-pairs (red/green/blue) |
+| m08_transforms | TRS chain, pre/post-rotation, pivots/offsets, geometric transform | scattered colored cubes |
+| m09_skinning | skeleton + clusters + weights + bind pose (static bent rest) | smoothly bent cylinder |
+| m10_morph | morph targets + in-between shapes (static deform) | flat plane with a raised central hill |
+| m11_node_anim | node animation (const/linear/cubic keys) | three posed cubes at the sampled frame |
+| m12_skeletal_anim | skeletal animation over time | cylinder bent at the sampled frame |
+| m13_morph_anim | DeformPercent animation | plane hill at the sampled frame |
+| m14_multiclip | multiple AnimationStacks → two clips ("Spin", "Bounce") | one cube; two animation groups |
+| m15_camera_lights | point/spot/directional lights + perspective/orthographic cameras, all aimed at the subject | lit sphere + ground, green spot pool, viewed through the FBX camera |
+| m16_axis_yup / m16_axis_zup / m16_units_254 | GlobalSettings axis conversion + unit scale | all three load identically (RGB gizmo, green up) |
+
+`.fbm` folders are texture-extraction artifacts created by SDK tools (Maya/fbx2gltf) when loading
+embedded-texture files; they are gitignored.