lectom
bedb357259
git-subtree-dir: apps/viewer-3d git-subtree-mainline:5e10bb1be4git-subtree-split:a71790070d
90 lines
3.7 KiB
Markdown
90 lines
3.7 KiB
Markdown
---
|
|
name: threejs-viewer
|
|
description: >
|
|
Domain knowledge for building the hmwebviewer Three.js 3D viewer. Load when working
|
|
on src/viewer, src/dnd, src/ui, the asset pipeline, or hydration. Covers the locked
|
|
technical decisions, loader setup, Draco/KTX2, Blob URL lifecycle, and SSR hydration
|
|
patterns specific to this project.
|
|
---
|
|
|
|
# hmwebviewer — Three.js 3D viewer domain guide
|
|
|
|
Source spec: `3d_viewer_architecture_spec.pdf`. Always also read `CLAUDE.md` + `PLAN.md`.
|
|
|
|
## Locked stack
|
|
- Three.js + Vite + TypeScript.
|
|
- Loaders: `GLTFLoader` + `DRACOLoader` + `KTX2Loader`.
|
|
- Compression: Draco (geometry) + KTX2/Basis Universal (textures).
|
|
|
|
## Critical patterns (do not deviate without approval)
|
|
|
|
### Single shared loader instances
|
|
Multiple simultaneous `DRACOLoader` instances crash (three.js #22445). KTX2 same risk. Build a singleton:
|
|
|
|
```ts
|
|
// src/viewer/loaders.ts
|
|
import * as THREE from 'three';
|
|
import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader.js';
|
|
import { DRACOLoader } from 'three/examples/jsm/loaders/DRACOLoader.js';
|
|
import { KTX2Loader } from 'three/examples/jsm/loaders/KTX2Loader.js';
|
|
|
|
let _gltf: GLTFLoader | null = null;
|
|
export function getLoaders(renderer: THREE.WebGLRenderer) {
|
|
if (!_gltf) {
|
|
const draco = new DRACOLoader().setDecoderPath('/draco/');
|
|
const ktx2 = new KTX2Loader().setTranscoderPath('/basis/').detectSupport(renderer);
|
|
_gltf = new GLTFLoader().setDRACOLoader(draco).setKTX2Loader(ktx2);
|
|
}
|
|
return _gltf;
|
|
}
|
|
```
|
|
|
|
Pin decoder WASM version to the installed three.js version. Mismatch → silent decode failures.
|
|
|
|
### Local file load (Blob URL lifecycle)
|
|
```ts
|
|
const url = URL.createObjectURL(file);
|
|
loader.load(url, (gltf) => {
|
|
scene.add(gltf.scene);
|
|
URL.revokeObjectURL(url); // success → revoke
|
|
}, undefined, (err) => {
|
|
URL.revokeObjectURL(url); // error → also revoke
|
|
throw err;
|
|
});
|
|
```
|
|
For repeat/cached loads: `FileReader` → `ArrayBuffer` → `GLTFLoader.parse()` enables IndexedDB caching and avoids URL overhead.
|
|
|
|
### Server asset (SSR + CSR + hydration)
|
|
1. SSR ships HTML/CSS skeleton + pre-rendered 360° animated WebP placeholder.
|
|
2. CSR background: `GLTFLoader.load(serverUrl, onLoad, onProgress)`.
|
|
3. Hydration: gate the fade on BOTH `webglReady` AND `modelLoaded` (Promise.all). Fade CSS `opacity 0.5s ease` → `display:none` after 500ms. Race → empty canvas flash.
|
|
|
|
### Drag & drop
|
|
```ts
|
|
dropzone.addEventListener('dragover', (e) => { e.preventDefault(); });
|
|
dropzone.addEventListener('drop', (e) => {
|
|
e.preventDefault();
|
|
const file = e.dataTransfer?.files?.[0];
|
|
if (!file) return;
|
|
if (!/\.gl[bt]f$/i.test(file.name)) return showError('GLB/GLTF only');
|
|
loadLocalFile(file); // viewer-core, handles createObjectURL/revoke
|
|
});
|
|
```
|
|
Also wire click→`<input type=file">` for accessibility.
|
|
|
|
### Disposal
|
|
On teardown / model swap: `geometry.dispose()`, `material.dispose()` (and material maps), `texture.dispose()`. Revoke any lingering object URLs.
|
|
|
|
## Offline asset pipeline
|
|
- Compress: `gltf-transform` CLI or programmatic functions — Draco + KTX2 in one pass.
|
|
- KTX2 encoder binary `toktx` must be on PATH (gltf-transform fetches via `@ktx2/basis-transcoder`/platform binaries — confirm available).
|
|
- Pre-render 360°: Blender headless `blender -b scene.blend -o //frame_### -f 1..N -F PNG` → ffmpeg → animated WebP. Fallback: Puppeteer + headless three.js screenshot per rotation.
|
|
|
|
## Common pitfalls
|
|
- `setDecoderPath` wrong → worker fetch 404 in console. Verify `/draco/` resolves under `public/`.
|
|
- Forgetting `e.preventDefault()` on dragover → browser opens the file.
|
|
- Decoder version mismatch → model fails to decode with no obvious error.
|
|
- Creating loaders per load → intermittent crashes + memory growth.
|
|
|
|
References in user memory `reference-threejs-resources.md`.
|