Upload 11 files

README.md

@@ -1,54 +1,45 @@
 ---
 title: Particle Blueprint 3D
-emoji: 🚀
+emoji: 🧊
 colorFrom: indigo
 colorTo: blue
 sdk: gradio
-sdk_version: 5.24.0
 app_file: app.py
-pinned: false
-python_version: 3.10
+python_version: "3.10"
+startup_duration_timeout: 1h
+preload_from_hub:
+  - tencent/Hunyuan3D-1
+  - Tencent-Hunyuan/HunyuanDiT-v1.1-Diffusers-Distilled
+  - tencent/Hunyuan3D-Omni
 ---
 
 # Particle Blueprint 3D
 
-Mobile-first Hugging Face Space for **prompt → live particle blueprint → inspect → mesh**.
+Mobile-first 3D concept workflow for Hugging Face Spaces.
 
-## What this version does
+## What this build does
 
-- works with a **flat repo root** so you can upload files directly without creating folders
-- uses a **two-step workflow**:
-  1. generate the particle blueprint live in stages
-  2. inspect it in the viewport
-  3. tap **Make mesh from blueprint** when happy
-- supports a local planner model for prompt-to-structure parsing
-- caches **`tencent/Hunyuan3D-Omni`** during the mesh step so the Space is prepared for deeper target-model integration later
+- takes a text prompt
+- tries to run **Hunyuan3D-1** for prompt-to-3D generation
+- converts the AI result into a **particle blueprint** for inspection
+- lets the user review that blueprint on iPhone first
+- exports the mesh as a **GLB** when approved
+- preloads **Hunyuan3D-Omni** into the Space cache for the next stage of controllable refinement work
 
-## Current reality
+## Why this shape
 
-This build gives you the UX and the working two-phase geometry pipeline now.
+This build is aimed at a scaffold-first workflow rather than a one-shot "magic GLB" workflow. The blueprint is treated as the inspection layer between prompt and final asset.
 
-- **Blueprint step** is real and working
-- **Mesh step** is real and working
-- **Hunyuan3D-Omni cache prep** is wired in
-- the final mesh generation still uses the app's local voxel mesher for reliability
+## Important note
 
-That means the Space already behaves the way you want for mobile use, while still preparing the official target model repo inside the Space filesystem.
+This repo is rebuilt around the official Hugging Face-hosted Tencent model weights, but the second-stage **Hunyuan3D-Omni** refinement command is still marked experimental in this build. The current mesh export step returns the Hunyuan3D-1 AI mesh normalized to GLB while also caching Omni for future control-driven refinement.
 
-## Files to upload to the Space root
+## First-run expectations
 
-- `app.py`
-- `generator.py`
-- `model_runtime.py`
-- `llm_parser.py`
-- `parser.py`
-- `requirements.txt`
-- `packages.txt`
-- `README.md`
-- `LICENSE`
+The first run can take a while because the Space may need to:
 
-## Notes
+1. cache the large model repos
+2. clone the upstream Tencent code repos
+3. run the heavier text-to-3D stack
 
-- if the Space restarts, model cache may need to be fetched again unless you use persistent storage
-- first run with local planner models can take longer because weights need to download
-- the 3D viewers are tuned for touch on iPhone
+If the Hunyuan path fails because the upstream repo still needs extra GPU-side dependencies in your runtime, the app falls back to the local scaffold builder so the UI still works.

ai_runtime.py

@@ -0,0 +1,302 @@
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+import sys
+import tempfile
+import zipfile
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Callable, Generator
+
+import numpy as np
+import requests
+import trimesh
+from huggingface_hub import snapshot_download
+
+from viewer import point_cloud_viewer_html, load_points_from_mesh_file
+
+MODEL_TEXT3D = "tencent/Hunyuan3D-1"
+MODEL_TEXT2IMAGE = "Tencent-Hunyuan/HunyuanDiT-v1.1-Diffusers-Distilled"
+MODEL_OMNI = "tencent/Hunyuan3D-Omni"
+
+REPO_TEXT3D = "https://github.com/Tencent-Hunyuan/Hunyuan3D-1.git"
+REPO_OMNI = "https://github.com/Tencent-Hunyuan/Hunyuan3D-Omni.git"
+REPO_TEXT3D_ZIP = "https://github.com/Tencent-Hunyuan/Hunyuan3D-1/archive/refs/heads/main.zip"
+REPO_OMNI_ZIP = "https://github.com/Tencent-Hunyuan/Hunyuan3D-Omni/archive/refs/heads/main.zip"
+
+BASE_CACHE = Path(os.getenv("PB3D_CACHE_ROOT", "/data/pb3d_cache" if Path("/data").exists() else "./pb3d_cache"))
+REPOS_DIR = BASE_CACHE / "repos"
+MODELS_DIR = BASE_CACHE / "models"
+
+
+@dataclass
+class AiBlueprintSession:
+    session_dir: str
+    blueprint_path: str
+    raw_ai_mesh_path: str
+    preview_glb_path: str
+    source_model: str
+    point_count: int
+    prompt: str
+
+    def to_state(self) -> dict:
+        return {
+            "session_dir": self.session_dir,
+            "blueprint_path": self.blueprint_path,
+            "raw_ai_mesh_path": self.raw_ai_mesh_path,
+            "preview_glb_path": self.preview_glb_path,
+            "source_model": self.source_model,
+            "point_count": self.point_count,
+            "prompt": self.prompt,
+        }
+
+
+def ensure_cache_home() -> Path:
+    if Path("/data").exists():
+        os.environ.setdefault("HF_HOME", "/data/.huggingface")
+    BASE_CACHE.mkdir(parents=True, exist_ok=True)
+    REPOS_DIR.mkdir(parents=True, exist_ok=True)
+    MODELS_DIR.mkdir(parents=True, exist_ok=True)
+    return BASE_CACHE
+
+
+def _download_repo_zip(zip_url: str, dest_root: Path) -> Path:
+    dest_root.parent.mkdir(parents=True, exist_ok=True)
+    archive_path = dest_root.parent / f"{dest_root.name}.zip"
+    resp = requests.get(zip_url, timeout=120)
+    resp.raise_for_status()
+    archive_path.write_bytes(resp.content)
+    with zipfile.ZipFile(archive_path, "r") as zf:
+        zf.extractall(dest_root.parent)
+    extracted = next(dest_root.parent.glob(f"{dest_root.name}-*"), None)
+    if extracted is None:
+        raise RuntimeError(f"Could not unpack {zip_url}")
+    if dest_root.exists():
+        shutil.rmtree(dest_root)
+    extracted.rename(dest_root)
+    return dest_root
+
+
+def ensure_repo_checkout(name: str, repo_url: str, zip_url: str) -> Path:
+    ensure_cache_home()
+    dest = REPOS_DIR / name
+    if (dest / ".git").exists() or dest.exists():
+        return dest
+
+    try:
+        subprocess.run(
+            ["git", "clone", "--depth", "1", repo_url, str(dest)],
+            check=True,
+            capture_output=True,
+            text=True,
+        )
+        return dest
+    except Exception:
+        return _download_repo_zip(zip_url, dest)
+
+
+def ensure_model_snapshot(repo_id: str, local_dir: Path) -> Path:
+    local_dir.mkdir(parents=True, exist_ok=True)
+    snapshot_download(
+        repo_id=repo_id,
+        local_dir=str(local_dir),
+        local_dir_use_symlinks=False,
+        resume_download=True,
+    )
+    return local_dir
+
+
+def prepare_hunyuan3d1_assets(progress: Callable[[str], None] | None = None) -> Path:
+    repo_root = ensure_repo_checkout("Hunyuan3D-1", REPO_TEXT3D, REPO_TEXT3D_ZIP)
+    weights_root = repo_root / "weights"
+    if progress:
+        progress("Pulling Hunyuan3D-1 weights into the Space cache…")
+    ensure_model_snapshot(MODEL_TEXT3D, weights_root)
+    if progress:
+        progress("Pulling HunyuanDiT text-to-image weights into the Space cache…")
+    ensure_model_snapshot(MODEL_TEXT2IMAGE, weights_root / "hunyuanDiT")
+    return repo_root
+
+
+def prepare_omni_assets(progress: Callable[[str], None] | None = None) -> Path:
+    repo_root = ensure_repo_checkout("Hunyuan3D-Omni", REPO_OMNI, REPO_OMNI_ZIP)
+    if progress:
+        progress("Pulling Hunyuan3D-Omni weights into the Space cache…")
+    ensure_model_snapshot(MODEL_OMNI, MODELS_DIR / "tencent--Hunyuan3D-Omni")
+    return repo_root
+
+
+def _find_first_mesh(root: Path) -> Path:
+    candidates = []
+    for ext in ("*.glb", "*.obj", "*.ply", "*.stl", "*.off"):
+        candidates.extend(root.rglob(ext))
+    candidates = sorted(candidates, key=lambda p: (p.suffix != ".glb", len(str(p))))
+    if not candidates:
+        raise FileNotFoundError(f"No mesh artifact found under {root}")
+    return candidates[0]
+
+
+def _normalize_to_glb(mesh_path: Path, out_path: Path) -> Path:
+    asset = trimesh.load(mesh_path, force="mesh")
+    if isinstance(asset, trimesh.Scene):
+        meshes = [g for g in asset.geometry.values() if isinstance(g, trimesh.Trimesh)]
+        mesh = trimesh.util.concatenate(meshes) if meshes else trimesh.creation.box()
+    elif isinstance(asset, trimesh.Trimesh):
+        mesh = asset
+    else:
+        mesh = trimesh.creation.box()
+
+    mesh.remove_unreferenced_vertices()
+    mesh.apply_translation(-mesh.bounding_box.centroid)
+    scale = float(max(mesh.extents)) or 1.0
+    mesh.apply_scale(1.0 / scale)
+    mesh.export(out_path)
+    return out_path
+
+
+def _points_to_ply(points: np.ndarray, out_path: Path) -> Path:
+    cloud = trimesh.points.PointCloud(points)
+    cloud.export(out_path)
+    return out_path
+
+
+def _run_command(cmd: list[str], cwd: Path) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(cmd, cwd=str(cwd), capture_output=True, text=True)
+
+
+def run_hunyuan3d1_text_to_mesh(
+    prompt: str,
+    save_dir: Path,
+    save_memory: bool = True,
+    max_faces_num: int = 90000,
+) -> Path:
+    repo_root = prepare_hunyuan3d1_assets()
+    save_dir.mkdir(parents=True, exist_ok=True)
+    cmd = [
+        sys.executable,
+        "main.py",
+        "--text_prompt",
+        prompt,
+        "--save_folder",
+        str(save_dir),
+        "--max_faces_num",
+        str(max_faces_num),
+    ]
+    if save_memory:
+        cmd.append("--save_memory")
+
+    result = _run_command(cmd, cwd=repo_root)
+    if result.returncode != 0:
+        tail = (result.stderr or result.stdout or "").strip()[-1800:]
+        raise RuntimeError(
+            "Hunyuan3D-1 failed. This usually means the Space still needs the repo's heavier CUDA-side dependencies "
+            f"or more GPU memory.\n\nLast output:\n{tail}"
+        )
+    return _find_first_mesh(save_dir)
+
+
+def iter_hunyuan_blueprint_session(
+    prompt: str,
+    save_memory: bool = True,
+    max_faces_num: int = 70000,
+    preview_points: int = 3200,
+) -> Generator[dict, None, dict]:
+    prompt = (prompt or "").strip()
+    if not prompt:
+        raise ValueError("Enter a prompt first.")
+
+    session_dir = Path(tempfile.mkdtemp(prefix="pb3d_hunyuan_session_"))
+    yield {"status": "Preparing Hugging Face cache and model repos…", "session_dir": str(session_dir)}
+
+    ensure_cache_home()
+    yield {"status": f"Queueing {MODEL_TEXT3D} for prompt-driven generation…", "session_dir": str(session_dir)}
+    raw_mesh = run_hunyuan3d1_text_to_mesh(
+        prompt=prompt,
+        save_dir=session_dir / "hunyuan3d1_output",
+        save_memory=save_memory,
+        max_faces_num=max_faces_num,
+    )
+
+    yield {"status": "Sampling the AI mesh into an inspectable particle blueprint…", "session_dir": str(session_dir)}
+    points = load_points_from_mesh_file(raw_mesh, max_points=preview_points)
+    blueprint_path = _points_to_ply(points, session_dir / "blueprint_from_ai_mesh.ply")
+    preview_glb = _normalize_to_glb(raw_mesh, session_dir / "preview_mesh.glb")
+
+    chunks = [0.22, 0.45, 0.7, 1.0]
+    for idx, frac in enumerate(chunks, start=1):
+        count = max(180, int(len(points) * frac))
+        preview = points[:count]
+        yield {
+            "status": f"Blueprint readying for inspection ({idx}/{len(chunks)})…",
+            "viewer_html": point_cloud_viewer_html(preview, status=f"AI blueprint • {count} points"),
+            "summary": {
+                "prompt": prompt,
+                "source_model": MODEL_TEXT3D,
+                "point_count": int(count),
+                "stage": idx,
+                "stage_count": len(chunks),
+                "raw_ai_mesh_path": str(raw_mesh),
+            },
+            "session_dir": str(session_dir),
+        }
+
+    state = AiBlueprintSession(
+        session_dir=str(session_dir),
+        blueprint_path=str(blueprint_path),
+        raw_ai_mesh_path=str(raw_mesh),
+        preview_glb_path=str(preview_glb),
+        source_model=MODEL_TEXT3D,
+        point_count=int(len(points)),
+        prompt=prompt,
+    ).to_state()
+
+    yield {
+        "status": "Blueprint ready. Rotate it on iPhone, then make the mesh when happy.",
+        "viewer_html": point_cloud_viewer_html(points, status=f"AI blueprint • {len(points)} points"),
+        "summary": {**state, "mode": "ai_blueprint_from_mesh"},
+        "blueprint_path": str(blueprint_path),
+        "state": state,
+        "mesh_preview": str(preview_glb),
+        "session_dir": str(session_dir),
+    }
+    return state
+
+
+def finalize_ai_mesh_session(state: dict, prepare_omni: bool = True) -> Generator[dict, None, dict]:
+    mesh_path = Path(state["raw_ai_mesh_path"])
+    session_dir = Path(state["session_dir"])
+
+    if prepare_omni:
+        try:
+            yield {"status": f"Preloading {MODEL_OMNI} for future controllable refinement…"}
+            prepare_omni_assets()
+            omni_note = f"{MODEL_OMNI} cached."
+        except Exception as exc:
+            omni_note = f"Could not cache {MODEL_OMNI}: {exc}"
+    else:
+        omni_note = "Skipped."
+
+    yield {"status": "Centering and converting the AI mesh to exportable GLB…"}
+    glb_path = _normalize_to_glb(mesh_path, session_dir / "final_mesh.glb")
+    mesh = trimesh.load(glb_path, force="mesh")
+    if isinstance(mesh, trimesh.Scene):
+        mesh = trimesh.util.concatenate([g for g in mesh.geometry.values() if isinstance(g, trimesh.Trimesh)])
+
+    summary = {
+        **state,
+        "mesh_path": str(glb_path),
+        "mesh_source": MODEL_TEXT3D,
+        "omni_cache_note": omni_note,
+        "vertex_count": int(len(mesh.vertices)) if isinstance(mesh, trimesh.Trimesh) else None,
+        "face_count": int(len(mesh.faces)) if isinstance(mesh, trimesh.Trimesh) else None,
+        "note": "This export is the AI mesh produced during the blueprint stage, normalized for download. Hunyuan3D-Omni is preloaded but not yet driving the second-stage refinement command in this build.",
+    }
+    yield {
+        "status": "Mesh ready.",
+        "mesh_path": str(glb_path),
+        "summary": summary,
+        "mesh_file": str(glb_path),
+    }
+    return summary

app.py

@@ -2,48 +2,42 @@ from __future__ import annotations
 
 import gradio as gr
 
-from generator import iter_blueprint_session, iter_meshify_session
-from llm_parser import DEFAULT_LOCAL_MODEL, MODEL_PRESETS
-from model_runtime import TARGET_OMNI_MODEL
-
+from ai_runtime import MODEL_OMNI, MODEL_TEXT3D, iter_hunyuan_blueprint_session, finalize_ai_mesh_session
+from fallback_generator import iter_blueprint_session as iter_fallback_blueprint
+from fallback_generator import iter_meshify_session as iter_fallback_mesh
+from viewer import empty_viewer_html, load_points_from_cloud_file, point_cloud_viewer_html
 
 TITLE = "Particle Blueprint 3D"
-TAGLINE = "Describe → generate blueprint live → inspect in 3D → mesh when approved"
-DESCRIPTION = (
-    "Built for iPhone use first. Generate a structured particle blueprint with visible progress, "
-    "inspect it in the viewport, then turn the approved blueprint into a mesh."
+TAGLINE = "Prompt → AI blueprint → inspect on iPhone → export mesh"
+SUBTITLE = (
+    "Rebuilt around Hugging Face-hosted Tencent Hunyuan 3D models. "
+    "The first stage uses Hunyuan3D-1 for prompt-driven 3D generation, then converts that AI output into a particle blueprint for review."
 )
 
-PROMPT_PRESETS = {
-    "Cargo hauler": "small cargo hauler with a boxy hull, cockpit, cargo bay, rear engines and landing gear",
-    "Compact fighter": "compact fighter with wings, sleek nose, twin engines and a small cockpit",
-    "Industrial dropship": "industrial dropship with cargo hold, fin tail, four engines and wing stubs",
+PROMPTS = {
+    "Cargo hauler": "small cargo hauler with a boxy hull, rear ramp, cargo bay, 4 engines and landing gear",
+    "Compact fighter": "compact fighter with a sleek hull, twin engines, short wings and a small cockpit",
+    "Industrial shuttle": "industrial shuttle with a rounded hull, cargo hold, fin tail and landing gear",
 }
 
 CSS = """
 footer {display:none !important}
-.gradio-container {max-width: 1120px !important; margin: 0 auto; padding: 0 12px 28px 12px !important}
-#app-shell {gap: 14px}
-.hero-card, .panel-card, .status-card {border: 1px solid rgba(255,255,255,0.08); border-radius: 22px; padding: 14px 16px; background: rgba(255,255,255,0.03)}
-.hero-title {font-size: 1.5rem; font-weight: 800; margin: 0 0 6px 0}
-.hero-sub {opacity: 0.88; margin: 0}
-.flow-grid {display:grid; grid-template-columns: 1fr 1fr; gap: 10px}
-.flow-chip {border:1px solid rgba(255,255,255,0.08); border-radius:16px; padding:12px; background:rgba(255,255,255,0.02)}
-.flow-chip strong {display:block; margin-bottom:4px}
-.cta-row {gap: 10px}
-.cta-row button {min-height: 52px !important; border-radius: 16px !important; font-size: 1rem !important}
-.preset-row {display:grid; grid-template-columns: repeat(3, minmax(0,1fr)); gap: 8px}
-.preset-row button {min-height: 46px !important; border-radius: 16px !important}
-.model3d-wrap {border-radius: 20px; overflow: hidden}
-.mobile-note {font-size: 0.92rem; opacity: 0.82}
-.small-note {font-size:0.88rem; opacity:0.8}
+.gradio-container {max-width: 1080px !important; margin: 0 auto; padding: 0 12px 28px !important}
+.hero, .panel, .status-card {border:1px solid rgba(255,255,255,.08); border-radius:22px; background:rgba(255,255,255,.03); padding:14px 16px}
+.hero-title {font-size:1.5rem; font-weight:800; margin:0 0 6px 0}
+.hero-sub {opacity:.88; margin:0}
+.flow {display:grid; grid-template-columns:repeat(4, minmax(0,1fr)); gap:10px; margin-top:10px}
+.flow div {border:1px solid rgba(255,255,255,.08); border-radius:16px; padding:12px; background:rgba(255,255,255,.02)}
+.flow strong {display:block; margin-bottom:4px}
+.cta-row button {min-height:52px !important; border-radius:16px !important; font-size:1rem !important}
+.preset-row button {min-height:44px !important; border-radius:14px !important}
 #status-box p {margin:0}
+.small-note {font-size:.88rem; opacity:.8}
 @media (max-width: 820px) {
-  .gradio-container {padding: 0 10px 22px 10px !important}
-  .hero-card, .panel-card, .status-card {padding: 12px 12px}
-  .hero-title {font-size: 1.28rem}
-  .preset-row, .flow-grid {grid-template-columns: 1fr}
-  .cta-row {position: sticky; bottom: 10px; z-index: 10; background: rgba(15,18,24,0.90); backdrop-filter: blur(12px); padding: 8px; border: 1px solid rgba(255,255,255,0.08); border-radius: 18px}
+  .gradio-container {padding:0 10px 22px !important}
+  .hero,.panel,.status-card {padding:12px}
+  .flow {grid-template-columns:1fr}
+  .cta-row {position:sticky; bottom:10px; z-index:12; background:rgba(10,13,22,.92); backdrop-filter:blur(12px); padding:8px; border:1px solid rgba(255,255,255,.08); border-radius:18px}
 }
 """
 
@@ -52,185 +46,224 @@ def _status_md(text: str) -> str:
     return f"**Status**\n\n{text}"
 
 
-def stream_blueprint(prompt: str, parser_mode: str, model_choice: str, detail: int):
+def _blueprint_html_from_ply(path: str | None) -> str:
+    if not path:
+        return empty_viewer_html()
+    try:
+        points = load_points_from_cloud_file(path)
+        return point_cloud_viewer_html(points, status=f"Blueprint • {len(points)} points")
+    except Exception as exc:
+        return empty_viewer_html(f"Blueprint file exists but the viewer could not read it: {exc}")
+
+
+def stream_blueprint(prompt: str, mode: str, save_memory: bool, max_faces: int, detail: int):
     prompt = (prompt or "").strip()
     if not prompt:
         raise gr.Error("Enter a prompt first.")
 
-    model_id = MODEL_PRESETS.get(model_choice, model_choice or DEFAULT_LOCAL_MODEL)
-    latest_summary = None
-    latest_path = None
-    latest_state = None
+    html = empty_viewer_html("Starting…")
+    summary = None
+    state = None
+    blueprint_file = None
+    mesh_preview = None
 
     yield (
         _status_md("Starting blueprint generation…"),
-        None,
+        html,
         None,
         None,
         None,
         gr.update(interactive=False),
+        None,
     )
 
-    for update in iter_blueprint_session(
-        prompt=prompt,
-        detail=detail,
-        parser_mode=parser_mode,
-        model_id=model_id,
-    ):
-        latest_summary = update.get("summary", latest_summary)
-        latest_path = update.get("blueprint_path", latest_path)
-        latest_state = update.get("state", latest_state)
-        status_text = update.get("status", "Working…")
+    if mode == "hunyuan":
+        try:
+            for update in iter_hunyuan_blueprint_session(
+                prompt=prompt,
+                save_memory=save_memory,
+                max_faces_num=int(max_faces),
+                preview_points=max(2200, int(detail) * 140),
+            ):
+                html = update.get("viewer_html", html)
+                summary = update.get("summary", summary)
+                blueprint_file = update.get("blueprint_path", blueprint_file)
+                mesh_preview = update.get("mesh_preview", mesh_preview)
+                state = update.get("state", state)
+                yield (
+                    _status_md(update.get("status", "Working…")),
+                    html,
+                    summary,
+                    blueprint_file,
+                    state,
+                    gr.update(interactive=bool(state)),
+                    mesh_preview,
+                )
+            return
+        except Exception as exc:
+            fallback_notice = f"AI model path failed, so the app is falling back to the local scaffold builder. Reason: {exc}"
+            yield (
+                _status_md(fallback_notice),
+                html,
+                {"fallback_reason": str(exc), "requested_mode": mode, "prompt": prompt},
+                blueprint_file,
+                state,
+                gr.update(interactive=False),
+                mesh_preview,
+            )
+
+    for update in iter_fallback_blueprint(prompt=prompt, detail=detail, parser_mode="heuristic"):
+        blueprint_path = update.get("blueprint_path")
+        if blueprint_path:
+            html = _blueprint_html_from_ply(blueprint_path)
+            blueprint_file = blueprint_path
+        summary = update.get("summary", summary)
+        state = update.get("state", state)
         yield (
-            _status_md(status_text),
-            latest_path,
-            latest_summary,
-            latest_path,
-            latest_state,
-            gr.update(interactive=bool(latest_state)),
+            _status_md(update.get("status", "Working…")),
+            html,
+            summary,
+            blueprint_file,
+            state,
+            gr.update(interactive=bool(state)),
+            mesh_preview,
         )
 
 
-def stream_mesh(state: dict, voxel_pitch: float, warm_target_model: bool):
+def stream_mesh(state: dict, prepare_omni: bool, voxel_pitch: float):
     if not state:
         raise gr.Error("Generate a blueprint first.")
 
-    latest_summary = None
-    latest_mesh_path = None
     yield _status_md("Starting mesh generation…"), None, None, None
 
-    for update in iter_meshify_session(
-        state=state,
-        voxel_pitch=voxel_pitch,
-        use_target_model_cache=warm_target_model,
-    ):
-        latest_summary = update.get("summary", latest_summary)
-        latest_mesh_path = update.get("mesh_path", latest_mesh_path)
-        status_text = update.get("status", "Meshing…")
-        yield _status_md(status_text), latest_mesh_path, latest_mesh_path, latest_summary
+    if state.get("raw_ai_mesh_path"):
+        for update in finalize_ai_mesh_session(state, prepare_omni=prepare_omni):
+            yield (
+                _status_md(update.get("status", "Meshing…")),
+                update.get("mesh_path"),
+                update.get("mesh_file"),
+                update.get("summary"),
+            )
+        return
+
+    for update in iter_fallback_mesh(state=state, voxel_pitch=voxel_pitch, use_target_model_cache=prepare_omni):
+        yield (
+            _status_md(update.get("status", "Meshing…")),
+            update.get("mesh_path"),
+            update.get("mesh_file"),
+            update.get("summary"),
+        )
 
 
 with gr.Blocks(theme=gr.themes.Soft(), css=CSS, title=TITLE, fill_width=True) as demo:
     session_state = gr.State(value=None)
 
-    with gr.Column(elem_id="app-shell"):
-        gr.HTML(
-            f"""
-            <div class='hero-card'>
-              <div class='hero-title'>{TITLE}</div>
-              <p class='hero-sub'><strong>{TAGLINE}</strong><br>{DESCRIPTION}</p>
-              <div class='flow-grid' style='margin-top:10px'>
-                <div class='flow-chip'><strong>1. Describe</strong>Tell it what to build.</div>
-                <div class='flow-chip'><strong>2. Watch blueprint form</strong>Hull, cockpit, cargo, engines and extras appear in stages.</div>
-                <div class='flow-chip'><strong>3. Inspect in 3D</strong>Rotate, pan and zoom the particle blueprint.</div>
-                <div class='flow-chip'><strong>4. Make mesh</strong>When it looks right, turn it into a GLB.</div>
-              </div>
-              <p class='mobile-note'>Target model cache: <strong>{TARGET_OMNI_MODEL}</strong></p>
-            </div>
-            """
+    gr.HTML(
+        f"""
+        <div class='hero'>
+          <div class='hero-title'>{TITLE}</div>
+          <p class='hero-sub'><strong>{TAGLINE}</strong><br>{SUBTITLE}</p>
+          <div class='flow'>
+            <div><strong>1. Describe</strong>Write what you want.</div>
+            <div><strong>2. Generate blueprint</strong>{MODEL_TEXT3D} runs, then its AI mesh is turned into a particle blueprint.</div>
+            <div><strong>3. Inspect</strong>Rotate, zoom and pan the blueprint on iPhone before committing.</div>
+            <div><strong>4. Make mesh</strong>Export the AI mesh as GLB, with {MODEL_OMNI} preloaded for later refinement work.</div>
+          </div>
+        </div>
+        """
+    )
+
+    with gr.Column(elem_classes=["panel"]):
+        prompt = gr.Textbox(
+            label="Describe the model",
+            lines=4,
+            max_lines=7,
+            placeholder="Example: small cargo hauler with a boxy hull, cargo bay, rear ramp, 4 engines and landing gear",
         )
 
-        with gr.Column(elem_classes=["panel-card"]):
-            prompt = gr.Textbox(
-                label="Describe the model",
-                lines=4,
-                max_lines=6,
-                placeholder="Example: small cargo hauler with a boxy hull, rear ramp, cargo bay, 4 engines and landing gear",
-                autofocus=True,
+        with gr.Row(elem_classes=["preset-row"]):
+            p1 = gr.Button("Cargo hauler")
+            p2 = gr.Button("Compact fighter")
+            p3 = gr.Button("Industrial shuttle")
+
+        with gr.Accordion("Generation settings", open=False):
+            mode = gr.Radio(
+                choices=[("Hunyuan3D-1 AI", "hunyuan"), ("Local fallback scaffold", "fallback")],
+                value="hunyuan",
+                label="Blueprint generation mode",
+                info="Use Hunyuan first. If its repo dependencies are not fully ready in the Space yet, the app will fall back automatically.",
+            )
+            save_memory = gr.Checkbox(
+                value=True,
+                label="Use save-memory mode for Hunyuan3D-1",
+                info="Useful on tighter ZeroGPU runs.",
+            )
+            max_faces = gr.Slider(20000, 90000, value=70000, step=5000, label="Max faces for the AI mesh")
+            detail = gr.Slider(14, 34, value=22, step=2, label="Blueprint preview density")
+            voxel_pitch = gr.Slider(0.055, 0.12, value=0.085, step=0.005, label="Fallback mesh density")
+            prepare_omni = gr.Checkbox(
+                value=True,
+                label=f"Preload {MODEL_OMNI} during mesh step",
+                info="This caches the controllable refinement model in the Space even though this build still exports the Hunyuan3D-1 mesh on step two.",
             )
 
-            with gr.Row(elem_classes=["preset-row"]):
-                preset_a = gr.Button("Cargo hauler")
-                preset_b = gr.Button("Compact fighter")
-                preset_c = gr.Button("Industrial dropship")
-
-            with gr.Accordion("Planner and mesh settings", open=False):
-                parser_mode = gr.Radio(
-                    choices=[("Fast heuristic", "heuristic"), ("Local HF planner", "local")],
-                    value="heuristic",
-                    label="Prompt planner",
-                    info="Use the local planner when the prompt is messy and you want better structure extraction.",
-                )
-                model_choice = gr.Dropdown(
-                    choices=list(MODEL_PRESETS.keys()),
-                    value="Qwen 2.5 1.5B",
-                    label="Local planner model",
-                )
-                detail = gr.Slider(12, 34, value=20, step=2, label="Blueprint detail")
-                voxel_pitch = gr.Slider(0.055, 0.12, value=0.085, step=0.005, label="Mesh density")
-                warm_target_model = gr.Checkbox(
-                    value=True,
-                    label="Warm Hunyuan3D-Omni cache during mesh step",
-                    info="This caches the target model repo in the Space for later deeper integration work.",
-                )
-
-            with gr.Row(elem_classes=["cta-row"]):
-                blueprint_btn = gr.Button("Generate blueprint", variant="primary")
-                mesh_btn = gr.Button("Make mesh from blueprint", interactive=False)
-                clear_btn = gr.Button("Clear")
-
-        with gr.Column(elem_classes=["status-card"]):
-            status = gr.Markdown(_status_md("Ready."), elem_id="status-box")
-            gr.Markdown("<span class='small-note'>On iPhone: use one finger to orbit and two fingers to zoom/pan the model viewer.</span>")
-
-        with gr.Tabs():
-            with gr.TabItem("Blueprint"):
-                blueprint_view = gr.Model3D(
-                    label="Particle blueprint (.ply)",
-                    display_mode="point_cloud",
-                    clear_color=(0.02, 0.02, 0.03, 1.0),
-                    camera_position=(35, 65, 6),
-                    zoom_speed=1.15,
-                    pan_speed=0.95,
-                    elem_classes=["model3d-wrap"],
-                    height=540,
-                )
-            with gr.TabItem("Mesh"):
-                mesh_view = gr.Model3D(
-                    label="Mesh preview (.glb)",
-                    display_mode="solid",
-                    clear_color=(0.02, 0.02, 0.03, 1.0),
-                    camera_position=(35, 65, 6),
-                    zoom_speed=1.15,
-                    pan_speed=0.95,
-                    elem_classes=["model3d-wrap"],
-                    height=540,
-                )
-            with gr.TabItem("Summary and files"):
-                summary = gr.JSON(label="Session summary")
-                blueprint_file = gr.File(label="Download blueprint (.ply)")
-                mesh_file = gr.File(label="Download mesh (.glb)")
-
-        preset_a.click(lambda: PROMPT_PRESETS["Cargo hauler"], outputs=prompt)
-        preset_b.click(lambda: PROMPT_PRESETS["Compact fighter"], outputs=prompt)
-        preset_c.click(lambda: PROMPT_PRESETS["Industrial dropship"], outputs=prompt)
-
-        blueprint_btn.click(
-            fn=stream_blueprint,
-            inputs=[prompt, parser_mode, model_choice, detail],
-            outputs=[status, blueprint_view, summary, blueprint_file, session_state, mesh_btn],
-        )
+        with gr.Row(elem_classes=["cta-row"]):
+            blueprint_btn = gr.Button("Generate blueprint", variant="primary")
+            mesh_btn = gr.Button("Make mesh", interactive=False)
+            clear_btn = gr.Button("Clear")
+
+    with gr.Column(elem_classes=["status-card"]):
+        status = gr.Markdown(_status_md("Ready."), elem_id="status-box")
+        gr.Markdown("<span class='small-note'>On iPhone: one finger orbits. Two fingers pan and zoom.</span>")
+
+    with gr.Tabs():
+        with gr.TabItem("Blueprint"):
+            blueprint_view = gr.HTML(value=empty_viewer_html(), label="Blueprint viewer")
+        with gr.TabItem("Mesh"):
+            mesh_view = gr.Model3D(
+                label="Mesh preview (.glb)",
+                display_mode="solid",
+                clear_color=(0.02, 0.02, 0.03, 1.0),
+                camera_position=(35, 65, 6),
+                zoom_speed=1.15,
+                pan_speed=0.95,
+                height=560,
+            )
+        with gr.TabItem("Summary and files"):
+            summary = gr.JSON(label="Session summary")
+            blueprint_file = gr.File(label="Particle blueprint (.ply)")
+            mesh_file = gr.File(label="Mesh export (.glb)")
+
+    p1.click(lambda: PROMPTS["Cargo hauler"], outputs=prompt)
+    p2.click(lambda: PROMPTS["Compact fighter"], outputs=prompt)
+    p3.click(lambda: PROMPTS["Industrial shuttle"], outputs=prompt)
+
+    blueprint_btn.click(
+        fn=stream_blueprint,
+        inputs=[prompt, mode, save_memory, max_faces, detail],
+        outputs=[status, blueprint_view, summary, blueprint_file, session_state, mesh_btn, mesh_view],
+    )
 
-        mesh_btn.click(
-            fn=stream_mesh,
-            inputs=[session_state, voxel_pitch, warm_target_model],
-            outputs=[status, mesh_view, mesh_file, summary],
-        )
+    mesh_btn.click(
+        fn=stream_mesh,
+        inputs=[session_state, prepare_omni, voxel_pitch],
+        outputs=[status, mesh_view, mesh_file, summary],
+    )
 
-        clear_btn.click(
-            lambda: (
-                "",
-                _status_md("Ready."),
-                None,
-                None,
-                None,
-                None,
-                None,
-                gr.update(interactive=False),
-                None,
-            ),
-            outputs=[prompt, status, blueprint_view, mesh_view, summary, blueprint_file, mesh_file, mesh_btn, session_state],
-        )
+    clear_btn.click(
+        lambda: (
+            "",
+            _status_md("Ready."),
+            empty_viewer_html(),
+            None,
+            None,
+            None,
+            None,
+            gr.update(interactive=False),
+            None,
+        ),
+        outputs=[prompt, status, blueprint_view, mesh_view, summary, blueprint_file, mesh_file, mesh_btn, session_state],
+    )
 
 
 if __name__ == "__main__":

fallback_generator.py

@@ -0,0 +1,409 @@
+from __future__ import annotations
+
+import math
+import tempfile
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Generator
+
+import numpy as np
+import trimesh
+from scipy import ndimage
+from skimage import measure
+
+from llm_parser import DEFAULT_LOCAL_MODEL, parse_prompt_with_local_llm
+from model_runtime import TARGET_OMNI_MODEL, ensure_target_model_cached
+from parser import PromptSpec, parse_prompt
+
+
+@dataclass
+class BuildArtifacts:
+    ply_path: str
+    glb_path: str
+    summary: dict
+
+
+SCALE_FACTORS = {
+    "small": 1.0,
+    "medium": 1.35,
+    "large": 1.85,
+}
+
+
+def _sample_box_surface(center, size, density: int, label: int) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
+    cx, cy, cz = center
+    sx, sy, sz = size
+    n = max(4, density)
+    u = np.linspace(-0.5, 0.5, n)
+    vv = np.linspace(-0.5, 0.5, n)
+    pts = []
+    normals = []
+    labels = []
+    for ax in (-1, 1):
+        x = np.full((n, n), cx + ax * sx / 2)
+        y, z = np.meshgrid(u * sy + cy, vv * sz + cz)
+        pts.append(np.column_stack([x.ravel(), y.ravel(), z.ravel()]))
+        normals.append(np.tile([ax, 0, 0], (n * n, 1)))
+        labels.append(np.full(n * n, label))
+    for ay in (-1, 1):
+        y = np.full((n, n), cy + ay * sy / 2)
+        x, z = np.meshgrid(u * sx + cx, vv * sz + cz)
+        pts.append(np.column_stack([x.ravel(), y.ravel(), z.ravel()]))
+        normals.append(np.tile([0, ay, 0], (n * n, 1)))
+        labels.append(np.full(n * n, label))
+    for az in (-1, 1):
+        z = np.full((n, n), cz + az * sz / 2)
+        x, y = np.meshgrid(u * sx + cx, vv * sy + cy)
+        pts.append(np.column_stack([x.ravel(), y.ravel(), z.ravel()]))
+        normals.append(np.tile([0, 0, az], (n * n, 1)))
+        labels.append(np.full(n * n, label))
+    return np.vstack(pts), np.vstack(normals), np.concatenate(labels)
+
+
+def _sample_ellipsoid_surface(center, radii, density: int, label: int) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
+    cx, cy, cz = center
+    rx, ry, rz = radii
+    nu = max(16, density * 3)
+    nv = max(10, density * 2)
+    u = np.linspace(0, 2 * math.pi, nu, endpoint=False)
+    v = np.linspace(-math.pi / 2, math.pi / 2, nv)
+    uu, vv = np.meshgrid(u, v)
+    x = cx + rx * np.cos(vv) * np.cos(uu)
+    y = cy + ry * np.cos(vv) * np.sin(uu)
+    z = cz + rz * np.sin(vv)
+    pts = np.column_stack([x.ravel(), y.ravel(), z.ravel()])
+    normals = np.column_stack([
+        (x - cx).ravel() / max(rx, 1e-6),
+        (y - cy).ravel() / max(ry, 1e-6),
+        (z - cz).ravel() / max(rz, 1e-6),
+    ])
+    normals /= np.linalg.norm(normals, axis=1, keepdims=True) + 1e-8
+    labels = np.full(len(pts), label)
+    return pts, normals, labels
+
+
+def _sample_cylinder_surface(center, radius, length, axis: str, density: int, label: int) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
+    cx, cy, cz = center
+    nt = max(18, density * 4)
+    nl = max(6, density)
+    theta = np.linspace(0, 2 * math.pi, nt, endpoint=False)
+    line = np.linspace(-length / 2, length / 2, nl)
+    tt, ll = np.meshgrid(theta, line)
+    if axis == "x":
+        x = cx + ll
+        y = cy + radius * np.cos(tt)
+        z = cz + radius * np.sin(tt)
+        normals = np.column_stack([np.zeros(x.size), np.cos(tt).ravel(), np.sin(tt).ravel()])
+    elif axis == "y":
+        x = cx + radius * np.cos(tt)
+        y = cy + ll
+        z = cz + radius * np.sin(tt)
+        normals = np.column_stack([np.cos(tt).ravel(), np.zeros(x.size), np.sin(tt).ravel()])
+    else:
+        x = cx + radius * np.cos(tt)
+        y = cy + radius * np.sin(tt)
+        z = cz + ll
+        normals = np.column_stack([np.cos(tt).ravel(), np.sin(tt).ravel(), np.zeros(x.size)])
+    pts = np.column_stack([x.ravel(), y.ravel(), z.ravel()])
+    labels = np.full(len(pts), label)
+    return pts, normals, labels
+
+
+def export_point_cloud_as_ply(points: np.ndarray, labels: np.ndarray, path: str) -> str:
+    colors = np.array([
+        [170, 170, 180],
+        [120, 180, 255],
+        [255, 190, 120],
+        [180, 180, 255],
+        [255, 120, 120],
+        [200, 255, 180],
+        [255, 255, 180],
+    ], dtype=np.uint8)
+    c = colors[labels % len(colors)]
+    pc = trimesh.points.PointCloud(vertices=points, colors=c)
+    pc.export(path)
+    return path
+
+
+def export_mesh_as_glb(mesh: trimesh.Trimesh, path: str) -> str:
+    mesh.visual.vertex_colors = np.tile(np.array([[185, 190, 200, 255]], dtype=np.uint8), (len(mesh.vertices), 1))
+    mesh.export(path)
+    return path
+
+
+def _resolve_spec(prompt: str, parser_mode: str, model_id: str | None = None) -> tuple[PromptSpec, str]:
+    parser_mode = (parser_mode or "heuristic").strip().lower()
+    if parser_mode.startswith("local"):
+        spec = parse_prompt_with_local_llm(prompt, model_id=model_id or DEFAULT_LOCAL_MODEL)
+        return spec, f"local_llm:{model_id or DEFAULT_LOCAL_MODEL}"
+    return parse_prompt(prompt), "heuristic"
+
+
+def _iter_part_specs(spec: PromptSpec, detail: int):
+    scale = SCALE_FACTORS[spec.scale]
+    density = max(6, detail)
+
+    hull_len = 2.8 * scale
+    hull_w = 1.2 * scale
+    hull_h = 0.8 * scale
+
+    if spec.hull_style == "rounded":
+        yield "Hull", *_sample_ellipsoid_surface((0.0, 0.0, 0.0), (hull_len / 2, hull_w / 2, hull_h / 2), density, 0)
+    elif spec.hull_style == "sleek":
+        p1, n1, l1 = _sample_ellipsoid_surface((0.12 * scale, 0.0, 0.0), (hull_len / 2.3, hull_w / 2.8, hull_h / 2.6), density, 0)
+        p2, n2, l2 = _sample_box_surface((-0.15 * scale, 0.0, -0.02 * scale), (hull_len * 0.52, hull_w * 0.5, hull_h * 0.55), max(4, density // 2), 0)
+        yield "Hull", np.vstack([p1, p2]), np.vstack([n1, n2]), np.concatenate([l1, l2])
+    else:
+        yield "Hull", *_sample_box_surface((0.0, 0.0, 0.0), (hull_len, hull_w, hull_h), density, 0)
+
+    cockpit_center = (hull_len / 2 - hull_len * spec.cockpit_ratio * 0.8, 0.0, hull_h * 0.14)
+    yield "Cockpit", *_sample_ellipsoid_surface(cockpit_center, (hull_len * spec.cockpit_ratio, hull_w * 0.22, hull_h * 0.24), max(4, density // 2), 1)
+
+    if spec.cargo_ratio > 0.16:
+        cargo_center = (-hull_len * 0.18, 0.0, -hull_h * 0.06)
+        cargo_size = (hull_len * spec.cargo_ratio, hull_w * 0.76, hull_h * 0.6)
+        yield "Cargo bay", *_sample_box_surface(cargo_center, cargo_size, max(4, density // 2), 2)
+
+    if spec.wing_span > 0:
+        wing_length = hull_len * 0.34
+        wing_width = hull_w * 0.18
+        wing_height = hull_h * 0.08
+        yoff = hull_w * 0.45 + wing_width * 0.6
+        wing_parts = []
+        wing_normals = []
+        wing_labels = []
+        for side in (-1, 1):
+            wc = (-0.1 * scale, side * yoff, -0.04 * scale)
+            pp, pn, pl = _sample_box_surface(wc, (wing_length, wing_width, wing_height), max(6, density // 3), 3)
+            wing_parts.append(pp)
+            wing_normals.append(pn)
+            wing_labels.append(pl)
+        yield "Wings", np.vstack(wing_parts), np.vstack(wing_normals), np.concatenate(wing_labels)
+
+    engine_radius = 0.14 * scale if spec.object_type != "fighter" else 0.1 * scale
+    engine_length = 0.48 * scale
+    engine_y_positions = np.linspace(-hull_w * 0.32, hull_w * 0.32, spec.engine_count)
+    engine_parts = []
+    engine_normals = []
+    engine_labels = []
+    for ypos in engine_y_positions:
+        ec = (-hull_len / 2 + engine_length * 0.3, ypos, 0.0)
+        pp, pn, pl = _sample_cylinder_surface(ec, engine_radius, engine_length, "x", max(6, density // 3), 4)
+        engine_parts.append(pp)
+        engine_normals.append(pn)
+        engine_labels.append(pl)
+    yield "Engines", np.vstack(engine_parts), np.vstack(engine_normals), np.concatenate(engine_labels)
+
+    if spec.fin_height > 0:
+        fin_center = (-hull_len * 0.25, 0.0, hull_h * 0.42)
+        fin_size = (hull_len * 0.18, hull_w * 0.1, hull_h * max(spec.fin_height, 0.12))
+        yield "Fin", *_sample_box_surface(fin_center, fin_size, max(6, density // 3), 5)
+
+    if spec.landing_gear:
+        gear_x = np.array([-hull_len * 0.18, hull_len * 0.12])
+        gear_y = np.array([-hull_w * 0.28, hull_w * 0.28])
+        gear_parts = []
+        gear_normals = []
+        gear_labels = []
+        for gx in gear_x:
+            for gy in gear_y:
+                gc = (gx, gy, -hull_h * 0.45)
+                pp, pn, pl = _sample_cylinder_surface(gc, 0.04 * scale, 0.22 * scale, "z", max(5, density // 5), 6)
+                gear_parts.append(pp)
+                gear_normals.append(pn)
+                gear_labels.append(pl)
+        yield "Landing gear", np.vstack(gear_parts), np.vstack(gear_normals), np.concatenate(gear_labels)
+
+
+def iter_blueprint_session(
+    prompt: str,
+    detail: int = 24,
+    parser_mode: str = "heuristic",
+    model_id: str | None = None,
+) -> Generator[dict, None, dict]:
+    prompt = (prompt or "").strip()
+    if not prompt:
+        raise ValueError("Enter a prompt first.")
+
+    out_dir = Path(tempfile.mkdtemp(prefix="particle_blueprint_session_"))
+    yield {"status": "Parsing prompt and planning shape…", "stage_index": 0, "stage_count": 1, "session_dir": str(out_dir)}
+
+    spec, parser_backend = _resolve_spec(prompt, parser_mode=parser_mode, model_id=model_id)
+    stages = list(_iter_part_specs(spec, detail=detail))
+
+    all_points = []
+    all_normals = []
+    all_labels = []
+
+    for idx, (stage_name, points, normals, labels) in enumerate(stages, start=1):
+        if spec.asymmetry > 0 and stage_name in {"Hull", "Cockpit", "Cargo bay"}:
+            mask = points[:, 1] > 0
+            points = points.copy()
+            points[mask, 2] += spec.asymmetry * np.sin(points[mask, 0] * 2.0)
+
+        all_points.append(points)
+        all_normals.append(normals)
+        all_labels.append(labels)
+
+        merged_points = np.vstack(all_points).astype(np.float32)
+        merged_normals = np.vstack(all_normals).astype(np.float32)
+        merged_labels = np.concatenate(all_labels).astype(np.int32)
+
+        preview_path = str(out_dir / f"blueprint_stage_{idx:02d}.ply")
+        export_point_cloud_as_ply(merged_points, merged_labels, preview_path)
+
+        summary = {
+            "prompt": prompt,
+            "parser_backend": parser_backend,
+            "spec": spec.to_dict(),
+            "stage": stage_name,
+            "stage_index": idx,
+            "stage_count": len(stages),
+            "point_count": int(len(merged_points)),
+        }
+        yield {
+            "status": f"{stage_name} added ({idx}/{len(stages)})",
+            "blueprint_path": preview_path,
+            "summary": summary,
+            "stage_index": idx,
+            "stage_count": len(stages),
+            "session_dir": str(out_dir),
+        }
+
+    final_points = np.vstack(all_points).astype(np.float32)
+    final_normals = np.vstack(all_normals).astype(np.float32)
+    final_labels = np.concatenate(all_labels).astype(np.int32)
+
+    npz_path = str(out_dir / "blueprint_data.npz")
+    np.savez_compressed(npz_path, points=final_points, normals=final_normals, labels=final_labels)
+
+    final_ply = str(out_dir / "blueprint_final.ply")
+    export_point_cloud_as_ply(final_points, final_labels, final_ply)
+
+    state = {
+        "prompt": prompt,
+        "parser_backend": parser_backend,
+        "spec": spec.to_dict(),
+        "point_count": int(len(final_points)),
+        "session_dir": str(out_dir),
+        "npz_path": npz_path,
+        "blueprint_path": final_ply,
+        "target_model": TARGET_OMNI_MODEL,
+    }
+    yield {
+        "status": "Blueprint ready. Inspect it, then run mesh generation when happy.",
+        "blueprint_path": final_ply,
+        "summary": {
+            **state,
+            "stage": "complete",
+        },
+        "stage_index": len(stages),
+        "stage_count": len(stages),
+        "state": state,
+        "session_dir": str(out_dir),
+    }
+    return state
+
+
+def points_to_mesh(points: np.ndarray, pitch: float = 0.08, padding: int = 5, sigma: float = 1.2, level: float = 0.11) -> trimesh.Trimesh:
+    mins = points.min(axis=0) - padding * pitch
+    maxs = points.max(axis=0) + padding * pitch
+    dims = np.ceil((maxs - mins) / pitch).astype(int) + 1
+    dims = np.clip(dims, 24, 192)
+
+    grid = np.zeros(tuple(dims.tolist()), dtype=np.float32)
+    coords = ((points - mins) / pitch).astype(int)
+    coords = np.clip(coords, 0, dims - 1)
+    np.add.at(grid, (coords[:, 0], coords[:, 1], coords[:, 2]), 1.0)
+
+    grid = ndimage.gaussian_filter(grid, sigma=sigma)
+    verts, faces, normals, _ = measure.marching_cubes(grid, level=level)
+    verts = verts * pitch + mins
+
+    mesh = trimesh.Trimesh(vertices=verts, faces=faces, vertex_normals=normals, process=True)
+    mesh.update_faces(mesh.nondegenerate_faces())
+    mesh.update_faces(mesh.unique_faces())
+    mesh.remove_unreferenced_vertices()
+    try:
+        mesh.fill_holes()
+    except Exception:
+        pass
+    try:
+        trimesh.smoothing.filter_humphrey(mesh, iterations=2)
+    except Exception:
+        pass
+    return mesh
+
+
+def iter_meshify_session(
+    state: dict,
+    voxel_pitch: float = 0.08,
+    use_target_model_cache: bool = True,
+) -> Generator[dict, None, dict]:
+    if not state or not state.get("npz_path"):
+        raise ValueError("Generate a blueprint first.")
+
+    data = np.load(state["npz_path"])
+    points = data["points"].astype(np.float32)
+    labels = data["labels"].astype(np.int32)
+    session_dir = Path(state["session_dir"])
+
+    model_note = None
+    if use_target_model_cache:
+        yield {"status": f"Preparing target model cache for {TARGET_OMNI_MODEL}…"}
+        model_cache = ensure_target_model_cached(TARGET_OMNI_MODEL)
+        model_note = model_cache["message"]
+        yield {"status": model_note}
+
+    yield {"status": "Converting blueprint into a watertight mesh…"}
+    mesh = points_to_mesh(points, pitch=voxel_pitch)
+
+    yield {"status": "Exporting GLB…"}
+    glb_path = str(session_dir / "mesh_final.glb")
+    export_mesh_as_glb(mesh, glb_path)
+
+    summary = {
+        **state,
+        "mesh_backend": "local_voxel_mesher",
+        "target_model_cached": bool(use_target_model_cache),
+        "target_model": TARGET_OMNI_MODEL,
+        "target_model_note": model_note,
+        "vertex_count": int(len(mesh.vertices)),
+        "face_count": int(len(mesh.faces)),
+        "bounds": mesh.bounds.round(3).tolist(),
+        "voxel_pitch": voxel_pitch,
+        "mesh_path": glb_path,
+    }
+    yield {
+        "status": "Mesh ready.",
+        "mesh_path": glb_path,
+        "summary": summary,
+        "mesh_file": glb_path,
+    }
+    return summary
+
+
+# Backward-compatible helper for older single-click flow.
+def run_pipeline(
+    prompt: str,
+    detail: int = 24,
+    voxel_pitch: float = 0.08,
+    parser_mode: str = "heuristic",
+    model_id: str | None = None,
+) -> BuildArtifacts:
+    final_state = None
+    final_summary = None
+    blueprint_path = None
+    for update in iter_blueprint_session(prompt, detail=detail, parser_mode=parser_mode, model_id=model_id):
+        blueprint_path = update.get("blueprint_path", blueprint_path)
+        final_state = update.get("state", final_state)
+        final_summary = update.get("summary", final_summary)
+    mesh_summary = None
+    mesh_path = None
+    if final_state is None:
+        raise RuntimeError("Blueprint generation failed.")
+    for update in iter_meshify_session(final_state, voxel_pitch=voxel_pitch, use_target_model_cache=False):
+        mesh_path = update.get("mesh_path", mesh_path)
+        mesh_summary = update.get("summary", mesh_summary)
+    summary = mesh_summary or final_summary or {}
+    return BuildArtifacts(ply_path=blueprint_path or "", glb_path=mesh_path or "", summary=summary)

llm_parser.py

@@ -0,0 +1,167 @@
+from __future__ import annotations
+
+import json
+import os
+import re
+from functools import lru_cache
+from typing import Any
+
+from parser import PromptSpec, merge_prompt_specs, parse_prompt
+
+try:
+    import spaces  # type: ignore
+except Exception:  # pragma: no cover
+    class _SpacesShim:
+        @staticmethod
+        def GPU(*args, **kwargs):
+            def decorator(fn):
+                return fn
+            return decorator
+
+    spaces = _SpacesShim()  # type: ignore
+
+
+DEFAULT_LOCAL_MODEL = os.getenv("PB3D_LOCAL_MODEL", "Qwen/Qwen2.5-1.5B-Instruct")
+MODEL_PRESETS = {
+    "Qwen 2.5 1.5B": "Qwen/Qwen2.5-1.5B-Instruct",
+    "SmolLM2 1.7B": "HuggingFaceTB/SmolLM2-1.7B-Instruct",
+}
+
+JSON_SCHEMA_HINT = {
+    "object_type": ["cargo_hauler", "fighter", "shuttle", "freighter", "dropship", "drone"],
+    "scale": ["small", "medium", "large"],
+    "hull_style": ["boxy", "rounded", "sleek"],
+    "engine_count": "integer 1-6",
+    "wing_span": "float 0.0-0.6",
+    "cargo_ratio": "float 0.0-0.65",
+    "cockpit_ratio": "float 0.10-0.30",
+    "fin_height": "float 0.0-0.3",
+    "landing_gear": "boolean",
+    "asymmetry": "float 0.0-0.2",
+    "notes": "short string",
+}
+
+
+def _clamp(value: float, low: float, high: float) -> float:
+    return max(low, min(high, value))
+
+
+@lru_cache(maxsize=2)
+def _load_generation_components(model_id: str):
+    from transformers import AutoModelForCausalLM, AutoTokenizer
+    import torch
+
+    tokenizer = AutoTokenizer.from_pretrained(model_id, trust_remote_code=True)
+    if tokenizer.pad_token is None:
+        tokenizer.pad_token = tokenizer.eos_token
+
+    has_cuda = torch.cuda.is_available()
+    torch_dtype = torch.bfloat16 if has_cuda else torch.float32
+    model = AutoModelForCausalLM.from_pretrained(
+        model_id,
+        torch_dtype=torch_dtype,
+        device_map="auto",
+        low_cpu_mem_usage=True,
+        trust_remote_code=True,
+    )
+    return tokenizer, model
+
+
+@spaces.GPU(duration=45)
+def _generate_structured_json(prompt: str, model_id: str) -> dict[str, Any]:
+    import torch
+
+    tokenizer, model = _load_generation_components(model_id)
+
+    system = (
+        "You are a compact design parser for a procedural 3D generator. "
+        "Convert the user request into a single JSON object and output JSON only."
+    )
+    user = (
+        "Return a JSON object using this schema: "
+        f"{json.dumps(JSON_SCHEMA_HINT)}\n"
+        "Rules: choose the closest allowed enum values, stay conservative, infer hard-surface sci-fi vehicle structure, "
+        "never explain anything, never use markdown fences, and keep notes brief.\n"
+        f"Prompt: {prompt}"
+    )
+
+    messages = [
+        {"role": "system", "content": system},
+        {"role": "user", "content": user},
+    ]
+
+    if hasattr(tokenizer, "apply_chat_template"):
+        rendered = tokenizer.apply_chat_template(messages, tokenize=False, add_generation_prompt=True)
+    else:
+        rendered = f"System: {system}\nUser: {user}\nAssistant:"
+
+    inputs = tokenizer(rendered, return_tensors="pt")
+    model_device = getattr(model, "device", None)
+    if model_device is not None:
+        inputs = {k: v.to(model_device) for k, v in inputs.items()}
+
+    with torch.no_grad():
+        output = model.generate(
+            **inputs,
+            max_new_tokens=220,
+            do_sample=False,
+            temperature=None,
+            top_p=None,
+            repetition_penalty=1.02,
+            pad_token_id=tokenizer.pad_token_id,
+            eos_token_id=tokenizer.eos_token_id,
+        )
+
+    new_tokens = output[0][inputs["input_ids"].shape[1]:]
+    text = tokenizer.decode(new_tokens, skip_special_tokens=True).strip()
+
+    match = re.search(r"\{.*\}", text, flags=re.S)
+    if not match:
+        raise ValueError("Local model did not return JSON.")
+    return json.loads(match.group(0))
+
+
+def _normalize_llm_payload(payload: dict[str, Any], original_prompt: str) -> PromptSpec:
+    def get_str(name: str, default: str) -> str:
+        value = str(payload.get(name, default)).strip().lower()
+        return value or default
+
+    def get_int(name: str, default: int, low: int, high: int) -> int:
+        try:
+            return int(_clamp(int(payload.get(name, default)), low, high))
+        except Exception:
+            return default
+
+    def get_float(name: str, default: float, low: float, high: float) -> float:
+        try:
+            return float(_clamp(float(payload.get(name, default)), low, high))
+        except Exception:
+            return default
+
+    landing_raw = payload.get("landing_gear", True)
+    if isinstance(landing_raw, bool):
+        landing_gear = landing_raw
+    else:
+        landing_gear = str(landing_raw).strip().lower() in {"1", "true", "yes", "y"}
+
+    return PromptSpec(
+        object_type=get_str("object_type", "cargo_hauler"),
+        scale=get_str("scale", "small"),
+        hull_style=get_str("hull_style", "boxy"),
+        engine_count=get_int("engine_count", 2, 1, 6),
+        wing_span=get_float("wing_span", 0.2, 0.0, 0.6),
+        cargo_ratio=get_float("cargo_ratio", 0.38, 0.0, 0.65),
+        cockpit_ratio=get_float("cockpit_ratio", 0.18, 0.10, 0.30),
+        fin_height=get_float("fin_height", 0.0, 0.0, 0.3),
+        landing_gear=landing_gear,
+        asymmetry=get_float("asymmetry", 0.0, 0.0, 0.2),
+        notes=str(payload.get("notes", original_prompt)).strip() or original_prompt,
+    )
+
+
+def parse_prompt_with_local_llm(prompt: str, model_id: str | None = None) -> PromptSpec:
+    model_id = model_id or DEFAULT_LOCAL_MODEL
+    heuristic = parse_prompt(prompt)
+    payload = _generate_structured_json(prompt=prompt, model_id=model_id)
+    llm_spec = _normalize_llm_payload(payload, original_prompt=prompt)
+    return merge_prompt_specs(heuristic, llm_spec)

model_runtime.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Callable
+
+from huggingface_hub import snapshot_download
+
+TARGET_OMNI_MODEL = os.getenv("PB3D_TARGET_MODEL", "tencent/Hunyuan3D-Omni")
+DEFAULT_CACHE_ROOT = Path(os.getenv("PB3D_MODEL_CACHE", "./models"))
+
+
+def get_target_model_dir(model_id: str = TARGET_OMNI_MODEL) -> Path:
+    safe = model_id.replace("/", "--")
+    return DEFAULT_CACHE_ROOT / safe
+
+
+def ensure_target_model_cached(
+    model_id: str = TARGET_OMNI_MODEL,
+    progress: Callable[[str], None] | None = None,
+) -> dict:
+    """
+    Best-effort local cache of the upstream target model repo.
+
+    This fetches the model repo into the Space filesystem so later integration work
+    can call the upstream inference stack directly. It does not assume internal file
+    names beyond the official repo id.
+    """
+    target_dir = get_target_model_dir(model_id)
+    target_dir.mkdir(parents=True, exist_ok=True)
+
+    if progress:
+        progress(f"Checking local cache for {model_id}…")
+
+    try:
+        local_path = snapshot_download(
+            repo_id=model_id,
+            local_dir=str(target_dir),
+            local_dir_use_symlinks=False,
+            resume_download=True,
+        )
+        return {
+            "ok": True,
+            "model_id": model_id,
+            "local_path": local_path,
+            "message": f"Cached {model_id} in {local_path}",
+        }
+    except Exception as exc:  # pragma: no cover
+        return {
+            "ok": False,
+            "model_id": model_id,
+            "local_path": str(target_dir),
+            "message": f"Could not cache {model_id}: {exc}",
+        }

packages.txt

@@ -0,0 +1,4 @@
+git
+ffmpeg
+libgl1
+libglib2.0-0

parser.py

@@ -0,0 +1,148 @@
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, asdict
+
+
+@dataclass
+class PromptSpec:
+    object_type: str = "cargo_hauler"
+    scale: str = "small"
+    hull_style: str = "boxy"
+    engine_count: int = 2
+    wing_span: float = 0.2
+    cargo_ratio: float = 0.38
+    cockpit_ratio: float = 0.18
+    fin_height: float = 0.0
+    landing_gear: bool = True
+    asymmetry: float = 0.0
+    notes: str = ""
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+TYPE_KEYWORDS = {
+    "fighter": "fighter",
+    "combat": "fighter",
+    "interceptor": "fighter",
+    "shuttle": "shuttle",
+    "freighter": "freighter",
+    "hauler": "cargo_hauler",
+    "cargo": "cargo_hauler",
+    "transport": "cargo_hauler",
+    "dropship": "dropship",
+    "drone": "drone",
+}
+
+STYLE_KEYWORDS = {
+    "boxy": "boxy",
+    "industrial": "boxy",
+    "hard-surface": "boxy",
+    "rounded": "rounded",
+    "sleek": "sleek",
+    "streamlined": "sleek",
+    "brutalist": "boxy",
+}
+
+SCALE_KEYWORDS = {
+    "tiny": "small",
+    "small": "small",
+    "compact": "small",
+    "medium": "medium",
+    "mid-size": "medium",
+    "large": "large",
+    "heavy": "large",
+    "huge": "large",
+}
+
+VALID_OBJECT_TYPES = {"cargo_hauler", "fighter", "shuttle", "freighter", "dropship", "drone"}
+VALID_SCALES = {"small", "medium", "large"}
+VALID_HULL_STYLES = {"boxy", "rounded", "sleek"}
+
+
+def _clamp(value: float, low: float, high: float) -> float:
+    return max(low, min(high, value))
+
+
+def merge_prompt_specs(primary: PromptSpec, secondary: PromptSpec) -> PromptSpec:
+    merged = PromptSpec(**primary.to_dict())
+
+    if secondary.object_type in VALID_OBJECT_TYPES:
+        merged.object_type = secondary.object_type
+    if secondary.scale in VALID_SCALES:
+        merged.scale = secondary.scale
+    if secondary.hull_style in VALID_HULL_STYLES:
+        merged.hull_style = secondary.hull_style
+
+    merged.engine_count = int(_clamp(secondary.engine_count, 1, 6))
+    merged.wing_span = float(_clamp(secondary.wing_span, 0.0, 0.6))
+    merged.cargo_ratio = float(_clamp(secondary.cargo_ratio, 0.0, 0.65))
+    merged.cockpit_ratio = float(_clamp(secondary.cockpit_ratio, 0.10, 0.30))
+    merged.fin_height = float(_clamp(secondary.fin_height, 0.0, 0.3))
+    merged.landing_gear = bool(secondary.landing_gear)
+    merged.asymmetry = float(_clamp(secondary.asymmetry, 0.0, 0.2))
+    merged.notes = secondary.notes or primary.notes
+
+    if merged.object_type in {"fighter", "drone"}:
+        merged.cargo_ratio = min(merged.cargo_ratio, 0.20)
+        if merged.hull_style == "boxy":
+            merged.hull_style = "sleek"
+
+    return merged
+
+
+def parse_prompt(prompt: str) -> PromptSpec:
+    text = prompt.lower().strip()
+    spec = PromptSpec(notes=prompt.strip())
+
+    for key, value in TYPE_KEYWORDS.items():
+        if key in text:
+            spec.object_type = value
+            break
+
+    for key, value in STYLE_KEYWORDS.items():
+        if key in text:
+            spec.hull_style = value
+            break
+
+    for key, value in SCALE_KEYWORDS.items():
+        if key in text:
+            spec.scale = value
+            break
+
+    if any(word in text for word in ["wing", "wings"]):
+        spec.wing_span = 0.42 if spec.object_type == "fighter" else 0.28
+    if any(word in text for word in ["no wings", "wingless"]):
+        spec.wing_span = 0.0
+
+    if any(word in text for word in ["cargo bay", "cargo hold", "container", "freight"]):
+        spec.cargo_ratio = 0.48
+
+    if any(word in text for word in ["big cockpit", "large cockpit", "glass nose"]):
+        spec.cockpit_ratio = 0.24
+    if any(word in text for word in ["small cockpit", "tiny cockpit"]):
+        spec.cockpit_ratio = 0.13
+
+    if any(word in text for word in ["fin", "tail", "vertical stabilizer"]):
+        spec.fin_height = 0.18 if spec.object_type != "fighter" else 0.12
+
+    if any(word in text for word in ["hover", "hovercraft", "antigrav"]):
+        spec.landing_gear = False
+
+    if spec.object_type in {"fighter", "drone"}:
+        spec.engine_count = 1 if "single engine" in text else 2
+        spec.cargo_ratio = min(spec.cargo_ratio, 0.18)
+        spec.hull_style = "sleek"
+    elif spec.object_type in {"cargo_hauler", "freighter", "dropship"}:
+        spec.engine_count = 4 if any(x in text for x in ["4 engine", "four engine", "quad engine"]) else 2
+        spec.hull_style = "boxy" if spec.hull_style == "sleek" else spec.hull_style
+
+    numeric_engine = re.search(r"(\d+)\s*(?:engine|engines)", text)
+    if numeric_engine:
+        spec.engine_count = max(1, min(6, int(numeric_engine.group(1))))
+
+    if any(word in text for word in ["asymmetric", "uneven", "offset"]):
+        spec.asymmetry = 0.12
+
+    return spec

requirements.txt

@@ -0,0 +1,12 @@
+gradio>=5.22.0
+numpy>=1.26.0
+trimesh[easy]>=4.5.0
+scipy>=1.13.0
+scikit-image>=0.24.0
+huggingface_hub>=0.34.0
+requests>=2.32.0
+transformers>=4.47.0
+pillow>=10.4.0
+torch>=2.5.0,<2.6.0
+torchvision>=0.20.0,<0.21.0
+torchaudio>=2.5.0,<2.6.0

viewer.py

@@ -0,0 +1,158 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Iterable
+
+import numpy as np
+import trimesh
+
+
+def _sample_points(points: np.ndarray, max_points: int = 3500) -> np.ndarray:
+    if len(points) <= max_points:
+        return points.astype(float)
+    idx = np.linspace(0, len(points) - 1, max_points).astype(int)
+    return points[idx].astype(float)
+
+
+def load_points_from_cloud_file(path: str | Path, max_points: int = 3500) -> np.ndarray:
+    cloud = trimesh.load(path, force="mesh")
+    if isinstance(cloud, trimesh.points.PointCloud):
+        points = np.asarray(cloud.vertices)
+    elif isinstance(cloud, trimesh.Trimesh):
+        if len(cloud.faces) > 0:
+            count = min(max_points * 2, max(1200, len(cloud.faces) * 3))
+            points = cloud.sample(count)
+        else:
+            points = np.asarray(cloud.vertices)
+    else:
+        points = np.asarray(getattr(cloud, "vertices", []))
+    return _sample_points(np.asarray(points, dtype=float), max_points=max_points)
+
+
+def load_points_from_mesh_file(path: str | Path, max_points: int = 3500) -> np.ndarray:
+    mesh = trimesh.load(path, force="mesh")
+    if isinstance(mesh, trimesh.Scene):
+        mesh = trimesh.util.concatenate([g for g in mesh.geometry.values() if isinstance(g, trimesh.Trimesh)])
+    if isinstance(mesh, trimesh.Trimesh):
+        if len(mesh.faces) > 0:
+            count = min(max_points * 2, max(1600, len(mesh.faces) * 2))
+            points = mesh.sample(count)
+        else:
+            points = np.asarray(mesh.vertices)
+    else:
+        points = np.asarray(getattr(mesh, "vertices", []))
+    return _sample_points(np.asarray(points, dtype=float), max_points=max_points)
+
+
+def empty_viewer_html(message: str = "Generate a blueprint to preview it here.") -> str:
+    return f"""
+    <div style='height:520px;border-radius:20px;border:1px solid rgba(255,255,255,.08);display:flex;align-items:center;justify-content:center;background:linear-gradient(180deg,#06070a,#0b1020);color:#cfd6ff;font-family:Inter,system-ui,sans-serif;'>
+      <div style='text-align:center;padding:18px 24px;max-width:420px;'>
+        <div style='font-size:1.12rem;font-weight:700;margin-bottom:6px;'>Blueprint Viewer</div>
+        <div style='opacity:.84;line-height:1.45'>{message}</div>
+      </div>
+    </div>
+    """
+
+
+def point_cloud_viewer_html(points: np.ndarray, status: str = "Blueprint") -> str:
+    points = np.asarray(points, dtype=float)
+    if points.size == 0:
+        return empty_viewer_html("No points to display yet.")
+
+    points = _sample_points(points)
+    mins = points.min(axis=0)
+    maxs = points.max(axis=0)
+    center = (mins + maxs) / 2.0
+    span = float(np.max(maxs - mins)) or 1.0
+    normalized = (points - center) / span
+    color_src = normalized - normalized.min(axis=0, keepdims=True)
+    denom = color_src.ptp(axis=0, keepdims=True)
+    denom[denom == 0] = 1.0
+    colors = np.clip(color_src / denom, 0.0, 1.0)
+
+    points_payload = np.round(normalized, 5).tolist()
+    colors_payload = np.round(colors, 5).tolist()
+
+    return f"""
+<div style="height:560px;border-radius:20px;overflow:hidden;border:1px solid rgba(255,255,255,.08);background:radial-gradient(circle at 50% 20%, #0f1630, #05070d 75%);position:relative;">
+  <div id="pb3d-label" style="position:absolute;top:12px;left:12px;z-index:2;background:rgba(16,21,40,.75);border:1px solid rgba(255,255,255,.08);backdrop-filter:blur(8px);padding:10px 12px;border-radius:14px;color:#eef2ff;font:600 14px/1.3 Inter,system-ui,sans-serif;">{status}<div style="opacity:.75;font-weight:500;margin-top:4px">One finger orbit • two fingers pan/zoom</div></div>
+  <canvas id="pb3d-canvas" style="width:100%;height:100%;display:block;touch-action:none"></canvas>
+</div>
+<script src="https://unpkg.com/three@0.160.0/build/three.min.js"></script>
+<script src="https://unpkg.com/three@0.160.0/examples/js/controls/OrbitControls.js"></script>
+<script>
+(() => {{
+  const canvas = document.currentScript.previousElementSibling;
+  const holder = canvas.parentElement;
+  if (!window.THREE || !window.THREE.OrbitControls) {{
+    holder.innerHTML = `<div style='height:100%;display:flex;align-items:center;justify-content:center;color:#eef2ff;font-family:Inter,system-ui,sans-serif;'>Viewer failed to load.</div>`;
+    return;
+  }}
+  const pts = {json.dumps(points_payload)};
+  const cols = {json.dumps(colors_payload)};
+  const THREE = window.THREE;
+  const scene = new THREE.Scene();
+  const camera = new THREE.PerspectiveCamera(50, holder.clientWidth / holder.clientHeight, 0.01, 100);
+  camera.position.set(1.8, 1.4, 2.2);
+
+  const renderer = new THREE.WebGLRenderer({{canvas, antialias:true, alpha:true}});
+  renderer.setPixelRatio(Math.min(window.devicePixelRatio || 1, 2));
+  renderer.setSize(holder.clientWidth, holder.clientHeight, false);
+  renderer.outputColorSpace = THREE.SRGBColorSpace;
+
+  const controls = new THREE.OrbitControls(camera, canvas);
+  controls.enableDamping = true;
+  controls.enablePan = true;
+  controls.minDistance = 0.4;
+  controls.maxDistance = 8;
+  controls.target.set(0,0,0);
+
+  const positions = new Float32Array(pts.length * 3);
+  const colors = new Float32Array(cols.length * 3);
+  for (let i = 0; i < pts.length; i++) {{
+    positions[i*3] = pts[i][0];
+    positions[i*3+1] = pts[i][2];
+    positions[i*3+2] = pts[i][1];
+    colors[i*3] = cols[i][0] * 0.85 + 0.15;
+    colors[i*3+1] = cols[i][1] * 0.85 + 0.15;
+    colors[i*3+2] = cols[i][2] * 0.85 + 0.15;
+  }}
+  const geometry = new THREE.BufferGeometry();
+  geometry.setAttribute('position', new THREE.BufferAttribute(positions, 3));
+  geometry.setAttribute('color', new THREE.BufferAttribute(colors, 3));
+  const material = new THREE.PointsMaterial({{size: 0.025, sizeAttenuation: true, vertexColors:true}});
+  const cloud = new THREE.Points(geometry, material);
+  scene.add(cloud);
+
+  const grid = new THREE.GridHelper(2.4, 12, 0x4c5cff, 0x1d2645);
+  grid.position.y = -0.72;
+  scene.add(grid);
+
+  const lightA = new THREE.DirectionalLight(0xffffff, 1.8);
+  lightA.position.set(2, 3, 2);
+  scene.add(lightA);
+  const lightB = new THREE.DirectionalLight(0x7795ff, 0.9);
+  lightB.position.set(-2, -1, -1.5);
+  scene.add(lightB);
+  scene.add(new THREE.AmbientLight(0xb8c8ff, 0.8));
+
+  function resize() {{
+    const w = holder.clientWidth;
+    const h = holder.clientHeight;
+    camera.aspect = w / h;
+    camera.updateProjectionMatrix();
+    renderer.setSize(w, h, false);
+  }}
+  window.addEventListener('resize', resize);
+
+  function tick() {{
+    controls.update();
+    renderer.render(scene, camera);
+    requestAnimationFrame(tick);
+  }}
+  tick();
+}})();
+</script>
+"""