initial commit

.claude/commands/nourish.md

@@ -0,0 +1,51 @@
+# 🍃 /nourish
+
+Complete conversation by updating context and applying cleanup.
+
+## Auto-Loaded Context:
+
+@CLAUDE.md
+@layers/structure.md
+@layers/context-template.md
+
+User arguments: "$ARGUMENTS"
+
+## Steps
+
+### 1. Identify Changes
+
+- Detect modified, added, or deleted files in conversation
+- Map changes to their parent folders and components
+
+### 2. Update Context Chain
+
+Traverse upward through context tiers (see CLAUDE.md):
+
+- **Tier 2**: Update relevant `context.md` files to reflect current code state
+- **Tier 1**: Update `layers/structure.md` if structure/commands/stack changed
+- Follow all rules from CLAUDE.md, especially "No History" principle
+
+### 3. Apply Cleanup
+
+Fix obvious issues encountered:
+
+- Remove comments; code should be self-explanatory without comments
+- Remove dead code and unused files
+- Consolidate duplicate patterns
+- Apply CLAUDE.md principles (simplicity, reuse, single responsibility)
+
+### 4. Verify
+
+- Context accurately reflects current state
+- Project is leaner or same size as before
+- No history references in code or context
+
+## Output
+
+Report conversation completion: updated context files and improvements made.
+
+## Guidelines
+
+- When updating context, don't over-specify implementation details
+- If changes were internal (e.g. business logic), it may not be necessary to update context
+- Context should be even shorter after updates, avoiding context rot

.claude/commands/peel.md

@@ -0,0 +1,34 @@
+# 🧄 /peel
+
+Load relevant context for the current conversation.
+
+## Auto-Loaded Context:
+
+@CLAUDE.md
+@layers/structure.md
+
+User arguments: "$ARGUMENTS"
+
+## Steps
+
+### 1. Parse Work Area
+
+- Analyze user request or arguments
+- Determine relevant components or features
+- Assess required context depth
+
+### 2. Load Targeted Context
+
+- Read relevant `context.md` files for identified areas
+- Skip unrelated component contexts to minimize tokens
+
+### 3. Confirm Scope
+
+- Brief summary of loaded context
+- State understanding of work focus
+- Note any assumptions made
+
+## Guidelines
+
+- Load only what's needed for the current task
+- Defer code reading until necessary

.claude/commands/plant.md

@@ -0,0 +1,41 @@
+# 🌱 /plant
+
+Initialize context management structure for the project.
+
+## Auto-Loaded Context:
+
+@CLAUDE.md
+@layers/structure.md
+@layers/context-template.md
+
+User arguments: "$ARGUMENTS"
+
+## Steps
+
+### 1. Analyze Project
+
+- Scan technology stack, build tools, directory structure
+- Identify major components and entry points
+- Understand existing patterns and conventions
+
+### 2. Fill Core Templates
+
+- Update `CLAUDE.md` with project-specific details
+- Complete `layers/structure.md` with actual stack, commands, layout
+- Remove template placeholders
+
+### 3. Create Component Context
+
+- Generate `context.md` files for major folders using templates
+- Document purpose, scope, dependencies for each component
+- Place in appropriate directories
+
+### 4. Validate
+
+- Ensure coverage of main components
+- Check that context hierarchy makes sense
+- Verify no placeholder text remains
+
+## Output
+
+List created/updated files by tier and any areas needing attention.

.gitattributes

@@ -0,0 +1,2 @@
+*.glb filter=lfs diff=lfs merge=lfs -text
+*.gltf filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,68 @@
+# Environment variables
+.env
+.env.local
+.env.*.local
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.egg
+*.egg-info/
+dist/
+build/
+eggs/
+.eggs/
+*.manifest
+*.spec
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+env/
+
+# Testing
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+.nox/
+*.cover
+.hypothesis/
+
+# Project
+input/
+output/
+dev/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store
+
+# Logs
+*.log
+pip-log.txt
+
+# Blender
+*.blend1
+*.blend2
+
+# Temporary files
+*.tmp
+*.bak
+.cache/
+temp/
+tmp/
+
+.ruff_cache/
+.claude/settings.local.json
+
+# UV specific
+uv.lock

.python-version

@@ -0,0 +1 @@
+3.10

CLAUDE.md

@@ -0,0 +1,36 @@
+# AI Context - Working Agreement
+
+<project-description>
+Mesh Palettizer - A web application for simplifying 3D model textures using optimized color palettes. Processes GLB/GLTF models to create clean, palettized textures for stylized rendering and game development.
+</project-description>
+
+**Required**: Read [layers/structure.md](layers/structure.md) before proceeding with any task
+
+## Context Management System
+
+- **Tier 0 — global**: `CLAUDE.md` (root). Global standards and system overview
+- **Tier 1 — project**: `layers/structure.md`. Project map (stack, commands, layout, entry points)
+- **Tier 2 — folder context**: `context.md` in any folder; one per folder; explains purpose/structure of that folder
+- **Tier 3 — implementation**: Code files (scripts)
+
+## Rules
+
+- **Priority**: Your number one priority is to manage your own context; always load appropriate context before doing anything else
+- **No History**: CRITICAL - Code and context must NEVER reference their own history. Write everything as the current, final state. Never include comments like "changed from X to Y" or "previously was Z". This is a severe form of context rot
+- **Simplicity**: Keep code simple, elegant, concise, and readable
+- **Structure**: Keep files small and single-responsibility; separate concerns (MVC/ECS as appropriate)
+- **Reuse**: Reuse before adding new code; avoid repetition
+- **Comments**: Code should be self-explanatory without comments; use concise comments only when necessary
+- **State**: Single source of truth; caches/derivations only
+- **Data**: Favor data-driven/declarative design
+- **Fail Fast**: Make bugs immediately visible rather than hiding them; favor simplicity over defensive patterns
+- **Backwards Compatibility**: Unless stated otherwise, favor simplicity over backwards compatibility; the design rules above should make breaking changes easy to trace and fix
+
+## Security
+
+- **Inputs & secrets**: Validate inputs; secrets only in env; never log sensitive data
+- **Auth**: Gateway auth; server-side token validation; sanitize inputs
+
+## Tools
+
+- **Context7**: Use as needed to fetch documentation

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Dylan Ebert
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,13 @@
+---
+title: MeshPalettizer
+emoji: 😻
+colorFrom: blue
+colorTo: purple
+sdk: gradio
+sdk_version: 5.46.1
+app_file: app.py
+pinned: false
+short_description: Convert textured meshes to palettized meshes
+---
+
+Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference

app.py

@@ -0,0 +1,685 @@
+#!/usr/bin/env python3
+import gradio as gr
+import trimesh
+import numpy as np
+import tempfile
+import zipfile
+import requests
+import os
+from pathlib import Path
+from typing import List, Tuple, Optional, Dict, Any
+from src import convert_meshes
+
+
+def load_mesh(
+    file_path: str,
+) -> Optional[Tuple[List[Tuple[str, trimesh.Trimesh]], Optional[Dict]]]:
+    try:
+        loaded = trimesh.load(str(file_path))
+        if isinstance(loaded, trimesh.Scene):
+            mesh_list = []
+            scene_data = {"graph": loaded.graph, "transforms": {}}
+
+            for geom_name, geom in loaded.geometry.items():
+                if hasattr(geom, "faces") and len(geom.faces) > 0:
+                    mesh_list.append((geom_name, geom))
+
+                    # Store transform for this geometry
+                    nodes = loaded.graph.geometry_nodes.get(geom_name, [])
+                    if nodes:
+                        scene_data["transforms"][geom_name] = loaded.graph.get(
+                            nodes[0]
+                        )[0]
+                    else:
+                        scene_data["transforms"][geom_name] = np.eye(4)
+
+            return (mesh_list, scene_data) if mesh_list else None
+        elif hasattr(loaded, "faces"):
+            # Single mesh case
+            return ([("mesh", loaded)], None)
+        else:
+            return None
+    except Exception as e:
+        print(f"Error loading {file_path}: {e}")
+        return None
+
+
+def export_processed_meshes(result, output_path, progress, total_files):
+    """Export processed meshes, reconstructing scenes when appropriate."""
+    processed_models = []
+
+    # Group meshes by their original file
+    file_groups = {}
+    for name, mesh in result.meshes:
+        # Extract file name from combined name (e.g., "Lantern_LanternPole_Body" -> "Lantern")
+        if "_" in name and result.scene_metadata:
+            parts = name.split("_", 1)
+            file_name = parts[0]
+            mesh_name = parts[1] if len(parts) > 1 else "mesh"
+        else:
+            file_name = name
+            mesh_name = "mesh"
+
+        if file_name not in file_groups:
+            file_groups[file_name] = []
+        file_groups[file_name].append((mesh_name, mesh))
+
+    # Export each file group
+    for i, (file_name, meshes) in enumerate(file_groups.items()):
+        progress_desc = f"Saving {file_name}..."
+        progress(
+            (total_files + 1 + i / len(file_groups)) / (total_files + 2),
+            desc=progress_desc,
+        )
+
+        # Check if this file had scene metadata
+        has_scene = result.scene_metadata and file_name in result.scene_metadata
+
+        if has_scene and len(meshes) > 1:
+            # Reconstruct and export as Scene
+            scene = trimesh.Scene()
+            scene_data = result.scene_metadata[file_name]
+
+            for mesh_name, mesh in meshes:
+                # Get transform for this mesh
+                transform = scene_data["transforms"].get(mesh_name, np.eye(4))
+
+                # Add to scene with proper naming
+                scene.add_geometry(
+                    mesh, node_name=mesh_name, geom_name=mesh_name, transform=transform
+                )
+
+            # Export the scene
+            model_path = output_path / f"{file_name}_palettized.glb"
+            scene.export(str(model_path))
+            processed_models.append(str(model_path))
+        else:
+            # Export individual meshes
+            for mesh_name, mesh in meshes:
+                if len(meshes) > 1:
+                    model_path = output_path / f"{file_name}_{mesh_name}_palettized.glb"
+                else:
+                    model_path = output_path / f"{file_name}_palettized.glb"
+                mesh.export(str(model_path), include_normals=True)
+                processed_models.append(str(model_path))
+
+    return processed_models
+
+
+def download_from_urls(
+    urls_text: str, progress=gr.Progress()
+) -> Tuple[List[str], List[str]]:
+    if not urls_text or not urls_text.strip():
+        return [], []
+
+    urls = [url.strip() for url in urls_text.strip().split("\n") if url.strip()]
+    downloaded_files = []
+    failed_urls = []
+
+    temp_dir = tempfile.mkdtemp(prefix="glb_downloads_")
+
+    for i, url in enumerate(urls):
+        progress((i + 1) / len(urls), desc=f"Downloading {i + 1}/{len(urls)}...")
+
+        try:
+            filename = os.path.basename(url.split("?")[0])
+            if not filename or not filename.endswith((".glb", ".gltf")):
+                filename = f"model_{i + 1}.glb"
+
+            file_path = os.path.join(temp_dir, filename)
+
+            response = requests.get(url, timeout=30)
+            response.raise_for_status()
+
+            with open(file_path, "wb") as f:
+                f.write(response.content)
+
+            downloaded_files.append(file_path)
+        except Exception as e:
+            print(f"Failed to download {url}: {e}")
+            failed_urls.append(url)
+
+    return downloaded_files, failed_urls
+
+
+def process_batch(
+    files: List[Any],
+    atlas_size: int,
+    sample_rate: float,
+    simplify_details: bool,
+    detail_filter_diameter: int,
+    detail_color_sigma: int,
+    detail_space_sigma: int,
+    progress=gr.Progress(),
+) -> Tuple[Optional[str], List[str], Optional[str], str, Dict]:
+
+    if not files:
+        return None, [], None, "No files to process.", {}
+
+    progress(0, desc="Starting batch processing...")
+
+    output_dir = tempfile.mkdtemp(prefix="glb_atlas_")
+    output_path = Path(output_dir)
+
+    mesh_list = []
+    failed_files = []
+    scene_metadata = {}
+
+    for i, file in enumerate(files):
+        if hasattr(file, "name"):
+            file_path = file.name
+            display_name = Path(file.name).name
+        else:
+            file_path = file
+            display_name = Path(file).name
+
+        progress((i + 1) / (len(files) + 2), desc=f"Loading {display_name}...")
+
+        file_name = Path(file_path).stem
+
+        loaded_data = load_mesh(file_path)
+        if loaded_data is not None:
+            meshes, scene_data = loaded_data
+
+            # Store scene data if present
+            if scene_data:
+                scene_metadata[file_name] = scene_data
+
+            # Add all meshes from this file to the list
+            for mesh_name, mesh in meshes:
+                # Create unique name combining file and mesh names
+                if len(meshes) > 1:
+                    combined_name = f"{file_name}_{mesh_name}"
+                else:
+                    combined_name = file_name
+                mesh_list.append((combined_name, mesh))
+        else:
+            failed_files.append(display_name)
+
+    if not mesh_list:
+        return (
+            None,
+            [],
+            None,
+            "No valid meshes could be loaded from the uploaded files.",
+            {},
+        )
+
+    try:
+        progress(len(files) / (len(files) + 2), desc="Generating texture atlas...")
+        detail_sensitivity = (
+            (detail_filter_diameter, detail_color_sigma, detail_space_sigma)
+            if simplify_details
+            else None
+        )
+        result = convert_meshes(
+            mesh_list,
+            atlas_size=atlas_size,
+            face_sampling_ratio=sample_rate,
+            simplify_details=simplify_details,
+            detail_sensitivity=detail_sensitivity,
+            scene_metadata=scene_metadata,
+        )
+
+        atlas_path = output_path / "shared_palette.png"
+        result.atlas.save(atlas_path)
+
+        # Export processed meshes, reconstructing scenes when appropriate
+        processed_models = export_processed_meshes(
+            result, output_path, progress, len(files)
+        )
+
+        status = f"✓ Processed {len(result.meshes)} model(s)\n📊 Atlas: {atlas_size}×{atlas_size} pixels"
+        if failed_files:
+            status += f"\n⚠ Failed: {len(failed_files)} file(s)"
+
+        # Extract display names for the processed models
+        display_names = []
+        for model_path in processed_models:
+            model_name = Path(model_path).stem
+            if model_name.endswith("_palettized"):
+                model_name = model_name[:-11]  # Remove "_palettized" suffix
+            display_names.append(model_name)
+
+        metadata = {
+            "models": processed_models,
+            "names": display_names,
+            "atlas_path": str(atlas_path),
+            "output_dir": output_dir,
+            "total": len(processed_models),
+        }
+
+        progress(1.0, desc="Processing complete!")
+
+        first_model = processed_models[0] if processed_models else None
+        return str(atlas_path), processed_models, first_model, status, metadata
+
+    except Exception as e:
+        return None, [], None, f"Error during processing: {str(e)}", {}
+
+
+def update_model_viewer(
+    direction: str, current_index: int, metadata: Dict
+) -> Tuple[Optional[str], int, str]:
+
+    if not metadata or "models" not in metadata:
+        return None, 0, "No models to display"
+
+    models = metadata["models"]
+    names = metadata["names"]
+    total = metadata["total"]
+
+    if not models:
+        return None, 0, "No models available"
+
+    if direction == "next":
+        new_index = (current_index + 1) % total
+    elif direction == "prev":
+        new_index = (current_index - 1) % total
+    else:
+        new_index = 0
+
+    model_path = models[new_index]
+    model_name = names[new_index]
+
+    label = f"Model {new_index + 1} of {total}: {model_name}"
+
+    return model_path, new_index, label
+
+
+def create_download_zip(metadata: Dict) -> Optional[str]:
+
+    if not metadata or "output_dir" not in metadata:
+        return None
+
+    output_dir = Path(metadata["output_dir"])
+    zip_path = output_dir / "glb_atlas_output.zip"
+
+    try:
+        with zipfile.ZipFile(zip_path, "w", zipfile.ZIP_DEFLATED) as zipf:
+            if "atlas_path" in metadata:
+                atlas_path = Path(metadata["atlas_path"])
+                if atlas_path.exists():
+                    zipf.write(atlas_path, atlas_path.name)
+
+            if "models" in metadata:
+                for model_path in metadata["models"]:
+                    model_file = Path(model_path)
+                    if model_file.exists():
+                        zipf.write(model_file, model_file.name)
+
+        return str(zip_path)
+    except Exception as e:
+        print(f"Error creating ZIP: {e}")
+        return None
+
+
+with gr.Blocks(
+    title="Mesh Palettizer",
+    theme=gr.themes.Soft(),
+    css="""
+    #atlas-display img {
+        width: 100%;
+        height: 100%;
+        object-fit: contain;
+        image-rendering: pixelated;
+        image-rendering: -moz-crisp-edges;
+        image-rendering: crisp-edges;
+    }
+    """,
+) as demo:
+    model_index = gr.State(value=0)
+    processing_metadata = gr.State(value={})
+
+    gr.Markdown(
+        """
+    # 🎨 Mesh Palettizer
+
+    Simplify 3D model textures using optimized color palettes.
+    Upload GLB/GLTF models to create clean, palettized textures for stylized rendering.
+    """
+    )
+
+    with gr.Row():
+        with gr.Column(scale=1):
+            with gr.Tabs() as input_tabs:
+                with gr.Tab("📁 Upload Files"):
+                    file_input = gr.File(
+                        label="Select GLB/GLTF Files",
+                        file_count="multiple",
+                        file_types=[".glb", ".gltf"],
+                        type="filepath",
+                    )
+
+                    gr.Examples(
+                        examples=[[["examples/Duck.glb", "examples/Lantern.glb"]]],
+                        inputs=file_input,
+                        label="Example Models",
+                    )
+
+                with gr.Tab("🔗 Load from URLs"):
+                    url_input = gr.Textbox(
+                        label="Enter URLs (one per line)",
+                        placeholder="https://example.com/model1.glb\nhttps://example.com/model2.glb",
+                        lines=5,
+                        interactive=True,
+                    )
+
+            atlas_size = gr.Dropdown(
+                choices=[8, 16, 32, 64, 128, 256, 512, 1024],
+                value=32,
+                label="Atlas Size",
+                info="N×N pixels",
+            )
+
+            with gr.Accordion("Advanced", open=False):
+                sample_rate = gr.Slider(
+                    minimum=0.01,
+                    maximum=1.0,
+                    value=0.1,
+                    step=0.01,
+                    label="Sampling Rate",
+                    info="% of faces to sample",
+                )
+                simplify_details = gr.Checkbox(
+                    value=True,
+                    label="Remove Texture Details",
+                    info="Apply bilateral filter to remove fine details (scales, fur, etc.)",
+                )
+
+                with gr.Row(visible=True) as detail_controls:
+                    detail_filter_diameter = gr.Slider(
+                        minimum=5,
+                        maximum=15,
+                        value=9,
+                        step=2,
+                        label="Filter Diameter",
+                        info="Pixel neighborhood diameter (higher = stronger smoothing)",
+                    )
+
+                    detail_color_sigma = gr.Slider(
+                        minimum=25,
+                        maximum=150,
+                        value=75,
+                        step=5,
+                        label="Color Sensitivity",
+                        info="Color difference threshold (higher = more colors mixed)",
+                    )
+
+                    detail_space_sigma = gr.Slider(
+                        minimum=25,
+                        maximum=150,
+                        value=75,
+                        step=5,
+                        label="Spatial Sensitivity",
+                        info="Spatial extent (higher = pixels farther apart influence each other)",
+                    )
+
+            process_btn = gr.Button("🚀 Process", variant="primary", size="lg")
+
+            status_text = gr.Textbox(
+                label="Status", lines=2, interactive=False, show_label=False
+            )
+
+        with gr.Column(scale=2):
+            with gr.Tabs():
+                with gr.Tab("📊 Palette"):
+                    atlas_image = gr.Image(
+                        label="Color Palette",
+                        type="filepath",
+                        show_download_button=True,
+                        height=400,
+                        container=True,
+                        elem_id="atlas-display",
+                    )
+
+                with gr.Tab("🎮 3D Preview"):
+                    model_label = gr.Markdown("")
+                    model_viewer = gr.Model3D(
+                        label="Model", height=400, clear_color=[0.95, 0.95, 0.95, 1.0]
+                    )
+
+                    with gr.Row():
+                        prev_btn = gr.Button("��", size="sm")
+                        model_counter = gr.Markdown(
+                            "Model 1 of 1", elem_id="model-counter"
+                        )
+                        next_btn = gr.Button("▶", size="sm")
+
+            with gr.Row():
+                download_btn = gr.Button(
+                    "📦 Download All", variant="secondary", size="lg"
+                )
+                download_file = gr.File(label="Package", visible=False)
+
+    def toggle_detail_controls(enabled):
+        return gr.update(visible=enabled)
+
+    simplify_details.change(
+        fn=toggle_detail_controls, inputs=[simplify_details], outputs=[detail_controls]
+    )
+
+    def process_from_files(
+        files,
+        atlas_size,
+        sample_rate,
+        simplify_details,
+        detail_filter_diameter,
+        detail_color_sigma,
+        detail_space_sigma,
+    ):
+        if not files:
+            return (
+                None,
+                None,
+                "Please upload files first.",
+                {},
+                0,
+                "",
+                "",
+                gr.update(visible=False),
+            )
+
+        atlas_path, models, first_model, status, metadata = process_batch(
+            files,
+            atlas_size,
+            sample_rate,
+            simplify_details,
+            detail_filter_diameter,
+            detail_color_sigma,
+            detail_space_sigma,
+        )
+
+        if models:
+            viewer_label = metadata["names"][0]
+            counter_text = f"Model 1 of {len(models)}"
+        else:
+            viewer_label = ""
+            counter_text = ""
+
+        return (
+            atlas_path,
+            first_model,
+            status,
+            metadata,
+            0,
+            viewer_label,
+            counter_text,
+            gr.update(visible=False),
+        )
+
+    def process_from_urls(
+        urls_text,
+        atlas_size,
+        sample_rate,
+        simplify_details,
+        detail_filter_diameter,
+        detail_color_sigma,
+        detail_space_sigma,
+    ):
+        if not urls_text or not urls_text.strip():
+            return (
+                None,
+                None,
+                "Please enter URLs first.",
+                {},
+                0,
+                "",
+                "",
+                gr.update(visible=False),
+            )
+
+        downloaded_files, failed_urls = download_from_urls(urls_text)
+
+        if not downloaded_files:
+            error_msg = "Failed to download any files."
+            if failed_urls:
+                error_msg += f" URLs that failed: {len(failed_urls)}"
+            return None, None, error_msg, {}, 0, "", "", gr.update(visible=False)
+
+        atlas_path, models, first_model, status, metadata = process_batch(
+            downloaded_files,
+            atlas_size,
+            sample_rate,
+            simplify_details,
+            detail_filter_diameter,
+            detail_color_sigma,
+            detail_space_sigma,
+        )
+
+        if failed_urls:
+            status += f"\n⚠ Failed to download {len(failed_urls)} URL(s)"
+
+        if models:
+            viewer_label = metadata["names"][0]
+            counter_text = f"Model 1 of {len(models)}"
+        else:
+            viewer_label = ""
+            counter_text = ""
+
+        return (
+            atlas_path,
+            first_model,
+            status,
+            metadata,
+            0,
+            viewer_label,
+            counter_text,
+            gr.update(visible=False),
+        )
+
+    def process_wrapper(
+        files,
+        urls_text,
+        atlas_size,
+        sample_rate,
+        simplify_details,
+        detail_filter_diameter,
+        detail_color_sigma,
+        detail_space_sigma,
+    ):
+        if files and len(files) > 0:
+            return process_from_files(
+                files,
+                atlas_size,
+                sample_rate,
+                simplify_details,
+                detail_filter_diameter,
+                detail_color_sigma,
+                detail_space_sigma,
+            )
+        elif urls_text and urls_text.strip():
+            return process_from_urls(
+                urls_text,
+                atlas_size,
+                sample_rate,
+                simplify_details,
+                detail_filter_diameter,
+                detail_color_sigma,
+                detail_space_sigma,
+            )
+        else:
+            return (
+                None,
+                None,
+                "Please provide files or URLs.",
+                {},
+                0,
+                "",
+                "",
+                gr.update(visible=False),
+            )
+
+    process_btn.click(
+        fn=process_wrapper,
+        inputs=[
+            file_input,
+            url_input,
+            atlas_size,
+            sample_rate,
+            simplify_details,
+            detail_filter_diameter,
+            detail_color_sigma,
+            detail_space_sigma,
+        ],
+        outputs=[
+            atlas_image,
+            model_viewer,
+            status_text,
+            processing_metadata,
+            model_index,
+            model_label,
+            model_counter,
+            download_file,
+        ],
+    )
+
+    def navigate_prev(current_index, metadata):
+        model_path, new_index, _ = update_model_viewer("prev", current_index, metadata)
+        counter_text = (
+            f"Model {new_index + 1} of {metadata['total']}"
+            if metadata and "total" in metadata
+            else ""
+        )
+        name_text = (
+            metadata["names"][new_index] if metadata and "names" in metadata else ""
+        )
+        return model_path, new_index, name_text, counter_text
+
+    def navigate_next(current_index, metadata):
+        model_path, new_index, _ = update_model_viewer("next", current_index, metadata)
+        counter_text = (
+            f"Model {new_index + 1} of {metadata['total']}"
+            if metadata and "total" in metadata
+            else ""
+        )
+        name_text = (
+            metadata["names"][new_index] if metadata and "names" in metadata else ""
+        )
+        return model_path, new_index, name_text, counter_text
+
+    prev_btn.click(
+        fn=navigate_prev,
+        inputs=[model_index, processing_metadata],
+        outputs=[model_viewer, model_index, model_label, model_counter],
+    )
+
+    next_btn.click(
+        fn=navigate_next,
+        inputs=[model_index, processing_metadata],
+        outputs=[model_viewer, model_index, model_label, model_counter],
+    )
+
+    def prepare_download(metadata):
+        zip_path = create_download_zip(metadata)
+        if zip_path:
+            return gr.update(value=zip_path, visible=True)
+        return gr.update(visible=False)
+
+    download_btn.click(
+        fn=prepare_download, inputs=[processing_metadata], outputs=[download_file]
+    )
+
+
+if __name__ == "__main__":
+    demo.launch(share=False, server_name="0.0.0.0", server_port=7860, show_error=True)

context.md

@@ -0,0 +1,39 @@
+# Mesh Palettizer
+
+Web application for simplifying 3D model textures with optimized color palettes
+
+## Purpose
+
+- Convert GLB/GLTF models to use palettized textures
+- Provide web interface for batch processing
+- Support file uploads and URL downloads for model inputs
+- Generate clean, simplified textures for stylized rendering
+
+## Layout
+
+```
+conversion/
+├── context.md       # This file
+├── app.py           # Gradio web interface
+├── src/             # Core conversion library
+│   └── context.md   # Library context
+├── examples/        # Example GLB models
+│   ├── Duck.glb
+│   └── Lantern.glb
+└── requirements.txt # HF Spaces dependencies
+```
+
+## Scope
+
+- In-scope: GLB/GLTF processing, batch operations, web interface
+- Out-of-scope: Direct Unity integration, texture detail preservation
+
+## Entrypoints
+
+- `app.py` - Web interface with example models and batch processing
+- `src.convert_meshes()` - Core conversion API
+
+## Dependencies
+
+- Internal: src module
+- External: trimesh, gradio, PIL, numpy, scikit-learn, requests

examples/Duck.glb

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:65bf938f54d6073e619e76e007820bbf980cdc3dc0daec0d94830ffc4ae54ab5
+size 120484

examples/Lantern.glb

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:2d7ea69e1f4b7f5b9f00854978b20f41b9effa392272c50f4c98b5a8db3152b2
+size 9872848

layers/context-template.md

@@ -0,0 +1,34 @@
+# Context Template
+
+Concise context for any folder; link to code or subfolders for deeper context
+
+## Purpose
+
+- [What this folder/module does]
+
+## Layout
+
+```
+[FOLDER]/
+context.md  # This file, folder context (Tier 2)
+├── [FILE1].[ext]  # File
+├── [FILE2].[ext]  # File
+├── [subfolder]/  # Subfolder
+│   ├── context.md  # Subfolder context
+│   ├── [FILE3].[ext]  # File
+│   └── [FILE4].[ext]  # File
+```
+
+## Scope
+
+- [In-scope]
+- [Out-of-scope]
+
+## Entrypoints
+
+- [Primary entry files or functions and when they are called]
+
+## Dependencies
+
+- [Internal modules]
+- [External libraries/services]

layers/structure.md

@@ -0,0 +1,68 @@
+# 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

pyproject.toml

@@ -0,0 +1,36 @@
+[project]
+name = "mesh-palettizer"
+version = "0.1.0"
+description = "Simplify 3D model textures using optimized color palettes"
+requires-python = ">=3.10"
+dependencies = [
+    "trimesh[easy]>=4.0.0",
+    "pillow>=10.0.0",
+    "numpy>=1.24.0",
+    "scipy>=1.10.0",
+    "scikit-learn>=1.3.0",
+    "gradio>=4.0.0",
+    "requests>=2.31.0",
+    "dotenv>=0.9.9",
+    "opencv-python>=4.8.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.4.0",
+    "ruff>=0.1.0",
+    "requests>=2.31.0",
+    "python-dotenv>=1.0.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src"]
+
+[dependency-groups]
+dev = [
+    "black>=25.9.0",
+]

requirements.txt

@@ -0,0 +1,8 @@
+trimesh[easy]>=4.0.0
+pillow>=10.0.0
+numpy>=1.24.0
+scipy>=1.10.0
+scikit-learn>=1.3.0
+gradio>=4.0.0
+requests>=2.31.0
+opencv-python>=4.11.0

src/__init__.py

@@ -0,0 +1,105 @@
+import numpy as np
+from .palette import create_palette, PaletteMapper
+from .atlas import create_atlas
+from .mesh import apply_atlas
+
+__all__ = ["convert_meshes", "ConversionConfig", "ConversionResult"]
+
+
+class ConversionConfig:
+    def __init__(
+        self,
+        atlas_size=16,
+        face_sampling_ratio=0.1,
+        simplify_details=True,
+        detail_sensitivity=None,
+    ):
+        self.atlas_size = atlas_size
+        self.face_sampling_ratio = face_sampling_ratio
+        self.simplify_details = simplify_details
+        self.detail_sensitivity = detail_sensitivity
+        self.total_palette_colors = atlas_size * atlas_size
+
+
+class ConversionResult:
+    def __init__(self, meshes, atlas, palette, scene_metadata=None):
+        self.meshes = meshes
+        self.atlas = atlas
+        self.palette = palette
+        self.scene_metadata = scene_metadata
+
+
+def convert_meshes(
+    mesh_list,
+    atlas_size=16,
+    face_sampling_ratio=0.1,
+    simplify_details=True,
+    detail_sensitivity=None,
+    scene_metadata=None,
+):
+    if not mesh_list:
+        raise ValueError("No meshes provided")
+
+    config = ConversionConfig(
+        atlas_size, face_sampling_ratio, simplify_details, detail_sensitivity
+    )
+
+    print(
+        f"Processing {len(mesh_list)} mesh(es) with {config.total_palette_colors}-color palette"
+    )
+
+    all_sampled_colors = []
+    meshes_with_valid_geometry = []
+    mesh_face_colors = {}
+
+    for mesh_name, mesh_object in mesh_list:
+        if mesh_object is None or len(mesh_object.faces) == 0:
+            print(f"Skipping {mesh_name}: no valid geometry")
+            continue
+
+        print(
+            f"Analyzing {mesh_name}: {len(mesh_object.faces)} faces, {len(mesh_object.vertices)} vertices"
+        )
+        meshes_with_valid_geometry.append((mesh_name, mesh_object))
+
+        from .extraction.reader import get_face_colors
+        face_colors = get_face_colors(
+            mesh_object,
+            simplify_details=config.simplify_details,
+            detail_sensitivity=config.detail_sensitivity,
+        )
+        mesh_face_colors[mesh_name] = face_colors
+
+        from .extraction import sample_colors
+        face_areas = mesh_object.area_faces if hasattr(mesh_object, "area_faces") else None
+        sampled_colors = sample_colors(face_colors, config.face_sampling_ratio, face_areas)
+        all_sampled_colors.extend(sampled_colors)
+
+    if not meshes_with_valid_geometry:
+        raise ValueError("No valid meshes found")
+
+    combined_color_array = np.array(all_sampled_colors, dtype=np.uint8)
+    print(
+        f"Total sampled colors: {len(combined_color_array)} from {len(meshes_with_valid_geometry)} mesh(es)"
+    )
+
+    quantized_palette = create_palette(combined_color_array, size=config.atlas_size)
+    texture_atlas_image, color_to_uv_mapping = create_atlas(
+        quantized_palette, size=config.atlas_size
+    )
+    nearest_color_mapper = PaletteMapper(quantized_palette)
+
+    atlas_applied_meshes = []
+    for mesh_name, mesh_object in meshes_with_valid_geometry:
+        print(f"Applying atlas to {mesh_name}")
+        mesh_with_atlas_texture = apply_atlas(
+            mesh_object, texture_atlas_image, color_to_uv_mapping, nearest_color_mapper,
+            face_colors=mesh_face_colors[mesh_name]
+        )
+        atlas_applied_meshes.append((mesh_name, mesh_with_atlas_texture))
+
+    print(f"✓ Successfully processed {len(atlas_applied_meshes)} mesh(es)")
+
+    return ConversionResult(
+        atlas_applied_meshes, texture_atlas_image, quantized_palette, scene_metadata
+    )

src/atlas/__init__.py

@@ -0,0 +1,7 @@
+from .builder import build_atlas, palette_to_atlas
+
+__all__ = ["build_atlas", "palette_to_atlas", "create_atlas"]
+
+
+def create_atlas(palette, size=16):
+    return palette_to_atlas(palette, atlas_size=size)

src/atlas/builder.py

@@ -0,0 +1,59 @@
+from PIL import Image
+import numpy as np
+
+DEFAULT_FILL_COLOR = [128, 128, 128]
+UV_PIXEL_CENTER_OFFSET = 0.5
+
+
+def build_atlas(colors, width, height):
+    atlas_pixel_array = create_empty_atlas_array(width, height)
+    fill_atlas_with_palette(atlas_pixel_array, colors, width, height)
+    return Image.fromarray(atlas_pixel_array, "RGB")
+
+
+def create_empty_atlas_array(width, height):
+    return np.zeros((height, width, 3), dtype=np.uint8)
+
+
+def fill_atlas_with_palette(atlas_array, palette_colors, width, height):
+    palette_index = 0
+
+    for row in range(height):
+        for column in range(width):
+            if palette_index < len(palette_colors):
+                atlas_array[row, column] = palette_colors[palette_index]
+                palette_index += 1
+            else:
+                atlas_array[row, column] = DEFAULT_FILL_COLOR
+
+
+def palette_to_atlas(palette, atlas_size=16):
+    atlas_image = build_atlas(palette, atlas_size, atlas_size)
+    uv_mapping = create_color_to_uv_mapping(palette, atlas_size)
+    return atlas_image, uv_mapping
+
+
+def create_color_to_uv_mapping(palette, atlas_dimensions):
+    color_to_uv_coordinates = {}
+    palette_index = 0
+
+    for row in range(atlas_dimensions):
+        for column in range(atlas_dimensions):
+            if palette_index < len(palette):
+                current_color = palette[palette_index]
+                rgb_tuple = convert_to_rgb_tuple(current_color)
+                uv_position = calculate_uv_for_pixel(column, row, atlas_dimensions)
+                color_to_uv_coordinates[rgb_tuple] = uv_position
+                palette_index += 1
+
+    return color_to_uv_coordinates
+
+
+def convert_to_rgb_tuple(color_array):
+    return tuple(int(channel) for channel in color_array)
+
+
+def calculate_uv_for_pixel(pixel_x, pixel_y, atlas_size):
+    u_coordinate = (pixel_x + UV_PIXEL_CENTER_OFFSET) / atlas_size
+    v_coordinate = 1.0 - (pixel_y + UV_PIXEL_CENTER_OFFSET) / atlas_size
+    return (u_coordinate, v_coordinate)

src/atlas/context.md

@@ -0,0 +1,33 @@
+# Atlas Module
+
+Texture atlas generation from color palettes
+
+## Purpose
+
+- Create texture atlases from palettes
+- Generate UV mappings for colors
+
+## Layout
+
+```
+atlas/
+├── context.md   # This file
+├── __init__.py  # API: create_atlas()
+└── builder.py   # Atlas construction logic
+```
+
+## Scope
+
+- In-scope: Atlas image creation, UV coordinate generation
+- Out-of-scope: Mesh processing, color quantization
+
+## Entrypoints
+
+- `create_atlas(palette, size)` - Main atlas creation
+- `palette_to_atlas(palette, atlas_size)` - Build with UV mapping
+- `build_atlas(colors, width, height)` - Low-level builder
+
+## Dependencies
+
+- Internal: None
+- External: Pillow, NumPy

src/context.md

@@ -0,0 +1,38 @@
+# Mesh Palettizer Core
+
+Core library for 3D model texture palette optimization
+
+## Purpose
+
+- Extract colors from mesh textures and materials
+- Generate optimized palettes via perceptual clustering
+- Build color palettes and remap mesh UVs
+- Support multi-mesh scenes with shared textures
+
+## Layout
+
+```
+src/
+├── context.md       # This file
+├── __init__.py      # Main API: convert_meshes()
+├── preprocessing/   # Texture detail removal
+├── extraction/      # Color extraction from meshes
+├── palette/         # Palette generation and mapping
+├── atlas/           # Palette texture creation
+└── mesh/            # UV remapping
+```
+
+## Scope
+
+- In-scope: Mesh processing, color quantization, UV mapping
+- Out-of-scope: File I/O, API calls, web interface
+
+## Entrypoints
+
+- `convert_meshes(mesh_list, atlas_size, face_sampling_ratio, simplify_details, detail_sensitivity, scene_metadata)` - Main API
+- Returns: `ConversionResult` with processed meshes, palette, and scene metadata
+
+## Dependencies
+
+- Internal: All submodules
+- External: numpy, trimesh, PIL, scikit-learn, scipy

src/extraction/__init__.py

@@ -0,0 +1,12 @@
+from .sampler import sample_colors
+from .reader import get_face_colors
+
+__all__ = ["sample_colors", "get_face_colors"]
+
+
+def extract_colors(
+    mesh, face_sampling_ratio=0.1, simplify_details=True, detail_sensitivity=None
+):
+    face_colors = get_face_colors(mesh, simplify_details, detail_sensitivity)
+    face_areas = mesh.area_faces if hasattr(mesh, "area_faces") else None
+    return sample_colors(face_colors, face_sampling_ratio, face_areas)

src/extraction/context.md

@@ -0,0 +1,35 @@
+# Color Extraction Module
+
+Extract colors from 3D mesh materials and textures
+
+## Purpose
+
+- Sample colors from mesh faces
+- Read from textures via UV coordinates
+- Apply area-weighted sampling
+
+## Layout
+
+```
+extraction/
+├── context.md    # This file
+├── __init__.py   # API: extract_colors()
+├── sampler.py    # Random sampling strategies
+└── reader.py     # Read colors from materials
+```
+
+## Scope
+
+- In-scope: Color extraction, texture sampling, UV mapping
+- Out-of-scope: Color quantization, atlas generation
+
+## Entrypoints
+
+- `extract_colors(mesh, sample_rate, simplify_details, detail_sensitivity)` - Main extraction function
+- `get_face_colors(mesh, simplify_details, detail_sensitivity)` - Read colors from mesh
+- `sample_colors(colors, sample_rate, areas)` - Sample with weighting
+
+## Dependencies
+
+- Internal: preprocessing.simplify_texture
+- External: NumPy, trimesh, OpenCV

src/extraction/reader.py

@@ -0,0 +1,136 @@
+import numpy as np
+from ..preprocessing import simplify_texture
+
+DEFAULT_GRAY_VALUE = 128
+TEXTURE_SAMPLING_CHUNK_SIZE = 10000
+
+
+def get_face_colors(mesh, simplify_details=True, detail_sensitivity=None):
+    extracted_colors = try_extract_from_material(
+        mesh, simplify_details, detail_sensitivity
+    )
+
+    if extracted_colors is None:
+        extracted_colors = try_extract_from_face_colors(mesh)
+
+    if extracted_colors is None:
+        extracted_colors = create_default_gray_colors(len(mesh.faces))
+
+    return extracted_colors
+
+
+def try_extract_from_material(mesh, simplify_details=True, detail_sensitivity=None):
+    if not hasattr(mesh.visual, "material"):
+        return None
+
+    material = mesh.visual.material
+    texture_image = get_texture_image(material)
+
+    if texture_image and has_valid_uv_coordinates(mesh):
+        # Always create a copy to avoid issues with shared textures
+        if hasattr(texture_image, "copy"):
+            texture_image = texture_image.copy()
+
+        if simplify_details:
+            if detail_sensitivity is not None:
+                d, sigma_color, sigma_space = detail_sensitivity
+                texture_image = simplify_texture(
+                    texture_image,
+                    enabled=True,
+                    d=d,
+                    sigma_color=sigma_color,
+                    sigma_space=sigma_space,
+                )
+            else:
+                texture_image = simplify_texture(texture_image)
+        return sample_colors_from_texture(mesh, texture_image)
+
+    if has_main_color(material):
+        return create_uniform_color_array(material.main_color, len(mesh.faces))
+
+    return None
+
+
+def get_texture_image(material):
+    if hasattr(material, "baseColorTexture") and material.baseColorTexture is not None:
+        return material.baseColorTexture
+    if hasattr(material, "image") and material.image is not None:
+        return material.image
+    return None
+
+
+def has_valid_uv_coordinates(mesh):
+    return hasattr(mesh.visual, "uv") and mesh.visual.uv is not None
+
+
+def has_main_color(material):
+    return hasattr(material, "main_color") and material.main_color is not None
+
+
+def create_uniform_color_array(color, face_count):
+    rgb_values = np.array(color[:3], dtype=np.uint8)
+    return np.tile(rgb_values, (face_count, 1))
+
+
+def try_extract_from_face_colors(mesh):
+    if hasattr(mesh.visual, "face_colors") and mesh.visual.face_colors is not None:
+        return mesh.visual.face_colors[:, :3].astype(np.uint8)
+    return None
+
+
+def create_default_gray_colors(face_count):
+    return np.full((face_count, 3), DEFAULT_GRAY_VALUE, dtype=np.uint8)
+
+
+def sample_colors_from_texture(mesh, texture_image):
+    try:
+        rgb_texture_array = convert_to_rgb_array(texture_image)
+        texture_height, texture_width = rgb_texture_array.shape[:2]
+
+        uv_coordinates = mesh.visual.uv
+        mesh_faces = mesh.faces
+
+        sampled_face_colors = np.zeros((len(mesh_faces), 3), dtype=np.uint8)
+
+        for chunk_start in range(0, len(mesh_faces), TEXTURE_SAMPLING_CHUNK_SIZE):
+            chunk_end = min(chunk_start + TEXTURE_SAMPLING_CHUNK_SIZE, len(mesh_faces))
+            current_chunk_faces = mesh_faces[chunk_start:chunk_end]
+
+            face_vertex_uvs = uv_coordinates[current_chunk_faces].reshape(-1, 3, 2)
+            pixel_x_coords = convert_u_to_pixel_x(
+                face_vertex_uvs[:, :, 0], texture_width
+            )
+            pixel_y_coords = convert_v_to_pixel_y(
+                face_vertex_uvs[:, :, 1], texture_height
+            )
+
+            sampled_vertex_colors = rgb_texture_array[
+                pixel_y_coords.ravel(), pixel_x_coords.ravel(), :3
+            ]
+            per_face_colors = sampled_vertex_colors.reshape(
+                len(current_chunk_faces), 3, 3
+            )
+            average_face_colors = np.mean(per_face_colors, axis=1).astype(np.uint8)
+
+            sampled_face_colors[chunk_start:chunk_end] = average_face_colors
+
+        return sampled_face_colors
+    except (IndexError, ValueError):
+        return create_default_gray_colors(len(mesh.faces))
+
+
+def convert_to_rgb_array(image):
+    if hasattr(image, "convert"):
+        image = image.convert("RGB")
+    return np.array(image, dtype=np.uint8)
+
+
+def convert_u_to_pixel_x(u_values, width):
+    pixel_values = (u_values * width).astype(int)
+    return np.clip(pixel_values, 0, width - 1)
+
+
+def convert_v_to_pixel_y(v_values, height):
+    flipped_v_values = 1 - v_values
+    pixel_values = (flipped_v_values * height).astype(int)
+    return np.clip(pixel_values, 0, height - 1)

src/extraction/sampler.py

@@ -0,0 +1,42 @@
+import numpy as np
+
+LARGE_MESH_THRESHOLD = 1000
+MINIMUM_SAMPLE_COUNT = 100
+MIN_AREA_WEIGHT = 1
+MAX_AREA_WEIGHT = 10
+
+
+def sample_colors(face_colors, sampling_ratio=0.1, face_areas=None):
+    total_faces = len(face_colors)
+
+    if total_faces > LARGE_MESH_THRESHOLD:
+        number_to_sample = max(int(total_faces * sampling_ratio), MINIMUM_SAMPLE_COUNT)
+        randomly_selected_indices = np.random.choice(
+            total_faces, size=number_to_sample, replace=False
+        )
+        selected_face_colors = face_colors[randomly_selected_indices]
+        print(
+            f"Sampled {number_to_sample} of {total_faces} faces ({sampling_ratio*100:.1f}%)"
+        )
+
+        if face_areas is not None:
+            selected_areas = face_areas[randomly_selected_indices]
+            area_based_repetitions = compute_area_weights(selected_areas)
+            return np.repeat(selected_face_colors, area_based_repetitions, axis=0)
+
+        return selected_face_colors
+    else:
+        print(f"Using all {total_faces} faces (below sampling threshold)")
+
+        if face_areas is not None:
+            area_based_repetitions = compute_area_weights(face_areas)
+            return np.repeat(face_colors, area_based_repetitions, axis=0)
+
+        return face_colors
+
+
+def compute_area_weights(areas):
+    mean_area = areas.mean()
+    normalized_weights = areas / mean_area
+    integer_weights = normalized_weights.astype(int)
+    return integer_weights.clip(MIN_AREA_WEIGHT, MAX_AREA_WEIGHT)

src/mesh/__init__.py

@@ -0,0 +1,7 @@
+from .uvmapper import apply_atlas_to_mesh
+
+__all__ = ["apply_atlas_to_mesh", "apply_atlas"]
+
+
+def apply_atlas(mesh, atlas, color_to_uv, mapper, face_colors=None):
+    return apply_atlas_to_mesh(mesh, atlas, color_to_uv, mapper, face_colors)

src/mesh/context.md

@@ -0,0 +1,32 @@
+# Mesh Module
+
+Apply texture atlases to 3D meshes
+
+## Purpose
+
+- Remap mesh UVs to atlas coordinates
+- Transform meshes with new textures
+
+## Layout
+
+```
+mesh/
+├── context.md   # This file
+├── __init__.py  # API: apply_atlas()
+└── uvmapper.py  # UV remapping logic
+```
+
+## Scope
+
+- In-scope: UV remapping, mesh transformation, vertex duplication
+- Out-of-scope: Mesh loading, color extraction
+
+## Entrypoints
+
+- `apply_atlas(mesh, atlas, color_to_uv, mapper, face_colors)` - Main application
+- `apply_atlas_to_mesh(mesh, atlas, color_to_uv, mapper, face_colors)` - Detailed UV remapping with cached colors
+
+## Dependencies
+
+- Internal: extraction.reader (for get_face_colors)
+- External: NumPy, trimesh

src/mesh/uvmapper.py

@@ -0,0 +1,85 @@
+import numpy as np
+import trimesh
+
+DEFAULT_UV_FALLBACK = (0.5, 0.5)
+
+
+def apply_atlas_to_mesh(mesh, atlas_texture, color_uv_mapping, palette_mapper, face_colors=None):
+    from ..extraction.reader import get_face_colors
+
+    if face_colors is None:
+        original_face_colors = get_face_colors(mesh)
+    else:
+        original_face_colors = face_colors
+    palette_matched_colors = palette_mapper.map_colors(original_face_colors)
+
+    uv_coordinates_per_face = generate_face_uv_coordinates(
+        palette_matched_colors, color_uv_mapping, len(mesh.faces)
+    )
+
+    duplicated_mesh = create_mesh_with_per_face_vertices(mesh, uv_coordinates_per_face)
+    apply_texture_to_mesh(duplicated_mesh, atlas_texture, uv_coordinates_per_face)
+
+    return duplicated_mesh
+
+
+def generate_face_uv_coordinates(face_colors, color_to_uv_map, total_faces):
+    uv_coordinates_array = np.zeros((total_faces, 3, 2), dtype=np.float32)
+    faces_without_mapping = 0
+
+    for face_index, face_color in enumerate(face_colors):
+        rgb_color_tuple = convert_color_to_tuple(face_color)
+        uv_position = color_to_uv_map.get(rgb_color_tuple, DEFAULT_UV_FALLBACK)
+
+        if (
+            uv_position == DEFAULT_UV_FALLBACK
+            and rgb_color_tuple not in color_to_uv_map
+        ):
+            faces_without_mapping += 1
+
+        assign_uniform_uv_to_face(uv_coordinates_array, face_index, uv_position)
+
+    if faces_without_mapping > 0:
+        print(f"Warning: {faces_without_mapping} faces had unmapped colors")
+
+    return uv_coordinates_array
+
+
+def convert_color_to_tuple(color):
+    return tuple(int(channel) for channel in color)
+
+
+def assign_uniform_uv_to_face(uv_array, face_index, uv_coordinate):
+    uv_array[face_index] = [uv_coordinate, uv_coordinate, uv_coordinate]
+
+
+def create_mesh_with_per_face_vertices(original_mesh, face_uv_coordinates):
+    face_vertex_positions = original_mesh.vertices[original_mesh.faces]
+    flattened_vertices = face_vertex_positions.reshape(-1, 3)
+    sequential_face_indices = np.arange(len(flattened_vertices)).reshape(-1, 3)
+
+    duplicated_mesh = trimesh.Trimesh(
+        vertices=flattened_vertices,
+        faces=sequential_face_indices,
+        vertex_normals=None,
+        process=False,
+    )
+
+    return duplicated_mesh
+
+
+def apply_texture_to_mesh(mesh, atlas_image, face_uv_array):
+    flattened_uv_coordinates = face_uv_array.reshape(-1, 2)
+
+    pbr_material = trimesh.visual.material.PBRMaterial(
+        baseColorTexture=atlas_image,
+        baseColorFactor=[1.0, 1.0, 1.0, 1.0],
+        roughnessFactor=1.0,
+        metallicFactor=0.0,
+    )
+
+    texture_visual = trimesh.visual.texture.TextureVisuals(
+        uv=flattened_uv_coordinates, image=atlas_image, material=pbr_material
+    )
+
+    mesh.visual = texture_visual

src/palette/__init__.py

@@ -0,0 +1,9 @@
+from .quantizer import quantize_colors
+from .mapper import PaletteMapper
+
+__all__ = ["quantize_colors", "PaletteMapper", "create_palette"]
+
+
+def create_palette(colors, size=16):
+    total_palette_colors = size * size
+    return quantize_colors(colors, target_color_count=total_palette_colors)

src/palette/color_space.py

@@ -0,0 +1,129 @@
+import numpy as np
+
+RGB_MAX_VALUE = 255.0
+SRGB_GAMMA = 2.4
+SRGB_LINEAR_THRESHOLD = 0.04045
+SRGB_OFFSET = 0.055
+SRGB_SCALE = 1.055
+SRGB_LINEAR_SCALE = 12.92
+
+D65_ILLUMINANT_X = 0.95047
+D65_ILLUMINANT_Z = 1.08883
+
+LAB_EPSILON = 216 / 24389
+LAB_KAPPA = 24389 / 27
+LAB_DELTA = 16 / 116
+
+
+def rgb_to_lab(rgb):
+    normalized_rgb = rgb.astype(np.float32) / RGB_MAX_VALUE
+    linear_rgb = apply_inverse_srgb_gamma(normalized_rgb)
+    xyz_values = convert_linear_rgb_to_xyz(linear_rgb)
+    normalized_xyz = normalize_xyz_by_d65_illuminant(xyz_values)
+    return convert_xyz_to_lab(normalized_xyz)
+
+
+def apply_inverse_srgb_gamma(normalized_rgb):
+    above_threshold = normalized_rgb > SRGB_LINEAR_THRESHOLD
+
+    linearized_high_values = ((normalized_rgb + SRGB_OFFSET) / SRGB_SCALE) ** SRGB_GAMMA
+    linearized_low_values = normalized_rgb / SRGB_LINEAR_SCALE
+
+    return np.where(above_threshold, linearized_high_values, linearized_low_values)
+
+
+def convert_linear_rgb_to_xyz(linear_rgb):
+    srgb_to_xyz_matrix = np.array(
+        [
+            [0.4124564, 0.3575761, 0.1804375],
+            [0.2126729, 0.7151522, 0.0721750],
+            [0.0193339, 0.1191920, 0.9503041],
+        ],
+        dtype=np.float32,
+    )
+    return linear_rgb @ srgb_to_xyz_matrix.T
+
+
+def normalize_xyz_by_d65_illuminant(xyz):
+    normalized = xyz.copy()
+    normalized[:, 0] /= D65_ILLUMINANT_X
+    normalized[:, 2] /= D65_ILLUMINANT_Z
+    return normalized
+
+
+def convert_xyz_to_lab(normalized_xyz):
+    above_epsilon = normalized_xyz > LAB_EPSILON
+
+    cubic_root_values = normalized_xyz ** (1 / 3)
+    linear_scaled_values = (LAB_KAPPA * normalized_xyz + 16) / 116
+
+    f_transformed = np.where(above_epsilon, cubic_root_values, linear_scaled_values)
+
+    lab_values = np.zeros_like(normalized_xyz)
+    lab_values[:, 0] = 116 * f_transformed[:, 1] - 16
+    lab_values[:, 1] = 500 * (f_transformed[:, 0] - f_transformed[:, 1])
+    lab_values[:, 2] = 200 * (f_transformed[:, 1] - f_transformed[:, 2])
+
+    return lab_values
+
+
+def lab_to_rgb(lab):
+    xyz_values = convert_lab_to_xyz(lab)
+    linear_rgb = convert_xyz_to_linear_rgb(xyz_values)
+    normalized_rgb = apply_srgb_gamma(linear_rgb)
+    return convert_normalized_to_8bit_rgb(normalized_rgb)
+
+
+def convert_lab_to_xyz(lab):
+    f_y = (lab[:, 0] + 16) / 116
+    f_x = lab[:, 1] / 500 + f_y
+    f_z = f_y - lab[:, 2] / 200
+
+    x_above_epsilon = f_x**3 > LAB_EPSILON
+    y_above_epsilon = lab[:, 0] > LAB_KAPPA * LAB_EPSILON
+    z_above_epsilon = f_z**3 > LAB_EPSILON
+
+    xyz_values = np.zeros((len(lab), 3), dtype=np.float32)
+
+    x_cubic = f_x**3
+    x_linear = (116 * f_x - 16) / LAB_KAPPA
+    xyz_values[:, 0] = np.where(x_above_epsilon, x_cubic, x_linear) * D65_ILLUMINANT_X
+
+    y_cubic = f_y**3
+    y_linear = lab[:, 0] / LAB_KAPPA
+    xyz_values[:, 1] = np.where(y_above_epsilon, y_cubic, y_linear)
+
+    z_cubic = f_z**3
+    z_linear = (116 * f_z - 16) / LAB_KAPPA
+    xyz_values[:, 2] = np.where(z_above_epsilon, z_cubic, z_linear) * D65_ILLUMINANT_Z
+
+    return xyz_values
+
+
+def convert_xyz_to_linear_rgb(xyz):
+    xyz_to_srgb_matrix = np.array(
+        [
+            [3.2404542, -1.5371385, -0.4985314],
+            [-0.9692660, 1.8760108, 0.0415560],
+            [0.0556434, -0.2040259, 1.0572252],
+        ],
+        dtype=np.float32,
+    )
+    return xyz @ xyz_to_srgb_matrix.T
+
+
+def apply_srgb_gamma(linear_rgb):
+    SRGB_LINEAR_CUTOFF = 0.0031308
+
+    above_cutoff = linear_rgb > SRGB_LINEAR_CUTOFF
+
+    gamma_corrected_high = SRGB_SCALE * (linear_rgb ** (1 / SRGB_GAMMA)) - SRGB_OFFSET
+    gamma_corrected_low = SRGB_LINEAR_SCALE * linear_rgb
+
+    return np.where(above_cutoff, gamma_corrected_high, gamma_corrected_low)
+
+
+def convert_normalized_to_8bit_rgb(normalized_rgb):
+    scaled_values = normalized_rgb * RGB_MAX_VALUE
+    clipped_values = np.clip(scaled_values, 0, RGB_MAX_VALUE)
+    return clipped_values.astype(np.uint8)

src/palette/context.md

@@ -0,0 +1,36 @@
+# Palette Module
+
+Color quantization and palette generation
+
+## Purpose
+
+- Quantize colors to fixed palettes
+- Map arbitrary colors to palette entries
+- Perform color space conversions
+
+## Layout
+
+```
+palette/
+├── context.md      # This file
+├── __init__.py     # API: create_palette()
+├── quantizer.py    # K-means clustering
+├── mapper.py       # Color-to-palette mapping
+└── color_space.py  # RGB/LAB conversions
+```
+
+## Scope
+
+- In-scope: Color quantization, LAB space clustering, nearest neighbor mapping
+- Out-of-scope: Image processing, texture generation
+
+## Entrypoints
+
+- `create_palette(colors, size)` - Generate palette
+- `PaletteMapper(palette)` - Map colors to palette
+- `quantize_colors(colors, n_colors)` - K-means quantization
+
+## Dependencies
+
+- Internal: color_space
+- External: NumPy, scikit-learn, SciPy

src/palette/mapper.py

@@ -0,0 +1,41 @@
+import numpy as np
+from scipy.spatial import KDTree
+from .color_space import rgb_to_lab
+
+
+class PaletteMapper:
+    def __init__(self, palette):
+        self.palette = palette
+        self.perceptual_color_tree = build_perceptual_color_tree(palette)
+
+    def map_colors(self, colors):
+        if len(colors) == 0:
+            return colors
+
+        perceptual_colors = rgb_to_lab(colors)
+        nearest_palette_indices = find_nearest_palette_indices(
+            self.perceptual_color_tree, perceptual_colors
+        )
+        return self.palette[nearest_palette_indices]
+
+    def get_palette_index(self, single_color):
+        single_color_array = single_color.reshape(1, -1)
+        perceptual_color = rgb_to_lab(single_color_array)
+        _, nearest_index = self.perceptual_color_tree.query(perceptual_color)
+        return extract_scalar_index(nearest_index)
+
+
+def build_perceptual_color_tree(palette):
+    palette_in_lab_space = rgb_to_lab(palette)
+    return KDTree(palette_in_lab_space)
+
+
+def find_nearest_palette_indices(kdtree, query_colors):
+    _, nearest_indices = kdtree.query(query_colors)
+    return nearest_indices
+
+
+def extract_scalar_index(index_result):
+    if isinstance(index_result, np.ndarray):
+        return index_result[0]
+    return index_result

src/palette/quantizer.py

@@ -0,0 +1,51 @@
+from sklearn.cluster import KMeans
+from .color_space import rgb_to_lab, lab_to_rgb
+
+LARGE_DATASET_THRESHOLD = 10000
+KMEANS_INIT_ATTEMPTS_FOR_LARGE_DATA = 3
+KMEANS_INIT_ATTEMPTS_FOR_SMALL_DATA = 10
+KMEANS_MAX_ITERATIONS_LARGE_DATA = 100
+KMEANS_MAX_ITERATIONS_SMALL_DATA = 300
+RANDOM_SEED = 42
+
+
+def quantize_colors(colors, target_color_count=256):
+    if len(colors) == 0:
+        raise ValueError("No colors to quantize")
+
+    perceptual_colors = rgb_to_lab(colors)
+    total_input_colors = len(perceptual_colors)
+
+    kmeans_config = determine_kmeans_parameters(total_input_colors)
+    actual_clusters = min(target_color_count, total_input_colors)
+
+    print(
+        f"Quantizing {total_input_colors} colors to {target_color_count} palette entries..."
+    )
+
+    cluster_model = KMeans(
+        n_clusters=actual_clusters,
+        n_init=kmeans_config["init_attempts"],
+        max_iter=kmeans_config["max_iterations"],
+        random_state=RANDOM_SEED,
+    )
+    cluster_model.fit(perceptual_colors)
+
+    palette_centers_in_lab = cluster_model.cluster_centers_
+    palette_in_rgb = lab_to_rgb(palette_centers_in_lab)
+
+    print(f"Created palette with {len(palette_in_rgb)} unique colors")
+    return palette_in_rgb
+
+
+def determine_kmeans_parameters(sample_count):
+    if sample_count >= LARGE_DATASET_THRESHOLD:
+        return {
+            "init_attempts": KMEANS_INIT_ATTEMPTS_FOR_LARGE_DATA,
+            "max_iterations": KMEANS_MAX_ITERATIONS_LARGE_DATA,
+        }
+    else:
+        return {
+            "init_attempts": KMEANS_INIT_ATTEMPTS_FOR_SMALL_DATA,
+            "max_iterations": KMEANS_MAX_ITERATIONS_SMALL_DATA,
+        }

src/preprocessing/__init__.py

@@ -0,0 +1,3 @@
+from .simplifier import simplify_texture
+
+__all__ = ["simplify_texture"]

src/preprocessing/context.md

@@ -0,0 +1,31 @@
+# Texture Preprocessing
+
+Simplification filters for removing fine details from textures
+
+## Purpose
+
+- Remove texture artifacts (scales, fur, feathers, noise)
+- Preserve edges and broad color zones
+- Prepare textures for cleaner palettization
+
+## Layout
+
+```
+preprocessing/
+├── context.md      # This file
+├── __init__.py     # Module exports
+└── simplifier.py   # Bilateral filter implementation
+```
+
+## Scope
+
+- In-scope: Edge-preserving texture smoothing
+- Out-of-scope: Color adjustment, resizing, format conversion
+
+## Entrypoints
+
+- `simplify_texture(image, enabled, d, sigma_color, sigma_space)` - Apply bilateral filter
+
+## Dependencies
+
+- External: opencv-python, PIL, numpy

src/preprocessing/simplifier.py

@@ -0,0 +1,29 @@
+import numpy as np
+from PIL import Image
+import cv2
+
+DEFAULT_BILATERAL_D = 9
+DEFAULT_BILATERAL_SIGMA_COLOR = 75
+DEFAULT_BILATERAL_SIGMA_SPACE = 75
+
+
+def simplify_texture(image, enabled=True, d=None, sigma_color=None, sigma_space=None):
+    if not enabled:
+        return image
+
+    if d is None:
+        d = DEFAULT_BILATERAL_D
+    if sigma_color is None:
+        sigma_color = DEFAULT_BILATERAL_SIGMA_COLOR
+    if sigma_space is None:
+        sigma_space = DEFAULT_BILATERAL_SIGMA_SPACE
+
+    if hasattr(image, "convert"):
+        rgb_image = image.convert("RGB")
+        img_array = np.array(rgb_image, dtype=np.uint8)
+    else:
+        img_array = np.array(image, dtype=np.uint8)
+
+    filtered = cv2.bilateralFilter(img_array, d, sigma_color, sigma_space)
+
+    return Image.fromarray(filtered, "RGB")