Upload 5 files

LICENSE

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

README.md

@@ -1,14 +1,104 @@
 ---
-title: 3DModelGen
-emoji: 😻
-colorFrom: blue
-colorTo: gray
+title: Particle Blueprint 3D
+emoji: 🧩
+colorFrom: indigo
+colorTo: blue
 sdk: gradio
-sdk_version: 6.10.0
-python_version: '3.12'
 app_file: app.py
 pinned: false
-short_description: This space is designed to easily generate models using the p
+license: mit
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Particle Blueprint 3D
+
+A Hugging Face Space for a scaffold-first 3D workflow:
+
+**prompt → structured particle blueprint → reconstructed mesh → GLB**
+
+This version is tuned for **mobile iPhone use first** and adds an optional **local Hugging Face model** for better prompt-to-shape planning.
+
+## What changed
+
+- 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.
+
+## Why the local model is used only for planning
+
+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:
+
+- 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.

app.py

@@ -0,0 +1,152 @@
+from __future__ import annotations
+
+import gradio as gr
+
+from src.generator import run_pipeline
+from src.llm_parser import DEFAULT_LOCAL_MODEL, MODEL_PRESETS
+
+
+TITLE = "Particle Blueprint 3D"
+TAGLINE = "Mobile-first prompt → particle scaffold → mesh → GLB"
+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."
+)
+
+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",
+}
+
+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-title {font-size: 1.5rem; font-weight: 800; margin: 0 0 6px 0}
+.hero-sub {opacity: 0.88; margin: 0}
+.cta-row {gap: 10px}
+.cta-row button {min-height: 50px !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}
+@media (max-width: 820px) {
+  .gradio-container {padding: 0 10px 22px 10px !important}
+  .hero-card, .panel-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}
+}
+"""
+
+
+def generate_asset(prompt: str, parser_mode: str, model_choice: str, detail: int, voxel_pitch: float):
+    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(
+        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
+
+
+with gr.Blocks(theme=gr.themes.Soft(), css=CSS, title=TITLE, fill_width=True) as demo:
+    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>
+            """
+        )
+
+        with gr.Column(elem_classes=["panel-card"]):
+            prompt = gr.Textbox(
+                label="Describe the object",
+                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"]):
+                preset_a = gr.Button("Cargo hauler")
+                preset_b = gr.Button("Compact fighter")
+                preset_c = gr.Button("Industrial dropship")
+
+            with gr.Accordion("Model and quality", open=False):
+                parser_mode = gr.Radio(
+                    choices=[("Fast heuristic", "heuristic"), ("Local HF model", "local")],
+                    value="heuristic",
+                    label="Prompt planner",
+                    info="Use the local model when you want better shape planning from messy prompts.",
+                )
+                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.",
+                )
+                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")
+                clear_btn = gr.Button("Clear")
+
+            status = gr.Markdown("Ready.")
+
+        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),
+                    elem_classes=["model3d-wrap"],
+                    height=520,
+                )
+            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),
+                    elem_classes=["model3d-wrap"],
+                    height=520,
+                )
+            with gr.TabItem("Summary and files"):
+                summary = gr.JSON(label="Build 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)
+
+        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],
+        )
+
+        clear_btn.click(
+            lambda: ("", None, None, None, None, None, "Ready."),
+            outputs=[prompt, blueprint_view, mesh_view, summary, blueprint_file, mesh_file, status],
+        )
+
+
+if __name__ == "__main__":
+    demo.queue(default_concurrency_limit=1).launch()

packages.txt

@@ -0,0 +1 @@
+libgl1

requirements.txt

@@ -0,0 +1,10 @@
+gradio>=5.24.0
+numpy>=1.26.4
+scipy>=1.13.1
+scikit-image>=0.24.0
+trimesh>=4.4.9
+huggingface_hub>=0.31.0
+transformers>=4.49.0
+accelerate>=1.4.0
+torch>=2.6.0
+safetensors>=0.5.3