Upload 9 files

README.md

@@ -1,117 +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
-license: mit
+python_version: 3.10
 ---
 
 # Particle Blueprint 3D
 
-A Hugging Face Space for a scaffold-first 3D workflow:
+Mobile-first Hugging Face Space for **prompt → live particle blueprint → inspect → mesh**.
 
-**prompt → structured particle blueprint → reconstructed mesh → GLB**
+## What this version does
 
-This version is tuned for **mobile iPhone use first** and adds an optional **local Hugging Face model** for better prompt-to-shape planning.
+- 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
 
-## What changed
+## Current reality
 
-- Mobile-first single-column UX with larger tap targets.
-- Sticky action area on narrow screens.
-- Prompt presets for fast one-thumb use.
-- Tabs instead of side-by-side viewers, which works better on phones.
-- Optional local model planner before blueprint generation.
+This build gives you the UX and the working two-phase geometry pipeline now.
 
-## Why the local model is used only for planning
+- **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
 
-The local model does **not** try to directly generate a final GLB.
-It is used to convert a messy natural-language prompt into a cleaner structured spec:
+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.
 
-- object type
-- scale
-- hull style
-- engine count
-- wing span
-- cargo ratio
-- cockpit ratio
-- fin height
-- landing gear
-- asymmetry
-
-That structured spec then drives the scaffold and meshing pipeline.
-This is much more realistic than pretending a small local model can do full end-to-end 3D generation well.
-
-## Recommended local models
-
-### Best default
-
-- `Qwen/Qwen2.5-1.5B-Instruct`
-
-Use this as the main local planner. It is the stronger option for extracting useful structure from prompts.
-
-### Lighter fallback
-
-- `HuggingFaceTB/SmolLM2-1.7B-Instruct`
-
-Use this if you want a smaller-feeling fallback or if Qwen has issues in your runtime.
-
-## Current pipeline
-
-1. Parse the prompt with either:
-   - fast heuristic parser
-   - local Hugging Face model planner
-2. Generate a structured particle blueprint.
-3. Convert the blueprint into a voxel field.
-4. Reconstruct a triangle mesh.
-5. Export both `.ply` and `.glb`.
-
-## ZeroGPU strategy
-
-Use the local model only when needed.
-The LLM generation function is isolated so it can be decorated for ZeroGPU use without forcing the whole app onto GPU every time.
-
-## Local development
-
-```bash
-pip install -r requirements.txt
-python app.py
-```
-
-## Deploy to Hugging Face
-
-Create a **Gradio** Space and push these files.
-
-```bash
-git init
-git add .
-git commit -m "Mobile UX + local HF planner"
-git branch -M main
-git remote add origin https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME
-git push -u origin main
-```
-
-## Notes
-
-This is still the right honest framing:
-
-- AI plans the shape
-- the app builds the scaffold
-- the scaffold becomes the mesh
-
-That middle layer is the product.
-
-
-## Flat repo layout
-
-This build is flattened so **every file lives in the repo root**.
-
-Upload these files directly into the Hugging Face Space root:
+## Files to upload to the Space root
 
 - `app.py`
 - `generator.py`
+- `model_runtime.py`
 - `llm_parser.py`
 - `parser.py`
 - `requirements.txt`
@@ -119,4 +47,8 @@ Upload these files directly into the Hugging Face Space root:
 - `README.md`
 - `LICENSE`
 
-No `src/` folder is needed.
+## Notes
+
+- 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

app.py

@@ -2,15 +2,16 @@ from __future__ import annotations
 
 import gradio as gr
 
-from generator import run_pipeline
+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
 
 
 TITLE = "Particle Blueprint 3D"
-TAGLINE = "Mobile-first prompt → particle scaffold → mesh → GLB"
+TAGLINE = "Describe → generate blueprint live → inspect in 3D → mesh when approved"
 DESCRIPTION = (
-    "Built for iPhone use first: a compact prompt flow, one-tap presets, low-friction controls, "
-    "and an optional local Hugging Face model that plans the blueprint before meshing."
+    "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."
 )
 
 PROMPT_PRESETS = {
@@ -23,60 +24,115 @@ 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 {border: 1px solid rgba(255,255,255,0.08); border-radius: 22px; padding: 14px 16px; background: rgba(255,255,255,0.03)}
+.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: 50px !important; border-radius: 16px !important; font-size: 1rem !important}
+.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}
+#status-box p {margin:0}
 @media (max-width: 820px) {
   .gradio-container {padding: 0 10px 22px 10px !important}
-  .hero-card, .panel-card {padding: 12px 12px}
+  .hero-card, .panel-card, .status-card {padding: 12px 12px}
   .hero-title {font-size: 1.28rem}
-  .preset-row {grid-template-columns: 1fr}
-  .cta-row {position: sticky; bottom: 10px; z-index: 10; background: rgba(15,18,24,0.86); backdrop-filter: blur(12px); padding: 8px; border: 1px solid rgba(255,255,255,0.08); border-radius: 18px}
+  .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}
 }
 """
 
 
-def generate_asset(prompt: str, parser_mode: str, model_choice: str, detail: int, voxel_pitch: float):
+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):
     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)
-    artifacts = run_pipeline(
+    latest_summary = None
+    latest_path = None
+    latest_state = None
+
+    yield (
+        _status_md("Starting blueprint generation…"),
+        None,
+        None,
+        None,
+        None,
+        gr.update(interactive=False),
+    )
+
+    for update in iter_blueprint_session(
         prompt=prompt,
         detail=detail,
-        voxel_pitch=voxel_pitch,
         parser_mode=parser_mode,
         model_id=model_id,
-    )
-    status = (
-        f"Built {artifacts.summary['point_count']} scaffold points and "
-        f"{artifacts.summary['face_count']} mesh faces using {artifacts.summary['parser_backend']}."
-    )
-    return artifacts.ply_path, artifacts.glb_path, artifacts.summary, artifacts.ply_path, artifacts.glb_path, status
+    ):
+        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…")
+        yield (
+            _status_md(status_text),
+            latest_path,
+            latest_summary,
+            latest_path,
+            latest_state,
+            gr.update(interactive=bool(latest_state)),
+        )
+
+
+def stream_mesh(state: dict, voxel_pitch: float, warm_target_model: bool):
+    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
 
 
 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>
-              <p class='mobile-note'>Best on mobile for ships, drones, cargo gear and other hard-surface forms.</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>
             """
         )
 
         with gr.Column(elem_classes=["panel-card"]):
             prompt = gr.Textbox(
-                label="Describe the object",
+                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",
@@ -88,27 +144,34 @@ with gr.Blocks(theme=gr.themes.Soft(), css=CSS, title=TITLE, fill_width=True) as
                 preset_b = gr.Button("Compact fighter")
                 preset_c = gr.Button("Industrial dropship")
 
-            with gr.Accordion("Model and quality", open=False):
+            with gr.Accordion("Planner and mesh settings", open=False):
                 parser_mode = gr.Radio(
-                    choices=[("Fast heuristic", "heuristic"), ("Local HF model", "local")],
+                    choices=[("Fast heuristic", "heuristic"), ("Local HF planner", "local")],
                     value="heuristic",
                     label="Prompt planner",
-                    info="Use the local model when you want better shape planning from messy prompts.",
+                    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 model",
-                    info="Qwen is the stronger planner. SmolLM2 is the lighter fallback.",
+                    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.",
                 )
-                detail = gr.Slider(12, 32, value=18, step=2, label="Detail")
-                voxel_pitch = gr.Slider(0.06, 0.12, value=0.09, step=0.005, label="Mesh density")
 
             with gr.Row(elem_classes=["cta-row"]):
-                run_btn = gr.Button("Generate blueprint", variant="primary")
+                blueprint_btn = gr.Button("Generate blueprint", variant="primary")
+                mesh_btn = gr.Button("Make mesh from blueprint", interactive=False)
                 clear_btn = gr.Button("Clear")
 
-            status = gr.Markdown("Ready.")
+        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"):
@@ -116,19 +179,25 @@ with gr.Blocks(theme=gr.themes.Soft(), css=CSS, title=TITLE, fill_width=True) as
                     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=520,
+                    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=520,
+                    height=540,
                 )
             with gr.TabItem("Summary and files"):
-                summary = gr.JSON(label="Build summary")
+                summary = gr.JSON(label="Session summary")
                 blueprint_file = gr.File(label="Download blueprint (.ply)")
                 mesh_file = gr.File(label="Download mesh (.glb)")
 
@@ -136,15 +205,31 @@ with gr.Blocks(theme=gr.themes.Soft(), css=CSS, title=TITLE, fill_width=True) as
         preset_b.click(lambda: PROMPT_PRESETS["Compact fighter"], outputs=prompt)
         preset_c.click(lambda: PROMPT_PRESETS["Industrial dropship"], outputs=prompt)
 
-        run_btn.click(
-            fn=generate_asset,
-            inputs=[prompt, parser_mode, model_choice, detail, voxel_pitch],
-            outputs=[blueprint_view, mesh_view, summary, blueprint_file, mesh_file, status],
+        blueprint_btn.click(
+            fn=stream_blueprint,
+            inputs=[prompt, parser_mode, model_choice, detail],
+            outputs=[status, blueprint_view, summary, blueprint_file, session_state, mesh_btn],
+        )
+
+        mesh_btn.click(
+            fn=stream_mesh,
+            inputs=[session_state, voxel_pitch, warm_target_model],
+            outputs=[status, mesh_view, mesh_file, summary],
         )
 
         clear_btn.click(
-            lambda: ("", None, None, None, None, None, "Ready."),
-            outputs=[prompt, blueprint_view, mesh_view, summary, blueprint_file, mesh_file, status],
+            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],
         )
 
 

generator.py

@@ -4,7 +4,7 @@ import math
 import tempfile
 from dataclasses import dataclass
 from pathlib import Path
-from typing import Iterable
+from typing import Generator
 
 import numpy as np
 import trimesh
@@ -12,6 +12,7 @@ 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
 
 
@@ -108,108 +109,200 @@ def _sample_cylinder_surface(center, radius, length, axis: str, density: int, la
     return pts, normals, labels
 
 
-def build_particle_blueprint(
-    prompt: str,
-    detail: int = 24,
-    parser_mode: str = "heuristic",
-    model_id: str | None = None,
-) -> tuple[np.ndarray, np.ndarray, np.ndarray, PromptSpec, str]:
+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()
-    parser_backend = "heuristic"
     if parser_mode.startswith("local"):
         spec = parse_prompt_with_local_llm(prompt, model_id=model_id or DEFAULT_LOCAL_MODEL)
-        parser_backend = f"local_llm:{model_id or DEFAULT_LOCAL_MODEL}"
-    else:
-        spec = parse_prompt(prompt)
+        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)
 
-    parts = []
-    normals = []
-    labels = []
-
     hull_len = 2.8 * scale
     hull_w = 1.2 * scale
     hull_h = 0.8 * scale
 
     if spec.hull_style == "rounded":
-        p, n, l = _sample_ellipsoid_surface((0.0, 0.0, 0.0), (hull_len / 2, hull_w / 2, hull_h / 2), density, 0)
+        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), density // 2, 0)
-        p = np.vstack([p1, p2])
-        n = np.vstack([n1, n2])
-        l = np.concatenate([l1, l2])
+        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:
-        p, n, l = _sample_box_surface((0.0, 0.0, 0.0), (hull_len, hull_w, hull_h), density, 0)
-    parts.append(p)
-    normals.append(n)
-    labels.append(l)
+        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)
-    cp, cn, cl = _sample_ellipsoid_surface(cockpit_center, (hull_len * spec.cockpit_ratio, hull_w * 0.22, hull_h * 0.24), density // 2, 1)
-    parts.append(cp)
-    normals.append(cn)
-    labels.append(cl)
+    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)
-        pp, pn, pl = _sample_box_surface(cargo_center, cargo_size, density // 2, 2)
-        parts.append(pp)
-        normals.append(pn)
-        labels.append(pl)
+        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)
-            parts.append(pp)
-            normals.append(pn)
-            labels.append(pl)
+            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)
-        parts.append(pp)
-        normals.append(pn)
-        labels.append(pl)
+        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))
-        pp, pn, pl = _sample_box_surface(fin_center, fin_size, max(6, density // 3), 5)
-        parts.append(pp)
-        normals.append(pn)
-        labels.append(pl)
+        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)
-                parts.append(pp)
-                normals.append(pn)
-                labels.append(pl)
-
-    points = np.vstack(parts)
-    point_normals = np.vstack(normals)
-    point_labels = np.concatenate(labels)
+                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)
 
-    if spec.asymmetry > 0:
-        mask = points[:, 1] > 0
-        points[mask, 2] += spec.asymmetry * np.sin(points[mask, 0] * 2.0)
 
-    return points.astype(np.float32), point_normals.astype(np.float32), point_labels.astype(np.int32), spec, parser_backend
+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:
@@ -242,58 +335,75 @@ def points_to_mesh(points: np.ndarray, pitch: float = 0.08, padding: int = 5, si
     return mesh
 
 
-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 run_pipeline(
-    prompt: str,
-    detail: int = 24,
+def iter_meshify_session(
+    state: dict,
     voxel_pitch: float = 0.08,
-    parser_mode: str = "heuristic",
-    model_id: str | None = None,
-) -> BuildArtifacts:
-    points, normals, labels, spec, parser_backend = build_particle_blueprint(
-        prompt,
-        detail=detail,
-        parser_mode=parser_mode,
-        model_id=model_id,
-    )
+    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)
 
-    out_dir = Path(tempfile.mkdtemp(prefix="particle_blueprint_"))
-    ply_path = str(out_dir / "blueprint.ply")
-    glb_path = str(out_dir / "mesh.glb")
-    export_point_cloud_as_ply(points, labels, ply_path)
+    yield {"status": "Exporting GLB…"}
+    glb_path = str(session_dir / "mesh_final.glb")
     export_mesh_as_glb(mesh, glb_path)
 
     summary = {
-        "prompt": prompt,
-        "parser_backend": parser_backend,
-        "spec": spec.to_dict(),
-        "point_count": int(len(points)),
+        **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
+
 
-    return BuildArtifacts(ply_path=ply_path, glb_path=glb_path, summary=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)

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}",
+        }

requirements.txt

@@ -8,3 +8,4 @@ transformers>=4.49.0
 accelerate>=1.4.0
 torch>=2.6.0
 safetensors>=0.5.3
+spaces>=0.35.0