Upload 8 files

.gitignore

@@ -0,0 +1,59 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+*.egg-info/
+.pytest_cache/
+.venv/
+venv/
+
+# Workspace runtime data (kept local, not pushed)
+workspace/current/*
+workspace/history/*
+!workspace/current/.gitkeep
+!workspace/history/.gitkeep
+!workspace/exports/.gitkeep
+!workspace/presets/.gitkeep
+
+# Model weights (downloaded at runtime, not committed)
+weights/
+models/
+*.safetensors
+*.bin
+*.pt
+*.pth
+*.ckpt
+
+# Large generated files
+*.glb
+*.fbx
+*.usdz
+!presets/*.glb  # if we ship example assets
+
+# Generated textures
+workspace/current/textures/*.png
+workspace/current/textures/*.jpg
+
+# OS junk
+.DS_Store
+Thumbs.db
+desktop.ini
+
+# Editor
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# HF Spaces
+.huggingface/
+
+# Logs
+*.log
+logs/
+
+# Temp
+tmp/
+*.tmp

README.md

@@ -0,0 +1,38 @@
+---
+title: Open3DForge
+emoji: 🛠️
+colorFrom: indigo
+colorTo: purple
+sdk: gradio
+sdk_version: 4.44.0
+app_file: app.py
+pinned: false
+license: mit
+hardware: zero-a10g
+short_description: Personal image-to-game-ready 3D asset pipeline for UE5
+---
+
+# Open3DForge
+
+> **Personal AI-powered image-to-game-ready 3D asset pipeline**
+> Built for solo game development. UE5-first. Runs on HF ZeroGPU.
+
+A solo-developer tool for generating special/custom 3D assets (characters, unique props) that can't be sourced from Fab or Megascans. Generation → cleanup → UV unwrap → PBR baking → LODs → collision → optional rigging → engine-ready export.
+
+## Pipeline
+
+1. **Generate** — TRELLIS.2 (hard surface) or Hunyuan3D-2 (organic) from 1-4 input images
+2. **Post-Process** — repair, decimate, UV unwrap (xatlas), bake normals/albedo/materials/AO (nvdiffrast), inpaint hidden UVs (SDXL), LODs, collision (CoACD), pivot, scale
+3. **Auto-Rig** — UniRig for character skeletons
+4. **Export** — UE5 FBX bundle with DirectX normals + ORM packing
+
+## Hardware
+
+- **HF ZeroGPU H200** (70GB VRAM, 25 min/day on Pro)
+- **Local fallback** on RTX 4070 when quota's exhausted
+
+## Status
+
+🚧 Active development — Milestone 1 (foundation) in progress.
+
+See `PLAN.md` for the full architecture document.

app.py

@@ -0,0 +1,447 @@
+"""
+Open3DForge — Image-to-game-ready 3D asset pipeline
+====================================================
+
+Milestone 1: Foundation
+-----------------------
+This is the scaffold. It validates that:
+  - The HF Space builds with the right Gradio + ZeroGPU configuration
+  - `@spaces.GPU` allocates and releases an H200 successfully
+  - `gr.Model3D` renders GLB files inline
+  - The 5-tab UI structure is sound
+  - Workspace folder management works
+  - Quota tracking persists across page reloads
+
+Subsequent milestones fill in the actual pipeline stages.
+
+Run locally:  python app.py
+Deploy:       git push to HF Space
+"""
+
+from __future__ import annotations
+
+import time
+from pathlib import Path
+
+import gradio as gr
+import spaces  # HF ZeroGPU
+
+from src import quota, ui_helpers, workspace
+
+# ---------------------------------------------------------------------------
+# ZeroGPU test function — proves that GPU allocation works.
+# Replaced in Milestone 2 with the actual TRELLIS.2 generator.
+# ---------------------------------------------------------------------------
+
+@spaces.GPU(duration=15)
+def zerogpu_smoke_test() -> str:
+    """Allocate a GPU, run a trivial torch op, release. Reports timing."""
+    start = time.time()
+    try:
+        import torch
+        if not torch.cuda.is_available():
+            return "❌ GPU not available inside @spaces.GPU. Something is wrong."
+
+        device = torch.device("cuda")
+        # Trivial GPU work
+        a = torch.randn(1024, 1024, device=device)
+        b = torch.randn(1024, 1024, device=device)
+        c = a @ b
+        torch.cuda.synchronize()
+        result_sum = float(c.sum().item())
+
+        gpu_name = torch.cuda.get_device_name(0)
+        vram_total = torch.cuda.get_device_properties(0).total_memory / 1e9
+        elapsed = time.time() - start
+
+        quota.record_usage("smoke_test", elapsed)
+
+        return (
+            f"✅ **GPU allocation successful**\n\n"
+            f"- Device: `{gpu_name}`\n"
+            f"- VRAM: `{vram_total:.1f} GB`\n"
+            f"- Test op (1024×1024 matmul): `{elapsed:.2f}s`\n"
+            f"- Result sum: `{result_sum:.2f}` (sanity check, non-zero = ✓)\n\n"
+            f"ZeroGPU integration is working. Ready for Milestone 2."
+        )
+    except Exception as e:
+        elapsed = time.time() - start
+        return f"❌ GPU test failed after {elapsed:.2f}s:\n```\n{type(e).__name__}: {e}\n```"
+
+
+# ---------------------------------------------------------------------------
+# Stage stubs — return placeholder messages until milestones implement them.
+# ---------------------------------------------------------------------------
+
+def _stub(stage: str) -> str:
+    return (
+        f"🚧 **{stage}** — not implemented yet.\n\n"
+        f"This stub will be replaced in a future milestone. "
+        f"See `PLAN.md` for the full pipeline spec."
+    )
+
+
+def stub_generate(*_args, **_kwargs):
+    return _stub("Stage 1: Generation")
+
+
+def stub_post_process(*_args, **_kwargs):
+    return _stub("Stage 2: Post-Processing")
+
+
+def stub_auto_rig(*_args, **_kwargs):
+    return _stub("Stage 3: Auto-Rigging")
+
+
+def stub_export(*_args, **_kwargs):
+    return _stub("Stage 4: Export"), None  # message, file
+
+
+# ---------------------------------------------------------------------------
+# Presets tab logic (this one is real even in Milestone 1)
+# ---------------------------------------------------------------------------
+
+def ui_refresh_presets() -> gr.Dropdown:
+    return gr.Dropdown(choices=workspace.list_presets(), label="Saved presets")
+
+
+def ui_save_preset(name: str) -> tuple[str, gr.Dropdown]:
+    if not name or not name.strip():
+        return "❌ Preset name cannot be empty.", ui_refresh_presets()
+    # Placeholder config — Milestone 9 wires in real settings from each tab
+    config = {
+        "name": name,
+        "version": 1,
+        "created_at": time.time(),
+        "note": "Placeholder — real preset data wired in Milestone 9",
+    }
+    workspace.save_preset(name, config)
+    return f"✅ Saved preset: `{name}`", ui_refresh_presets()
+
+
+def ui_delete_preset(name: str) -> tuple[str, gr.Dropdown]:
+    if not name:
+        return "❌ Select a preset to delete.", ui_refresh_presets()
+    if workspace.delete_preset(name):
+        return f"🗑️ Deleted preset: `{name}`", ui_refresh_presets()
+    return f"❌ Preset not found: `{name}`", ui_refresh_presets()
+
+
+# ---------------------------------------------------------------------------
+# Layout
+# ---------------------------------------------------------------------------
+
+CUSTOM_CSS = """
+.status-bar {
+    font-size: 0.85em;
+    color: #888;
+    padding: 8px 12px;
+    border-top: 1px solid #333;
+    margin-top: 12px;
+}
+.asset-summary {
+    font-size: 0.9em;
+    background: rgba(255,255,255,0.03);
+    padding: 12px;
+    border-radius: 6px;
+    border: 1px solid rgba(255,255,255,0.08);
+}
+"""
+
+
+def build_ui() -> gr.Blocks:
+    with gr.Blocks(
+        title="Open3DForge",
+        theme=gr.themes.Soft(primary_hue="indigo", neutral_hue="slate"),
+        css=CUSTOM_CSS,
+    ) as demo:
+
+        # --- Header --------------------------------------------------------
+        gr.Markdown(
+            "# 🛠️ Open3DForge\n"
+            "*Personal image-to-game-ready 3D asset pipeline · UE5-first · "
+            "Built on HF ZeroGPU*"
+        )
+
+        # --- Tabs ----------------------------------------------------------
+        with gr.Tabs() as tabs:
+
+            # ============ Tab 1: Generate =================================
+            with gr.Tab("1. Generate", id=1):
+                gr.Markdown(
+                    "### Stage 1 — Image to 3D\n"
+                    "Upload 1–4 reference images. Multi-view dramatically "
+                    "improves quality for characters (front / 3-quarter / side / back)."
+                )
+                with gr.Row():
+                    with gr.Column(scale=1):
+                        gen_images = gr.File(
+                            label="Reference images (1–4)",
+                            file_count="multiple",
+                            file_types=["image"],
+                        )
+                        gen_model = gr.Radio(
+                            choices=[
+                                "TRELLIS.2 (Hard Surface)",
+                                "Hunyuan3D-2 (Organic / Characters)",
+                            ],
+                            value="TRELLIS.2 (Hard Surface)",
+                            label="Generation model",
+                        )
+                        gen_quality = gr.Radio(
+                            choices=["Fast (~30s)", "Balanced (~60s)", "Hero (~90s)"],
+                            value="Balanced (~60s)",
+                            label="Quality preset",
+                        )
+                        with gr.Accordion("Advanced", open=False):
+                            gen_seed = gr.Number(value=42, label="Seed", precision=0)
+                            gen_steps = gr.Slider(
+                                20, 50, value=35, step=5,
+                                label="Inference steps",
+                            )
+                            gen_octree = gr.Dropdown(
+                                choices=[128, 192, 256], value=192,
+                                label="Octree resolution",
+                            )
+                            gen_tex_size = gr.Dropdown(
+                                choices=[1024, 2048, 4096], value=2048,
+                                label="Texture size",
+                            )
+                            gen_symmetry = gr.Radio(
+                                choices=["off", "bilateral", "radial"],
+                                value="off",
+                                label="Symmetry hint",
+                            )
+                        gen_btn = gr.Button("Generate", variant="primary")
+                    with gr.Column(scale=1):
+                        gen_status = gr.Markdown("*Awaiting input.*")
+                gen_btn.click(
+                    fn=stub_generate,
+                    inputs=[gen_images, gen_model, gen_quality, gen_seed,
+                            gen_steps, gen_octree, gen_tex_size, gen_symmetry],
+                    outputs=gen_status,
+                )
+
+            # ============ Tab 2: Post-Process =============================
+            with gr.Tab("2. Post-Process", id=2):
+                gr.Markdown(
+                    "### Stage 2 — Mesh cleanup, UV unwrap, texture baking\n"
+                    "Toggle steps on/off. Decimation has a live preview, the "
+                    "rest run on confirm."
+                )
+                with gr.Row():
+                    with gr.Column(scale=1):
+                        pp_repair = gr.Checkbox(value=True, label="Mesh repair (pymeshfix)")
+                        pp_cleanup = gr.Checkbox(value=True, label="Geometry cleanup (PyMeshLab)")
+                        pp_decimate = gr.Checkbox(value=True, label="Decimation")
+                        pp_target_faces = gr.Slider(
+                            1000, 200000, value=25000, step=1000,
+                            label="Target faces",
+                        )
+                        pp_symmetry = gr.Checkbox(value=False, label="Enforce bilateral symmetry")
+                        pp_unwrap = gr.Checkbox(value=True, label="UV unwrap (xatlas)")
+                        pp_normal_bake = gr.Checkbox(value=True, label="Normal bake (nvdiffrast)")
+                        pp_normal_format = gr.Radio(
+                            choices=["DirectX (UE5)", "OpenGL (Unity/Godot)"],
+                            value="DirectX (UE5)",
+                            label="Normal format",
+                        )
+                        pp_albedo_bake = gr.Checkbox(value=True, label="Albedo bake")
+                        pp_material_bake = gr.Checkbox(value=True, label="Material bake (TRELLIS.2 attrs)")
+                        pp_ao = gr.Checkbox(value=True, label="AO bake")
+                        pp_ao_quality = gr.Radio(
+                            choices=["Fast", "Standard", "High"],
+                            value="Standard",
+                            label="AO quality",
+                        )
+                        pp_inpaint = gr.Checkbox(value=False, label="SDXL inpaint hidden UVs (~30s GPU)")
+                        pp_lods = gr.Checkbox(value=True, label="Generate LODs (LOD0/1/2)")
+                        pp_collision = gr.Checkbox(value=True, label="Collision mesh (CoACD)")
+                        pp_pivot = gr.Radio(
+                            choices=["bottom_center", "geometric_center", "custom"],
+                            value="bottom_center",
+                            label="Pivot point",
+                        )
+                        pp_scale_m = gr.Number(value=1.8, label="Real-world height (meters)")
+                        pp_btn = gr.Button("Run Post-Processing", variant="primary")
+                    with gr.Column(scale=1):
+                        pp_status = gr.Markdown("*No asset to process. Generate one first.*")
+                pp_btn.click(
+                    fn=stub_post_process,
+                    inputs=[pp_repair, pp_cleanup, pp_decimate, pp_target_faces,
+                            pp_symmetry, pp_unwrap, pp_normal_bake, pp_normal_format,
+                            pp_albedo_bake, pp_material_bake, pp_ao, pp_ao_quality,
+                            pp_inpaint, pp_lods, pp_collision, pp_pivot, pp_scale_m],
+                    outputs=pp_status,
+                )
+
+            # ============ Tab 3: Auto-Rig =================================
+            with gr.Tab("3. Auto-Rig", id=3):
+                gr.Markdown(
+                    "### Stage 3 — Auto-rigging (optional)\n"
+                    "Uses UniRig (VAST-AI). For characters and creatures. "
+                    "After rigging, drop the FBX into [Mixamo](https://mixamo.com) "
+                    "for free animation presets."
+                )
+                with gr.Row():
+                    with gr.Column(scale=1):
+                        rig_type = gr.Dropdown(
+                            choices=["Humanoid", "Quadruped", "Bird", "Insect", "Custom"],
+                            value="Humanoid",
+                            label="Character type",
+                        )
+                        rig_seed = gr.Number(value=0, label="Skeleton seed", precision=0)
+                        rig_spring = gr.Checkbox(value=False, label="Spring bones (hair/cloth/tail)")
+                        rig_format = gr.Radio(
+                            choices=["FBX (UE5 recommended)", "GLB"],
+                            value="FBX (UE5 recommended)",
+                            label="Export format",
+                        )
+                        rig_btn = gr.Button("Auto-Rig", variant="primary")
+                    with gr.Column(scale=1):
+                        rig_status = gr.Markdown("*Process an asset in Stage 2 first.*")
+                rig_btn.click(
+                    fn=stub_auto_rig,
+                    inputs=[rig_type, rig_seed, rig_spring, rig_format],
+                    outputs=rig_status,
+                )
+
+            # ============ Tab 4: Export ===================================
+            with gr.Tab("4. Export", id=4):
+                gr.Markdown(
+                    "### Stage 4 — Engine-ready export\n"
+                    "UE5 default: FBX with DirectX normals + ORM-packed textures."
+                )
+                with gr.Row():
+                    with gr.Column(scale=1):
+                        ex_engine = gr.Dropdown(
+                            choices=["UE5", "Unity (HDRP)", "Godot 4", "Blender", "Web (Three.js)"],
+                            value="UE5",
+                            label="Target engine",
+                        )
+                        ex_name = gr.Textbox(value="Asset_01", label="Asset name")
+                        ex_type = gr.Radio(
+                            choices=["Character (SK_)", "Prop (SM_)", "Environment (SM_)"],
+                            value="Prop (SM_)",
+                            label="Asset type",
+                        )
+                        ex_include_lods = gr.Checkbox(value=True, label="Include LODs")
+                        ex_include_collision = gr.Checkbox(value=True, label="Include collision mesh")
+                        ex_btn = gr.Button("Export", variant="primary")
+                    with gr.Column(scale=1):
+                        ex_status = gr.Markdown("*Nothing to export yet.*")
+                        ex_file = gr.File(label="Download", visible=True)
+                ex_btn.click(
+                    fn=stub_export,
+                    inputs=[ex_engine, ex_name, ex_type, ex_include_lods, ex_include_collision],
+                    outputs=[ex_status, ex_file],
+                )
+
+            # ============ Tab 5: Presets ==================================
+            with gr.Tab("5. Presets", id=5):
+                gr.Markdown(
+                    "### Saved configurations\n"
+                    "Save parameter sets for asset types you create repeatedly "
+                    "(e.g., \"character_UE5_hero\", \"prop_UE5_standard\"). "
+                    "Wired up properly in Milestone 9."
+                )
+                with gr.Row():
+                    with gr.Column():
+                        pr_list = gr.Dropdown(
+                            choices=workspace.list_presets(),
+                            label="Saved presets",
+                        )
+                        pr_refresh = gr.Button("Refresh list", size="sm")
+                        with gr.Row():
+                            pr_name = gr.Textbox(label="New preset name", scale=2)
+                            pr_save = gr.Button("Save current settings", variant="primary", scale=1)
+                        pr_delete = gr.Button("Delete selected", variant="stop")
+                        pr_status = gr.Markdown()
+                pr_refresh.click(fn=ui_refresh_presets, outputs=pr_list)
+                pr_save.click(fn=ui_save_preset, inputs=pr_name, outputs=[pr_status, pr_list])
+                pr_delete.click(fn=ui_delete_preset, inputs=pr_list, outputs=[pr_status, pr_list])
+
+            # ============ Tab 6: Diagnostics (hidden in prod, useful now) =
+            with gr.Tab("Diagnostics", id=99):
+                gr.Markdown(
+                    "### Milestone 1 — Foundation check\n"
+                    "Verify the Space environment is working correctly before "
+                    "building out the pipeline."
+                )
+                with gr.Row():
+                    with gr.Column():
+                        diag_btn = gr.Button("🧪 Run GPU smoke test", variant="primary")
+                        diag_out = gr.Markdown()
+                    with gr.Column():
+                        gr.Markdown("**Workspace state:**")
+                        diag_state = gr.JSON(value=workspace.get_state().to_dict())
+                        diag_refresh = gr.Button("Refresh state", size="sm")
+                diag_btn.click(fn=zerogpu_smoke_test, outputs=diag_out)
+                diag_refresh.click(
+                    fn=lambda: workspace.get_state().to_dict(),
+                    outputs=diag_state,
+                )
+
+        # --- Persistent right-side viewer + asset summary ------------------
+        gr.Markdown("---")
+        with gr.Row():
+            with gr.Column(scale=2):
+                viewer = gr.Model3D(
+                    label="3D viewer",
+                    value=ui_helpers.get_viewer_model_path(),
+                    clear_color=[0.1, 0.1, 0.12, 1.0],
+                    height=500,
+                )
+            with gr.Column(scale=1):
+                summary = gr.Markdown(
+                    value=ui_helpers.get_asset_summary(),
+                    elem_classes=["asset-summary"],
+                )
+                refresh_summary = gr.Button("🔄 Refresh viewer", size="sm")
+                refresh_summary.click(
+                    fn=lambda: (
+                        ui_helpers.get_viewer_model_path(),
+                        ui_helpers.get_asset_summary(),
+                    ),
+                    outputs=[viewer, summary],
+                )
+
+        # --- Global status bar --------------------------------------------
+        status_bar = gr.Markdown(
+            value=ui_helpers.get_status_bar(),
+            elem_classes=["status-bar"],
+        )
+
+        # --- Global refresh: every pipeline action updates the viewer, summary,
+        # and status bar. We chain .then() onto each button so the refresh runs
+        # only after the action completes (and even if it fails — Gradio still
+        # fires .then() after exceptions inside the main handler).
+        def _global_refresh():
+            return (
+                ui_helpers.get_viewer_model_path(),
+                ui_helpers.get_asset_summary(),
+                ui_helpers.get_status_bar(),
+            )
+
+        for trigger_btn in (gen_btn, pp_btn, rig_btn, ex_btn,
+                            diag_btn, diag_refresh, refresh_summary):
+            trigger_btn.click(
+                fn=_global_refresh,
+                outputs=[viewer, summary, status_bar],
+            )
+
+    return demo
+
+
+# ---------------------------------------------------------------------------
+# Entrypoint
+# ---------------------------------------------------------------------------
+
+if __name__ == "__main__":
+    workspace.ensure_dirs()
+    demo = build_ui()
+    demo.queue(default_concurrency_limit=1).launch(
+        server_name="0.0.0.0",
+        server_port=7860,
+        show_error=True,
+    )

quota.py

@@ -0,0 +1,148 @@
+"""
+ZeroGPU quota tracking.
+
+HF Pro gives 1500s (25 min) of H200 time per day. There's no official Python
+API to query remaining quota directly — we track it locally per-call.
+
+This module:
+- Records GPU time consumed via the `@spaces.GPU` decorated functions
+- Provides estimates for upcoming operations
+- Resets daily (per-day file on disk)
+
+Note: this is approximate. The authoritative source is HF's quota error if
+you go over. Our tracking is for UX (showing "~18/25 min used today").
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from dataclasses import dataclass
+from pathlib import Path
+
+from .workspace import WORKSPACE
+
+QUOTA_FILE = WORKSPACE / "quota_log.json"
+DAILY_QUOTA_SECONDS = 1500   # 25 minutes for HF Pro
+OVERAGE_RATE_PER_SECOND = 1.0 / 600.0   # $1 per 600s (10 min)
+
+
+@dataclass
+class QuotaState:
+    date: str                # YYYY-MM-DD (UTC)
+    used_seconds: float
+    operations: list[dict]   # log of recent operations
+
+    def remaining_seconds(self) -> float:
+        return max(0.0, DAILY_QUOTA_SECONDS - self.used_seconds)
+
+    def usage_fraction(self) -> float:
+        return min(1.0, self.used_seconds / DAILY_QUOTA_SECONDS)
+
+    def overage_cost_usd(self) -> float:
+        overage = max(0.0, self.used_seconds - DAILY_QUOTA_SECONDS)
+        return overage * OVERAGE_RATE_PER_SECOND
+
+
+def _today_utc() -> str:
+    return time.strftime("%Y-%m-%d", time.gmtime())
+
+
+def _load_or_new() -> QuotaState:
+    today = _today_utc()
+    if QUOTA_FILE.exists():
+        try:
+            with QUOTA_FILE.open("r") as f:
+                data = json.load(f)
+            if data.get("date") == today:
+                return QuotaState(
+                    date=data["date"],
+                    used_seconds=float(data["used_seconds"]),
+                    operations=data.get("operations", []),
+                )
+        except (json.JSONDecodeError, KeyError, ValueError):
+            pass
+    # Fresh day or corrupted file
+    return QuotaState(date=today, used_seconds=0.0, operations=[])
+
+
+def _save(state: QuotaState) -> None:
+    with QUOTA_FILE.open("w") as f:
+        json.dump(
+            {
+                "date": state.date,
+                "used_seconds": state.used_seconds,
+                "operations": state.operations[-50:],  # keep last 50
+            },
+            f,
+            indent=2,
+        )
+
+
+def get_state() -> QuotaState:
+    """Get current quota state, refreshed for today."""
+    return _load_or_new()
+
+
+def record_usage(operation: str, seconds: float) -> QuotaState:
+    """Record a completed GPU operation. Returns updated state."""
+    state = _load_or_new()
+    state.used_seconds += seconds
+    state.operations.append({
+        "op": operation,
+        "seconds": round(seconds, 2),
+        "timestamp": time.time(),
+    })
+    _save(state)
+    return state
+
+
+# ---------------------------------------------------------------------------
+# Per-operation estimates (used by UI to warn before expensive operations)
+# ---------------------------------------------------------------------------
+
+ESTIMATES = {
+    # Stage 1
+    "generate_trellis2_fast": 30,
+    "generate_trellis2_balanced": 60,
+    "generate_trellis2_hero": 90,
+    "generate_hunyuan3d": 60,
+    # Stage 2 — baking (nvdiffrast is fast)
+    "bake_normal_2k": 5,
+    "bake_normal_4k": 12,
+    "bake_albedo": 2,
+    "bake_materials": 3,
+    "bake_ao_fast": 3,
+    "bake_ao_standard": 10,
+    "bake_ao_high": 30,
+    # Stage 2 — optional
+    "inpaint_sdxl": 30,
+    # Stage 3
+    "auto_rig": 40,
+}
+
+
+def estimate(operation: str) -> int:
+    """Get the typical GPU duration for an operation, in seconds.
+
+    Used to:
+      - set `@spaces.GPU(duration=N)` correctly
+      - show cost warnings in the UI before triggering an operation
+    """
+    return ESTIMATES.get(operation, 60)
+
+
+def format_status() -> str:
+    """One-line quota summary for the UI status bar."""
+    s = get_state()
+    used_min = s.used_seconds / 60
+    total_min = DAILY_QUOTA_SECONDS / 60
+    remaining_min = s.remaining_seconds() / 60
+
+    if s.used_seconds >= DAILY_QUOTA_SECONDS:
+        cost = s.overage_cost_usd()
+        return f"⚠️ Quota: {used_min:.1f}/{total_min:.0f} min (overage: ${cost:.2f})"
+    elif s.usage_fraction() > 0.8:
+        return f"⚠️ Quota: {used_min:.1f}/{total_min:.0f} min ({remaining_min:.1f} min left)"
+    else:
+        return f"Quota: {used_min:.1f}/{total_min:.0f} min H200 today"

requirements.txt

@@ -0,0 +1,44 @@
+# Open3DForge — Dependencies
+# Versions pinned for HF Spaces stability (ZeroGPU torch 2.4.x compatible)
+
+# ===== Milestone 1: Foundation =====
+gradio==4.44.0
+spaces                      # HF ZeroGPU decorator
+huggingface-hub>=0.24,<0.26 # Gradio 4.44 requires HfFolder (removed in 0.26+)
+numpy>=1.26,<2.0
+pillow>=10.0.0
+
+# ===== Milestone 2: Stage 1 Generation (uncomment as needed) =====
+# torch==2.4.0
+# torchvision==0.19.0
+# rembg[gpu]==2.0.59
+# transformers>=4.44.0
+# diffusers>=0.30.0
+# huggingface-hub>=0.24.0
+# # TRELLIS.2 — install from source in app.py or via setup script
+# # Hunyuan3D-2 — install from source in app.py or via setup script
+# einops>=0.8.0
+# scipy>=1.13.0
+
+# ===== Milestone 3: Stage 2 CPU pipeline =====
+# trimesh[easy]>=4.4.0
+# pymeshfix>=0.17.0
+# pymeshlab>=2025.7
+# xatlas>=0.0.9
+# fast-simplification>=0.1.7
+# coacd==1.0.4              # pinned: newer versions break on some HF environments
+
+# ===== Milestone 4: Stage 2 GPU baking =====
+# nvdiffrast @ git+https://github.com/NVlabs/nvdiffrast.git
+# imageio>=2.34.0
+
+# ===== Milestone 5: Stage 2 SDXL inpainting =====
+# # Uses diffusers (already included)
+# accelerate>=0.33.0
+# safetensors>=0.4.3
+
+# ===== Milestone 7: Stage 3 Auto-rigging =====
+# # UniRig — install from source in app.py or via setup script
+
+# ===== Milestone 8: Export =====
+# pygltflib>=1.16.0

ui_helpers.py

@@ -0,0 +1,119 @@
+"""
+UI helpers — shared functions across Gradio tabs.
+
+Keeps `app.py` focused on layout, not formatting logic.
+"""
+
+from __future__ import annotations
+
+from . import quota, workspace
+
+
+def get_status_bar() -> str:
+    """Build the global status bar shown at the bottom of every tab.
+
+    Markdown-formatted single line with quota + workspace info.
+    """
+    state = workspace.get_state()
+    parts = [
+        quota.format_status(),
+        f"📁 Workspace: {workspace.current_size_mb():.1f} MB",
+        f"📦 Exports: {workspace.export_count()}",
+    ]
+    if state.model_used:
+        parts.append(f"🔧 Last: {state.model_used}")
+    return " · ".join(parts)
+
+
+def get_asset_summary() -> str:
+    """Multi-line summary of what's currently in `workspace/current/`.
+
+    Used in the viewer panel to show pipeline progress.
+    """
+    state = workspace.get_state()
+    lines = [f"**Asset:** `{state.asset_name}`"]
+
+    if state.face_count:
+        lines.append(f"- Faces: {state.face_count:,}")
+        lines.append(f"- Vertices: {state.vertex_count:,}")
+
+    stages = []
+    if state.high_poly_glb:
+        stages.append("✓ Generated")
+    if state.cleaned_glb:
+        stages.append("✓ Cleaned")
+    if state.low_poly_glb:
+        stages.append("✓ Decimated")
+    if state.unwrapped_glb:
+        stages.append("✓ UV unwrapped")
+    if state.normal_dx_png or state.normal_gl_png:
+        stages.append("✓ Normal baked")
+    if state.albedo_png:
+        stages.append("✓ Albedo baked")
+    if state.orm_png or (state.roughness_png and state.metallic_png):
+        stages.append("✓ PBR maps")
+    if state.lod_glbs:
+        stages.append(f"✓ LODs ({len(state.lod_glbs)})")
+    if state.collision_glb:
+        stages.append("✓ Collision")
+    if state.rigged_glb or state.rigged_fbx:
+        stages.append("✓ Rigged")
+
+    if stages:
+        lines.append("")
+        lines.append("**Progress:**")
+        for s in stages:
+            lines.append(f"- {s}")
+    else:
+        lines.append("")
+        lines.append("*No asset loaded yet. Start at the Generate tab.*")
+
+    return "\n".join(lines)
+
+
+def get_viewer_model_path() -> str | None:
+    """Pick the best GLB to show in the 3D viewer right now.
+
+    Prefers the most-processed version available.
+    """
+    state = workspace.get_state()
+    # Order: most processed → least processed
+    candidates = (
+        state.rigged_glb,
+        state.final_glb,
+        state.unwrapped_glb,
+        state.low_poly_glb,
+        state.cleaned_glb,
+        state.repaired_glb,
+        state.raw_gen_glb,
+        state.high_poly_glb,
+    )
+    for path in candidates:
+        if path and path.exists():
+            return str(path)
+    return None
+
+
+def quota_warning(operation: str) -> str:
+    """Generate a warning if an operation would exceed the daily quota.
+
+    Returns an empty string if the operation fits comfortably.
+    """
+    estimated = quota.estimate(operation)
+    state = quota.get_state()
+    remaining = state.remaining_seconds()
+
+    if estimated > remaining:
+        overage = estimated - remaining
+        cost = overage * quota.OVERAGE_RATE_PER_SECOND
+        return (
+            f"⚠️ **Quota warning:** This will use ~{estimated}s but you only "
+            f"have {remaining:.0f}s left today. "
+            f"Overage cost: ~${cost:.2f}"
+        )
+    elif estimated > remaining * 0.5:
+        return (
+            f"ℹ️ Estimated GPU time: ~{estimated}s "
+            f"({remaining:.0f}s remaining today)"
+        )
+    return ""

workspace.py

@@ -0,0 +1,219 @@
+"""
+Workspace management for Open3DForge.
+
+Single-user pattern: one persistent workspace folder.
+No session IDs, no multi-tenancy.
+
+Layout:
+    workspace/
+        current/    -- active work, overwritten per generation
+        exports/    -- finished asset zips, kept indefinitely
+        presets/    -- saved parameter configurations (JSON)
+        history/    -- thumbnails + metadata of past assets
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+# ---------------------------------------------------------------------------
+# Paths
+# ---------------------------------------------------------------------------
+
+ROOT = Path(__file__).resolve().parent.parent
+WORKSPACE = ROOT / "workspace"
+CURRENT = WORKSPACE / "current"
+EXPORTS = WORKSPACE / "exports"
+PRESETS = WORKSPACE / "presets"
+HISTORY = WORKSPACE / "history"
+
+# Subdirectories of `current/` created on each generation
+CURRENT_TEXTURES = CURRENT / "textures"
+CURRENT_LODS = CURRENT / "lods"
+
+
+def ensure_dirs() -> None:
+    """Create all workspace directories if missing. Safe to call repeatedly."""
+    for p in (WORKSPACE, CURRENT, EXPORTS, PRESETS, HISTORY,
+              CURRENT_TEXTURES, CURRENT_LODS):
+        p.mkdir(parents=True, exist_ok=True)
+
+
+def reset_current() -> None:
+    """Clear `current/` for a fresh asset. Called at the start of generation."""
+    if CURRENT.exists():
+        shutil.rmtree(CURRENT)
+    CURRENT.mkdir(parents=True, exist_ok=True)
+    CURRENT_TEXTURES.mkdir(parents=True, exist_ok=True)
+    CURRENT_LODS.mkdir(parents=True, exist_ok=True)
+
+
+# ---------------------------------------------------------------------------
+# Asset state (in-memory representation of what's in `current/`)
+# ---------------------------------------------------------------------------
+
+@dataclass
+class AssetState:
+    """Tracks what files exist in `current/` and the pipeline progress.
+
+    Updated by each stage as it completes. Used by the UI to enable/disable
+    buttons and show status indicators.
+    """
+
+    # Input
+    input_images: list[Path] = field(default_factory=list)
+
+    # Stage 1 outputs
+    high_poly_glb: Path | None = None         # raw TRELLIS.2 output, kept for baking
+    raw_gen_glb: Path | None = None           # decimated base from generation
+
+    # Stage 2 outputs
+    repaired_glb: Path | None = None
+    cleaned_glb: Path | None = None
+    low_poly_glb: Path | None = None          # post-decimation working mesh
+    unwrapped_glb: Path | None = None         # has UV coordinates
+    final_glb: Path | None = None             # all post-processing done
+
+    # Textures (Stage 2 baking)
+    albedo_png: Path | None = None
+    normal_gl_png: Path | None = None
+    normal_dx_png: Path | None = None
+    roughness_png: Path | None = None
+    metallic_png: Path | None = None
+    ao_png: Path | None = None
+    orm_png: Path | None = None               # UE5-packed AO/Rough/Metal
+    metallic_smoothness_png: Path | None = None  # Unity-packed
+
+    # LODs
+    lod_glbs: list[Path] = field(default_factory=list)
+
+    # Collision
+    collision_glb: Path | None = None
+
+    # Rigging (Stage 3)
+    rigged_glb: Path | None = None
+    rigged_fbx: Path | None = None
+
+    # Metadata
+    asset_name: str = "untitled"
+    generated_at: float = field(default_factory=time.time)
+    model_used: str = ""                      # "TRELLIS.2" or "Hunyuan3D-2"
+    face_count: int = 0
+    vertex_count: int = 0
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialise for status display / debug."""
+        out: dict[str, Any] = {}
+        for k, v in self.__dict__.items():
+            if isinstance(v, Path):
+                out[k] = str(v) if v else None
+            elif isinstance(v, list):
+                out[k] = [str(p) for p in v]
+            else:
+                out[k] = v
+        return out
+
+
+# Module-level singleton: in a single-user app, this is fine.
+# In Gradio, requests are serialized so there's no race condition at the
+# typical interaction level. Real concurrent generation would need locking.
+_state: AssetState = AssetState()
+
+
+def get_state() -> AssetState:
+    return _state
+
+
+def reset_state() -> AssetState:
+    """Replace the global state with a fresh one. Returns the new state."""
+    global _state
+    _state = AssetState()
+    return _state
+
+
+# ---------------------------------------------------------------------------
+# Presets (JSON-on-disk, loaded as dicts)
+# ---------------------------------------------------------------------------
+
+def list_presets() -> list[str]:
+    """Return preset names (filenames without .json), sorted."""
+    if not PRESETS.exists():
+        return []
+    return sorted(p.stem for p in PRESETS.glob("*.json"))
+
+
+def load_preset(name: str) -> dict[str, Any]:
+    """Load a preset by name. Raises FileNotFoundError if missing."""
+    path = PRESETS / f"{name}.json"
+    if not path.exists():
+        raise FileNotFoundError(f"Preset not found: {name}")
+    with path.open("r", encoding="utf-8") as f:
+        return json.load(f)
+
+
+def save_preset(name: str, config: dict[str, Any]) -> Path:
+    """Save a preset as JSON. Overwrites if exists."""
+    safe_name = _sanitize_filename(name)
+    path = PRESETS / f"{safe_name}.json"
+    with path.open("w", encoding="utf-8") as f:
+        json.dump(config, f, indent=2, sort_keys=True)
+    return path
+
+
+def delete_preset(name: str) -> bool:
+    """Delete a preset. Returns True if deleted, False if it didn't exist."""
+    path = PRESETS / f"{name}.json"
+    if path.exists():
+        path.unlink()
+        return True
+    return False
+
+
+def _sanitize_filename(name: str) -> str:
+    """Strip path separators and unsafe chars from a filename stem."""
+    return "".join(c for c in name if c.isalnum() or c in "_-").strip("_-") or "preset"
+
+
+# ---------------------------------------------------------------------------
+# Workspace stats (for UI status bar)
+# ---------------------------------------------------------------------------
+
+def workspace_size_mb() -> float:
+    """Total size of the workspace in MB."""
+    total = 0
+    if WORKSPACE.exists():
+        for path in WORKSPACE.rglob("*"):
+            if path.is_file():
+                total += path.stat().st_size
+    return total / (1024 * 1024)
+
+
+def current_size_mb() -> float:
+    """Size of `current/` only (active work)."""
+    total = 0
+    if CURRENT.exists():
+        for path in CURRENT.rglob("*"):
+            if path.is_file():
+                total += path.stat().st_size
+    return total / (1024 * 1024)
+
+
+def export_count() -> int:
+    """How many exported zips exist."""
+    if not EXPORTS.exists():
+        return 0
+    return len(list(EXPORTS.glob("*.zip")))
+
+
+# ---------------------------------------------------------------------------
+# Module init
+# ---------------------------------------------------------------------------
+
+# Auto-create folders on import so the app never crashes on a fresh checkout
+ensure_dirs()