@pixel-point/toolcraft 0.0.15 → 0.0.16

package/templates/runtime/model-import/formats/fbx-binary-preflight-reader.ts

@@ -0,0 +1,179 @@
+import type { ToolcraftModelDecodeContext } from "../model-import-types";
+import {
+  checkedThreeStaticGeometryTotal,
+  threeStaticGeometryFailure,
+} from "./obj-stl-ply-model-format-adapter-support";
+
+const ARRAY_ELEMENT_BYTES = Object.freeze({
+  b: 1,
+  c: 1,
+  d: 8,
+  f: 4,
+  i: 4,
+  l: 8,
+} as const);
+
+export type FbxBinaryPreflightState = {
+  arrayBytes: number;
+  nodeCount: number;
+  vertexCoordinates: number;
+};
+
+export function readFbxUint64(view: DataView, offset: number): number {
+  const low = view.getUint32(offset, true);
+  const high = view.getUint32(offset + 4, true);
+  const value = high * 0x1_0000_0000 + low;
+  if (!Number.isSafeInteger(value)) {
+    return threeStaticGeometryFailure(
+      "format",
+      "unsafe-fbx-integer",
+      "FBX binary offsets and counts must be safe integers.",
+    );
+  }
+  return value;
+}
+
+export function requireFbxBinaryRange(
+  offset: number,
+  length: number,
+  end: number,
+  code = "malformed-binary-fbx",
+): void {
+  if (
+    !Number.isSafeInteger(offset) ||
+    !Number.isSafeInteger(length) ||
+    offset < 0 ||
+    length < 0 ||
+    offset > end - length
+  ) {
+    return threeStaticGeometryFailure(
+      "format",
+      code,
+      "FBX binary data contains an invalid or truncated range.",
+    );
+  }
+}
+
+export function readFbxBinaryName(
+  bytes: Uint8Array,
+  offset: number,
+  length: number,
+): string {
+  requireFbxBinaryRange(offset, length, bytes.byteLength);
+  try {
+    return new TextDecoder("utf-8", { fatal: true }).decode(
+      bytes.subarray(offset, offset + length),
+    );
+  } catch {
+    return threeStaticGeometryFailure(
+      "format",
+      "invalid-fbx-node-name",
+      "FBX binary node names must use valid UTF-8.",
+    );
+  }
+}
+
+function scalarByteLength(type: string): number | undefined {
+  if (type === "C") return 1;
+  if (type === "Y") return 2;
+  if (type === "F" || type === "I") return 4;
+  if (type === "D" || type === "L") return 8;
+  return undefined;
+}
+
+export function parseFbxBinaryProperty(
+  view: DataView,
+  offset: number,
+  end: number,
+  nodeName: string,
+  state: FbxBinaryPreflightState,
+  limits: ToolcraftModelDecodeContext["limits"],
+): number {
+  requireFbxBinaryRange(offset, 1, end);
+  const type = String.fromCharCode(view.getUint8(offset));
+  const scalarBytes = scalarByteLength(type);
+  if (scalarBytes !== undefined) {
+    requireFbxBinaryRange(offset + 1, scalarBytes, end);
+    return offset + 1 + scalarBytes;
+  }
+  if (type === "R" || type === "S") {
+    requireFbxBinaryRange(offset + 1, 4, end);
+    const length = view.getUint32(offset + 1, true);
+    requireFbxBinaryRange(offset + 5, length, end);
+    return offset + 5 + length;
+  }
+  if (!(type in ARRAY_ELEMENT_BYTES)) {
+    return threeStaticGeometryFailure(
+      "format",
+      "unsupported-fbx-property",
+      `FBX binary property type ${JSON.stringify(type)} is unsupported.`,
+    );
+  }
+
+  requireFbxBinaryRange(offset + 1, 12, end);
+  const arrayLength = view.getUint32(offset + 1, true);
+  const encoding = view.getUint32(offset + 5, true);
+  const storedLength = view.getUint32(offset + 9, true);
+  const decodedBytes = arrayLength * ARRAY_ELEMENT_BYTES[
+    type as keyof typeof ARRAY_ELEMENT_BYTES
+  ];
+  if (!Number.isSafeInteger(decodedBytes)) {
+    return threeStaticGeometryFailure(
+      "resource-limit",
+      "decoded-byte-limit-exceeded",
+      "FBX binary array size exceeds the protected integer range.",
+    );
+  }
+  state.arrayBytes = checkedThreeStaticGeometryTotal(
+    state.arrayBytes,
+    decodedBytes,
+    limits.maxDecodedBytes,
+    "decoded-byte-limit-exceeded",
+    "FBX decoded array bytes",
+  );
+  if (nodeName === "Vertices") {
+    if (type !== "d" && type !== "f") {
+      return threeStaticGeometryFailure(
+        "geometry",
+        "invalid-fbx-vertices",
+        "FBX vertex coordinates must use a floating-point array.",
+      );
+    }
+    state.vertexCoordinates = checkedThreeStaticGeometryTotal(
+      state.vertexCoordinates,
+      arrayLength,
+      limits.maxVertices * 3,
+      "max-vertices-exceeded",
+      "FBX source vertex coordinates",
+    );
+  }
+  if (encoding !== 0 && encoding !== 1) {
+    return threeStaticGeometryFailure(
+      "format",
+      "unsupported-fbx-array-encoding",
+      "FBX binary arrays must be uncompressed or zlib-compressed.",
+    );
+  }
+  const payloadLength = encoding === 0 ? decodedBytes : storedLength;
+  if (encoding === 0 && storedLength !== decodedBytes) {
+    return threeStaticGeometryFailure(
+      "format",
+      "invalid-fbx-array-length",
+      "FBX uncompressed array length does not match its declared values.",
+    );
+  }
+  requireFbxBinaryRange(offset + 13, payloadLength, end);
+  return offset + 13 + payloadLength;
+}
+
+export function isFbxNullRecord(
+  bytes: Uint8Array,
+  offset: number,
+  length: number,
+): boolean {
+  requireFbxBinaryRange(offset, length, bytes.byteLength);
+  for (let index = offset; index < offset + length; index += 1) {
+    if (bytes[index] !== 0) return false;
+  }
+  return true;
+}

package/templates/runtime/model-import/formats/fbx-binary-preflight.ts

@@ -0,0 +1,277 @@
+import type { ToolcraftModelDecodeContext } from "../model-import-types";
+import {
+  checkedThreeStaticGeometryTotal,
+  threeStaticGeometryFailure,
+  throwIfThreeStaticGeometryAborted,
+} from "./obj-stl-ply-model-format-adapter-support";
+import {
+  isFbxNullRecord,
+  parseFbxBinaryProperty,
+  readFbxBinaryName,
+  readFbxUint64,
+  requireFbxBinaryRange,
+  type FbxBinaryPreflightState,
+} from "./fbx-binary-preflight-reader";
+
+const FBX_BINARY_MAGIC = "Kaydara FBX Binary  \0\x1a\0";
+const UNSUPPORTED_NODE_NAMES = new Set([
+  "AnimationCurve",
+  "AnimationCurveNode",
+  "AnimationLayer",
+  "AnimationStack",
+  "Deformer",
+  "Pose",
+]);
+
+export type FbxBinaryEmbeddedImage = Readonly<{
+  bytes: Uint8Array;
+  fileName: string;
+  id: number;
+}>;
+
+type MutableFbxBinaryVideo = {
+  bytes?: Uint8Array;
+  fileName?: string;
+  id?: number;
+};
+
+function readIntegerProperty(
+  view: DataView,
+  offset: number,
+  end: number,
+): number | undefined {
+  requireFbxBinaryRange(offset, 1, end);
+  const type = String.fromCharCode(view.getUint8(offset));
+  if (type === "I") {
+    requireFbxBinaryRange(offset + 1, 4, end);
+    return view.getInt32(offset + 1, true);
+  }
+  if (type === "L") {
+    requireFbxBinaryRange(offset + 1, 8, end);
+    return readFbxUint64(view, offset + 1);
+  }
+  return undefined;
+}
+
+function readStringProperty(
+  bytes: Uint8Array,
+  view: DataView,
+  offset: number,
+  end: number,
+): string | undefined {
+  requireFbxBinaryRange(offset, 5, end);
+  if (String.fromCharCode(view.getUint8(offset)) !== "S") return undefined;
+  const length = view.getUint32(offset + 1, true);
+  requireFbxBinaryRange(offset + 5, length, end);
+  return readFbxBinaryName(bytes, offset + 5, length);
+}
+
+function readRawProperty(
+  bytes: Uint8Array,
+  view: DataView,
+  offset: number,
+  end: number,
+): Uint8Array | undefined {
+  requireFbxBinaryRange(offset, 5, end);
+  if (String.fromCharCode(view.getUint8(offset)) !== "R") return undefined;
+  const length = view.getUint32(offset + 1, true);
+  requireFbxBinaryRange(offset + 5, length, end);
+  return bytes.subarray(offset + 5, offset + 5 + length);
+}
+
+function parseNode(
+  bytes: Uint8Array,
+  view: DataView,
+  offset: number,
+  version: number,
+  parentEnd: number,
+  state: FbxBinaryPreflightState,
+  context: ToolcraftModelDecodeContext,
+  embeddedImages: MutableFbxBinaryVideo[],
+  parentVideo?: MutableFbxBinaryVideo,
+): number {
+  throwIfThreeStaticGeometryAborted(context.signal);
+  const wide = version >= 7500;
+  const headerLength = wide ? 25 : 13;
+  requireFbxBinaryRange(offset, headerLength, parentEnd);
+  const readCount = (at: number) =>
+    wide ? readFbxUint64(view, at) : view.getUint32(at, true);
+  const endOffset = readCount(offset);
+  const propertyCount = readCount(offset + (wide ? 8 : 4));
+  const propertyBytes = readCount(offset + (wide ? 16 : 8));
+  const nameLength = view.getUint8(offset + (wide ? 24 : 12));
+  if (endOffset === 0) return offset + headerLength;
+  if (endOffset <= offset || endOffset > parentEnd) {
+    return threeStaticGeometryFailure(
+      "format",
+      "invalid-fbx-node-range",
+      "FBX binary node offsets must stay within their parent.",
+    );
+  }
+  const nameOffset = offset + headerLength;
+  const nodeName = readFbxBinaryName(bytes, nameOffset, nameLength);
+  if (UNSUPPORTED_NODE_NAMES.has(nodeName)) {
+    return threeStaticGeometryFailure(
+      "format",
+      "unsupported-fbx-feature",
+      `Geometry-only FBX import does not accept ${nodeName} nodes.`,
+    );
+  }
+  state.nodeCount = checkedThreeStaticGeometryTotal(
+    state.nodeCount,
+    1,
+    context.limits.maxNodes,
+    "max-nodes-exceeded",
+    "FBX nodes",
+  );
+
+  let cursor = nameOffset + nameLength;
+  const propertyEnd = cursor + propertyBytes;
+  requireFbxBinaryRange(cursor, propertyBytes, endOffset);
+  const video = nodeName === "Video" ? {} : parentVideo;
+  for (let index = 0; index < propertyCount; index += 1) {
+    const propertyOffset = cursor;
+    cursor = parseFbxBinaryProperty(
+      view,
+      cursor,
+      propertyEnd,
+      nodeName,
+      state,
+      context.limits,
+    );
+    if (video && index === 0) {
+      if (nodeName === "Video") {
+        video.id = readIntegerProperty(view, propertyOffset, propertyEnd);
+      } else if (nodeName === "Filename" || nodeName === "RelativeFilename") {
+        video.fileName = readStringProperty(
+          bytes,
+          view,
+          propertyOffset,
+          propertyEnd,
+        );
+      } else if (nodeName === "Content") {
+        video.bytes = readRawProperty(bytes, view, propertyOffset, propertyEnd);
+      }
+    }
+  }
+  if (cursor !== propertyEnd) {
+    return threeStaticGeometryFailure(
+      "format",
+      "invalid-fbx-property-list",
+      "FBX binary property bytes do not match the declared property count.",
+    );
+  }
+  if (nodeName === "Video" && video) embeddedImages.push(video);
+  while (cursor < endOffset) {
+    const nullLength = wide ? 25 : 13;
+    if (
+      endOffset - cursor === nullLength &&
+      isFbxNullRecord(bytes, cursor, nullLength)
+    ) {
+      cursor = endOffset;
+      break;
+    }
+    const next = parseNode(
+      bytes,
+      view,
+      cursor,
+      version,
+      endOffset,
+      state,
+      context,
+      embeddedImages,
+      video,
+    );
+    if (next <= cursor) {
+      return threeStaticGeometryFailure(
+        "format",
+        "invalid-fbx-node-progress",
+        "FBX binary child traversal did not advance.",
+      );
+    }
+    cursor = next;
+  }
+  return cursor;
+}
+
+export function isBinaryFbx(source: ArrayBuffer): boolean {
+  if (source.byteLength < FBX_BINARY_MAGIC.length) return false;
+  return readFbxBinaryName(
+    new Uint8Array(source),
+    0,
+    FBX_BINARY_MAGIC.length,
+  ) === FBX_BINARY_MAGIC;
+}
+
+export function preflightBinaryFbx(
+  source: ArrayBuffer,
+  context: ToolcraftModelDecodeContext,
+): readonly FbxBinaryEmbeddedImage[] {
+  const bytes = new Uint8Array(source);
+  const view = new DataView(source);
+  requireFbxBinaryRange(0, 27, bytes.byteLength);
+  const version = view.getUint32(23, true);
+  if (version < 6400 || version > 7700) {
+    return threeStaticGeometryFailure(
+      "format",
+      "unsupported-fbx-version",
+      `FBX binary version ${version} is outside the supported range.`,
+    );
+  }
+  const state: FbxBinaryPreflightState = {
+    arrayBytes: 0,
+    nodeCount: 0,
+    vertexCoordinates: 0,
+  };
+  const embeddedImages: MutableFbxBinaryVideo[] = [];
+  let cursor = 27;
+  const nullLength = version >= 7500 ? 25 : 13;
+  while (cursor + nullLength <= bytes.byteLength) {
+    throwIfThreeStaticGeometryAborted(context.signal);
+    if (isFbxNullRecord(bytes, cursor, nullLength)) break;
+    cursor = parseNode(
+      bytes,
+      view,
+      cursor,
+      version,
+      bytes.byteLength,
+      state,
+      context,
+      embeddedImages,
+    );
+  }
+  if (state.vertexCoordinates === 0 || state.vertexCoordinates % 3 !== 0) {
+    return threeStaticGeometryFailure(
+      "geometry",
+      "invalid-fbx-vertices",
+      "FBX requires complete nonempty XYZ vertex coordinates.",
+    );
+  }
+  checkedThreeStaticGeometryTotal(
+    0,
+    source.byteLength * 4 + state.arrayBytes * 8,
+    context.limits.maxEstimatedWorkerBytes,
+    "estimated-worker-memory-limit-exceeded",
+    "FBX preflight worker memory",
+  );
+  const admitted: FbxBinaryEmbeddedImage[] = [];
+  const ids = new Set<number>();
+  for (const image of embeddedImages) {
+    const { bytes: imageBytes, fileName, id } = image;
+    if (!imageBytes || imageBytes.byteLength === 0) continue;
+    if (
+      typeof id !== "number" || !Number.isSafeInteger(id) || id < 0 ||
+      !fileName || ids.has(id)
+    ) {
+      return threeStaticGeometryFailure(
+        "format",
+        "invalid-fbx-embedded-image",
+        "Embedded FBX images require unique non-negative ids and filenames.",
+      );
+    }
+    ids.add(id);
+    admitted.push({ bytes: imageBytes, fileName, id });
+  }
+  admitted.sort((left, right) => left.id - right.id);
+  return Object.freeze(admitted.map((image) => Object.freeze(image)));
+}

package/templates/runtime/model-import/formats/fbx-binary-test-fixture-builder.ts

@@ -0,0 +1,129 @@
+const encoder = new TextEncoder();
+
+export type FbxBinaryFixtureNode = Readonly<{
+  children?: readonly FbxBinaryFixtureNode[];
+  name: string;
+  properties?: readonly Uint8Array[];
+}>;
+
+function join(parts: readonly Uint8Array[]): Uint8Array {
+  const output = new Uint8Array(
+    parts.reduce((total, part) => total + part.byteLength, 0),
+  );
+  let offset = 0;
+  for (const part of parts) {
+    output.set(part, offset);
+    offset += part.byteLength;
+  }
+  return output;
+}
+
+function integer(value: number, bytes: 4 | 8): Uint8Array {
+  const output = new Uint8Array(bytes);
+  const view = new DataView(output.buffer);
+  if (bytes === 4) view.setInt32(0, value, true);
+  else {
+    view.setUint32(0, value >>> 0, true);
+    view.setUint32(4, Math.floor(value / 0x1_0000_0000), true);
+  }
+  return output;
+}
+
+function uint32(value: number): Uint8Array {
+  const output = new Uint8Array(4);
+  new DataView(output.buffer).setUint32(0, value, true);
+  return output;
+}
+
+function numericArray(
+  values: readonly number[],
+  bytesPerValue: 4 | 8,
+  write: (view: DataView, offset: number, value: number) => void,
+): Uint8Array {
+  const output = new Uint8Array(values.length * bytesPerValue);
+  const view = new DataView(output.buffer);
+  values.forEach((value, index) => write(view, index * bytesPerValue, value));
+  return output;
+}
+
+function arrayProperty(type: "d" | "i", values: readonly number[]): Uint8Array {
+  const bytes = type === "d"
+    ? numericArray(values, 8, (view, offset, value) =>
+        view.setFloat64(offset, value, true))
+    : numericArray(values, 4, (view, offset, value) =>
+        view.setInt32(offset, value, true));
+  return join([
+    encoder.encode(type),
+    uint32(values.length),
+    uint32(0),
+    uint32(bytes.byteLength),
+    bytes,
+  ]);
+}
+
+export const fbxBinaryFixtureProperty = Object.freeze({
+  float64: (value: number): Uint8Array => {
+    const bytes = new Uint8Array(9);
+    bytes[0] = "D".charCodeAt(0);
+    new DataView(bytes.buffer).setFloat64(1, value, true);
+    return bytes;
+  },
+  float64Array: (values: readonly number[]): Uint8Array =>
+    arrayProperty("d", values),
+  int32: (value: number): Uint8Array =>
+    join([encoder.encode("I"), integer(value, 4)]),
+  int32Array: (values: readonly number[]): Uint8Array =>
+    arrayProperty("i", values),
+  int64: (value: number): Uint8Array =>
+    join([encoder.encode("L"), integer(value, 8)]),
+  raw: (value: Uint8Array): Uint8Array =>
+    join([encoder.encode("R"), uint32(value.byteLength), value]),
+  string: (value: string): Uint8Array => {
+    const bytes = encoder.encode(value);
+    return join([encoder.encode("S"), uint32(bytes.byteLength), bytes]);
+  },
+});
+
+function encodeNode(
+  node: FbxBinaryFixtureNode,
+  startOffset: number,
+): Uint8Array {
+  const name = encoder.encode(node.name);
+  const properties = join(node.properties ?? []);
+  const children: Uint8Array[] = [];
+  let cursor = startOffset + 13 + name.byteLength + properties.byteLength;
+  for (const child of node.children ?? []) {
+    const encoded = encodeNode(child, cursor);
+    children.push(encoded);
+    cursor += encoded.byteLength;
+  }
+  const nullRecord = children.length > 0 ? new Uint8Array(13) : new Uint8Array();
+  return join([
+    uint32(cursor + nullRecord.byteLength),
+    uint32(node.properties?.length ?? 0),
+    uint32(properties.byteLength),
+    new Uint8Array([name.byteLength]),
+    name,
+    properties,
+    ...children,
+    nullRecord,
+  ]);
+}
+
+export function encodeBinaryFbxFixture(
+  nodes: readonly FbxBinaryFixtureNode[],
+): Uint8Array {
+  const header = join([
+    encoder.encode("Kaydara FBX Binary  \0"),
+    new Uint8Array([0x1a, 0]),
+    uint32(7400),
+  ]);
+  const encodedNodes: Uint8Array[] = [];
+  let cursor = header.byteLength;
+  for (const node of nodes) {
+    const encoded = encodeNode(node, cursor);
+    encodedNodes.push(encoded);
+    cursor += encoded.byteLength;
+  }
+  return join([header, ...encodedNodes, new Uint8Array(176)]);
+}

package/templates/runtime/model-import/formats/fbx-model-format-adapter.test-fixtures.ts

@@ -0,0 +1,119 @@
+import type { ToolcraftModelSourceBundleTransfer } from "../model-import-types";
+import { GLTF_APPEARANCE_PNG } from "../test-fixtures/gltf-appearance-fixtures";
+import {
+  encodeBinaryFbxFixture,
+  fbxBinaryFixtureProperty as property,
+  type FbxBinaryFixtureNode,
+} from "./fbx-binary-test-fixture-builder";
+
+const encoder = new TextEncoder();
+
+export const ASCII_FBX_FIXTURE = encoder.encode(`; FBX 7.4.0 project file
+FBXHeaderExtension:  {
+	FBXHeaderVersion: 1003
+	FBXVersion: 7400
+}
+GlobalSettings:  {
+	Version: 1000
+	Properties70:  {
+		P: "UpAxis", "int", "Integer", "",1
+		P: "UnitScaleFactor", "double", "Number", "",1
+	}
+}
+Objects:  {
+	Geometry: 1, "Geometry::Triangle", "Mesh" {
+		Vertices: *9 {
+			a: 10,20,30,12,20,30,10,23,30
+		}
+		PolygonVertexIndex: *3 {
+			a: 0,1,-3
+		}
+	}
+	Model: 2, "Model::Triangle", "Mesh" {
+		Version: 232
+		Properties70:  {
+			P: "Lcl Translation", "Lcl Translation", "", "A",0,0,0
+			P: "Lcl Rotation", "Lcl Rotation", "", "A",0,0,0
+			P: "Lcl Scaling", "Lcl Scaling", "", "A",1,1,1
+		}
+		Shading: T
+		Culling: "CullingOff"
+	}
+}
+Connections:  {
+	C: "OO",1,2
+	C: "OO",2,0
+}
+`);
+
+export function createBinaryFbxFixture(): Uint8Array {
+  const geometry: FbxBinaryFixtureNode = {
+    children: [
+      {
+        name: "Vertices",
+        properties: [
+          property.float64Array([10, 20, 30, 12, 20, 30, 10, 23, 30]),
+        ],
+      },
+      {
+        name: "PolygonVertexIndex",
+        properties: [property.int32Array([0, 1, -3])],
+      },
+    ],
+    name: "Geometry",
+    properties: [
+      property.int64(1),
+      property.string("Geometry::Triangle"),
+      property.string("Mesh"),
+    ],
+  };
+  const model: FbxBinaryFixtureNode = {
+    name: "Model",
+    properties: [
+      property.int64(2),
+      property.string("Model::Triangle"),
+      property.string("Mesh"),
+    ],
+  };
+  const connection = (from: number, to: number): FbxBinaryFixtureNode => ({
+    name: "C",
+    properties: [
+      property.string("OO"),
+      property.int64(from),
+      property.int64(to),
+    ],
+  });
+  return encodeBinaryFbxFixture([
+    { children: [geometry, model], name: "Objects" },
+    {
+      children: [connection(1, 2), connection(2, 0)],
+      name: "Connections",
+    },
+  ]);
+}
+
+export function transferForFbx(
+  bytes: Uint8Array<ArrayBufferLike>,
+  includeDiffuseTexture = false,
+): ToolcraftModelSourceBundleTransfer {
+  const ownedBytes = new Uint8Array(bytes.byteLength);
+  ownedBytes.set(bytes);
+  return Object.freeze({
+    aggregateDigest: "fixture-fbx",
+    rootPath: "models/scene.fbx",
+    sourceFiles: Object.freeze([
+      Object.freeze({
+        bytes: ownedBytes.buffer,
+        contentDigest: "fixture-fbx-root",
+        mimeType: "application/octet-stream",
+        path: "models/scene.fbx",
+      }),
+      ...(includeDiffuseTexture ? [Object.freeze({
+        bytes: GLTF_APPEARANCE_PNG.slice().buffer,
+        contentDigest: "fixture-fbx-diffuse",
+        mimeType: "image/png",
+        path: "models/textures/diffuse.png",
+      })] : []),
+    ]),
+  });
+}