AIMesher 🚀

AIMesher is an AI-first, real-time generative 3D editor based on Three.js and a modular patch-based architecture.

Living Wiki

The canonical specifications, architecture, decisions, research, and roadmap are indexed in docs/wiki/README.md.

📦 Project Structure

/project-root
    /src
        /engine
            core.js          # App loop & orchestrator
            renderer.js      # WebGLRenderer configuration
            scene.js         # Scene initialization & lighting
            camera.js        # PerspectiveCamera setup
            controls.js      # OrbitControls setup
            materials.js     # Materials registry & updates
            objects.js       # Geometries & objects registry
            patches.js       # Real-time patch applicator
        /ui
            index.html       # Minimal viewport & UI panel HTML
            styles.css       # Premium styles for the editor interface
            panel.js         # Text prompt interaction and logging
            stop-button.js   # Interruption logic
            timeline.js      # Patch visual history component
        /llm
            harness.js       # Client WebSocket / LLM interface
            agent.md         # Principal agent specifications
            claude.md        # Coherence assistant specifications
            /prompts
                system.md    # Global generation/interruption rules
                generation.md# Prompt templates for raw patch generation
                correction.md# Prompt templates for correction mode
                patches.md   # Patch schemas and instructions
        /api
            server.py        # FastAPI API host & static server
            websocket.py     # WebSocket logic for streaming patches
            /routes
                llm.py       # REST route for LLM API integration
                patches.py   # REST route for managing applied patches
                assets.py    # REST route for serving textures/models
        /assets
            /textures        # Texture files
            /models          # 3D models
            /shaders         # Custom shaders
    /docs
        architecture.md      # Detailed system architecture
        pipeline.md          # Generation pipeline (LLM -> Engine)
        llm-protocol.md      # Communication formats and lifecycle
        realtime-generation.md# Patch streaming design
        patch-format.md      # JSON schema specifications for patches
    package.json             # NPM dependencies & scripts
    README.md                # Quickstart & overview

⚙️ Core Pipeline

1. Generation (Real-time): LLM stream patches over WebSockets. The harness passes these to the engine, which executes actions like adding objects or updating materials.
2. STOP (Interrupt): Clicking "STOP" pauses the engine execution and switches the session context to Correction mode.
3. Correction: The user inspects/describes what's wrong, or the helper agent analyzes, and a correction prompt is compiled for the principal LLM.
4. Reprise: The engine resumes executing modified or corrected patches from the stream.

🚀 Quick Start

Local Setup

1. Install Python dependencies:

   pip install -r requirements.txt

2. Start the API server & frontend:

   python src/api/server.py

3. Open http://localhost:8000 in your web browser.

Docker Setup (Containerized)

1. Build and launch the container with Docker Compose:

   docker-compose up --build

2. The server will start and listen on port 8000.

🎹 Keyboard Shortcuts

3D Manipulation (Gizmos)

• W: Translate (Move) selected object
• E: Rotate selected object
• R: Scale selected object
• Escape: Deselect active object

Viewport Overlays & Rendering

• G: Toggle ground grid helper visibility
• H: Toggle RGB coordinate axes orientation lines
• B: Toggle post-processing bloom glow effect

💾 Project Save & Load

• Save Project (.json): Click to download a JSON file of applied patches.
• Load Project (.json): Select a saved JSON file to reset the scene and progressively replay the construction step-by-step with a 150ms delay.

🧪 Testing

• API End-to-End Tests:

  python src/api/test_e2e.py

• Retopology Unit Tests:

  node src/engine/test_retopology.js