timmy-config/docs/glitch-detection.md

3D World Glitch Detection — Matrix Scanner

Reference: timmy-config#491 Label: gemma-4-multimodal Version: 0.1.0

Overview

The Matrix Glitch Detector scans 3D web worlds for visual artifacts and rendering anomalies. It uses browser automation to capture screenshots from multiple camera angles, then sends them to a vision AI model for analysis against a library of known glitch patterns.

Detected Glitch Categories

Category	Severity	Description
Floating Assets	HIGH	Objects not grounded — hovering above surfaces
Z-Fighting	MEDIUM	Coplanar surfaces flickering/competing for depth
Missing Textures	CRITICAL	Placeholder colors (magenta, checkerboard)
Clipping	HIGH	Geometry passing through other objects
Broken Normals	MEDIUM	Inside-out or incorrectly lit surfaces
Shadow Artifacts	LOW	Detached, mismatched, or acne shadows
LOD Popping	LOW	Abrupt level-of-detail transitions
Lightmap Errors	MEDIUM	Dark splotches, light leaks, baking failures
Water/Reflection	MEDIUM	Incorrect environment reflections
Skybox Seam	LOW	Visible seams at cubemap face edges

Installation

No external dependencies required — pure Python 3.10+.

# Clone the repo
git clone https://forge.alexanderwhitestone.com/Timmy_Foundation/timmy-config.git
cd timmy-config

Usage

Basic Scan

python bin/matrix_glitch_detector.py https://matrix.example.com/world/alpha

Multi-Angle Scan

python bin/matrix_glitch_detector.py https://matrix.example.com/world/alpha \
    --angles 8 \
    --output glitch_report.json

Demo Mode

python bin/matrix_glitch_detector.py --demo

Options

Flag	Default	Description
url	(required)	URL of the 3D world to scan
--angles N	4	Number of camera angles to capture
--output PATH	stdout	Output file for JSON report
--min-severity	info	Minimum severity: info/low/medium/high/critical
--demo	off	Run with simulated detections
--verbose	off	Enable verbose output

Report Format

The JSON report includes:

{
  "scan_id": "uuid",
  "url": "https://...",
  "timestamp": "ISO-8601",
  "total_screenshots": 4,
  "angles_captured": ["front", "right", "back", "left"],
  "glitches": [
    {
      "id": "short-uuid",
      "category": "floating_assets",
      "name": "Floating Chair",
      "description": "Office chair floating 0.3m above floor",
      "severity": "high",
      "confidence": 0.87,
      "location_x": 35.2,
      "location_y": 62.1,
      "screenshot_index": 0,
      "screenshot_angle": "front",
      "timestamp": "ISO-8601"
    }
  ],
  "summary": {
    "total_glitches": 4,
    "by_severity": {"critical": 1, "high": 2, "medium": 1},
    "by_category": {"floating_assets": 1, "missing_textures": 1, ...},
    "highest_severity": "critical",
    "clean_screenshots": 0
  },
  "metadata": {
    "detector_version": "0.1.0",
    "pattern_count": 10,
    "reference": "timmy-config#491"
  }
}

Vision AI Integration

The detector supports any OpenAI-compatible vision API. Set these environment variables:

export VISION_API_KEY="your-api-key"
export VISION_API_BASE="https://api.openai.com/v1"  # optional
export VISION_MODEL="gpt-4o"  # optional, default: gpt-4o

For browser-based capture with browser_vision:

export BROWSER_VISION_SCRIPT="/path/to/browser_vision.py"

Glitch Patterns

Pattern definitions live in bin/glitch_patterns.py. Each pattern includes:

• category — Enum matching the glitch type
• detection_prompts — Instructions for the vision model
• visual_indicators — What to look for in screenshots
• confidence_threshold — Minimum confidence to report

Adding Custom Patterns

from glitch_patterns import GlitchPattern, GlitchCategory, GlitchSeverity

custom = GlitchPattern(
    category=GlitchCategory.FLOATING_ASSETS,
    name="Custom Glitch",
    description="Your description",
    severity=GlitchSeverity.MEDIUM,
    detection_prompts=["Look for..."],
    visual_indicators=["indicator 1", "indicator 2"],
)

Testing

python -m pytest tests/test_glitch_detector.py -v
# or
python tests/test_glitch_detector.py

Architecture

bin/
  matrix_glitch_detector.py  — Main CLI entry point
  glitch_patterns.py         — Pattern definitions and prompt builder
tests/
  test_glitch_detector.py    — Unit and integration tests
docs/
  glitch-detection.md        — This documentation

Limitations

• Browser automation requires a headless browser environment
• Vision AI analysis depends on model availability and API limits
• Placeholder screenshots are generated when browser capture is unavailable
• Detection accuracy varies by scene complexity and lighting conditions