model-preview 0.1.0

package/README.md

@@ -0,0 +1,42 @@
+# model-preview
+
+Three.js utilities for loading, previewing, and thumbnailing 3D models (GLB/GLTF, FBX, OBJ).
+
+Depends on [`model-file-types`](../model-file-types).
+
+## Install
+
+```bash
+pnpm add model-preview model-file-types three
+```
+
+## Usage
+
+```ts
+import { ModelPreviewViewport, loadModel } from 'model-preview';
+
+const buffer = await file.arrayBuffer();
+const model = await loadModel(buffer, { filename: file.name });
+```
+
+## Development
+
+```bash
+pnpm install
+pnpm --dir ../model-file-types run build
+pnpm run check
+```
+
+## Browser bundlers
+
+Some loaders reference Node built-ins. Alias them to the package shim when bundling for the browser:
+
+```ts
+// vite.config.ts
+resolve: {
+  alias: {
+    'node:fs': 'model-preview/src/shims/empty-node-module.ts',
+    'node:path': 'model-preview/src/shims/empty-node-module.ts',
+  },
+},
+```

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "model-preview",
+  "version": "0.1.0",
+  "description": "Three.js-based 3D model preview, loaders, viewport, and thumbnail capture",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": ["src"],
+  "scripts": {
+    "typecheck": "tsc -b",
+    "test": "vitest run",
+    "check": "pnpm run typecheck && pnpm run test"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "@gltf-transform/core": "^4.4.1",
+    "@gltf-transform/extensions": "^4.4.1",
+    "@gltf-transform/functions": "^4.4.1",
+    "model-file-types": "file:../model-file-types",
+    "three": "^0.185.0"
+  },
+  "devDependencies": {
+    "@types/three": "^0.185.4",
+    "typescript": "^5.8.2",
+    "vitest": "^4.1.10"
+  }
+}

package/src/ModelPreviewViewport.ts

@@ -0,0 +1,259 @@
+import {
+  AmbientLight,
+  Box3,
+  DirectionalLight,
+  PerspectiveCamera,
+  Scene,
+  WebGLRenderer,
+} from 'three';
+
+import { DEFAULT_VIEW_FOV } from './constants.js';
+import { CustomControls, MOUSE } from './viewport/CustomControls.js';
+import { ViewGrid } from './viewport/ViewGrid.js';
+import { WorldAxes } from './viewport/WorldAxes.js';
+import {
+  applySceneEnvironment,
+  configureRenderer,
+  createRoomEnvironmentMap,
+} from './viewport/renderQuality.js';
+import { createViewportBackground, frameObjectInView } from './viewport/ViewportUtils.js';
+import type { PreviewModelSource } from './types.js';
+
+const _box = new Box3();
+
+export type ModelPreviewViewportOptions = {
+  fov?: number;
+  padding?: number;
+};
+
+/**
+ * Isolated Three.js viewport for GLB model and animation preview.
+ * Used by UEditor animation panel and Netdisk model preview.
+ */
+export class ModelPreviewViewport {
+  private canvas: HTMLCanvasElement;
+  private viewport: HTMLElement;
+  private sourceModel: PreviewModelSource | null = null;
+  private previewModel: PreviewModelSource | null = null;
+  private scene: Scene | null = null;
+  private camera: PerspectiveCamera | null = null;
+  private renderer: WebGLRenderer | null = null;
+  private controls: CustomControls | null = null;
+  private viewGrid = new ViewGrid();
+  private worldAxes = new WorldAxes();
+  private rafId: number | null = null;
+  private lastTime = 0;
+  private resizeObserver: ResizeObserver | null = null;
+  private frameClipName: string | null = null;
+  private environmentHandle: ReturnType<typeof createRoomEnvironmentMap> | null = null;
+  private readonly fov: number;
+  private readonly padding: number;
+
+  constructor(canvas: HTMLCanvasElement, options: ModelPreviewViewportOptions = {}) {
+    this.canvas = canvas;
+    this.viewport = canvas.parentElement ?? canvas;
+    this.fov = options.fov ?? DEFAULT_VIEW_FOV;
+    this.padding = options.padding ?? 1.8;
+  }
+
+  mount(sourceModel: PreviewModelSource, clipName: string | null = null) {
+    this.dispose();
+
+    this.sourceModel = sourceModel;
+    this.previewModel = sourceModel.createPreviewInstance();
+    this.frameClipName = clipName;
+
+    this.scene = new Scene();
+    this.scene.background = createViewportBackground();
+
+    const ambient = new AmbientLight(0xffffff, 0.15);
+    const directional = new DirectionalLight(0xfff4e0, 2.2);
+    directional.position.set(2, 4, 3);
+    directional.castShadow = true;
+    this.scene.add(ambient);
+    this.scene.add(directional);
+
+    if (this.previewModel.object) {
+      this.scene.add(this.previewModel.object);
+    }
+
+    const width = Math.max(this.viewport.clientWidth, 1);
+    const height = Math.max(this.viewport.clientHeight, 1);
+
+    this.camera = new PerspectiveCamera(this.fov, width / height, 0.01, 1000);
+
+    this.renderer = new WebGLRenderer({ canvas: this.canvas, antialias: true, alpha: true });
+    configureRenderer(this.renderer, { pixelRatio: Math.min(window.devicePixelRatio || 1, 2) });
+    this.environmentHandle = createRoomEnvironmentMap(this.renderer);
+    applySceneEnvironment(this.scene, this.environmentHandle.envMap, 0.85);
+    this.resize();
+
+    this.controls = new CustomControls(this.camera, this.renderer.domElement);
+    this.controls.enableDamping = false;
+    this.controls.zoomSpeed = 0.3;
+    this.controls.mouseButtons = { LEFT: null, MIDDLE: MOUSE.ROTATE, RIGHT: null };
+
+    this.scene.add(this.worldAxes.create(this.camera));
+    this.scene.add(this.viewGrid.create(this.camera, this.controls));
+
+    this.frameInitialView();
+    this.bindResizeObserver();
+    this.render();
+    this.startLoop();
+  }
+
+  private bindResizeObserver() {
+    if (typeof ResizeObserver === 'undefined') return;
+
+    this.resizeObserver = new ResizeObserver(() => {
+      this.resize();
+      this.render();
+    });
+    this.resizeObserver.observe(this.viewport);
+  }
+
+  resize() {
+    if (!this.renderer || !this.camera) return;
+
+    const width = Math.max(this.viewport.clientWidth, 1);
+    const height = Math.max(this.viewport.clientHeight, 1);
+
+    this.camera.aspect = width / height;
+    this.camera.updateProjectionMatrix();
+    this.renderer.setSize(width, height, false);
+    this.renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));
+  }
+
+  private getModelBounds() {
+    if (!this.previewModel?.object) {
+      return _box.makeEmpty();
+    }
+
+    if (this.frameClipName) {
+      return this.previewModel.getAnimatedBounds(this.frameClipName);
+    }
+
+    _box.setFromObject(this.previewModel.object);
+    return _box;
+  }
+
+  private frameInitialView() {
+    if (!this.camera || !this.controls) return;
+
+    frameObjectInView({
+      camera: this.camera,
+      controls: this.controls,
+      getBounds: () => this.getModelBounds(),
+      fov: this.fov,
+      aspect: this.camera.aspect,
+      padding: this.padding,
+    });
+  }
+
+  setClipName(clipName: string) {
+    this.frameClipName = clipName;
+  }
+
+  isReady() {
+    return Boolean(this.previewModel?.isReady());
+  }
+
+  getAnimationClips() {
+    return this.sourceModel?.getAnimationClips() ?? [];
+  }
+
+  play(clipName: string) {
+    if (!this.previewModel) return false;
+
+    this.frameClipName = clipName;
+    this.previewModel.playAnimation(clipName, { loop: true });
+    return true;
+  }
+
+  pause() {
+    this.previewModel?.pauseAnimation();
+  }
+
+  stop() {
+    if (!this.previewModel) return;
+
+    this.previewModel.stopAnimation();
+    this.previewModel.resetPose();
+    this.render();
+  }
+
+  private startLoop() {
+    this.stopLoop();
+    this.lastTime = performance.now();
+
+    const tick = (now: number) => {
+      this.rafId = requestAnimationFrame(tick);
+      const delta = Math.min((now - this.lastTime) / 1000, 0.1);
+      this.lastTime = now;
+      this.update(delta);
+    };
+
+    this.rafId = requestAnimationFrame(tick);
+  }
+
+  private stopLoop() {
+    if (this.rafId !== null) {
+      cancelAnimationFrame(this.rafId);
+      this.rafId = null;
+    }
+  }
+
+  update(delta: number) {
+    if (!this.previewModel) return;
+
+    this.previewModel.update(delta);
+    this.render();
+  }
+
+  render() {
+    if (!this.renderer || !this.scene || !this.camera) return;
+
+    const height = Math.max(this.viewport.clientHeight, 1);
+
+    this.controls?.update();
+    this.viewGrid.update(height);
+    this.worldAxes.update();
+    this.renderer.render(this.scene, this.camera);
+  }
+
+  dispose() {
+    this.stop();
+    this.stopLoop();
+
+    this.resizeObserver?.disconnect();
+    this.resizeObserver = null;
+
+    this.controls?.dispose();
+    this.controls = null;
+
+    if (this.viewGrid.grid) {
+      this.viewGrid.grid.geometry?.dispose();
+      (this.viewGrid.grid.material as { dispose?: () => void })?.dispose?.();
+      this.viewGrid.grid = null;
+    }
+
+    this.worldAxes.lines.forEach((line) => {
+      line.geometry?.dispose();
+      (line.material as { dispose?: () => void })?.dispose?.();
+    });
+    this.worldAxes.lines = [];
+    this.worldAxes.axes = null;
+
+    this.renderer?.dispose();
+    this.renderer = null;
+
+    this.environmentHandle?.dispose();
+    this.environmentHandle = null;
+
+    this.previewModel = null;
+    this.sourceModel = null;
+    this.scene = null;
+    this.camera = null;
+    this.frameClipName = null;
+  }
+}

package/src/PreviewModel.ts

@@ -0,0 +1,242 @@
+import {
+  AnimationMixer,
+  Box3,
+  LoopOnce,
+  LoopRepeat,
+  type AnimationAction,
+  type AnimationClip,
+  type Object3D,
+} from 'three';
+import { clone as cloneSkinnedScene } from 'three/addons/utils/SkeletonUtils.js';
+
+import { HELPER_OBJECT_TYPE } from './constants.js';
+import { formatAnimationClipName } from './animation/format.js';
+import type { AnimationClipInfo, PreviewModelSource } from './types.js';
+
+function cloneObjectTree(object: Object3D) {
+  const savedUserData: Array<{ child: Object3D; backup: Record<string, unknown> }> = [];
+  const detachedHelpers: Array<{ child: Object3D; parent: Object3D }> = [];
+
+  object.traverse((child) => {
+    const backup: Record<string, unknown> = {};
+    if (child.userData?.sceneMesh) {
+      backup.sceneMesh = child.userData.sceneMesh;
+      delete child.userData.sceneMesh;
+    }
+    if (child.userData?.root) {
+      backup.root = child.userData.root;
+      delete child.userData.root;
+    }
+    if (Object.keys(backup).length > 0) {
+      savedUserData.push({ child, backup });
+    }
+    if (child.userData?.objectType === HELPER_OBJECT_TYPE && child.parent) {
+      detachedHelpers.push({ child, parent: child.parent });
+    }
+  });
+
+  detachedHelpers.forEach(({ child, parent }) => {
+    parent.remove(child);
+  });
+
+  const cloned = cloneSkinnedScene(object);
+
+  detachedHelpers.forEach(({ child, parent }) => {
+    parent.add(child);
+  });
+
+  savedUserData.forEach(({ child, backup }) => {
+    Object.assign(child.userData, backup);
+  });
+
+  return cloned;
+}
+
+function removeHelperNodes(object: Object3D) {
+  const helpers: Object3D[] = [];
+  object.traverse((child) => {
+    if (child.userData?.objectType === HELPER_OBJECT_TYPE) {
+      helpers.push(child);
+    }
+  });
+  helpers.forEach((child) => {
+    child.parent?.remove(child);
+  });
+}
+
+/** Loaded 3D model with animation playback for preview viewports and the editor. */
+export class PreviewModel implements PreviewModelSource {
+  object: Object3D | null = null;
+  animations: AnimationClip[] = [];
+  mixer: AnimationMixer | null = null;
+  activeAction: AnimationAction | null = null;
+
+  /** When true, {@link update} is skipped (timeline-driven models in the editor). */
+  timelineControlled = false;
+
+  static fromLoadedScene(object: Object3D, animations: AnimationClip[] = []) {
+    const model = new PreviewModel();
+    model.object = object;
+    model.animations = animations;
+    model.resetPose();
+
+    if (model.animations.length > 0) {
+      model.mixer = new AnimationMixer(model.object);
+    }
+
+    return model;
+  }
+
+  isReady() {
+    return Boolean(this.mixer);
+  }
+
+  resetPose() {
+    if (!this.object) return;
+
+    this.object.traverse((child) => {
+      const skinned = child as Object3D & { isSkinnedMesh?: boolean; skeleton?: { pose(): void } };
+      if (skinned.isSkinnedMesh && skinned.skeleton) {
+        skinned.skeleton.pose();
+        child.updateMatrixWorld(true);
+      }
+    });
+  }
+
+  hasAnimations() {
+    return this.animations.length > 0;
+  }
+
+  getAnimationClips(): AnimationClipInfo[] {
+    return this.animations.map((clip, index) => ({
+      name: formatAnimationClipName(clip.name, index),
+      duration: clip.duration,
+      clip,
+    }));
+  }
+
+  findAnimationClip(clipName: string) {
+    return (
+      this.animations.find((item, index) => {
+        const name = formatAnimationClipName(item.name, index);
+        return name === clipName;
+      }) ||
+      this.animations[0] ||
+      null
+    );
+  }
+
+  getAnimatedBounds(clipName: string, sampleCount = 16) {
+    const box = new Box3();
+    if (!this.object) return box;
+
+    const clip = this.findAnimationClip(clipName);
+    if (!clip || !this.mixer) {
+      box.setFromObject(this.object);
+      return box;
+    }
+
+    const action = this.mixer.clipAction(clip);
+    action.play();
+    action.paused = true;
+
+    for (let i = 0; i <= sampleCount; i++) {
+      action.time = (i / sampleCount) * clip.duration;
+      this.mixer.update(0);
+      this.object.traverse((child) => {
+        const skinned = child as Object3D & { isSkinnedMesh?: boolean; skeleton?: { update(): void } };
+        if (skinned.isSkinnedMesh && skinned.skeleton) {
+          skinned.skeleton.update();
+        }
+      });
+      this.object.updateMatrixWorld(true);
+      box.expandByObject(this.object);
+    }
+
+    action.stop();
+    this.mixer.stopAllAction();
+    this.resetPose();
+
+    return box;
+  }
+
+  playAnimation(clipName: string, { loop = true } = {}) {
+    if (!this.mixer || this.animations.length === 0) return false;
+
+    this.stopAnimation();
+
+    const clip = this.findAnimationClip(clipName);
+    if (!clip) return false;
+
+    this.activeAction = this.mixer.clipAction(clip);
+    this.activeAction.setLoop(loop ? LoopRepeat : LoopOnce, loop ? Infinity : 1);
+    this.activeAction.clampWhenFinished = !loop;
+    this.activeAction.reset().play();
+    return true;
+  }
+
+  pauseAnimation() {
+    if (this.activeAction) {
+      this.activeAction.paused = true;
+    }
+  }
+
+  resumeAnimation() {
+    if (this.activeAction) {
+      this.activeAction.paused = false;
+    }
+  }
+
+  stopAnimation() {
+    if (this.mixer) {
+      this.mixer.stopAllAction();
+    }
+    this.activeAction = null;
+  }
+
+  isAnimationPlaying() {
+    return Boolean(this.activeAction && !this.activeAction.paused);
+  }
+
+  update(delta: number) {
+    if (!this.mixer || this.timelineControlled) return;
+
+    this.mixer.update(delta);
+    this._updateSkeletons();
+  }
+
+  createPreviewInstance() {
+    if (!this.object) {
+      throw new Error('Cannot create preview instance without a loaded model');
+    }
+
+    const instance = new PreviewModel();
+    instance.object = cloneObjectTree(this.object);
+    removeHelperNodes(instance.object);
+
+    instance.object.position.set(0, 0, 0);
+    instance.object.rotation.set(0, 0, 0);
+    instance.object.scale.set(1, 1, 1);
+    instance.object.updateMatrixWorld(true);
+
+    instance.animations = this.animations;
+    instance.resetPose();
+
+    if (instance.animations.length > 0) {
+      instance.mixer = new AnimationMixer(instance.object);
+    }
+
+    return instance;
+  }
+
+  private _updateSkeletons() {
+    this.object?.traverse((child) => {
+      const skinned = child as Object3D & { isSkinnedMesh?: boolean; skeleton?: { update(): void } };
+      if (skinned.isSkinnedMesh && skinned.skeleton) {
+        skinned.skeleton.update();
+      }
+    });
+  }
+}
+
+export { cloneObjectTree, removeHelperNodes };

package/src/animation/format.ts

@@ -0,0 +1,8 @@
+export function formatAnimationClipName(name: string, index: number): string {
+  return name.trim() || `Animation ${index + 1}`;
+}
+
+export function formatAnimationDuration(seconds: number): string {
+  if (!Number.isFinite(seconds) || seconds < 0) return '—';
+  return `${seconds.toFixed(2)} 秒`;
+}

package/src/constants.ts

@@ -0,0 +1,8 @@
+/** Marker for helper objects (grid, axes) excluded from model clones; matches UEditor OBJECT_TYPE.HELPER. */
+export const HELPER_OBJECT_TYPE = 0;
+
+export const DEFAULT_VIEW_FOV = 45;
+
+export const AXIS_X_COLOR = 0xff3653;
+export const AXIS_Y_COLOR = 0x7ecb50;
+export const AXIS_Z_COLOR = 0x4da6ff;

package/src/dispose/disposeObject3D.ts

@@ -0,0 +1,28 @@
+import type { Material, Object3D } from 'three';
+
+function disposeMaterial(material: Material) {
+  for (const value of Object.values(material)) {
+    if (value && typeof value === 'object' && 'isTexture' in value && (value as { isTexture?: boolean }).isTexture) {
+      (value as { dispose(): void }).dispose();
+    }
+  }
+  material.dispose();
+}
+
+/** Release geometry / material / texture resources on an object subtree. */
+export function disposeObject3D(object: Object3D | null | undefined) {
+  if (!object) return;
+
+  object.traverse((child) => {
+    const mesh = child as Object3D & { geometry?: { dispose(): void }; material?: Material | Material[] };
+    mesh.geometry?.dispose();
+
+    const materials = Array.isArray(mesh.material)
+      ? mesh.material
+      : mesh.material
+        ? [mesh.material]
+        : [];
+
+    materials.forEach(disposeMaterial);
+  });
+}

package/src/gltf/metalRoughConverter.ts

@@ -0,0 +1,70 @@
+import { WebIO } from '@gltf-transform/core';
+import { ALL_EXTENSIONS } from '@gltf-transform/extensions';
+import { metalRough } from '@gltf-transform/functions';
+
+const GLTF_MAGIC = 0x46546c67;
+const SPEC_GLOSS_EXTENSION = 'KHR_materials_pbrSpecularGlossiness';
+
+let ioInstance: WebIO | null = null;
+
+function getIo() {
+  if (!ioInstance) {
+    ioInstance = new WebIO().registerExtensions(ALL_EXTENSIONS);
+  }
+  return ioInstance;
+}
+
+/** Parse GLB JSON chunk to detect Spec/Gloss materials that need conversion. */
+export function glbNeedsSpecGlossConversion(arrayBuffer: ArrayBuffer): boolean {
+  if (!(arrayBuffer instanceof ArrayBuffer) || arrayBuffer.byteLength < 20) {
+    return false;
+  }
+
+  const view = new DataView(arrayBuffer);
+  if (view.getUint32(0, true) !== GLTF_MAGIC) {
+    return false;
+  }
+
+  const jsonChunkLength = view.getUint32(12, true);
+  if (jsonChunkLength <= 0 || 20 + jsonChunkLength > arrayBuffer.byteLength) {
+    return false;
+  }
+
+  try {
+    const jsonBytes = new Uint8Array(arrayBuffer, 20, jsonChunkLength);
+    const json = JSON.parse(new TextDecoder().decode(jsonBytes)) as {
+      extensionsRequired?: string[];
+      extensionsUsed?: string[];
+      materials?: Array<{ extensions?: Record<string, unknown> }>;
+    };
+
+    if (json.extensionsRequired?.includes(SPEC_GLOSS_EXTENSION)) {
+      return true;
+    }
+
+    if (!json.extensionsUsed?.includes(SPEC_GLOSS_EXTENSION)) {
+      return false;
+    }
+
+    return json.materials?.some((material) => material.extensions?.[SPEC_GLOSS_EXTENSION]) ?? false;
+  } catch {
+    return false;
+  }
+}
+
+/** Convert Spec/Gloss workflow GLB to Metal/Rough for Three.js. */
+export async function convertGlbToMetalRough(arrayBuffer: ArrayBuffer): Promise<ArrayBuffer> {
+  const io = getIo();
+  const document = await io.readBinary(new Uint8Array(arrayBuffer));
+  await document.transform(metalRough());
+  const converted = await io.writeBinary(document);
+  return converted.buffer.slice(converted.byteOffset, converted.byteOffset + converted.byteLength);
+}
+
+/** Preprocess GLB before load: convert materials only when needed. */
+export async function prepareGlbArrayBuffer(arrayBuffer: ArrayBuffer): Promise<ArrayBuffer> {
+  if (!glbNeedsSpecGlossConversion(arrayBuffer)) {
+    return arrayBuffer;
+  }
+  return convertGlbToMetalRough(arrayBuffer);
+}