feat(hyshape): GPU geometry warmup on page load (ZeroGPU cold start)

- Default NEAR_HYSHAPE_GEOMETRY_WARMUP_ON_LOAD=1: demo.load + warmup loads Hunyuan once per visit\n- Add libopengl0 to packages.txt for pymeshlab libOpenGL noise\n- Document env var in README/DEPLOY; extend architecture test

Made-with: Cursor

DEPLOY_HF_SPACE.md

@@ -78,6 +78,7 @@ If you maintain a separate template tree (e.g. `NeAR_space`), copy changes **int
 | `NEAR_GSPLAT_WARMUP` | `0` | `1` |
 | `NEAR_GSPLAT_SOURCE_SPEC` | unset unless you have a proven build path | optional if you want build-time source compile |
 | `NEAR_ZEROGPU_HF_CEILING_S` | `90` | tune to your tier |
+| `NEAR_HYSHAPE_GEOMETRY_WARMUP_ON_LOAD` | `1` when Space entry is **`app_hyshape.py`** (default in code: load Hunyuan on first page view via `demo.load` + `@spaces.GPU`) | `0` to load geometry only when the user clicks **Generate Mesh** (saves one GPU allocation per visit, but repeats cold start) |
 
 ### 2b2. Mirroring DINOv2 and other auxiliary assets
 
@@ -141,6 +142,8 @@ If the UI shows **no examples** or **`No PNG examples`**, usually:
 | `requirements.txt` | `pip` dependencies. |
 | `packages.txt` | Optional `apt` packages (OpenGL, etc.). |
 
+Root **`packages.txt`** lists **`libgl1`** and **`libopengl0`** so imports that pull in **`pymeshlab`** are less likely to spam logs about **`libOpenGL.so.0`**. Those plugins are not required for the core NeAR / HyShape paths; if warnings persist after rebuild, they are usually safe to ignore.
+
 ## 4. Git push: large files & binary files on the Hub
 
 ### 4a. Files **> 10 MiB** in plain Git

README.md

@@ -49,6 +49,7 @@ This repository combines:
 ## ZeroGPU Runtime Notes
 
 - The Space is temporarily pointed at **`app_hyshape.py`** (Hunyuan geometry only) for isolating ZeroGPU init issues. Restore **`app_file: app.py`** in the YAML header above when you want the full NeAR UI again.
+- **`app_hyshape.py`** defaults to **`NEAR_HYSHAPE_GEOMETRY_WARMUP_ON_LOAD=1`**: opening the Space triggers one GPU callback that loads Hunyuan so **Generate Mesh** does not pay the full ~40s cold start again in the same session. Set to **`0`** to disable (saves GPU seconds per visitor, slower first mesh).
 - The full `app.py` Space keeps **page-load image defaults** and **HDRI preview** on lightweight CPU paths so the first page visit does not spend the first ZeroGPU allocation on model initialization.
 - Runtime loading is split by responsibility: **Hunyuan3D geometry** is loaded only for mesh generation, **NeAR relighting** is loaded only for SLaT/render/export, and **gsplat warmup** is delayed until the first real render.
 - Binary wheels and mirrored auxiliary assets are stored separately:

app_hyshape.py

@@ -41,7 +41,7 @@ print(
 )
 
 try:
-    import spaces
+    import spaces  # pyright: ignore[reportMissingImports]
 except ImportError:
     spaces = None
 
@@ -52,6 +52,21 @@ os.environ.setdefault("TORCH_CUDA_ARCH_LIST", "7.5;8.0;8.6;8.9;9.0")
 
 GPU = spaces.GPU if spaces is not None else (lambda f: f)
 
+
+def _truthy_env(name: str, default: str) -> bool:
+    value = (os.environ.get(name) if name in os.environ else default).strip().lower()
+    return value in ("1", "true", "yes", "on")
+
+
+# Default on for this probe Space: first "Generate Mesh" stays under ZeroGPU budget after weights are on GPU.
+_HYSHAPE_WARMUP_ON_LOAD = _truthy_env("NEAR_HYSHAPE_GEOMETRY_WARMUP_ON_LOAD", "1")
+print(
+    f"[HyShape] geometry warmup on page load: "
+    f"{'enabled' if _HYSHAPE_WARMUP_ON_LOAD else 'disabled'} "
+    f"(NEAR_HYSHAPE_GEOMETRY_WARMUP_ON_LOAD, default 1).",
+    flush=True,
+)
+
 APP_DIR = Path(__file__).resolve().parent
 CACHE_DIR = APP_DIR / "tmp_gradio_hyshape"
 CACHE_DIR.mkdir(exist_ok=True)
@@ -226,6 +241,24 @@ def ensure_geometry_pipeline() -> Any:
         return GEOMETRY_PIPELINE
 
 
+@GPU
+@torch.inference_mode()
+def warmup_hunyuan_geometry_on_load():
+    """Pay Hunyuan load + GPU move on first page view so Generate Mesh does not repeat it."""
+    started_at = time.time()
+    print(
+        "[HyShape] warmup_on_load: entered GPU callback "
+        f"(cuda_available={torch.cuda.is_available()})",
+        flush=True,
+    )
+    ensure_geometry_pipeline()
+    elapsed = time.time() - started_at
+    print(f"[HyShape] warmup_on_load: finished in {elapsed:.1f}s", flush=True)
+    return (
+        f"Geometry ready ({elapsed:.1f}s). Click **Generate Mesh** — model should already be on GPU."
+    )
+
+
 @GPU
 @torch.inference_mode()
 def generate_mesh(
@@ -284,7 +317,8 @@ This diagnostic app isolates the Hunyuan geometry path.
 
 - Upload an image or click an example.
 - The upload path only performs lightweight preprocessing.
-- `Generate Mesh` is the only GPU callback and does not touch NeAR or gsplat.
+- `Generate Mesh` is the main GPU callback and does not touch NeAR or gsplat.
+- With default settings, the first page load runs a **geometry warmup** on GPU so mesh generation does not pay the full cold start again.
             """
         )
 
@@ -322,6 +356,12 @@ This diagnostic app isolates the Hunyuan geometry path.
 
         demo.unload(end_session)
 
+        if _HYSHAPE_WARMUP_ON_LOAD:
+            demo.load(
+                warmup_hunyuan_geometry_on_load,
+                outputs=[status_md],
+            )
+
         image_input.upload(
             preprocess_image_only,
             inputs=[image_input],

packages.txt

@@ -1,2 +1,3 @@
 libgl1
+libopengl0
 libglib2.0-0

tests/test_app_hyshape_architecture.py

@@ -51,6 +51,19 @@ class AppHyShapeArchitectureTests(unittest.TestCase):
 
         self.assertIn("[HyShape] generate_mesh callback entered", source)
 
+    def test_page_load_warmup_calls_geometry_loader_only(self) -> None:
+        tree = _load_tree()
+        warmup = _get_function(tree, "warmup_hunyuan_geometry_on_load")
+        called = _called_names(warmup)
+
+        self.assertIn("ensure_geometry_pipeline", called)
+        self.assertNotIn("ensure_near_pipeline", called)
+        self.assertNotIn("ensure_gsplat_ready", called)
+
+        source = APP_PATH.read_text(encoding="utf-8")
+        self.assertIn("demo.load(", source)
+        self.assertIn("warmup_hunyuan_geometry_on_load", source)
+
 
 if __name__ == "__main__":
     unittest.main()