dsh-3d-viewer 0.1.0 → 0.2.0

package/src/loaders/workspace.js

@@ -1,295 +0,0 @@
-import { Cache, ImageLoader, Loader, LoadingManager, Texture } from 'three';
-import {
-  ABSOLUTE_PATH,
-  abortError,
-  decodeLocalPath,
-  isLocalPath,
-  mimeOf,
-  warn,
-} from '../bytes.js';
-
-const FILE_ADDRESS_PREFIX = 'dsh-resource://file/';
-// Any relative/absolute local path can be an MTL/FBX texture. Schemes are
-// excluded so data/blob/http URLs keep using Three's normal loaders.
-const WORKSPACE_TEXTURE_PATH = /^(?!data:|blob:|https?:|file:|\/\/).+$/i;
-const TEXTURE_TIMEOUT_MS = 5000;
-
-// 1x1 opaque white PNG, used when a texture exists in the MTL/OBJ but its
-// bytes cannot be read. White keeps the material color visible instead of
-// turning the whole surface black.
-export const WHITE_PIXEL = 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR4nGP4////fwAJ+wP9KobjigAAAABJRU5ErkJggg==';
-
-/** Shared image decoder; a LoadingManager per texture would be wasteful. */
-const IMAGE_LOADER = new ImageLoader(new LoadingManager());
-
-/**
- * Parse a `dsh-resource://file/...` address into its session and path.
- *
- * Mirrors the DSH workspace-path grammar. Query and fragment suffixes are
- * ignored and each path segment is decoded.
- *
- * @param {unknown} address Candidate resource address.
- * @returns {{ scope: 'session', sessionId: string, path: string } | undefined} Parsed session file address.
- */
-export function parseFileAddress(address) {
-  if (typeof address !== 'string' || !address.startsWith(FILE_ADDRESS_PREFIX)) return undefined;
-
-  try {
-    const end = address.search(/[?#]/);
-    const [scope, ...rest] = address.slice(FILE_ADDRESS_PREFIX.length, end === -1 ? undefined : end).split('/');
-    if (scope !== 'session') return undefined;
-    const [id, ...segments] = rest;
-    if (id === undefined || id === '' || segments.length === 0) return undefined;
-    return {
-      scope: 'session',
-      sessionId: decodeURIComponent(id),
-      path: segments.map(decodeURIComponent).join('/'),
-    };
-  } catch {
-    return undefined;
-  }
-}
-
-/**
- * Read a sibling workspace file through the DSH workspace-files Remote.
- *
- * @param {object | undefined} remote Client Remote face.
- * @param {string} address Original document resource address.
- * @param {string} path Workspace-relative or absolute target path.
- * @param {{ baseFile?: string, signal?: AbortSignal }} [options] Base file for relative resolution and cancellation.
- * @returns {Promise<{ ok: true, value: object } | { ok: false, error: { message: string } }>} Remote result.
- */
-export async function readWorkspaceFile(remote, address, path, options = {}) {
-  const parsed = parseFileAddress(address);
-  if (parsed === undefined) {
-    return { ok: false, error: { message: `Not a session file address: ${String(address)}` } };
-  }
-
-  const workspaceFiles = remote?.workspaceFiles;
-  if (workspaceFiles === undefined || typeof workspaceFiles.readBytes !== 'function') {
-    return { ok: false, error: { message: 'The workspaceFiles Remote is unavailable.' } };
-  }
-
-  const request = {};
-  const baseFile = typeof options.baseFile === 'string' && options.baseFile !== ''
-    ? options.baseFile
-    : parsed.path;
-  if (baseFile !== '') request.baseFile = baseFile;
-
-  try {
-    return await workspaceFiles.readBytes(parsed.sessionId, path.replaceAll('\\', '/'), request, options.signal);
-  } catch (error) {
-    return {
-      ok: false,
-      error: { message: error instanceof Error ? error.message : String(error) },
-    };
-  }
-}
-
-/**
- * Read a workspace asset, retrying the basename of an unreadable absolute path.
- *
- * FBX/OBJ/MTL exporters commonly bake in the authoring machine's absolute
- * path. When that path does not exist in the session, the file usually sits
- * next to the model, so the basename is tried before giving up.
- *
- * @param {(path: string) => Promise<object | undefined>} readFile Reads one workspace path.
- * @param {string} path Raw or normalized asset path.
- * @returns {Promise<object | undefined>} The first successful read result.
- */
-export async function readWithBasenameFallback(readFile, path) {
-  const result = await readFile(path);
-  if (result !== undefined && result.ok === true) return result;
-
-  const normalized = String(path).replaceAll('\\', '/');
-  if (!ABSOLUTE_PATH.test(normalized)) return result;
-
-  const basename = normalized.slice(normalized.lastIndexOf('/') + 1);
-  if (basename === '' || basename === normalized) return result;
-  return readFile(basename);
-}
-
-/**
- * Load one image URL into a Texture placeholder.
- *
- * @param {Texture} texture Placeholder returned synchronously to Three.js.
- * @param {string} url Image URL.
- * @param {AbortSignal | undefined} signal Cancellation signal.
- * @returns {Promise<void>} Resolves when the image is assigned.
- */
-function loadImage(texture, url, signal) {
-  return new Promise((resolve, reject) => {
-    if (signal?.aborted === true) {
-      reject(abortError('Texture loading was cancelled.'));
-      return;
-    }
-
-    IMAGE_LOADER.load(url, (image) => {
-      texture.image = image;
-      texture.needsUpdate = true;
-      resolve();
-    }, undefined, reject);
-  });
-}
-
-/**
- * A Three.js loader that resolves MTL/OBJ/FBX texture paths through the DSH
- * workspace instead of HTTP.
- *
- * It returns a Texture immediately, like TextureLoader, and assigns the image
- * when the workspace read and browser decode finish. Missing files fall back
- * to a white pixel so the material color remains visible.
- */
-class WorkspaceTextureLoader extends Loader {
-  constructor(manager, options) {
-    super(manager);
-    this.readFile = options.readFile;
-    this.signal = options.signal;
-    this.onWarn = options.onWarn;
-    this.pending = options.pending;
-    this.blobUrls = options.blobUrls;
-    this.listeners = options.listeners;
-    this.disposed = options.isDisposed;
-  }
-
-  load(url, onLoad, onProgress, onError) {
-    const texture = new Texture();
-    texture.name = url;
-
-    const task = (async () => {
-      let blobUrl = null;
-      try {
-        if (this.signal?.aborted === true || this.disposed?.() === true) {
-          throw abortError('Texture loading was cancelled.');
-        }
-
-        let imageUrl = url;
-        if (isLocalPath(url)) {
-          const path = decodeLocalPath(url);
-          const result = await readWithBasenameFallback(this.readFile, path);
-          if (result === undefined || result.ok !== true) {
-            throw new Error(result?.error?.message ?? `Could not read texture ${url}`);
-          }
-          if (this.signal?.aborted === true || this.disposed?.() === true) {
-            throw abortError('Texture loading was cancelled.');
-          }
-
-          blobUrl = URL.createObjectURL(new Blob([result.value.data], { type: mimeOf(path) }));
-          this.blobUrls.add(blobUrl);
-          imageUrl = blobUrl;
-        }
-
-        await loadImage(texture, imageUrl, this.signal);
-        onLoad?.(texture);
-      } catch (error) {
-        if (blobUrl !== null && this.blobUrls.has(blobUrl)) {
-          URL.revokeObjectURL(blobUrl);
-          this.blobUrls.delete(blobUrl);
-        }
-        if (this.signal?.aborted !== true && this.disposed?.() !== true) {
-          this.onWarn?.(`[dsh-3d-viewer] Could not load texture "${url}": ${String(error)}`);
-          try {
-            await loadImage(texture, WHITE_PIXEL, this.signal);
-          } catch {
-            // Keep the empty placeholder when even the fallback cannot decode.
-          }
-          onLoad?.(texture);
-          onError?.(error);
-        }
-      } finally {
-        for (const listener of this.listeners) {
-          try {
-            listener(texture);
-          } catch {
-            // A render request must never break texture loading.
-          }
-        }
-      }
-    })();
-
-    this.pending.add(task);
-    task.then(
-      () => this.pending.delete(task),
-      () => this.pending.delete(task),
-    );
-    return texture;
-  }
-}
-
-/**
- * Create a workspace-backed asset loader and its Three.js LoadingManager.
- *
- * @param {{
- *   readFile: (path: string) => Promise<object | undefined>,
- *   signal?: AbortSignal,
- *   onWarn?: (message: string) => void,
- * }} options Workspace reader, cancellation, and diagnostics.
- * @returns {{
- *   manager: LoadingManager,
- *   settle: (timeout?: number) => Promise<void>,
- *   onTextureLoad: (listener: (texture: Texture) => void) => () => void,
- *   dispose: () => void,
- * }} Asset loader controls.
- */
-export function createWorkspaceAssetLoader({ readFile, signal, onWarn = warn }) {
-  const pending = new Set();
-  const blobUrls = new Set();
-  const listeners = new Set();
-  let disposed = false;
-
-  const manager = new LoadingManager();
-  const textureLoader = new WorkspaceTextureLoader(manager, {
-    readFile,
-    signal,
-    onWarn,
-    pending,
-    blobUrls,
-    listeners,
-    isDisposed: () => disposed,
-  });
-  manager.addHandler(WORKSPACE_TEXTURE_PATH, textureLoader);
-
-  async function settle(timeout = TEXTURE_TIMEOUT_MS) {
-    if (pending.size === 0) return;
-    if (signal?.aborted === true) return;
-
-    let timer;
-    let stopWaiting;
-    const timeoutPromise = new Promise((resolve) => {
-      timer = setTimeout(resolve, timeout);
-    });
-    const abortPromise = new Promise((resolve) => {
-      stopWaiting = resolve;
-      signal?.addEventListener('abort', resolve, { once: true });
-    });
-    try {
-      await Promise.race([Promise.allSettled([...pending]), timeoutPromise, abortPromise]);
-    } finally {
-      clearTimeout(timer);
-      signal?.removeEventListener('abort', stopWaiting);
-    }
-  }
-
-  function onTextureLoad(listener) {
-    listeners.add(listener);
-    return () => listeners.delete(listener);
-  }
-
-  function dispose() {
-    if (disposed) return;
-    disposed = true;
-    for (const url of blobUrls) {
-      Cache.remove(`image:${url}`);
-      URL.revokeObjectURL(url);
-    }
-    blobUrls.clear();
-    listeners.clear();
-  }
-
-  return {
-    manager,
-    settle,
-    onTextureLoad,
-    dispose,
-  };
-}

package/src/model.js

@@ -1,417 +0,0 @@
-import {
-  Box3,
-  DoubleSide,
-  Mesh,
-  MeshStandardMaterial,
-  Vector3,
-} from 'three';
-import { STLLoader } from 'three/addons/loaders/STLLoader.js';
-import { OBJLoader } from 'three/addons/loaders/OBJLoader.js';
-import { decodeText, toArrayBuffer, warn } from './bytes.js';
-import { FBXLoader } from './vendor/FBXLoaderPbr.js';
-
-/**
- * Parse one complete FBX file with Three.js.
- *
- * Texture loads are asynchronous and optional. A missing sidecar texture
- * must not reject a model whose geometry is perfectly readable, so the
- * loading manager only logs those failures and the scene is returned as
- * soon as its graph exists.
- *
- * @param {Uint8Array | ArrayBuffer} data Complete file bytes.
- * @returns {import('three').Object3D} The parsed FBX scene graph.
- */
-export function parseFbxBytes(data) {
-  const loader = new FBXLoader();
-  loader.manager.onError = (url) => {
-    // Deliberately non-fatal: embedded materials and geometry still render.
-    warn(`[dsh-3d-viewer] Could not load a referenced FBX texture: ${url}`);
-  };
-  return loader.parse(toArrayBuffer(data), '');
-}
-
-/**
- * Parse one complete OBJ file with Three.js.
- *
- * OBJ is a text format, so the preview bytes are decoded as UTF-8 first.
- * `.mtl` sidecars and external textures are not available to the document
- * preview; the loader falls back to default materials while preserving
- * `usemtl` names and vertex colors.
- *
- * @param {Uint8Array | ArrayBuffer | string} data Complete file bytes or decoded text.
- * @returns {import('three').Group} The parsed OBJ scene graph.
- */
-export function parseObjBytes(data) {
-  const loader = new OBJLoader();
-  loader.manager.onError = (url) => {
-    warn(`[dsh-3d-viewer] Could not load a referenced OBJ resource: ${url}`);
-  };
-  return loader.parse(decodeText(data));
-}
-
-/**
- * Parse one complete STL file (ASCII or binary) into a single mesh.
- *
- * STL has no material library or scene hierarchy, so a neutral double-sided
- * PBR material is assigned. Binary STL vertex colors are retained when present.
- *
- * @param {Uint8Array | ArrayBuffer | string} data Complete STL bytes or text.
- * @returns {import('three').Mesh} The parsed STL mesh.
- */
-export function parseStlBytes(data) {
-  const geometry = new STLLoader().parse(toArrayBuffer(data));
-  if (geometry.getAttribute('normal') === undefined) geometry.computeVertexNormals();
-  const hasColors = geometry.hasColors === true;
-  const material = new MeshStandardMaterial({
-    name: 'STL',
-    color: hasColors ? 0xffffff : 0xc9c9c9,
-    metalness: 0,
-    roughness: 0.8,
-    side: DoubleSide,
-    vertexColors: hasColors,
-  });
-  const mesh = new Mesh(geometry, material);
-  mesh.name = 'STL';
-  mesh.animations = [];
-  return mesh;
-}
-
-/**
- * Synchronous parsers for the formats that have no external resources.
- *
- * glTF/GLB is deliberately absent: it needs the asynchronous workspace loader
- * from `loaders/model-loader.js`, so it cannot be parsed here.
- */
-const SYNC_PARSERS = Object.freeze({
-  fbx: parseFbxBytes,
-  obj: parseObjBytes,
-  stl: parseStlBytes,
-});
-
-/**
- * Parse a preview according to the registered document format.
- *
- * @param {Uint8Array | ArrayBuffer | string} data Complete file bytes or decoded text.
- * @param {'fbx' | 'obj' | 'stl'} format Document format.
- * @returns {import('three').Object3D} Parsed scene graph.
- */
-export function parseModelBytes(data, format) {
-  if (!Object.hasOwn(SYNC_PARSERS, format)) {
-    throw new TypeError(`Unsupported 3D model format: ${String(format)}`);
-  }
-  return SYNC_PARSERS[format](data);
-}
-
-/** Normalized bits used when a position component is NaN. */
-const NAN_BITS = 0x7fc00000;
-
-/**
- * Hash three IEEE-754 float bit patterns into one 32-bit bucket key.
- *
- * @param {number} x X bits.
- * @param {number} y Y bits.
- * @param {number} z Z bits.
- * @returns {number} 32-bit hash.
- */
-function hashPosition(x, y, z) {
-  let hash = Math.imul(x ^ 0x9e3779b9, 0x85ebca6b);
-  hash = Math.imul(hash ^ y, 0xc2b2ae35);
-  hash = Math.imul(hash ^ z, 0x27d4eb2f);
-  return hash ^ (hash >>> 15);
-}
-
-/**
- * Compare two vertices of a non-interleaved Float32 position attribute.
- *
- * @param {Float32Array} array Position storage.
- * @param {number} a First vertex index.
- * @param {number} b Second vertex index.
- * @returns {boolean} True when the positions are identical (NaN equals NaN).
- */
-function samePosition(array, a, b) {
-  const ao = a * 3;
-  const bo = b * 3;
-  for (let component = 0; component < 3; component += 1) {
-    const left = array[ao + component];
-    const right = array[bo + component];
-    if (left === right) continue;
-    if (left !== left && right !== right) continue;
-    return false;
-  }
-  return true;
-}
-
-/**
- * Count distinct positions without allocating one string per vertex.
- *
- * FBX exporters commonly split a shared vertex by normal or UV seam, so
- * deduplicating by exact position keeps the HUD count meaningful.
- *
- * @param {Float32Array} array Position storage.
- * @param {number} count Number of vertices.
- * @returns {number} Distinct position count.
- */
-function countUniqueFloat32(array, count) {
-  const bits = new Uint32Array(array.buffer, array.byteOffset, array.length);
-  const buckets = new Map();
-  let unique = 0;
-
-  for (let index = 0; index < count; index += 1) {
-    const offset = index * 3;
-    const x = array[offset];
-    const y = array[offset + 1];
-    const z = array[offset + 2];
-    const xBits = x === 0 ? 0 : (x !== x ? NAN_BITS : bits[offset]);
-    const yBits = y === 0 ? 0 : (y !== y ? NAN_BITS : bits[offset + 1]);
-    const zBits = z === 0 ? 0 : (z !== z ? NAN_BITS : bits[offset + 2]);
-    const key = hashPosition(xBits, yBits, zBits);
-    const bucket = buckets.get(key);
-
-    if (bucket === undefined) {
-      buckets.set(key, index);
-      unique += 1;
-      continue;
-    }
-
-    if (typeof bucket === 'number') {
-      if (samePosition(array, bucket, index)) continue;
-      buckets.set(key, [bucket, index]);
-      unique += 1;
-      continue;
-    }
-
-    let found = false;
-    for (let candidate = 0; candidate < bucket.length; candidate += 1) {
-      if (samePosition(array, bucket[candidate], index)) {
-        found = true;
-        break;
-      }
-    }
-    if (!found) {
-      bucket.push(index);
-      unique += 1;
-    }
-  }
-
-  return unique;
-}
-
-/**
- * Count distinct positions for any BufferAttribute.
- *
- * The fast path avoids string allocation for the common non-interleaved
- * Float32 position attribute; interleaved or non-float attributes fall back
- * to exact key strings.
- *
- * @param {import('three').BufferAttribute | import('three').InterleavedBufferAttribute} position Position attribute.
- * @returns {number} Distinct position count.
- */
-function countUniquePositions(position) {
-  const count = position.count;
-  if (count <= 0) return 0;
-
-  if (position.itemSize === 3
-    && position.array instanceof Float32Array
-    && position.isInterleavedBufferAttribute !== true) {
-    return countUniqueFloat32(position.array, count);
-  }
-
-  const seen = new Set();
-  for (let index = 0; index < count; index += 1) {
-    seen.add(`${position.getX(index)},${position.getY(index)},${position.getZ(index)}`);
-  }
-  return seen.size;
-}
-
-/**
- * Add every material reachable from one mesh to the shared set.
- *
- * @param {unknown} material Mesh material or material array.
- * @param {Set<object>} materials Accumulating material set.
- */
-function collectMaterials(material, materials) {
-  if (Array.isArray(material)) {
-    for (const entry of material) {
-      if (entry !== undefined && entry !== null) materials.add(entry);
-    }
-  } else if (material !== undefined && material !== null) {
-    materials.add(material);
-  }
-}
-
-/**
- * Collect the values the HUD and the camera fit need from one parsed graph.
- *
- * Vertices are measured per mesh by distinct position, then summed across
- * meshes. This keeps the count meaningful for FBX exports that split vertices
- * by normal or UV seam instead of sharing an index buffer.
- *
- * The graph is walked once, carrying visibility down the tree, so an invisible
- * branch costs one check instead of one ancestor scan per descendant.
- *
- * @param {import('three').Object3D} object Parsed model graph.
- * @returns {{
- *   meshes: number,
- *   renderables: number,
- *   vertices: number,
- *   triangles: number,
- *   materials: number,
- *   box: Box3,
- *   size: Vector3,
- *   center: Vector3,
- *   maxDimension: number,
- * }} Mesh counts and a world-space bounding volume.
- */
-export function collectModelStats(object) {
-  object.updateMatrixWorld(true);
-  const box = new Box3();
-  const size = new Vector3();
-  const center = new Vector3();
-  const scratch = new Box3();
-
-  let meshes = 0;
-  let renderables = 0;
-  let vertices = 0;
-  let triangles = 0;
-  const materials = new Set();
-
-  /** @param {import('three').Object3D} node */
-  const visit = (node) => {
-    if (node.visible === false) return;
-
-    const geometry = node.geometry;
-    if (geometry !== undefined && geometry !== null) {
-      const isMesh = node.isMesh === true;
-      const isLine = node.isLine === true;
-      const isPoints = node.isPoints === true;
-
-      if (isMesh || isLine || isPoints) {
-        renderables += 1;
-        geometry.computeBoundingBox();
-        if (geometry.boundingBox !== null) {
-          box.union(scratch.copy(geometry.boundingBox).applyMatrix4(node.matrixWorld));
-        }
-
-        if (isMesh) {
-          meshes += 1;
-          const position = geometry.getAttribute('position');
-          if (position !== undefined && position.count > 0) {
-            vertices += countUniquePositions(position);
-            const index = geometry.getIndex();
-            triangles += Math.floor((index === null ? position.count : index.count) / 3);
-          }
-          collectMaterials(node.material, materials);
-        }
-      }
-    }
-
-    const children = node.children;
-    for (let index = 0; index < children.length; index += 1) visit(children[index]);
-  };
-
-  visit(object);
-
-  box.getSize(size);
-  box.getCenter(center);
-
-  return {
-    meshes,
-    renderables,
-    vertices,
-    triangles,
-    materials: materials.size,
-    box,
-    size,
-    center,
-    maxDimension: Math.max(size.x, size.y, size.z),
-  };
-}
-
-/**
- * Remove lights, cameras, and audio nodes that belong to the source file.
- *
- * FBX and glTF documents can carry their own lights and cameras. The preview
- * supplies its own lighting and camera, so embedded ones would double-light
- * the model or leave stray nodes in the graph.
- *
- * @param {import('three').Object3D} root Parsed scene graph.
- * @returns {number} Number of removed nodes.
- */
-export function stripEmbeddedSceneNodes(root) {
-  const embedded = [];
-  root.traverse((child) => {
-    if (child.isLight === true || child.isCamera === true || child.isAudio === true) {
-      embedded.push(child);
-    }
-  });
-
-  for (const node of embedded) {
-    node.removeFromParent();
-    node.dispose?.();
-  }
-  return embedded.length;
-}
-
-/**
- * Dispose every geometry, material, texture, skeleton, and embedded Blob URL
- * reachable from one graph. Shared resources are released once.
- *
- * @param {import('three').Object3D} root Parsed graph or whole scene.
- */
-export function disposeObject(root) {
-  const geometries = new Set();
-  const materials = new Set();
-  const textures = new Set();
-  const skeletons = new Set();
-  const blobUrls = new Set();
-
-  root.traverse((child) => {
-    if (child.geometry !== undefined && child.geometry !== null) {
-      geometries.add(child.geometry);
-    }
-    if (child.isSkinnedMesh === true && child.skeleton !== undefined && child.skeleton !== null) {
-      skeletons.add(child.skeleton);
-    }
-
-    const material = child.material;
-    if (material === undefined || material === null) return;
-
-    for (const entry of Array.isArray(material) ? material : [material]) {
-      if (entry === undefined || entry === null) continue;
-      materials.add(entry);
-
-      for (const value of Object.values(entry)) {
-        if (value === null || typeof value !== 'object') continue;
-        if (value.isTexture === true) {
-          textures.add(value);
-        } else if (Array.isArray(value)) {
-          for (const nested of value) {
-            if (nested !== null && typeof nested === 'object' && nested.isTexture === true) {
-              textures.add(nested);
-            }
-          }
-        }
-      }
-    }
-  });
-
-  for (const texture of textures) {
-    const source = texture.image?.src;
-    if (typeof source === 'string' && source.startsWith('blob:')) blobUrls.add(source);
-    texture.dispose();
-  }
-
-  if (typeof URL.revokeObjectURL === 'function') {
-    for (const url of blobUrls) {
-      try {
-        URL.revokeObjectURL(url);
-      } catch {
-        // A URL already released by the browser is harmless.
-      }
-    }
-  }
-
-  for (const skeleton of skeletons) skeleton.dispose();
-  for (const material of materials) material.dispose();
-  for (const geometry of geometries) geometry.dispose();
-}