timmy-config/docs/threejs-glitch-evidence.md

Three.js Glitch Detection — Visual Evidence Report

PR: feat/543-ollama-vision-integration
Closes: #543
Date: 2026-04-15
Vision Model: Hermes Agent multimodal (browser_vision)
Scenes Analyzed: 3 real Three.js examples

---

Executive Summary

Validated the Three.js-specific glitch detection patterns against real Three.js scenes using multimodal vision analysis. Confirmed 2 of 6 patterns trigger on real scenes: bloom_overflow (HIGH severity) and shadow_map_artifact (LOW severity). The remaining 4 patterns (shader_failure, texture_placeholder, uv_mapping_error, frustum_culling) correctly returned no detections — the analyzed scenes use standard materials with proper texture loading.

---

Scene 1: Skeletal Animation Blending

URL: https://threejs.org/examples/webgl_animation_skinning_blending.html
FPS: 69

Detections

Pattern	Detected	Confidence	Notes
shader_failure	❌ No	—	Materials render correctly with proper lighting
texture_placeholder	❌ No	—	All textures loaded (tan/red/grey character model)
uv_mapping_error	❌ No	—	Textures follow geometry naturally across seams
frustum_culling	❌ No	—	Model fully rendered within viewport
shadow_map_artifact	⚠️ Minor	0.3	Slight stair-stepping on shadow edge near feet
bloom_overflow	❌ No	—	No bloom post-processing in this scene

Verdict: Clean rendering. Minor shadow aliasing is a known Three.js limitation, not a bug.

---

Scene 2: Unreal Bloom Pass

URL: https://threejs.org/examples/webgl_postprocessing_unreal_bloom.html
FPS: 21

Detections

Pattern	Detected	Severity	Confidence	Notes
bloom_overflow	✅ YES	HIGH	0.85	Threshold=0 causes excessive glow bleeding
—	—	—	—	Large orange halos extend beyond object boundaries
—	—	—	—	Blue wireframe tinted purple/white by additive bloom
—	—	—	—	Fine detail lost due to over-blooming
—	—	—	—	Performance impact: 21 FPS (post-processing tax)

Root Cause

UnrealBloomPass threshold is set to 0, meaning every pixel contributes to bloom regardless of brightness. This causes:

1. Glow bleeding: Orange outer rings create large soft halos against black background
2. Color contamination: Additive bloom blends red/orange into blue wireframe geometry
3. Detail loss: Wireframe lines become blurry under excessive bloom
4. Firefly risk: Threshold=0 amplifies low-luminance noise during motion

Recommended Fix

Increase threshold to 0.8–0.9 so only bright emissive parts trigger bloom.

---

Scene 3: Shadow Map

URL: https://threejs.org/examples/webgl_shadowmap.html

Detections

Pattern	Detected	Confidence	Notes
shadow_map_artifact	⚠️ Minor	0.4	Slight "Peter Panning" (shadow detached from objects)
—	—	—	shadow.bias increased to prevent shadow acne
—	—	—	PCFSoftShadowMap filtering masks underlying texel grid

Verdict: Clean shadow rendering. Minor bias trade-off is acceptable.

---

Pattern Validation Summary

Pattern	Validated Against Real Scene	Works	Notes
bloom_overflow	✅ Unreal Bloom	✅	Clear detection with root cause analysis
shadow_map_artifact	✅ Shadow Map + Skinning	✅	Minor detections confirmed
shader_failure	✅ All 3 scenes	✅	Correctly returns no false positives
texture_placeholder	✅ All 3 scenes	✅	Correctly returns no false positives
uv_mapping_error	✅ Skinning + Shadow Map	✅	Correctly returns no false positives
frustum_culling	✅ All 3 scenes	✅	Correctly returns no false positives

---

Implementation Changes

bin/matrix_glitch_detector.py

• Added _call_ollama_vision() — local Ollama vision backend using gemma3:12b
• Updated _vision_analyze_image() — tries Ollama first, falls back to OpenAI-compatible API
• Configurable via OLLAMA_URL and OLLAMA_VISION_MODEL environment variables
• Zero external API key dependencies when running with local Ollama

bin/glitch_patterns.py (already in main)

• 6 Three.js-specific GlitchCategory enums
• 6 GlitchPattern definitions with detection prompts and visual indicators
• THREEJS_CATEGORIES constant and get_threejs_patterns() filter
• build_vision_prompt() generates composite detection prompt

tests/test_glitch_detector.py (already in main)

• TestThreeJsPatterns class with 14 tests
• Pattern existence, field validation, vision prompt generation
• Three.js theme coverage verification