three-cad-viewer 4.3.5 → 4.3.7

package/src/utils/decode-instances.ts

@@ -1,233 +0,0 @@
-/**
- * Decode the compressed/instanced shape format.
- *
- * The instanced format wraps a standard Shapes object:
- * ```
- * { instances: [ { vertices: {shape,dtype,buffer,codec}, ... }, ... ],
- *   shapes:    { version, parts, loc, name, id, bb, ... } }
- * ```
- *
- * Each instance contains base64-encoded geometry buffers. Parts reference
- * instances via `"shape": { "ref": N }`. After decoding, the result is a
- * standard Shapes tree with TypedArrays — identical to the existing format.
- */
-import type { Shape, Shapes } from "../core/types.js";
-
-// =============================================================================
-// Types for the encoded format
-// =============================================================================
-
-/** A single base64-encoded buffer entry. */
-interface EncodedBuffer {
-  shape: number[];
-  dtype: "float32" | "int32" | "uint32";
-  buffer: string;
-  codec: "b64";
-}
-
-/** An encoded geometry instance (all 9 buffer fields + optional uvs). */
-interface EncodedInstance {
-  vertices: EncodedBuffer;
-  triangles: EncodedBuffer;
-  normals: EncodedBuffer;
-  edges: EncodedBuffer;
-  obj_vertices: EncodedBuffer;
-  face_types: EncodedBuffer;
-  edge_types: EncodedBuffer;
-  triangles_per_face: EncodedBuffer;
-  segments_per_edge: EncodedBuffer;
-  uvs?: EncodedBuffer;
-}
-
-/** Top-level structure of the instanced format. */
-interface InstancedData {
-  instances: EncodedInstance[];
-  shapes: Shapes;
-}
-
-/** Shape reference (before resolution). */
-interface ShapeRef {
-  ref: number;
-}
-
-// =============================================================================
-// Decoding
-// =============================================================================
-
-/** Maximum decoded buffer size (512 MB). */
-const MAX_BUFFER_BYTES = 512 * 1024 * 1024;
-
-/** Decode a base64 string to a Uint8Array. */
-function fromBase64(b64: string): Uint8Array {
-  const binary = atob(b64);
-  if (binary.length > MAX_BUFFER_BYTES) {
-    throw new Error(
-      `Decoded buffer size ${binary.length} bytes exceeds maximum of ${MAX_BUFFER_BYTES} bytes`,
-    );
-  }
-  const bytes = new Uint8Array(binary.length);
-  for (let i = 0; i < binary.length; i++) {
-    bytes[i] = binary.charCodeAt(i);
-  }
-  return bytes;
-}
-
-/** Decode a single encoded buffer entry to a typed array. */
-function decodeBuffer(buf: EncodedBuffer): Float32Array | Uint32Array {
-  const bytes = fromBase64(buf.buffer);
-  const arrayBuffer = bytes.buffer.slice(
-    bytes.byteOffset,
-    bytes.byteOffset + bytes.byteLength,
-  );
-  switch (buf.dtype) {
-    case "float32":
-      return new Float32Array(arrayBuffer);
-    case "int32":
-    case "uint32":
-      return new Uint32Array(arrayBuffer);
-    default:
-      throw new Error(`Unknown dtype: ${buf.dtype}`);
-  }
-}
-
-/** Decode all buffer fields of an instance into a Shape object. */
-function decodeInstance(inst: EncodedInstance): Shape {
-  const shape: Shape = {
-    vertices: decodeBuffer(inst.vertices) as Float32Array,
-    triangles: decodeBuffer(inst.triangles) as Uint32Array,
-    normals: decodeBuffer(inst.normals) as Float32Array,
-    edges: decodeBuffer(inst.edges) as Float32Array,
-    obj_vertices: decodeBuffer(inst.obj_vertices) as Float32Array,
-    face_types: decodeBuffer(inst.face_types) as Uint32Array,
-    edge_types: decodeBuffer(inst.edge_types) as Uint32Array,
-    triangles_per_face: decodeBuffer(inst.triangles_per_face) as Uint32Array,
-    segments_per_edge: decodeBuffer(inst.segments_per_edge) as Uint32Array,
-  };
-  if (inst.uvs) {
-    shape.uvs = decodeBuffer(inst.uvs) as Float32Array;
-  }
-  return shape;
-}
-
-/** Check if a value is an encoded buffer (inline base64 field). */
-function isEncodedBuffer(val: unknown): val is EncodedBuffer {
-  return (
-    typeof val === "object" &&
-    val !== null &&
-    "buffer" in val &&
-    "dtype" in val &&
-    "codec" in val &&
-    (val as EncodedBuffer).codec === "b64"
-  );
-}
-
-/**
- * Decode any inline encoded buffers on a shape object.
- * Mutates the shape in place, replacing EncodedBuffer fields with TypedArrays.
- */
-function decodeInlineShapeBuffers(shape: Record<string, unknown>): void {
-  for (const key of Object.keys(shape)) {
-    if (isEncodedBuffer(shape[key])) {
-      shape[key] = decodeBuffer(shape[key] as EncodedBuffer);
-    }
-  }
-}
-
-/**
- * Walk the shapes tree and decode any inline encoded buffers found in
- * part.shape objects. This handles edge/vertex-only objects that embed
- * encoded buffers directly (not via instance refs).
- */
-function decodeInlineBuffers(shapes: Shapes): void {
-  if (shapes.parts) {
-    for (const part of shapes.parts) {
-      if (
-        part.shape != null &&
-        typeof part.shape === "object" &&
-        !isShapeRef(part.shape as unknown)
-      ) {
-        decodeInlineShapeBuffers(part.shape as unknown as Record<string, unknown>);
-      }
-      if (part.parts) {
-        decodeInlineBuffers(part);
-      }
-    }
-  }
-}
-
-/** Check if a shape field is an unresolved reference. */
-function isShapeRef(shape: unknown): shape is ShapeRef {
-  return (
-    typeof shape === "object" &&
-    shape !== null &&
-    "ref" in shape &&
-    typeof (shape as ShapeRef).ref === "number"
-  );
-}
-
-/**
- * Recursively walk the shapes tree and replace { ref: N } entries
- * with the corresponding decoded instance.
- *
- * Before decoding, `part.shape` may be `{ ref: N }` which doesn't match
- * the `Shape` type. We use `unknown` casts since this operates on raw
- * (pre-typed) data that is being transformed into the proper type.
- */
-function resolveRefs(shapes: Shapes, decoded: Shape[]): void {
-  if (shapes.parts) {
-    for (const part of shapes.parts) {
-      if (isShapeRef(part.shape as unknown)) {
-        const ref = (part.shape as unknown as ShapeRef).ref;
-        if (ref < 0 || ref >= decoded.length) {
-          throw new Error(
-            `Shape ref ${ref} is out of bounds (${decoded.length} instances decoded)`,
-          );
-        }
-        part.shape = decoded[ref];
-      }
-      if (part.parts) {
-        resolveRefs(part, decoded);
-      }
-    }
-  }
-}
-
-// =============================================================================
-// Public API
-// =============================================================================
-
-/**
- * Type guard: check if data is in the instanced format.
- * Detected by the presence of an `instances` array and a `shapes` object.
- */
-function isInstancedFormat(data: unknown): data is InstancedData {
-  return (
-    typeof data === "object" &&
-    data !== null &&
-    "instances" in data &&
-    Array.isArray((data as InstancedData).instances) &&
-    "shapes" in data &&
-    typeof (data as InstancedData).shapes === "object"
-  );
-}
-
-/**
- * Decode the instanced format into a standard Shapes object.
- *
- * 1. Decode all instance buffers from base64 → TypedArrays
- * 2. Walk the shapes tree and replace { ref: N } with decoded instances
- * 3. Return the unwrapped Shapes object
- */
-function decodeInstancedFormat(data: InstancedData): Shapes {
-  // Decode all instances
-  const decoded = data.instances.map(decodeInstance);
-
-  // Resolve all shape references
-  const shapes = data.shapes;
-  resolveRefs(shapes, decoded);
-
-  return shapes;
-}
-
-export { isInstancedFormat, decodeInstancedFormat, decodeInlineBuffers };
-export type { InstancedData, EncodedBuffer, EncodedInstance };

package/src/utils/font.ts

@@ -1,60 +0,0 @@
-/**
- * Helvetiker font subset - only X, Y, Z glyphs for axis labels.
- * Full font: https://github.com/mrdoob/three.js/blob/dev/examples/fonts/helvetiker_regular.typeface.json
- */
-
-interface Glyph {
-  x_min: number;
-  x_max: number;
-  ha: number;
-  o: string;
-}
-
-export interface FontData {
-  glyphs: Record<string, Glyph>;
-  cssFontWeight?: string;
-  ascender: number;
-  underlinePosition: number;
-  cssFontStyle?: string;
-  boundingBox: { yMin: number; xMin: number; yMax: number; xMax: number };
-  resolution: number;
-  descender: number;
-  familyName: string;
-  lineHeight?: number;
-  underlineThickness: number;
-  original_font_information: Record<string, string>;
-}
-
-export const helvetiker: FontData = {
-  glyphs: {
-    X: {
-      x_min: -0.015625,
-      x_max: 854.15625,
-      ha: 940,
-      o: "m 854 0 l 683 0 l 423 409 l 166 0 l 0 0 l 347 519 l 18 1013 l 186 1013 l 428 637 l 675 1013 l 836 1013 l 504 520 l 854 0 ",
-    },
-    Y: {
-      x_min: 0,
-      x_max: 820,
-      ha: 886,
-      o: "m 820 1013 l 482 416 l 482 0 l 342 0 l 342 416 l 0 1013 l 140 1013 l 411 534 l 679 1012 l 820 1013 ",
-    },
-    Z: {
-      x_min: 0,
-      x_max: 779,
-      ha: 849,
-      o: "m 779 0 l 0 0 l 0 113 l 621 896 l 40 896 l 40 1013 l 779 1013 l 778 887 l 171 124 l 779 124 l 779 0 ",
-    },
-  },
-  cssFontWeight: "normal",
-  ascender: 1189,
-  underlinePosition: -100,
-  cssFontStyle: "normal",
-  boundingBox: { yMin: -334, xMin: -111, yMax: 1189, xMax: 1672 },
-  resolution: 1000,
-  descender: -334,
-  familyName: "Helvetiker",
-  lineHeight: 1522,
-  underlineThickness: 50,
-  original_font_information: {},
-};

package/src/utils/gpu-tracker.ts

@@ -1,265 +0,0 @@
-/**
- * GPU Resource Tracker for three-cad-viewer.
- *
- * Tracks Three.js GPU resources (geometries, materials, textures) to detect memory leaks
- * or inspect current allocations. By default, only maintains counts. Enable debug mode
- * for detailed creation info.
- *
- * @example
- * // Check resource counts
- * import { gpuTracker } from "three-cad-viewer";
- * console.log(gpuTracker.summary);
- * // { geometry: 5, material: 10, texture: 1, total: 16 }
- *
- * @example
- * // Debug mode - see detailed allocation info
- * gpuTracker.enableDebug();
- * // ... create viewer and render objects ...
- * gpuTracker.details(); // Shows what's currently allocated
- * // ... dispose viewer ...
- * gpuTracker.details(); // After dispose, shows any leaks
- */
-
-import { logger } from "./logger.js";
-
-/** Resource types tracked by the GPU tracker */
-export type ResourceType = "geometry" | "material" | "texture";
-
-/** Information about a tracked resource (debug mode only) */
-export interface TrackedResource {
-  /** Type of GPU resource */
-  type: ResourceType;
-  /** Human-readable label for identification */
-  label: string;
-  /** Stack trace at creation time (truncated) */
-  stack: string;
-  /** Timestamp of creation (performance.now()) */
-  timestamp: number;
-}
-
-/** Summary of current resource counts */
-export interface ResourceSummary {
-  geometry: number;
-  material: number;
-  texture: number;
-  total: number;
-}
-
-// Internal state
-const counts: Record<ResourceType, number> = {
-  geometry: 0,
-  material: 0,
-  texture: 0,
-};
-
-let debugMode = false;
-const tracked = new Map<object, TrackedResource>();
-
-/**
- * GPU Resource Tracker.
- *
- * Tracks creation and disposal of Three.js GPU resources to help detect memory leaks.
- * Access via `window.tcv_gpu` in browser console for debugging.
- */
-export const gpuTracker = {
-  /**
-   * Enable debug mode to capture creation info (stack traces, labels).
-   * Call before creating any viewer resources for full tracking.
-   *
-   * Performance impact: Captures stack trace on every resource creation.
-   * Only enable when debugging leaks.
-   */
-  enableDebug(): void {
-    debugMode = true;
-    logger.info("GPU tracker debug mode enabled");
-  },
-
-  /**
-   * Disable debug mode and clear tracked objects.
-   */
-  disableDebug(): void {
-    debugMode = false;
-    tracked.clear();
-    logger.info("GPU tracker debug mode disabled");
-  },
-
-  /**
-   * Check if debug mode is enabled.
-   */
-  get isDebugEnabled(): boolean {
-    return debugMode;
-  },
-
-  /**
-   * Track a GPU resource creation.
-   *
-   * @param type - Resource type (geometry, material, texture)
-   * @param obj - The Three.js object being tracked
-   * @param label - Optional descriptive label (e.g., "front face material for /Assembly/Part1")
-   */
-  track(type: ResourceType, obj: object, label?: string): void {
-    counts[type]++;
-
-    if (debugMode) {
-      // Capture stack trace, skip first 2 lines (Error + this function)
-      const stack = new Error().stack?.split("\n").slice(2, 6).join("\n") ?? "";
-
-      tracked.set(obj, {
-        type,
-        label: label ?? "unlabeled",
-        stack,
-        timestamp: performance.now(),
-      });
-    }
-  },
-
-  /**
-   * Untrack a GPU resource after disposal.
-   *
-   * @param type - Resource type (required in non-debug mode)
-   * @param obj - The Three.js object being untracked (optional in non-debug mode)
-   */
-  untrack(type: ResourceType, obj?: object): void {
-    if (debugMode && obj) {
-      const info = tracked.get(obj);
-      if (info) {
-        counts[info.type]--;
-        tracked.delete(obj);
-        return;
-      }
-      // Object not found - was created before debug mode enabled or before tracking was added
-      // Don't warn, just fall through to decrement (or skip if count is 0)
-    }
-
-    // Non-debug mode or object not found: decrement counter if positive
-    // Silently ignore if count is already 0 (resource wasn't tracked)
-    if (counts[type] > 0) {
-      counts[type]--;
-    }
-  },
-
-  /**
-   * Get current resource counts.
-   */
-  get summary(): ResourceSummary {
-    return {
-      geometry: counts.geometry,
-      material: counts.material,
-      texture: counts.texture,
-      total: counts.geometry + counts.material + counts.texture,
-    };
-  },
-
-  /**
-   * Get all tracked resources (debug mode only).
-   *
-   * @returns Array of currently tracked resources
-   */
-  getResources(): TrackedResource[] {
-    if (!debugMode) {
-      logger.warn("GPU tracker: getResources() requires debug mode - call enableDebug() first");
-      return [];
-    }
-    return Array.from(tracked.values());
-  },
-
-  /**
-   * Get tracked resources grouped by type.
-   */
-  getResourcesByType(): Record<ResourceType, TrackedResource[]> {
-    const resources = this.getResources();
-    return {
-      geometry: resources.filter((r) => r.type === "geometry"),
-      material: resources.filter((r) => r.type === "material"),
-      texture: resources.filter((r) => r.type === "texture"),
-    };
-  },
-
-  /**
-   * Log details of currently tracked resources.
-   * Useful for inspecting allocations or detecting leaks after disposal.
-   * Always outputs to console regardless of logger level.
-   */
-  details(): void {
-    const { total, geometry, material, texture } = this.summary;
-
-    if (total === 0) {
-      console.log("GPU tracker: No resources currently allocated");
-      return;
-    }
-
-    console.log(`GPU tracker: ${total} resources allocated:`);
-    console.log(`  - Geometries: ${geometry}`);
-    console.log(`  - Materials: ${material}`);
-    console.log(`  - Textures: ${texture}`);
-
-    if (debugMode) {
-      const resources = this.getResources();
-      console.log("\nResource details:");
-      resources.forEach((resource, i) => {
-        console.log(`\n[${i + 1}] ${resource.type}: ${resource.label}`);
-        console.log(`    Created at: ${resource.timestamp.toFixed(2)}ms`);
-        console.log(`    Stack:\n${resource.stack}`);
-      });
-    } else {
-      console.log("\nFor detailed resource info, enable debug mode before creating resources:");
-      console.log("  gpuTracker.enableDebug()");
-    }
-  },
-
-  /**
-   * Reset all counters and tracked objects.
-   * Useful for testing or starting fresh.
-   */
-  reset(): void {
-    counts.geometry = 0;
-    counts.material = 0;
-    counts.texture = 0;
-    tracked.clear();
-  },
-
-  /**
-   * Assert that all resources have been disposed.
-   * Useful in tests.
-   *
-   * @throws Error if any resources remain
-   */
-  assertEmpty(): void {
-    const { total } = this.summary;
-    if (total !== 0) {
-      this.details();
-      throw new Error(`GPU tracker: ${total} resources not disposed`);
-    }
-  },
-
-  // Convenience methods for common Three.js types
-
-  /**
-   * Track a geometry and return it (for chaining).
-   */
-  trackGeometry<T extends object>(geometry: T, label?: string): T {
-    this.track("geometry", geometry, label);
-    return geometry;
-  },
-
-  /**
-   * Track a material and return it (for chaining).
-   */
-  trackMaterial<T extends object>(material: T, label?: string): T {
-    this.track("material", material, label);
-    return material;
-  },
-
-  /**
-   * Track a texture and return it (for chaining).
-   */
-  trackTexture<T extends object>(texture: T, label?: string): T {
-    this.track("texture", texture, label);
-    return texture;
-  },
-};
-
-// Expose globally for browser debugging
-if (typeof window !== "undefined") {
-  (window as unknown as { tcv_gpu: typeof gpuTracker }).tcv_gpu = gpuTracker;
-}

package/src/utils/logger.ts

@@ -1,92 +0,0 @@
-/**
- * Minimal logging utility for three-cad-viewer.
- *
- * Provides leveled logging that can be controlled by library consumers.
- * Default level is "warn" (only warnings and errors shown).
- *
- * @example
- * // Library consumer can enable debug output:
- * import { logger } from "three-cad-viewer";
- * logger.setLevel("debug");
- *
- * @example
- * // Silence all logging:
- * logger.setLevel("silent");
- */
-
-/** Available log levels in order of verbosity */
-export type LogLevel = "debug" | "info" | "warn" | "error" | "silent";
-
-const levels: Record<LogLevel, number> = {
-  debug: 0,
-  info: 1,
-  warn: 2,
-  error: 3,
-  silent: 4,
-};
-
-let currentLevel: LogLevel = "warn";
-
-/**
- * Logger instance for three-cad-viewer.
- *
- * Methods: debug, info, warn, error
- * Control: setLevel(), getLevel()
- */
-export const logger = {
-  /**
-   * Set the minimum log level. Messages below this level are suppressed.
-   * @param level - The minimum level to display
-   */
-  setLevel(level: LogLevel): void {
-    currentLevel = level;
-  },
-
-  /**
-   * Get the current log level.
-   * @returns The current minimum log level
-   */
-  getLevel(): LogLevel {
-    return currentLevel;
-  },
-
-  /**
-   * Log debug message (verbose, for development).
-   * Only shown when level is "debug".
-   */
-  debug(...args: unknown[]): void {
-    if (levels[currentLevel] <= levels.debug) {
-      console.log("[three-cad-viewer]", ...args);
-    }
-  },
-
-  /**
-   * Log info message (general information).
-   * Shown when level is "debug" or "info".
-   */
-  info(...args: unknown[]): void {
-    if (levels[currentLevel] <= levels.info) {
-      console.log("[three-cad-viewer]", ...args);
-    }
-  },
-
-  /**
-   * Log warning message (potential issues).
-   * Shown when level is "debug", "info", or "warn".
-   */
-  warn(...args: unknown[]): void {
-    if (levels[currentLevel] <= levels.warn) {
-      console.warn("[three-cad-viewer]", ...args);
-    }
-  },
-
-  /**
-   * Log error message (failures).
-   * Shown unless level is "silent".
-   */
-  error(...args: unknown[]): void {
-    if (levels[currentLevel] <= levels.error) {
-      console.error("[three-cad-viewer]", ...args);
-    }
-  },
-};