dsh-3d-viewer 0.1.0 → 0.2.0

package/src/scene/animation.js

@@ -1,149 +0,0 @@
-import { AnimationMixer, LoopRepeat } from 'three';
-
-const NOTIFY_INTERVAL_MS = 33;
-
-/**
- * Drive the FBX animation clips without coupling playback state to React.
- *
- * Only the first clip is prepared at construction; it starts paused so the
- * caller decides when playback begins. Progress notifications are throttled
- * to roughly 30 Hz and are emitted only while the mixer is actually running.
- *
- * @param {import('three').Object3D} object Parsed FBX graph.
- * @param {{ onTick?: (state: { time: number, duration: number, index: number, playing: boolean }) => void }} [options] Progress callback.
- * @returns {{
- *   animations: Array<{ name: string, duration: number }>,
- *   setPlaying: (enabled: boolean) => boolean,
- *   setClip: (index: number) => boolean,
- *   seek: (seconds: number) => boolean,
- *   update: (delta: number, timestamp: number) => void,
- *   snapshot: () => { time: number, duration: number, index: number, playing: boolean },
- *   isPlaying: () => boolean,
- *   dispose: () => void,
- * }} Animation controls.
- */
-export function createAnimationController(object, { onTick } = {}) {
-  const clips = Array.isArray(object.animations)
-    ? object.animations.filter((clip) => Number.isFinite(clip.duration)
-      && clip.duration > 0
-      && clip.tracks.length > 0)
-    : [];
-  const animations = clips.map((clip) => ({ name: clip.name, duration: clip.duration }));
-  const mixer = clips.length > 0 ? new AnimationMixer(object) : null;
-  const actions = [];
-  let index = 0;
-  let playing = false;
-  let lastNotify = -Infinity;
-  let disposed = false;
-
-  if (mixer !== null) {
-    for (const clip of clips) {
-      const action = mixer.clipAction(clip);
-      action.setLoop(LoopRepeat, Infinity);
-      action.clampWhenFinished = false;
-      actions.push(action);
-    }
-
-    const first = actions[0];
-    first.reset().play();
-    first.paused = true;
-    mixer.update(0);
-  }
-
-  function currentAction() {
-    return actions[index];
-  }
-
-  function currentDuration() {
-    const action = currentAction();
-    return action === undefined ? 0 : action.getClip().duration;
-  }
-
-  function currentTime() {
-    const action = currentAction();
-    return action === undefined ? 0 : action.time;
-  }
-
-  function snapshot() {
-    return { time: currentTime(), duration: currentDuration(), index, playing };
-  }
-
-  function emit() {
-    if (disposed || typeof onTick !== 'function') return;
-    onTick(snapshot());
-  }
-
-  function update(delta, timestamp) {
-    if (disposed || mixer === null || !playing) return;
-
-    mixer.update(delta);
-    if (timestamp - lastNotify >= NOTIFY_INTERVAL_MS) {
-      lastNotify = timestamp;
-      emit();
-    }
-  }
-
-  function setPlaying(enabled) {
-    if (disposed || mixer === null) return false;
-
-    const next = Boolean(enabled);
-    if (next === playing) return false;
-
-    playing = next;
-    const action = currentAction();
-    if (action !== undefined) action.paused = !playing;
-    lastNotify = -Infinity;
-    emit();
-    return true;
-  }
-
-  function setClip(nextIndex) {
-    if (disposed || mixer === null) return false;
-    if (!Number.isInteger(nextIndex) || nextIndex < 0 || nextIndex >= actions.length) return false;
-
-    index = nextIndex;
-    for (const action of actions) action.stop();
-    const action = actions[index];
-    action.reset().play();
-    action.paused = !playing;
-    mixer.update(0);
-    lastNotify = -Infinity;
-    emit();
-    return true;
-  }
-
-  function seek(seconds) {
-    if (disposed || mixer === null) return false;
-
-    const action = currentAction();
-    if (action === undefined) return false;
-
-    const duration = action.getClip().duration;
-    const next = Number(seconds);
-    action.time = Math.max(0, Math.min(duration, Number.isFinite(next) ? next : 0));
-    mixer.update(0);
-    lastNotify = -Infinity;
-    emit();
-    return true;
-  }
-
-  function dispose() {
-    if (disposed) return;
-    disposed = true;
-    if (mixer !== null) {
-      mixer.stopAllAction();
-      mixer.uncacheRoot(object);
-    }
-  }
-
-  return {
-    animations,
-    setPlaying,
-    setClip,
-    seek,
-    update,
-    snapshot,
-    isPlaying: () => playing,
-    dispose,
-  };
-}

package/src/scene/blue-noise.js

@@ -1,48 +0,0 @@
-import {
-  DataTexture,
-  NearestFilter,
-  NoColorSpace,
-  RedFormat,
-  RepeatWrapping,
-  UnsignedByteType,
-} from 'three';
-import { decodeBase64 } from '../bytes.js';
-
-/** Edge length of the embedded 8-bit blue-noise mask. */
-export const BLUE_NOISE_SIZE = 64;
-
-// Generated offline from an isotropic high-pass random field, then rank-normalized
-// to a uniform 0..1 distribution. The mask has most of its energy above the
-// low-frequency band, which keeps dithering visually even without a visible
-// repeating pattern.
-const BLUE_NOISE_BASE64 = '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';
-
-/** Decoded mask, shared by every viewer on the page. */
-let blueNoiseBytes = null;
-
-/**
- * Create the repeating blue-noise texture used by the post-processing dither.
- *
- * The mask is decoded once and wrapped in a per-composer GPU texture.
- *
- * @returns {import('three').DataTexture} Nearest-filtered blue-noise mask.
- */
-export function createBlueNoiseTexture() {
-  blueNoiseBytes ??= decodeBase64(BLUE_NOISE_BASE64);
-  const texture = new DataTexture(
-    blueNoiseBytes,
-    BLUE_NOISE_SIZE,
-    BLUE_NOISE_SIZE,
-    RedFormat,
-    UnsignedByteType,
-  );
-  texture.name = 'dsh3dv-blue-noise';
-  texture.colorSpace = NoColorSpace;
-  texture.wrapS = RepeatWrapping;
-  texture.wrapT = RepeatWrapping;
-  texture.magFilter = NearestFilter;
-  texture.minFilter = NearestFilter;
-  texture.generateMipmaps = false;
-  texture.needsUpdate = true;
-  return texture;
-}

package/src/scene/camera.js

@@ -1,83 +0,0 @@
-import { Spherical, Vector3 } from 'three';
-
-const FIT_DIRECTION = new Vector3(1, 0.55, 1.3).normalize();
-const KEY_STEP = Math.PI / 36;
-const _offset = new Vector3();
-const _spherical = new Spherical();
-
-/**
- * Keep the near/far planes proportional to the current orbit distance so the
- * grid's projection-depth fog stays stable across zoom levels.
- *
- * @param {import('three').PerspectiveCamera} camera Active camera.
- * @param {number} distance Camera-to-target distance.
- * @param {number} maxDimension Largest model dimension.
- */
-export function updateClipPlanes(camera, distance, maxDimension) {
-  const near = Math.max(distance / 500, maxDimension / 10000, 0.0001);
-  const far = Math.max(distance * 40, maxDimension * 20);
-  if (camera.near === near && camera.far === far) return;
-
-  camera.near = near;
-  camera.far = far;
-  camera.updateProjectionMatrix();
-}
-
-/**
- * Frame the model from a three-quarter view and set orbit limits.
- *
- * @param {import('three').PerspectiveCamera} camera Active camera.
- * @param {import('three').OrbitControls} controls Orbit controls.
- * @param {ReturnType<import('../model.js').collectModelStats>} stats Model bounds.
- * @param {number} maxDimension Largest model dimension.
- * @returns {number} Camera-to-target distance.
- */
-export function frameModel(camera, controls, stats, maxDimension) {
-  const fov = (camera.fov * Math.PI) / 180;
-  const aspect = camera.aspect > 0 ? camera.aspect : 1;
-  const fitHeight = stats.size.y / (2 * Math.tan(fov / 2));
-  const fitWidth = stats.size.x / (2 * Math.tan(fov / 2) * aspect);
-  const fitDepth = stats.size.z * 0.8;
-  let distance = Math.max(fitHeight, fitWidth, fitDepth) * 2.5;
-  if (!Number.isFinite(distance) || distance <= 0) distance = maxDimension * 2.5;
-  distance = Math.max(distance, maxDimension * 0.9);
-
-  camera.position.copy(stats.center).addScaledVector(FIT_DIRECTION, distance);
-  controls.target.copy(stats.center);
-  controls.minDistance = Math.max(distance * 0.02, maxDimension * 0.03);
-  controls.maxDistance = Math.max(distance * 30, maxDimension * 10);
-  controls.update();
-  return distance;
-}
-
-/**
- * Whether a key is handled by the orbit keyboard controls.
- *
- * @param {string} key KeyboardEvent.key value.
- * @returns {boolean} True for the four arrow keys.
- */
-export function isOrbitKey(key) {
-  return key === 'ArrowLeft' || key === 'ArrowRight' || key === 'ArrowUp' || key === 'ArrowDown';
-}
-
-/**
- * Orbit the camera by one keyboard step.
- *
- * @param {import('three').PerspectiveCamera} camera Active camera.
- * @param {import('three').OrbitControls} controls Orbit controls.
- * @param {string} key KeyboardEvent.key value.
- */
-export function orbitByKey(camera, controls, key) {
-  _offset.copy(camera.position).sub(controls.target);
-  _spherical.setFromVector3(_offset);
-
-  if (key === 'ArrowLeft') _spherical.theta += KEY_STEP;
-  else if (key === 'ArrowRight') _spherical.theta -= KEY_STEP;
-  else if (key === 'ArrowUp') _spherical.phi = Math.max(controls.minPolarAngle, _spherical.phi - KEY_STEP);
-  else if (key === 'ArrowDown') _spherical.phi = Math.min(controls.maxPolarAngle, _spherical.phi + KEY_STEP);
-  else return;
-
-  camera.position.copy(controls.target).add(_offset.setFromSpherical(_spherical));
-  camera.lookAt(controls.target);
-  controls.update();
-}

package/src/scene/createSceneView.js

@@ -1,375 +0,0 @@
-import {
-  ACESFilmicToneMapping,
-  PCFSoftShadowMap,
-  PerspectiveCamera,
-  Scene,
-  SRGBColorSpace,
-  WebGLRenderer,
-} from 'three';
-import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
-import { disposeObject } from '../model.js';
-import { createAnimationController } from './animation.js';
-import { frameModel, isOrbitKey, orbitByKey, updateClipPlanes } from './camera.js';
-import { DEFAULT_ENVIRONMENT, createEnvironment } from './environment.js';
-import { createGround } from './ground.js';
-import { createLighting } from './lighting.js';
-import { createMaterialController } from './materials.js';
-import { createPostProcessing } from './postprocessing.js';
-import { createRenderLoop } from './render-loop.js';
-import { ViewerError } from './viewer-error.js';
-
-const MAX_PIXEL_RATIO = 2;
-
-/** Device pixel ratio, clamped so 4K/5K displays do not quadruple the cost. */
-function readPixelRatio() {
-  return Math.min(globalThis.devicePixelRatio || 1, MAX_PIXEL_RATIO);
-}
-
-/**
- * Attach a disposable, orbitable Three.js view to a host element.
- *
- * The renderer is transparent so the host's themed background stays visible.
- * Frames render on demand; only auto-rotate or animation keeps a continuous
- * loop, and that loop pauses while the viewer is off-screen or the page is
- * hidden.
- *
- * @param {HTMLElement} host Element that will own the canvas.
- * @param {import('three').Object3D} object Parsed FBX graph.
- * @param {ReturnType<import('../model.js').collectModelStats>} stats Model bounds and counts.
- * @param {{ ariaLabel?: string, environment?: string }} [options] Localized accessibility text and initial IBL environment.
- * @returns {{
- *   animations: Array<{ name: string, duration: number }>,
- *   subscribeAnimation: (listener: (state: { time: number, duration: number, index: number, playing: boolean }) => void) => () => void,
- *   setAnimationPlaying: (enabled: boolean) => void,
- *   setAnimationClip: (index: number) => void,
- *   seekAnimation: (seconds: number) => void,
- *   setAutoRotate: (enabled: boolean) => boolean,
- *   setGrid: (visible: boolean) => boolean,
- *   setEnvironment: (id: string) => boolean,
- *   setMaterialPreset: (id: string) => boolean,
- *   setWireframe: (enabled: boolean) => boolean,
- *   reset: () => void,
- *   invalidate: () => void,
- *   dispose: () => void,
- * }} View controls.
- */
-export function createSceneView(host, object, stats, options = {}) {
-  let renderer;
-  try {
-    renderer = new WebGLRenderer({
-      alpha: true,
-      antialias: true,
-      powerPreference: 'high-performance',
-    });
-  } catch (error) {
-    throw new ViewerError('webgl', 'A WebGL context could not be created.', error);
-  }
-
-  const canvas = renderer.domElement;
-  canvas.className = 'dsh3dv-canvas';
-  canvas.dataset.dsh3dCanvas = '';
-  canvas.tabIndex = 0;
-  canvas.setAttribute('role', 'img');
-  canvas.setAttribute('aria-label', options.ariaLabel ?? '3D model');
-  canvas.style.touchAction = 'none';
-  host.appendChild(canvas);
-
-  const initialWidth = Math.max(host.clientWidth, 1);
-  const initialHeight = Math.max(host.clientHeight, 1);
-  const initialPixelRatio = readPixelRatio();
-
-  renderer.setPixelRatio(initialPixelRatio);
-  renderer.setSize(initialWidth, initialHeight, false);
-  renderer.outputColorSpace = SRGBColorSpace;
-  renderer.toneMapping = ACESFilmicToneMapping;
-  renderer.toneMappingExposure = 1.0;
-  renderer.setClearColor(0x000000, 0);
-  renderer.shadowMap.enabled = true;
-  renderer.shadowMap.type = PCFSoftShadowMap;
-
-  const scene = new Scene();
-  const camera = new PerspectiveCamera(38, initialWidth / initialHeight, 0.1, 1000);
-  const maxDimension = stats.maxDimension > 0 ? stats.maxDimension : 1;
-
-  const environment = createEnvironment({ renderer, scene });
-  environment.set(options.environment ?? DEFAULT_ENVIRONMENT);
-  renderer.setRenderTarget(null);
-  renderer.setClearColor(0x000000, 0);
-
-  const lighting = createLighting({ scene, center: stats.center, maxDimension });
-  scene.add(object);
-
-  const materials = createMaterialController(object);
-  const ground = createGround({
-    scene,
-    stats,
-    maxDimension,
-    maxAnisotropy: renderer.capabilities.getMaxAnisotropy(),
-  });
-
-  const animationListeners = new Set();
-  const animation = createAnimationController(object, {
-    onTick(state) {
-      for (const listener of animationListeners) {
-        try {
-          listener(state);
-        } catch (error) {
-          console.error('[dsh-3d-viewer] Animation listener failed.', error);
-        }
-      }
-    },
-  });
-
-  const post = createPostProcessing({
-    renderer,
-    scene,
-    camera,
-    width: initialWidth,
-    height: initialHeight,
-    pixelRatio: initialPixelRatio,
-  });
-
-  const controls = new OrbitControls(camera, canvas);
-  controls.enableDamping = false;
-  controls.screenSpacePanning = true;
-  controls.rotateSpeed = 0.9;
-  controls.zoomSpeed = 0.9;
-  controls.panSpeed = 0.8;
-  controls.autoRotateSpeed = 1.6;
-  controls.minPolarAngle = 0.02;
-  controls.maxPolarAngle = Math.PI * 0.98;
-
-  let autoRotate = false;
-  let disposed = false;
-  let onScreen = true;
-  let lastWidth = 0;
-  let lastHeight = 0;
-  let lastPixelRatio = 0;
-  let lastSyncDistance = Number.NaN;
-  let lastSyncTargetX = Number.NaN;
-  let lastSyncTargetZ = Number.NaN;
-  let resizeObserver;
-  let intersectionObserver;
-
-  const loop = createRenderLoop((delta, timestamp) => {
-    animation.update(delta, timestamp);
-    if (autoRotate) controls.update();
-    post.render(delta);
-  });
-
-  function syncView() {
-    const distance = Math.max(camera.position.distanceTo(controls.target), maxDimension * 0.05);
-    const targetX = controls.target.x;
-    const targetZ = controls.target.z;
-
-    // Auto-rotation changes the camera orientation but not its distance or
-    // target, so the grid and clip planes can stay untouched in that case.
-    if (distance === lastSyncDistance
-      && targetX === lastSyncTargetX
-      && targetZ === lastSyncTargetZ) {
-      return;
-    }
-    lastSyncDistance = distance;
-    lastSyncTargetX = targetX;
-    lastSyncTargetZ = targetZ;
-
-    updateClipPlanes(camera, distance, maxDimension);
-    ground.update(camera, controls.target, distance);
-  }
-
-  function updateLoop() {
-    if (autoRotate || animation.isPlaying()) loop.start();
-    else {
-      loop.stop();
-      loop.invalidate();
-    }
-  }
-
-  function onControlsChange() {
-    syncView();
-    loop.invalidate();
-  }
-
-  function resize() {
-    if (disposed) return;
-
-    const width = Math.max(host.clientWidth, 1);
-    const height = Math.max(host.clientHeight, 1);
-    const pixelRatio = readPixelRatio();
-    if (width === lastWidth && height === lastHeight && pixelRatio === lastPixelRatio) return;
-
-    const pixelRatioChanged = pixelRatio !== lastPixelRatio;
-    const sizeChanged = width !== lastWidth || height !== lastHeight;
-    lastWidth = width;
-    lastHeight = height;
-    lastPixelRatio = pixelRatio;
-
-    if (pixelRatioChanged) renderer.setPixelRatio(pixelRatio);
-    if (sizeChanged) renderer.setSize(width, height, false);
-    post.setSize(width, height, pixelRatio);
-
-    if (sizeChanged) {
-      camera.aspect = width / height;
-      camera.updateProjectionMatrix();
-    }
-    loop.invalidate();
-  }
-
-  function onKeyDown(event) {
-    if (!isOrbitKey(event.key)) return;
-    event.preventDefault();
-    orbitByKey(camera, controls, event.key);
-    loop.invalidate();
-  }
-
-  function onPointerDown() {
-    canvas.focus({ preventScroll: true });
-  }
-
-  function onVisibilityChange() {
-    loop.setActive(onScreen && !document.hidden);
-  }
-
-  function setAutoRotate(enabled) {
-    const next = Boolean(enabled);
-    if (next === autoRotate) return false;
-
-    autoRotate = next;
-    controls.autoRotate = next;
-    updateLoop();
-    if (!next) loop.invalidate();
-    return true;
-  }
-
-  function setGrid(visible) {
-    if (!ground.setGridVisible(visible)) return false;
-    loop.invalidate();
-    return true;
-  }
-
-  function setEnvironment(id) {
-    if (!environment.set(id)) return false;
-    loop.invalidate();
-    return true;
-  }
-
-  function setMaterialPreset(id) {
-    if (!materials.setPreset(id)) return false;
-    loop.invalidate();
-    return true;
-  }
-
-  function setWireframe(enabled) {
-    if (!materials.setWireframe(enabled)) return false;
-    ground.setShadowVisible(!materials.wireframe);
-    loop.invalidate();
-    return true;
-  }
-
-  function setAnimationPlaying(enabled) {
-    if (!animation.setPlaying(enabled)) return;
-    updateLoop();
-  }
-
-  function setAnimationClip(index) {
-    if (!animation.setClip(index)) return;
-    updateLoop();
-    loop.invalidate();
-  }
-
-  function seekAnimation(seconds) {
-    if (animation.seek(seconds)) loop.invalidate();
-  }
-
-  function subscribeAnimation(listener) {
-    if (typeof listener !== 'function' || disposed) return () => {};
-
-    animationListeners.add(listener);
-    listener(animation.snapshot());
-    return () => {
-      animationListeners.delete(listener);
-    };
-  }
-
-  function reset() {
-    frameModel(camera, controls, stats, maxDimension);
-    syncView();
-    loop.invalidate();
-  }
-
-  function invalidate() {
-    loop.invalidate();
-  }
-
-  function dispose() {
-    if (disposed) return;
-    disposed = true;
-
-    loop.dispose();
-    resizeObserver?.disconnect();
-    intersectionObserver?.disconnect();
-    window.removeEventListener('resize', resize);
-    document.removeEventListener('visibilitychange', onVisibilityChange);
-    controls.removeEventListener('change', onControlsChange);
-    canvas.removeEventListener('keydown', onKeyDown);
-    canvas.removeEventListener('pointerdown', onPointerDown);
-    animationListeners.clear();
-
-    animation.dispose();
-    materials.dispose();
-    ground.dispose();
-    lighting.dispose();
-    environment.dispose();
-    controls.dispose();
-    post.dispose();
-    disposeObject(scene);
-    scene.clear();
-    renderer.dispose();
-    renderer.forceContextLoss();
-    canvas.remove();
-  }
-
-  controls.addEventListener('change', onControlsChange);
-  canvas.addEventListener('keydown', onKeyDown);
-  canvas.addEventListener('pointerdown', onPointerDown);
-  window.addEventListener('resize', resize);
-  document.addEventListener('visibilitychange', onVisibilityChange);
-
-  if (typeof ResizeObserver === 'function') {
-    resizeObserver = new ResizeObserver(resize);
-    resizeObserver.observe(host);
-  }
-
-  if (typeof IntersectionObserver === 'function') {
-    intersectionObserver = new IntersectionObserver((entries) => {
-      const entry = entries[entries.length - 1];
-      if (entry === undefined) return;
-      onScreen = entry.isIntersecting;
-      onVisibilityChange();
-    }, { threshold: 0.01 });
-    intersectionObserver.observe(host);
-  }
-
-  resize();
-  frameModel(camera, controls, stats, maxDimension);
-  syncView();
-  loop.setActive(onScreen && !document.hidden);
-  if (autoRotate || animation.isPlaying()) loop.start();
-  else loop.invalidate();
-
-  return {
-    animations: animation.animations,
-    subscribeAnimation,
-    setAnimationPlaying,
-    setAnimationClip,
-    seekAnimation,
-    setAutoRotate,
-    setGrid,
-    setEnvironment,
-    setMaterialPreset,
-    setWireframe,
-    reset,
-    invalidate,
-    dispose,
-  };
-}