layers/structure.md

Project Structure

Mesh Palettizer - Web application for 3D model texture simplification

Stack

• Runtime: Python 3.10+
• 3D Processing: Trimesh
• Image Processing: Pillow, NumPy, OpenCV
• ML/Clustering: Scikit-learn
• Spatial Indexing: SciPy
• Web Interface: Gradio

Commands

• Web interface: uv run python app.py
• Install: uv sync
• Lint: uv run ruff check .
• Format: uv run black src/

Layout

conversion/
├── CLAUDE.md        # Global context (Tier 0)
├── app.py           # Web interface with Gradio
├── README.md        # Public documentation
├── pyproject.toml   # Dependencies
├── context.md       # Project context (Tier 2)
├── src/             # Core tool - reusable texture palettizer
│   ├── context.md   # Module context (Tier 2)
│   ├── __init__.py  # Main API: convert_meshes()
│   ├── preprocessing/  # Texture detail removal
│   │   ├── __init__.py
│   │   └── simplifier.py # Bilateral filter for artifact removal
│   ├── extraction/  # Color extraction from meshes
│   │   ├── __init__.py
│   │   ├── sampler.py    # Face sampling with area weighting
│   │   └── reader.py     # Texture/material color reading
│   ├── palette/     # Palette generation and mapping
│   │   ├── __init__.py
│   │   ├── quantizer.py  # K-means clustering in LAB space
│   │   ├── mapper.py     # Nearest color mapping via KD-tree
│   │   └── color_space.py # RGB/LAB conversion
│   ├── atlas/       # Texture atlas generation
│   │   ├── __init__.py
│   │   └── builder.py    # Atlas construction with UV mapping
│   └── mesh/        # Mesh transformation
│       ├── __init__.py
│       └── uvmapper.py   # UV remapping to atlas
└── layers/
    └── structure.md # This file (Tier 1)

Architecture

GLB processing with K-means color quantization and configurable palette sizes

• Pattern: Direct transformation pipeline
• Flow: Load meshes → Simplify textures → Sample colors → Quantize to palette → Create atlas → Apply → Export
• Palette sizes: Powers of 2 (8×8=64 colors, 16×16=256, 32×32=1024, etc.)
• State: None - pure transformation
• Optimization: Random sampling, vectorized operations, LAB color space

Entry Points

app.py - Gradio web interface with configurable detail removal sensitivity src.convert_meshes() - Core API with palette generation and detail control