Sroberge/1 0

.claude/docs/RENDERING_OPTIMIZATIONS.md

@@ -0,0 +1,203 @@
+# WebGL Shader Materials & Rendering Patterns
+
+This document describes the shader material architecture and rendering patterns used in the WebGL viewer. All materials use GLSL ES 3.0 (WebGL 2).
+
+## Material Architecture
+
+The `Materials` singleton (`materials.ts`) owns and manages all material instances. It exposes a public `IMaterials` interface for property configuration and keeps system materials (mask, outline, merge) internal.
+
+### Material Inventory
+
+| Material | File | Purpose | GLSL Version |
+|----------|------|---------|--------------|
+| **StandardMaterial** | `standardMaterial.ts` | Default opaque/transparent rendering. Patches Three.js Lambert shader via `onBeforeCompile` to inject palette coloring, visibility, and section strokes. | GLSL1 (Three.js managed) |
+| **ModelMaterial** | `modelMaterial.ts` | Fast rendering mode. Custom shader using screen-space derivative normals and pre-normalized lighting. | GLSL3 |
+| **GhostMaterial** | `ghostMaterial.ts` | Transparent fill for hidden/ghosted elements in isolation mode. | GLSL3 |
+| **PickingMaterial** | `pickingMaterial.ts` | GPU object picking. Outputs packed element ID, depth, and surface normal to Float32 render target. | GLSL3 |
+| **MaskMaterial** | `maskMaterial.ts` | Selection mask pass. Writes depth only for selected elements; non-selected vertices are clipped. | GLSL3 |
+| **OutlineMaterial** | `outlineMaterial.ts` | Post-process edge detection on depth buffer. Outputs outline intensity to RedFormat texture. | GLSL3 |
+| **MergeMaterial** | `mergeMaterial.ts` | Final compositing pass. Blends scene texture with outline texture using configurable color. | GLSL3 |
+| **TransferMaterial** | `transferMaterial.ts` | Simple texture passthrough (blit). | GLSL3 |
+
+### MaterialSet
+
+`MaterialSet` (`materialSet.ts`) groups materials by role: `opaque`, `transparent`, and `hidden` (ghost). The `applyMaterial()` helper in `materials.ts` resolves a `MaterialSet` into the correct `THREE.Material` or `[visible, hidden]` array for a given mesh based on its `userData.transparent` flag.
+
+### Color Palette System
+
+All scene materials (StandardMaterial, ModelMaterial) use a shared color palette texture for submesh coloring. The `Materials` singleton owns a single 128x128 RGBA `DataTexture` (16,384 colors max) and distributes it to all materials via `setSubmeshColorTexture()`.
+
+The palette is built by `colorPalette.ts`:
+- Extracts unique colors from submesh material data
+- If unique colors exceed 16,384, applies uniform quantization (25 levels per channel = 15,625 max)
+- Packs into a `Float32Array` for texture upload
+
+Shaders look up colors using `texelFetch` with integer coordinates derived from a per-vertex `submeshIndex` attribute:
+
+```glsl
+int x = int(submeshIndex) % 128;
+int y = int(submeshIndex) / 128;
+vColor = texelFetch(submeshColorTexture, ivec2(x, y), 0).rgb;
+```
+
+Instance color overrides are blended using the `colored` attribute (1 = instance color, 0 = palette color):
+
+```glsl
+#ifdef USE_INSTANCING
+  vColor = colored * instanceColor + (1.0 - colored) * vColor;
+#endif
+```
+
+---
+
+## Shader Patterns
+
+### Pre-Normalized Light Direction (ModelMaterial)
+
+The light direction is a compile-time constant, avoiding per-fragment `normalize()`:
+
+```glsl
+// (sqrt(2), sqrt(3), sqrt(5)) normalized: magnitude = sqrt(10)
+const vec3 LIGHT_DIR = vec3(0.447214, 0.547723, 0.707107);
+float light = dot(normal, LIGHT_DIR);
+light = 0.5 + (light * 0.5); // Remap to [0.5, 1.0]
+```
+
+### Pre-Divided Opacity (GhostMaterial)
+
+The ghost opacity uniform stores the final shader value directly (`7/255 = 0.0275`), so the fragment shader uses it as-is without per-fragment division:
+
+```glsl
+fragColor = vec4(fillColor, opacity);
+```
+
+The `GhostMaterial` class getter/setter expose the raw value without conversion.
+
+### Vertex Shader Early Culling
+
+All visibility-aware materials (Ghost, Model, Mask, Picking) use the same pattern to cull invisible geometry in the vertex shader by placing vertices behind the near plane:
+
+```glsl
+if (ignore > 0.0) {
+  gl_Position = vec4(0.0, 0.0, -2.0, 1.0);
+  return;
+}
+```
+
+This is faster than fragment `discard` because no fragments are generated for clipped triangles.
+
+### Static Temp Vector Reuse (PickingMaterial)
+
+The `PickingMaterial` class uses a static `THREE.Vector3` for camera direction updates, avoiding per-frame allocations:
+
+```typescript
+private static _tempDir = new THREE.Vector3()
+
+updateCamera(camera: THREE.Camera): void {
+  camera.getWorldDirection(PickingMaterial._tempDir)
+  this.three.uniforms.uCameraPos.value.copy(camera.position)
+  this.three.uniforms.uCameraDir.value.copy(PickingMaterial._tempDir)
+}
+```
+
+### Picking Output Format
+
+The picking material encodes four values into a Float32 RGBA render target:
+
+| Channel | Value | Encoding |
+|---------|-------|----------|
+| R | Element ID | `uintBitsToFloat(packedId)` where `packedId = (vimIndex << 24) \| elementIndex` |
+| G | Depth | Distance along camera direction (0 = miss) |
+| B | Normal X | Screen-space derivative normal |
+| A | Normal Y | Screen-space derivative normal |
+
+Normal Z is reconstructed as `sqrt(1 - x^2 - y^2)`, always positive since the normal faces the camera.
+
+### Section Stroke Rendering (StandardMaterial)
+
+The standard material renders colored strokes where geometry intersects clipping planes. The stroke width scales with fragment depth using a configurable falloff exponent:
+
+```glsl
+float thick = pow(vFragDepth, sectionStrokeFalloff) * sectionStrokeWidth;
+```
+
+Perpendicular surfaces are excluded by comparing the surface normal against the clipping plane normal.
+
+---
+
+## Shader Optimization Principles
+
+### General Rules
+
+1. **Move computations out of shaders** whenever possible:
+   - Constants: Pre-compute in JavaScript or as shader `const`
+   - Per-frame: Compute in uniforms
+   - Per-vertex: Keep in vertex shader
+   - Per-fragment: Only when necessary
+
+2. **Avoid per-fragment operations:**
+   - `normalize()` on constants
+   - Divisions (use pre-multiplied reciprocals)
+   - Expensive math functions (`sqrt`, `pow`, `sin`, `cos`)
+   - Prefer simple arithmetic (`+`, `-`, `*`)
+   - Prefer dot products, cross products
+   - Texture lookups are GPU-cached and relatively cheap
+
+3. **Memory access patterns:**
+   - `texelFetch()` for indexed access (faster than `texture()` when no filtering needed)
+   - `uniform` reads are GPU-cached
+   - `in` (varying) interpolation cost depends on geometry complexity
+
+4. **Branching:**
+   - Early returns in vertex shader skip all subsequent work
+   - Fragment shader branches may execute both paths on GPU (warp divergence)
+
+### Relative Cost of Operations
+
+| Operation | Cost | Example |
+|-----------|------|---------|
+| Uniform read | 1x | `uniform float value` |
+| Texture fetch | 2-4x | `texture(sampler, uv)` |
+| Addition/Subtraction | 1x | `a + b` |
+| Multiplication | 1x | `a * b` |
+| Division | 3-5x | `a / b` |
+| `normalize()` | 10-15x | `sqrt` + 3 divides |
+| `sin()`, `cos()` | 8-12x | Approximated in hardware |
+
+---
+
+## GLSL3 Syntax Reference
+
+All custom shader materials use `glslVersion: THREE.GLSL3`. The StandardMaterial uses Three.js managed GLSL1 (via `onBeforeCompile` patching).
+
+| GLSL1 | GLSL3 |
+|-------|-------|
+| `attribute` | `in` (vertex shader) |
+| `varying` | `out` (vertex), `in` (fragment) |
+| `gl_FragColor` | `out vec4 fragColor` |
+| `texture2D()` | `texture()` |
+| N/A | `texelFetch()` for indexed access |
+
+---
+
+## References
+
+### Material Files
+
+- `src/vim-web/core-viewers/webgl/loader/materials/standardMaterial.ts`
+- `src/vim-web/core-viewers/webgl/loader/materials/modelMaterial.ts`
+- `src/vim-web/core-viewers/webgl/loader/materials/ghostMaterial.ts`
+- `src/vim-web/core-viewers/webgl/loader/materials/pickingMaterial.ts`
+- `src/vim-web/core-viewers/webgl/loader/materials/maskMaterial.ts`
+- `src/vim-web/core-viewers/webgl/loader/materials/outlineMaterial.ts`
+- `src/vim-web/core-viewers/webgl/loader/materials/mergeMaterial.ts`
+- `src/vim-web/core-viewers/webgl/loader/materials/transferMaterial.ts`
+- `src/vim-web/core-viewers/webgl/loader/materials/materials.ts`
+- `src/vim-web/core-viewers/webgl/loader/materials/materialSet.ts`
+- `src/vim-web/core-viewers/webgl/loader/materials/colorPalette.ts`
+
+### Related Documentation
+
+- [CLAUDE.md](../../CLAUDE.md) - Main project documentation
+- [INPUT.md](./INPUT.md) - Input system architecture
+- [optimization.md](./optimization.md) - Loading pipeline performance

.claude/docs/optimization.md

@@ -0,0 +1,143 @@
+# VIM Loading Performance
+
+How the WebGL loading pipeline works and how to profile it.
+
+## Loading Phases
+
+VIM file loading consists of four sequential phases:
+
+1. **Network/Parsing** - Fetch and parse BFast container (G3d geometry, VimDocument, ElementMapping)
+2. **Geometry Building** - Create Three.js meshes from G3d data (primary optimization target)
+3. **GPU Upload** - Transfer geometry buffers to GPU
+4. **Rendering** - First frame render
+
+## Mesh Building Pipeline
+
+```
+VimMeshFactory.add(G3dSubset)
+  |-- Split by instance count: <=5 instances -> merged, >5 -> instanced
+  |-- Merged path (InsertableMeshFactory)
+  |   |-- G3dSubset.chunks(16M indices) -- chunk large meshes
+  |   |-- Create InsertableMesh per chunk
+  |   |-- insertFromG3d() -- bake matrices, build geometry
+  |   +-- scene.addMesh() -- register submeshes
+  +-- Instanced path (InstancedMeshFactory)
+      |-- Create THREE.InstancedMesh per unique geometry
+      |-- setMatrices() -- GPU instancing matrices
+      +-- scene.addMesh() -- register submeshes
+```
+
+**Chunk Size**: 16M indices (not vertices) per merged mesh. This threshold was chosen because GPU picking eliminates the need for CPU raycast traversal, removing the constraint that kept chunk sizes small.
+
+## Current Performance Patterns
+
+### Lazy Element3D Creation
+
+Element3D objects are **not** created during mesh loading. When `scene.addMesh()` is called, it only builds an `instance -> submesh[]` map. Element3D objects are created lazily on first access via `vim.getElement()` or `vim.getElementFromIndex()`.
+
+This avoids constructing thousands of full Element3D objects during the loading hot path when most will never be accessed.
+
+**Key file**: `src/vim-web/core-viewers/webgl/loader/scene.ts` -- `registerSubmesh()` only populates `_instanceToMeshes`.
+
+### Buffer Reuse in Hot Loops
+
+In `InsertableGeometry.insertFromG3d()`, which iterates over every vertex and index in merged meshes:
+
+- **Matrix buffer**: A single `Float32Array(16)` is allocated once outside the per-instance loop, then reused for each instance's transform matrix. This avoids per-instance allocation in a loop that runs thousands of times.
+- **Color index hoisting**: The `submeshColor` lookup (`g3d.submeshColor[sub]`) is hoisted out of the inner per-index loop and computed once per submesh.
+- **Direct array access**: Typed array references (`indices`, `submeshIndices`) are assigned once outside loops to avoid repeated property lookups.
+
+**Key file**: `src/vim-web/core-viewers/webgl/loader/progressive/insertableGeometry.ts`
+
+### Color Palette System
+
+The color palette optimization reduces GPU memory by replacing per-vertex color attributes with a texture-based lookup. It is **always enabled**.
+
+Two components:
+1. **`submeshColor: Uint16Array`** - Always present. Maps each submesh index to a color palette index.
+2. **`colorPalette: Float32Array | undefined`** - A flat RGB array of unique colors, used as a texture. Set to `undefined` only if the model exceeds 16,384 unique colors (128x128 texture limit).
+
+If a model has too many unique colors, quantization is applied (25 levels per channel, yielding up to 15,625 distinct colors) to bring the palette within limits. If quantization still exceeds the limit, the palette is disabled (`undefined`) and the shader falls back to per-vertex colors.
+
+**Key files**:
+- `src/vim-web/core-viewers/webgl/loader/materials/colorPalette.ts` - Palette building with quantization
+- `src/vim-web/core-viewers/webgl/loader/progressive/mappedG3d.ts` - `MappedG3d` type definition
+- `src/vim-web/core-viewers/webgl/loader/progressive/insertableGeometry.ts` - `submeshColor` lookup in geometry building
+
+## How to Profile
+
+### Timing Instrumentation Pattern
+
+Add cumulative timing to identify hotspots. This pattern collects timing across many calls (e.g., thousands of mesh builds) rather than measuring a single call:
+
+```typescript
+class SomeFactory {
+  private static _cumulativeTiming = {
+    phase1: 0,
+    phase2: 0,
+    calls: 0
+  }
+
+  someMethod() {
+    const t0 = performance.now()
+    // ... phase 1 work
+    const t1 = performance.now()
+    SomeFactory._cumulativeTiming.phase1 += t1 - t0
+
+    // ... phase 2 work
+    const t2 = performance.now()
+    SomeFactory._cumulativeTiming.phase2 += t2 - t1
+
+    SomeFactory._cumulativeTiming.calls++
+  }
+
+  static logAndResetTiming(label: string) {
+    const t = SomeFactory._cumulativeTiming
+    console.log(`[SomeFactory] ${label} breakdown (${t.calls} calls):`)
+    console.log(`  Phase 1: ${t.phase1.toFixed(2)}ms`)
+    console.log(`  Phase 2: ${t.phase2.toFixed(2)}ms`)
+    // Reset for next batch
+    t.phase1 = 0
+    t.phase2 = 0
+    t.calls = 0
+  }
+}
+```
+
+### Profiling Steps
+
+1. **Add timing instrumentation** using the cumulative pattern above
+2. **Look for gaps** - If outer timing is much larger than the sum of inner phases, the overhead between phases is the real bottleneck
+3. **Use Chrome DevTools** - Performance tab, look for long tasks and GC pauses
+4. **Test on real models** - Performance characteristics vary significantly by model size and complexity
+5. **Compare before/after** - Always measure the impact of changes
+
+## Optimization Principles
+
+### What to Optimize
+
+1. **Eliminate unnecessary work** - Deferring or skipping work entirely yields the largest gains (e.g., lazy Element3D creation)
+2. **Hot loops** - Code executed millions of times (vertex/index loops in geometry building)
+3. **Allocations in loops** - Reuse buffers, minimize GC pressure
+4. **Cache locality** - Copy data to local arrays before tight loops
+
+### What NOT to Optimize (Diminishing Returns)
+
+1. **Three.js internals** - `BufferGeometry` creation, `computeBoundingBox()` are already well-optimized
+2. **One-time operations** - Setup code executed once per mesh type
+3. **Already-fast code** - Operations under a few milliseconds with no clear improvement path
+4. **Micro-optimizations without measurement** - Always measure before and after
+
+### Red Flags to Investigate
+
+- **Outer timing >> inner timing** - Indicates hidden overhead between instrumented phases
+- **Per-item overhead > 0.1ms** - For operations on thousands of items, even small overhead compounds
+- **Unexpected allocations** - Check Chrome DevTools Performance tab for GC pauses during geometry building
+
+## References
+
+- **Loading Pipeline**: [CLAUDE.md -- Loading Pipeline](../../CLAUDE.md)
+- **Mesh Building**: `src/vim-web/core-viewers/webgl/loader/progressive/vimMeshFactory.ts`
+- **Scene Management**: `src/vim-web/core-viewers/webgl/loader/scene.ts`
+- **Element3D**: `src/vim-web/core-viewers/webgl/loader/element3d.ts`
+- **Color Palette**: `src/vim-web/core-viewers/webgl/loader/materials/colorPalette.ts`