model-preview 0.1.0

package/src/index.ts

@@ -0,0 +1,89 @@
+export { PreviewModel, cloneObjectTree, removeHelperNodes } from './PreviewModel.js';
+export { ModelPreviewViewport, type ModelPreviewViewportOptions } from './ModelPreviewViewport.js';
+
+export {
+  ModelLoaderRegistry,
+  defaultModelLoaderRegistry,
+  getFileExtension,
+  isPreviewableModelFile,
+  loadModel,
+  loadModelFromFile,
+} from './loaders/registry.js';
+
+export { glbLoader, loadGlbBuffer } from './loaders/glbLoader.js';
+export { fbxLoader, loadFbxBuffer } from './loaders/fbxLoader.js';
+export { objLoader, loadObjBuffer } from './loaders/objLoader.js';
+export type { ModelLoadOptions, ModelLoader } from './loaders/types.js';
+
+export {
+  DEFAULT_VIEW_FOV,
+  HELPER_OBJECT_TYPE,
+  AXIS_X_COLOR,
+  AXIS_Y_COLOR,
+  AXIS_Z_COLOR,
+} from './constants.js';
+
+export type { AnimationClipInfo, PreviewModelSource } from './types.js';
+
+export { formatAnimationClipName, formatAnimationDuration } from './animation/format.js';
+
+export { disposeObject3D } from './dispose/disposeObject3D.js';
+
+export {
+  glbNeedsSpecGlossConversion,
+  convertGlbToMetalRough,
+  prepareGlbArrayBuffer,
+} from './gltf/metalRoughConverter.js';
+
+export { CustomControls, MOUSE } from './viewport/CustomControls.js';
+export { ViewGrid } from './viewport/ViewGrid.js';
+export { WorldAxes } from './viewport/WorldAxes.js';
+
+export {
+  DEFAULT_TONE_MAPPING_EXPOSURE,
+  configureRenderer,
+  createRoomEnvironmentMap,
+  applySceneEnvironment,
+} from './viewport/renderQuality.js';
+
+export {
+  degToRad,
+  computeCameraPlacement,
+  getViewHeightAtDistance,
+  getViewAspect,
+  createViewportBackground,
+  frameObjectInView,
+  type ViewCamera,
+} from './viewport/ViewportUtils.js';
+
+export { captureModelThumbnailBlob } from './thumbnail/captureModelThumbnail.js';
+export type { CaptureModelThumbnailOptions } from './thumbnail/captureModelThumbnail.js';
+export {
+  assertThumbnailBlobSize,
+  assertThumbnailHasVisibleContent,
+  countNonBackgroundPixels,
+  MIN_THUMBNAIL_BYTES,
+  MIN_VISIBLE_THUMBNAIL_PIXELS,
+} from './thumbnail/thumbnailValidation.js';
+
+/** @deprecated Use {@link PreviewModel} */
+export { PreviewModel as GlbModel } from './PreviewModel.js';
+
+/** @deprecated Use {@link loadModel} or {@link loadGlbBuffer} */
+export { loadGlbBuffer as loadGlbModel } from './loaders/glbLoader.js';
+
+/** @deprecated Use {@link loadModel} */
+export const GlbLoader = {
+  load: (arrayBuffer: ArrayBuffer, options: import('./loaders/types.js').ModelLoadOptions = {}) =>
+    import('./loaders/glbLoader.js').then(({ loadGlbBuffer }) => loadGlbBuffer(arrayBuffer, options)),
+  loadFromFile: async (file: File, options: import('./loaders/types.js').ModelLoadOptions = {}) => {
+    const { loadGlbBuffer } = await import('./loaders/glbLoader.js');
+    const arrayBuffer = await file.arrayBuffer();
+    return loadGlbBuffer(arrayBuffer, {
+      ...options,
+      filename: file.name,
+      name: options.name || file.name.replace(/\.[^.]+$/, ''),
+      mimeType: file.type || 'application/octet-stream',
+    });
+  },
+};

package/src/loaders/fbxLoader.ts

@@ -0,0 +1,53 @@
+import { FBXLoader } from 'three/addons/loaders/FBXLoader.js';
+import type { AnimationClip, Object3D } from 'three';
+
+import { PreviewModel } from '../PreviewModel.js';
+import type { ModelLoadOptions, ModelLoader } from './types.js';
+
+function collectAnimations(object: Object3D): AnimationClip[] {
+  const clips: AnimationClip[] = [];
+  object.traverse((node) => {
+    const nodeClips = (node as Object3D & { animations?: AnimationClip[] }).animations;
+    if (nodeClips?.length) {
+      clips.push(...nodeClips);
+    }
+  });
+  return clips;
+}
+
+function applyModelName(model: PreviewModel, options: ModelLoadOptions) {
+  const baseName = (options.name || (options.filename || '').replace(/\.[^.]+$/, '') || '').trim();
+  if (baseName && model.object) {
+    model.object.name = baseName;
+  }
+}
+
+async function loadFbxBuffer(arrayBuffer: ArrayBuffer, options: ModelLoadOptions): Promise<PreviewModel> {
+  const loader = new FBXLoader();
+
+  if (options.resourceBaseUrl) {
+    loader.setResourcePath(options.resourceBaseUrl);
+  }
+
+  const blob = new Blob([arrayBuffer], {
+    type: options.mimeType || 'application/octet-stream',
+  });
+  const url = URL.createObjectURL(blob);
+
+  try {
+    const object = await loader.loadAsync(url);
+    const animations = collectAnimations(object);
+    const model = PreviewModel.fromLoadedScene(object, animations);
+    applyModelName(model, options);
+    return model;
+  } finally {
+    URL.revokeObjectURL(url);
+  }
+}
+
+export const fbxLoader: ModelLoader = {
+  extensions: ['.fbx'],
+  load: loadFbxBuffer,
+};
+
+export { loadFbxBuffer };

package/src/loaders/glbLoader.ts

@@ -0,0 +1,39 @@
+import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
+
+import { PreviewModel } from '../PreviewModel.js';
+import { prepareGlbArrayBuffer } from '../gltf/metalRoughConverter.js';
+import type { ModelLoadOptions, ModelLoader } from './types.js';
+
+function applyModelName(model: PreviewModel, options: ModelLoadOptions) {
+  const baseName = (options.name || (options.filename || '').replace(/\.[^.]+$/, '') || '').trim();
+  if (baseName && model.object) {
+    model.object.name = baseName;
+  }
+}
+
+async function loadGlbBuffer(arrayBuffer: ArrayBuffer, options: ModelLoadOptions): Promise<PreviewModel> {
+  const preparedBuffer = await prepareGlbArrayBuffer(arrayBuffer);
+
+  const loader = new GLTFLoader();
+  const blob = new Blob([preparedBuffer], {
+    type: options.mimeType || 'application/octet-stream',
+  });
+  const url = URL.createObjectURL(blob);
+
+  try {
+    const gltf = await loader.loadAsync(url);
+    const model = PreviewModel.fromLoadedScene(gltf.scene, gltf.animations || []);
+    applyModelName(model, options);
+    return model;
+  } finally {
+    URL.revokeObjectURL(url);
+  }
+}
+
+export const glbLoader: ModelLoader = {
+  extensions: ['.glb', '.gltf'],
+  mimeTypes: ['model/gltf-binary', 'model/gltf+json'],
+  load: loadGlbBuffer,
+};
+
+export { loadGlbBuffer };

package/src/loaders/objLoader.ts

@@ -0,0 +1,70 @@
+import { MTLLoader } from 'three/addons/loaders/MTLLoader.js';
+import { OBJLoader } from 'three/addons/loaders/OBJLoader.js';
+
+import { PreviewModel } from '../PreviewModel.js';
+import type { ModelLoadOptions, ModelLoader } from './types.js';
+
+function applyModelName(model: PreviewModel, options: ModelLoadOptions) {
+  const baseName = (options.name || (options.filename || '').replace(/\.[^.]+$/, '') || '').trim();
+  if (baseName && model.object) {
+    model.object.name = baseName;
+  }
+}
+
+function objMaterialBasename(filename?: string): string | null {
+  const base = (filename || '').replace(/\.[^.]+$/, '').trim();
+  return base || null;
+}
+
+async function tryLoadMtlMaterials(
+  objLoader: OBJLoader,
+  options: ModelLoadOptions,
+): Promise<void> {
+  if (!options.resourceBaseUrl) return;
+
+  const basename = objMaterialBasename(options.filename);
+  if (!basename) return;
+
+  const mtlLoader = new MTLLoader();
+  mtlLoader.setResourcePath(options.resourceBaseUrl);
+
+  const mtlUrl = `${options.resourceBaseUrl}${basename}.mtl`;
+  const materials = await mtlLoader.loadAsync(mtlUrl);
+  materials.preload();
+  objLoader.setMaterials(materials);
+}
+
+async function loadObjBuffer(arrayBuffer: ArrayBuffer, options: ModelLoadOptions): Promise<PreviewModel> {
+  const objLoader = new OBJLoader();
+
+  if (options.resourceBaseUrl) {
+    objLoader.setResourcePath(options.resourceBaseUrl);
+    try {
+      await tryLoadMtlMaterials(objLoader, options);
+    } catch {
+      // Companion MTL is optional; geometry preview still works without it.
+    }
+  }
+
+  const blob = new Blob([arrayBuffer], {
+    type: options.mimeType || 'text/plain',
+  });
+  const url = URL.createObjectURL(blob);
+
+  try {
+    const object = await objLoader.loadAsync(url);
+    const model = PreviewModel.fromLoadedScene(object, []);
+    applyModelName(model, options);
+    return model;
+  } finally {
+    URL.revokeObjectURL(url);
+  }
+}
+
+export const objLoader: ModelLoader = {
+  extensions: ['.obj'],
+  mimeTypes: ['model/obj'],
+  load: loadObjBuffer,
+};
+
+export { loadObjBuffer };

package/src/loaders/registry.ts

@@ -0,0 +1,69 @@
+import {
+  getModelFileExtension as getFileExtension,
+  isPreviewableModelFile,
+} from 'model-file-types';
+import { fbxLoader } from './fbxLoader.js';
+import { glbLoader } from './glbLoader.js';
+import { objLoader } from './objLoader.js';
+import type { ModelLoadOptions, ModelLoader } from './types.js';
+import type { PreviewModel } from '../PreviewModel.js';
+
+export { getFileExtension, isPreviewableModelFile };
+
+const DEFAULT_LOADERS: ModelLoader[] = [glbLoader, fbxLoader, objLoader];
+
+export class ModelLoaderRegistry {
+  private loaders: ModelLoader[];
+
+  constructor(loaders: ModelLoader[] = DEFAULT_LOADERS) {
+    this.loaders = [...loaders];
+  }
+
+  register(loader: ModelLoader) {
+    this.loaders.push(loader);
+  }
+
+  resolve(filename?: string, mimeType?: string): ModelLoader | null {
+    const ext = getFileExtension(filename);
+    const mime = (mimeType || '').toLowerCase();
+
+    if (ext) {
+      const byExt = this.loaders.find((loader) => loader.extensions.includes(ext));
+      if (byExt) return byExt;
+    }
+
+    if (mime) {
+      const byMime = this.loaders.find((loader) =>
+        loader.mimeTypes?.some((item) => mime.includes(item.replace('*', '')) || mime === item),
+      );
+      if (byMime) return byMime;
+    }
+
+    return null;
+  }
+
+  async load(arrayBuffer: ArrayBuffer, options: ModelLoadOptions = {}): Promise<PreviewModel> {
+    const loader = this.resolve(options.filename, options.mimeType);
+    if (!loader) {
+      const hint = options.filename || options.mimeType || 'unknown format';
+      throw new Error(`No model loader registered for ${hint}`);
+    }
+    return loader.load(arrayBuffer, options);
+  }
+}
+
+export const defaultModelLoaderRegistry = new ModelLoaderRegistry();
+
+export async function loadModel(arrayBuffer: ArrayBuffer, options: ModelLoadOptions = {}): Promise<PreviewModel> {
+  return defaultModelLoaderRegistry.load(arrayBuffer, options);
+}
+
+export async function loadModelFromFile(file: File, options: ModelLoadOptions = {}): Promise<PreviewModel> {
+  const arrayBuffer = await file.arrayBuffer();
+  return loadModel(arrayBuffer, {
+    ...options,
+    filename: file.name,
+    name: options.name || file.name.replace(/\.[^.]+$/, ''),
+    mimeType: file.type || options.mimeType || 'application/octet-stream',
+  });
+}

package/src/loaders/types.ts

@@ -0,0 +1,15 @@
+import type { PreviewModel } from '../PreviewModel.js';
+
+export type ModelLoadOptions = {
+  name?: string;
+  filename?: string;
+  mimeType?: string;
+  /** Base URL for resolving external textures (FBX/OBJ). */
+  resourceBaseUrl?: string;
+};
+
+export interface ModelLoader {
+  readonly extensions: readonly string[];
+  readonly mimeTypes?: readonly string[];
+  load(source: ArrayBuffer, options: ModelLoadOptions): Promise<PreviewModel>;
+}

package/src/shims/empty-node-module.ts

@@ -0,0 +1,3 @@
+const emptyNodeModule = {};
+
+export default emptyNodeModule;

package/src/thumbnail/captureModelThumbnail.ts

@@ -0,0 +1,127 @@
+import {
+  AmbientLight,
+  Box3,
+  DirectionalLight,
+  PerspectiveCamera,
+  Scene,
+  WebGLRenderer,
+} from 'three';
+
+import { DEFAULT_VIEW_FOV } from '../constants.js';
+import {
+  applySceneEnvironment,
+  configureRenderer,
+  createRoomEnvironmentMap,
+} from '../viewport/renderQuality.js';
+import { createViewportBackground, frameObjectInView } from '../viewport/ViewportUtils.js';
+import { disposeObject3D } from '../dispose/disposeObject3D.js';
+import type { PreviewModelSource } from '../types.js';
+import { assertThumbnailBlobSize, assertThumbnailHasVisibleContent } from './thumbnailValidation.js';
+
+const DEFAULT_THUMBNAIL_SIZE = 256;
+const _box = new Box3();
+
+export type CaptureModelThumbnailOptions = {
+  width?: number;
+  height?: number;
+  padding?: number;
+  mimeType?: string;
+  quality?: number;
+};
+
+/**
+ * Render one WebGL preview frame in the browser and export it as an image blob.
+ * Matches the Netdisk / UEditor model preview pipeline (PBR + IBL).
+ */
+export async function captureModelThumbnailBlob(
+  sourceModel: PreviewModelSource,
+  options: CaptureModelThumbnailOptions = {},
+): Promise<Blob> {
+  if (typeof document === 'undefined') {
+    throw new Error('captureModelThumbnailBlob requires a browser environment');
+  }
+
+  const width = options.width ?? DEFAULT_THUMBNAIL_SIZE;
+  const height = options.height ?? DEFAULT_THUMBNAIL_SIZE;
+  const padding = options.padding ?? 1.8;
+  const mimeType = options.mimeType ?? 'image/webp';
+  const quality = options.quality ?? 0.9;
+
+  const canvas = document.createElement('canvas');
+  canvas.width = width;
+  canvas.height = height;
+
+  const previewModel = sourceModel.createPreviewInstance();
+  const scene = new Scene();
+  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;
+  scene.add(ambient);
+  scene.add(directional);
+
+  if (previewModel.object) {
+    scene.add(previewModel.object);
+  }
+
+  const camera = new PerspectiveCamera(DEFAULT_VIEW_FOV, width / height, 0.01, 1000);
+  const renderer = new WebGLRenderer({ canvas, antialias: true, alpha: false });
+  configureRenderer(renderer, { pixelRatio: 1 });
+  renderer.setSize(width, height, false);
+
+  const environmentHandle = createRoomEnvironmentMap(renderer);
+  applySceneEnvironment(scene, environmentHandle.envMap, 0.85);
+
+  frameObjectInView({
+    camera,
+    controls: null,
+    getBounds: () => {
+      _box.makeEmpty();
+      if (previewModel.object) {
+        _box.setFromObject(previewModel.object);
+      }
+      return _box;
+    },
+    fov: DEFAULT_VIEW_FOV,
+    aspect: width / height,
+    padding,
+  });
+
+  renderer.render(scene, camera);
+
+  const sampleCanvas = document.createElement('canvas');
+  sampleCanvas.width = width;
+  sampleCanvas.height = height;
+  const sampleCtx = sampleCanvas.getContext('2d');
+  if (!sampleCtx) {
+    throw new Error('缩略图校验失败');
+  }
+  sampleCtx.drawImage(canvas, 0, 0, width, height);
+  assertThumbnailHasVisibleContent(sampleCtx, width, height);
+
+  const blob = await new Promise<Blob>((resolve, reject) => {
+    canvas.toBlob(
+      (result) => {
+        if (!result) {
+          reject(new Error('缩略图导出失败'));
+          return;
+        }
+        resolve(result);
+      },
+      mimeType,
+      quality,
+    );
+  });
+
+  assertThumbnailBlobSize(blob.size);
+
+  environmentHandle.dispose();
+  renderer.dispose();
+  if (previewModel.object) {
+    disposeObject3D(previewModel.object);
+  }
+
+  return blob;
+}

package/src/thumbnail/thumbnailValidation.ts

@@ -0,0 +1,44 @@
+/** Minimum non-background pixels for a usable model thumbnail. */
+export const MIN_VISIBLE_THUMBNAIL_PIXELS = 120;
+
+/** Minimum encoded WebP size (bytes). */
+export const MIN_THUMBNAIL_BYTES = 64;
+
+type PixelSampleContext = {
+  getImageData(sx: number, sy: number, sw: number, sh: number): { data: Uint8ClampedArray };
+};
+
+/** Count pixels that differ noticeably from the dark viewport background. */
+export function countNonBackgroundPixels(
+  ctx: PixelSampleContext,
+  width: number,
+  height: number,
+): number {
+  const data = ctx.getImageData(0, 0, width, height).data;
+  let count = 0;
+  for (let i = 0; i < data.length; i += 4) {
+    const r = data[i];
+    const g = data[i + 1];
+    const b = data[i + 2];
+    if (r > 90 || g > 90 || b > 90) {
+      count += 1;
+    }
+  }
+  return count;
+}
+
+export function assertThumbnailHasVisibleContent(
+  ctx: PixelSampleContext,
+  width: number,
+  height: number,
+): void {
+  if (countNonBackgroundPixels(ctx, width, height) < MIN_VISIBLE_THUMBNAIL_PIXELS) {
+    throw new Error('缩略图生成失败：模型画面为空');
+  }
+}
+
+export function assertThumbnailBlobSize(byteLength: number): void {
+  if (byteLength < MIN_THUMBNAIL_BYTES) {
+    throw new Error('缩略图生成失败：输出文件无效');
+  }
+}

package/src/types.ts

@@ -0,0 +1,22 @@
+import type { AnimationClip, Box3, Object3D } from 'three';
+
+export type AnimationClipInfo = {
+  name: string;
+  duration: number;
+  clip: AnimationClip;
+};
+
+/** Contract for models that can be mounted in {@link ModelPreviewViewport}. */
+export interface PreviewModelSource {
+  readonly object: Object3D | null;
+  createPreviewInstance(): PreviewModelSource;
+  getAnimationClips(): AnimationClipInfo[];
+  hasAnimations(): boolean;
+  playAnimation(clipName: string, options?: { loop?: boolean }): boolean;
+  pauseAnimation(): void;
+  stopAnimation(): void;
+  resetPose(): void;
+  update(delta: number): void;
+  getAnimatedBounds(clipName: string, sampleCount?: number): Box3;
+  isReady(): boolean;
+}