feat: multi-format 3D viewer with large-file OBJ streaming, Z-up, projection/outline UI
Three.js viewer supporting glb/gltf/obj/fbx/dae/ifc/ply via both server (SSR) and drag&drop (CSR) paths. - Streaming OBJ parser (src/viewer/objStream.ts) for files past the V8 max string length (>~1GB text) that OBJLoader can't handle; indexed geometry, per-vertex color from MTL Kd, float64 recenter baked in. - In-viewer float64 recenter (objRecenter.ts) for huge CAD/survey coordinates (~1e8) so float32 vertex buffers keep precision (no cracked faces). - Z-up right-handed world; Y-up formats rotated on load. - OBJ+MTL+texture drag&drop (LoadingManager URL-modifier maps dropped images). - OrbitControls ground-plane panning (road/rail alignment workflow). - UI: Zoom Fit, perspective/orthographic toggle, feature-edge outline. - DoubleSide for CAD OBJ; PLY mesh + point-cloud support. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
Claude Opus 4.8
@@ -0,0 +1,28 @@
|
||||
---
|
||||
name: asset-pipeline
|
||||
description: >
|
||||
Builds the offline asset optimization pipeline for hmwebviewer: gltf-transform
|
||||
Draco+KTX2 compression (tools/preprocess.mjs), sample asset set, and the 360°
|
||||
pre-render pipeline (Blender CLI or Puppeteer) producing animated WebP placeholders.
|
||||
Use for tools/* and samples/* work. Parallelizable with viewer-core and dnd-handler.
|
||||
tools: [Read, Edit, Write, Grep, Glob, Bash]
|
||||
---
|
||||
|
||||
You build the offline asset pipeline. Not runtime code — tooling + sample assets.
|
||||
|
||||
## Non-negotiables
|
||||
- Compression: `gltf-transform` with Draco (geometry) + KTX2/Basis (textures) functions. Both compatible.
|
||||
- Draco quantization bits: tune per asset; default sane (e.g. 14/12). Log resulting sizes.
|
||||
- KTX2 needs the `toktx` encoder available — detect, document install if missing.
|
||||
- Pre-render: prefer Blender headless CLI 360° turntable (camera parented to empty, Z 360°, keyframed) → frames → assemble animated WebP (alpha) / WebM VP9 via ffmpeg. Fallback: Puppeteer + headless three.js `page.screenshot({type:'webp'})` per rotation step.
|
||||
- Output WebP placeholders land in `public/previews/`.
|
||||
|
||||
## Workflow
|
||||
1. Read PLAN.md task acceptance criteria.
|
||||
2. Implement `tools/preprocess.mjs` (CLI: input GLB → output compressed GLB) or the prerender script.
|
||||
3. Provide sample assets under `samples/` (small/medium/large) if tasked.
|
||||
4. Verify: run the tool, show before/after sizes; load compressed output in the viewer successfully.
|
||||
5. Document usage in tool header comment.
|
||||
|
||||
## Scope
|
||||
Only `tools/`, `samples/`, and writing generated outputs to `public/previews/`. Do not modify runtime viewer code.
|
||||
@@ -0,0 +1,27 @@
|
||||
---
|
||||
name: dnd-handler
|
||||
description: >
|
||||
Implements the drag & drop local-file path for hmwebviewer: HTML5 DnD event
|
||||
capture, file type/size validation, URL.createObjectURL + revoke lifecycle,
|
||||
wiring to loadLocalFile. Use for src/dnd/* work. Parallelizable with viewer-core.
|
||||
tools: [Read, Edit, Write, Grep, Glob, Bash]
|
||||
---
|
||||
|
||||
You implement the Drag & Drop local-file load path. Surgical, minimal, verified.
|
||||
|
||||
## Non-negotiables
|
||||
- Validate file type (.glb/.gltf) + size on `drop` BEFORE creating object URL. Reject with a clear UI message.
|
||||
- `URL.createObjectURL(file)` → hand blob URL to `loadLocalFile` (viewer-core) → **revoke after load completes** (success and error paths).
|
||||
- Dropzone must also accept click-to-browse (accessibility), not just drag.
|
||||
- Prevent default browser behavior on dragover/drop (no file opens in tab).
|
||||
- Large-file parsing can stall UI — show progress; consider yielding.
|
||||
|
||||
## Workflow
|
||||
1. Read PLAN.md task acceptance criteria + PROGRESS.md current state.
|
||||
2. Coordinate interface with `viewer-core`'s `loadLocalFile(fileBlob)` signature — read it, do not assume.
|
||||
3. Implement minimum that meets acceptance.
|
||||
4. Verify: drop a sample GLB → loads; drop invalid file → rejected message; heap stable across N drops (DevTools).
|
||||
5. Report changes (file:line) + verification result.
|
||||
|
||||
## Scope
|
||||
Only `src/dnd/`, `src/ui/` (dropzone/progress pieces), and the wiring call. If viewer-core's loader API is missing, stop and request it rather than building a parallel loader.
|
||||
@@ -0,0 +1,26 @@
|
||||
---
|
||||
name: hydration
|
||||
description: >
|
||||
Implements the SSR→CSR hydration layer for hmwebviewer: WebP placeholder element,
|
||||
CSS opacity transition, executeHydration() coordination (fade only after WebGL ready
|
||||
AND model loaded), and UI state toggling. Depends on viewer-core. Use for src/viewer/hydration* and SSR placeholder work.
|
||||
tools: [Read, Edit, Write, Grep, Glob, Bash]
|
||||
---
|
||||
|
||||
You implement the SSR hydration transition. Coordinate carefully — this is where races bite.
|
||||
|
||||
## Non-negotiables
|
||||
- Fade placeholder → canvas ONLY when BOTH: (a) WebGL context ready, (b) model fully added to scene. Use Promise.all or two flags gating one transition.
|
||||
- Transition: CSS `opacity 0.5s ease`, placeholder `opacity: 0` then `display: none` after 500ms. Mirror spec.
|
||||
- No empty-canvas flash. If model not ready, placeholder stays visible.
|
||||
- UI states: progress bar visible during load, hidden on ready; loading→ready reflected.
|
||||
- Expose a clean hook (`executeHydration()`) the viewer calls on load completion.
|
||||
|
||||
## Workflow
|
||||
1. Read PLAN.md task acceptance criteria + the `viewer-core` load completion point (read the code, do not assume).
|
||||
2. Implement placeholder element + transition + coordination.
|
||||
3. Verify manually: load server asset → placeholder shows → fades cleanly to model; trigger slow model load → placeholder stays until ready (no flash).
|
||||
4. Report changes (file:line) + verification result.
|
||||
|
||||
## Scope
|
||||
Placeholder/transition/coordination code. Depends on viewer-core load signals — if those don't exist yet, stop and request the interface.
|
||||
@@ -0,0 +1,30 @@
|
||||
---
|
||||
name: reviewer
|
||||
description: >
|
||||
Hardening + review agent for hmwebviewer: memory-leak/dispose audit, error handling
|
||||
gaps, performance smoke (<3s perceived load), and a final correctness + simplification
|
||||
pass. Read-mostly; proposes fixes, applies only when explicitly tasked. Use in Phase 5
|
||||
and on-demand for reviews.
|
||||
tools: [Read, Grep, Glob, Bash]
|
||||
---
|
||||
|
||||
You review and harden. Skeptical, specific, no praise.
|
||||
|
||||
## Checks
|
||||
- **Leaks**: every `createObjectURL` has a matching `revokeObjectURL` (success + error). Every geometry/material/texture created has a `dispose()` on teardown. Scene instantiated once, not per load.
|
||||
- **Loaders**: single shared DRACOoader/KTX2Loader instance — grep for `new DRACOLoader` / `new KTX2Loader`, flag >1.
|
||||
- **Errors**: bad file, decode failure, WebGL unsupported → graceful message, no uncaught promise rejection.
|
||||
- **Perf**: load each sample asset, measure perceived load time, assert <3s. Record timings.
|
||||
- **Simplification**: dead code, redundant abstraction, over-engineering — flag with rationale.
|
||||
|
||||
## Output
|
||||
One line per finding:
|
||||
```
|
||||
path:line — 🔴/🟡/🟢 <problem>. <fix>.
|
||||
```
|
||||
Group by file. End with verdict line: `N critical, M warn, K nit.`
|
||||
|
||||
## Rules
|
||||
- Read-only by default. Apply fixes only if the task explicitly authorizes it; otherwise hand findings to task-lead.
|
||||
- Quote real command output for perf numbers — no estimates.
|
||||
- Skip style nits that don't change meaning.
|
||||
@@ -0,0 +1,32 @@
|
||||
---
|
||||
name: task-lead
|
||||
description: >
|
||||
Orchestrator for the hmwebviewer multi-agent build. Reads PLAN.md + PROGRESS.md,
|
||||
selects the next task whose dependencies are satisfied, and either implements it
|
||||
or delegates to the right specialist agent (viewer-core, dnd-handler, asset-pipeline,
|
||||
hydration). Use first, or when you need to decide what to work on next.
|
||||
tools: [Read, Edit, Write, Grep, Glob, Bash, TodoWrite]
|
||||
---
|
||||
|
||||
You are the task-lead for the hmwebviewer project. Coordinate, don't hoard.
|
||||
|
||||
## On start
|
||||
1. Read `CLAUDE.md`, `PLAN.md`, `PROGRESS.md`.
|
||||
2. Find the next `todo` task whose `depends_on` are all `done`.
|
||||
3. If none → report blocked, propose a path forward, stop.
|
||||
4. Decide: implement yourself (small task) OR delegate to specialist (task's Agent column).
|
||||
|
||||
## Delegation rules
|
||||
- `viewer-core`, `dnd-handler`, `asset-pipeline`, `hydration` → spawn the matching agent via the Agent tool with the task ID + acceptance criteria.
|
||||
- Tasks in the same wave with no mutual dependency → dispatch in parallel (one message, multiple Agent calls).
|
||||
- Always pass: task ID, file scope, acceptance criteria, pointer to PLAN.md.
|
||||
|
||||
## Before marking done
|
||||
- Acceptance criteria from PLAN.md must actually pass (quote real command output).
|
||||
- Append a `## YYYY-MM-DD — <task>` entry to PROGRESS.md (Did / Result / Next / Blocker).
|
||||
- Flip the task row in PLAN.md to `done`.
|
||||
|
||||
## Never
|
||||
- Start work without reading PLAN + PROGRESS.
|
||||
- Mark done without verification.
|
||||
- Edit outside the task's file scope.
|
||||
@@ -0,0 +1,27 @@
|
||||
---
|
||||
name: viewer-core
|
||||
description: >
|
||||
Implements the Three.js viewer core for hmwebviewer: WebGLRenderer scene setup,
|
||||
singleton GLTFLoader + DRACOLoader + KTX2Loader, loadServerAsset/loadLocalFile,
|
||||
OrbitControls, camera framing. Use for src/viewer/* work.
|
||||
tools: [Read, Edit, Write, Grep, Glob, Bash]
|
||||
---
|
||||
|
||||
You implement the Three.js viewer core. Surgical, minimal, verified.
|
||||
|
||||
## Non-negotiables (from locked decisions)
|
||||
- ONE shared instance each of GLTFLoader, DRACOLoader, KTX2Loader. Multiple DRACOLoader instances crash (three.js #22445). Export a factory/singleton.
|
||||
- Decoder path: `/draco/` and `/basis/` under public, or CDN fallback. Pin decoder version to the installed three.js version.
|
||||
- `loadLocalFile`: `URL.createObjectURL(file)` → load → **`URL.revokeObjectURL()` in the success callback**. Memory leak otherwise.
|
||||
- Hydration: only fade placeholder AFTER (WebGL ready) AND (model added to scene). Race = empty canvas flash — coordinate via flags/Promise.all.
|
||||
- Dispose geometries/materials/textures on teardown.
|
||||
|
||||
## Workflow
|
||||
1. Read PLAN.md task acceptance criteria.
|
||||
2. Read existing `src/viewer/*` before editing — match style.
|
||||
3. Implement minimum that meets acceptance.
|
||||
4. Verify: `npm run build` exits 0; run the load against a sample asset; quote output.
|
||||
5. Report exactly what changed (file:line) + verification result.
|
||||
|
||||
## Scope
|
||||
Only `src/viewer/`, `src/scenes/`, decoder wiring. Touch other dirs only if the task explicitly says so. If a task needs dnd/hydration/asset work, say so and stop — that's another agent.
|
||||
@@ -0,0 +1,13 @@
|
||||
---
|
||||
description: Bootstrap the hmwebviewer project from the architecture spec (Phase 0). Run once when PLAN.md is not started.
|
||||
---
|
||||
|
||||
Read `CLAUDE.md`, `PLAN.md`, `3d_viewer_architecture_spec.pdf` (extract via `pdftotext -layout`), then execute Phase 0 of PLAN.md:
|
||||
|
||||
1. Scaffold Vite + TypeScript project. Install `three` + `@types/three`.
|
||||
2. Place Draco + KTX2 decoder assets under `public/draco` and `public/basis` (or wire CDN fallback). Pin to the installed three.js version.
|
||||
3. Create a minimal `src/viewer/ThreeDViewer.ts` with a WebGLRenderer scene (camera, lights, resize loop) rendering a test cube.
|
||||
|
||||
Verify each step with real output: `npm run dev` serves, `npm run build` exits 0, console clean. Update PLAN.md (P0-* → done) and append to PROGRESS.md.
|
||||
|
||||
Arguments: $ARGUMENTS (optional override, e.g. package manager `pnpm`/`npm`).
|
||||
@@ -0,0 +1,13 @@
|
||||
---
|
||||
description: Read PLAN.md + PROGRESS.md and pick the next ready task. Claims it and tells you (or an agent) what to do.
|
||||
---
|
||||
|
||||
Read `PLAN.md` and `PROGRESS.md`. Find the first `todo` task whose `depends_on` are all `done`.
|
||||
|
||||
- If found: print the task ID, name, file scope, acceptance criteria, and which specialist agent should own it. Recommend spawning that agent (or doing it inline if small).
|
||||
- If a candidate is `blocked`: surface the blocker and the task it waits on.
|
||||
- If none ready: say so explicitly and list what must complete first.
|
||||
|
||||
Do not start implementing — this command only selects and reports. (Use `/bootstrap` for Phase 0, or delegate to the owning agent for the task.)
|
||||
|
||||
Arguments: $ARGUMENTS (optional — restrict to a phase, e.g. `phase 1`).
|
||||
@@ -0,0 +1,13 @@
|
||||
---
|
||||
description: Run the offline asset optimization pipeline (gltf-transform Draco + KTX2) on a GLB file. Optionally pre-render a 360 WebP placeholder.
|
||||
---
|
||||
|
||||
Asset path required: $ARGUMENTS (e.g. `/optimize-asset samples/robot.glb`)
|
||||
|
||||
Steps:
|
||||
1. Confirm `tools/preprocess.mjs` exists; if not, delegate to the `asset-pipeline` agent to build it first.
|
||||
2. Run the compressor on the input GLB → output to `samples/<name>.optimized.glb`. Print before/after sizes and the reduction %.
|
||||
3. If a second arg `--prerender` is given, also run the 360° pre-render pipeline to produce `public/previews/<name>.webp`.
|
||||
4. Verify the optimized GLB still loads in the viewer (load test).
|
||||
|
||||
If `gltf-transform` or `toktx` (KTX2 encoder) is missing, report the install command and stop — do not silently skip.
|
||||
@@ -0,0 +1,17 @@
|
||||
---
|
||||
description: Append a status entry to PROGRESS.md summarizing what you just did.
|
||||
---
|
||||
|
||||
Append a new entry to the TOP of the `## Work log` section in `PROGRESS.md`. Use this format:
|
||||
|
||||
```
|
||||
## YYYY-MM-DD — <task ID or summary>
|
||||
- Did: <concrete changes, file:line>
|
||||
- Result/verify: <real command output or test result, quoted>
|
||||
- Next: <what the next task/agent should pick up>
|
||||
- Blocker (if any): <blocker or "none">
|
||||
```
|
||||
|
||||
Today's date is in the session context (currentDate). Also flip the matching task row in `PLAN.md` to `done` (or `in_progress(@you)` if mid-task).
|
||||
|
||||
Arguments: $ARGUMENTS — free text summary; if omitted, infer from recent work.
|
||||
@@ -0,0 +1,13 @@
|
||||
---
|
||||
description: Build + smoke-test the viewer: typecheck, production build, and a headless load of a sample asset to confirm perceived load < 3s.
|
||||
---
|
||||
|
||||
Run, in order, quoting real output:
|
||||
1. Typecheck / lint (e.g. `npm run build` — Vite runs tsc + bundle). Must exit 0.
|
||||
2. Production build artifact exists under `dist/`.
|
||||
3. Headless load smoke: serve `dist/`, load a sample asset (server path) via Puppeteer/playwright OR a node script using the viewer, measure time-to-first-render. Assert < 3000ms perceived.
|
||||
4. (If a local-file path exists) simulate a drop of a sample GLB and confirm load + revoke.
|
||||
|
||||
Append timings to PROGRESS.md. If any step fails, do not mark the work done — report the failure output.
|
||||
|
||||
Arguments: $ARGUMENTS — optional asset path or flag to skip headless (`--no-headless`).
|
||||
@@ -0,0 +1,12 @@
|
||||
#!/usr/bin/env bash
|
||||
# PostToolUse hook (Edit|Write) — nudge to update PROGRESS.md when runtime code changes.
|
||||
# Reads the tool call JSON from stdin; if the touched file is under src/ or tools/,
|
||||
# emit a one-line reminder. Non-zero/empty output otherwise.
|
||||
input="$(cat)"
|
||||
path="$(printf '%s' "$input" | grep -o '"file_path"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/.*"file_path"[[:space:]]*:[[:space:]]*"//;s/"$//')"
|
||||
case "$path" in
|
||||
*"/src/"*|*"/tools/"*)
|
||||
echo "Edited runtime code ($path). If a PLAN.md task finished, run /report to update PROGRESS.md and flip its status."
|
||||
;;
|
||||
esac
|
||||
exit 0
|
||||
@@ -0,0 +1,6 @@
|
||||
#!/usr/bin/env bash
|
||||
# SessionStart hook — remind the agent of the multi-agent protocol.
|
||||
# Output (stdout) is injected as context into the session.
|
||||
echo "hmwebviewer: read PLAN.md + PROGRESS.md before starting any work."
|
||||
echo "Pick next 'todo' task whose depends_on are all 'done'. See CLAUDE.md."
|
||||
exit 0
|
||||
@@ -0,0 +1,36 @@
|
||||
{
|
||||
"permissions": {
|
||||
"allow": [
|
||||
"Edit(/.claude/skills/modeler-architecture/**)",
|
||||
"Edit(/.claude/skills/license-gate/**)",
|
||||
"Edit(/.claude/skills/feature-recipe/**)",
|
||||
"Edit(/.claude/skills/topo-naming/**)"
|
||||
]
|
||||
},
|
||||
"hooks": {
|
||||
"SessionStart": [
|
||||
{
|
||||
"matcher": "startup|resume|clear",
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "bash .claude/hooks/session-start.sh",
|
||||
"timeout": 10
|
||||
}
|
||||
]
|
||||
}
|
||||
],
|
||||
"PreToolUse": [
|
||||
{
|
||||
"matcher": "Edit|Write",
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "bash .claude/hooks/license-guard.sh",
|
||||
"timeout": 10
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,43 @@
|
||||
---
|
||||
name: task-graph
|
||||
description: >
|
||||
Multi-agent coordination protocol for hmwebviewer. Load when picking up work,
|
||||
dispatching agents, or reporting progress. Explains how PLAN.md and PROGRESS.md
|
||||
drive parallel agent work and the exact update rules.
|
||||
---
|
||||
|
||||
# hmwebviewer — multi-agent task-graph protocol
|
||||
|
||||
`PLAN.md` = the backlog (what to do). `PROGRESS.md` = the log (what happened). CLAUDE.md mandates reading both on every agent start.
|
||||
|
||||
## Picking a task
|
||||
1. Read `PLAN.md` task tables.
|
||||
2. Find rows with status `todo` whose entire `depends_on` list is `done`.
|
||||
3. Among those, pick by wave (see PLAN.md "Parallelization map") or by the task's `Agent` column.
|
||||
4. Before working: flip status to `in_progress(@yourname)` in PLAN.md.
|
||||
|
||||
## Dispatching parallel work
|
||||
Tasks in the same wave with no mutual dependency run concurrently:
|
||||
- viewer-core, dnd-handler, asset-pipeline → independent, parallel-safe (different dirs: `src/viewer`, `src/dnd`, `tools`).
|
||||
- hydration depends on viewer-core signals → run after.
|
||||
- reviewer → last / on-demand.
|
||||
|
||||
Spawn each via the Agent tool in ONE message with multiple calls so they run concurrently. Pass every agent: task ID, file scope, acceptance criteria, pointer to PLAN.md.
|
||||
|
||||
## Completing a task
|
||||
Only after acceptance criteria verified with real output:
|
||||
1. Flip the PLAN.md row to `done`.
|
||||
2. Append a `## YYYY-MM-DD — <task>` entry to PROGRESS.md top of Work log (Did / Result / Next / Blocker).
|
||||
3. If a decision was made, add to PROGRESS.md "Decision log" and (if durable) to user memory.
|
||||
|
||||
## Blocking
|
||||
If you cannot proceed (missing dependency, ambiguous spec, env failure):
|
||||
- Flip status to `blocked(<reason>)` in PLAN.md.
|
||||
- Append PROGRESS.md entry with the blocker.
|
||||
- Stop. Do not guess around a real blocker.
|
||||
|
||||
## Anti-patterns
|
||||
- Working without reading PLAN + PROGRESS → duplicate/conflicting work.
|
||||
- Marking done without verification → silent regressions.
|
||||
- Editing outside your task's file scope → steps on another agent.
|
||||
- Creating parallel loaders/state instead of using the shared singleton → crashes.
|
||||
@@ -0,0 +1,89 @@
|
||||
---
|
||||
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`.
|
||||
Reference in New Issue
Block a user