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