feat(space): HyShape-only ZeroGPU diagnostic app as Space entry

- Add app_hyshape.py (Hunyuan mesh only, early GPU callback logs)\n- Point README app_file at app_hyshape.py; document switch back to app.py\n- Add plan doc and AST architecture test

Made-with: Cursor

README.md

@@ -6,7 +6,7 @@ colorTo: indigo
 sdk: gradio
 sdk_version: 6.9.0
 python_version: "3.10"
-app_file: app.py
+app_file: app_hyshape.py
 pinned: false
 license: apache-2.0
 short_description: "Relightable 3D from one image: SLAT, neural renderer, HDRI"
@@ -48,7 +48,8 @@ This repository combines:
 
 ## ZeroGPU Runtime Notes
 
-- The Space now 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.
+- 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.
+- 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:
   - **`luh0502/near-wheels`**: prebuilt wheels such as `nvdiffrast` and optional future `gsplat` wheels
@@ -100,7 +101,8 @@ Compared with a standard image-to-3D pipeline, NeAR focuses on:
 Key files and directories:
 
 - `example.py` — minimal end-to-end inference example.
-- `app.py` — Gradio / Hugging Face Space entrypoint.
+- `app_hyshape.py` — current Hugging Face Space entrypoint (HyShape-only ZeroGPU diagnostic).
+- `app.py` — full NeAR Gradio app; set `app_file: app.py` in this README to switch back.
 - `setup.sh` — environment setup helper.
 - `checkpoints/` — local pipeline configuration and model checkpoints.
 - `trellis/pipelines/near_image_to_relightable_3d.py` — main NeAR inference pipeline.

app_hyshape.py

@@ -0,0 +1,373 @@
+import os
+import sys
+import shutil
+import threading
+import time
+from pathlib import Path
+from typing import Any, Optional
+
+import gradio as gr
+import numpy as np
+import torch
+from PIL import Image
+
+# transformers/huggingface_hub authenticate gated repos via HF_TOKEN (or HUGGING_FACE_HUB_TOKEN).
+if not os.environ.get("HF_TOKEN") and not os.environ.get("HUGGING_FACE_HUB_TOKEN"):
+    _hub_tok = (os.environ.get("near") or os.environ.get("NEAR") or "").strip()
+    if _hub_tok:
+        os.environ["HF_TOKEN"] = _hub_tok
+        print(
+            "[HyShape] HF_TOKEN unset; using Space secret 'near' as HF_TOKEN.",
+            flush=True,
+        )
+
+# ZeroGPU variables must be clamped before importing spaces.
+try:
+    _raw_zerogpu_cap = int(os.environ.get("NEAR_ZEROGPU_HF_CEILING_S", "90"))
+except ValueError:
+    _raw_zerogpu_cap = 90
+_ZEROGPU_ENV_CAP_S = min(max(15, _raw_zerogpu_cap), 120)
+for _env_key in ("NEAR_ZEROGPU_MAX_SECONDS", "NEAR_ZEROGPU_DURATION_CAP"):
+    if _env_key in os.environ:
+        try:
+            if int(os.environ[_env_key]) > _ZEROGPU_ENV_CAP_S:
+                os.environ[_env_key] = str(_ZEROGPU_ENV_CAP_S)
+        except ValueError:
+            pass
+print(
+    f"[HyShape] ZeroGPU cap set to {_ZEROGPU_ENV_CAP_S}s. "
+    "Callbacks use plain spaces.GPU.",
+    flush=True,
+)
+
+try:
+    import spaces
+except ImportError:
+    spaces = None
+
+sys.path.insert(0, "./hy3dshape")
+os.environ.setdefault("ATTN_BACKEND", "xformers")
+os.environ.setdefault("SPCONV_ALGO", "native")
+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)
+
+APP_DIR = Path(__file__).resolve().parent
+CACHE_DIR = APP_DIR / "tmp_gradio_hyshape"
+CACHE_DIR.mkdir(exist_ok=True)
+DEFAULT_IMAGE = APP_DIR / "assets/example_image/T.png"
+DEFAULT_PORT = 7860
+
+_SESSION_LAST_TOUCH: dict[str, float] = {}
+_SESSION_TOUCH_LOCK = threading.Lock()
+_MODEL_LOCK = threading.Lock()
+_LIGHT_PREPROCESS_LOCK = threading.Lock()
+_LIGHT_PREPROCESSOR: Any | None = None
+GEOMETRY_PIPELINE: Any | None = None
+
+
+def _path_is_git_lfs_pointer(path: Path) -> bool:
+    try:
+        if not path.is_file():
+            return False
+        if path.stat().st_size > 512:
+            return False
+        head = path.read_bytes()[:120]
+        return head.startswith(b"version https://git-lfs.github.com/spec/v1")
+    except OSError:
+        return False
+
+
+def _session_touch(session_id: str) -> None:
+    with _SESSION_TOUCH_LOCK:
+        _SESSION_LAST_TOUCH[session_id] = time.time()
+
+
+def _session_forget(session_id: str) -> None:
+    with _SESSION_TOUCH_LOCK:
+        _SESSION_LAST_TOUCH.pop(session_id, None)
+
+
+def ensure_session_dir(req: Optional[gr.Request]) -> Path:
+    session_id = getattr(req, "session_hash", None) or "shared"
+    session_dir = CACHE_DIR / str(session_id)
+    session_dir.mkdir(parents=True, exist_ok=True)
+    _session_touch(str(session_id))
+    return session_dir
+
+
+def clear_session_dir(req: Optional[gr.Request]) -> str:
+    session_dir = ensure_session_dir(req)
+    shutil.rmtree(session_dir, ignore_errors=True)
+    session_dir.mkdir(parents=True, exist_ok=True)
+    if torch.cuda.is_available():
+        torch.cuda.empty_cache()
+    return "HyShape cache cleared."
+
+
+def end_session(req: gr.Request) -> None:
+    session_id = getattr(req, "session_hash", None) or "shared"
+    shutil.rmtree(CACHE_DIR / str(session_id), ignore_errors=True)
+    _session_forget(str(session_id))
+
+
+def _runtime_device() -> str:
+    return "cuda" if torch.cuda.is_available() else "cpu"
+
+
+def _ensure_rgba(image: Image.Image) -> Image.Image:
+    if image.mode == "RGBA":
+        return image
+    if image.mode == "RGB":
+        r, g, b = image.split()
+        a = Image.new("L", image.size, 255)
+        return Image.merge("RGBA", (r, g, b, a))
+    return image.convert("RGBA")
+
+
+def _flatten_rgba_on_matte(image: Image.Image, matte_rgb: tuple[float, float, float]) -> Image.Image:
+    rgba = _ensure_rgba(image)
+    matte = tuple(int(round(channel * 255)) for channel in matte_rgb)
+    background = Image.new("RGBA", rgba.size, matte + (255,))
+    return Image.alpha_composite(background, rgba).convert("RGB")
+
+
+def _get_light_image_preprocessor():
+    global _LIGHT_PREPROCESSOR
+    if _LIGHT_PREPROCESSOR is not None:
+        return _LIGHT_PREPROCESSOR
+    with _LIGHT_PREPROCESS_LOCK:
+        if _LIGHT_PREPROCESSOR is None:
+            from hy3dshape.rembg import BackgroundRemover  # pyright: ignore[reportMissingImports]
+
+            _LIGHT_PREPROCESSOR = BackgroundRemover()
+            print("[HyShape] Background remover ready.", flush=True)
+    return _LIGHT_PREPROCESSOR
+
+
+def _preprocess_image_rgba_light(input_image: Image.Image) -> Image.Image:
+    image = _ensure_rgba(input_image)
+    has_alpha = False
+    if image.mode == "RGBA":
+        alpha = np.array(image)[:, :, 3]
+        has_alpha = not np.all(alpha == 255)
+
+    if has_alpha:
+        output = image
+    else:
+        rgb = image.convert("RGB")
+        max_size = max(rgb.size)
+        scale = min(1, 1024 / max_size)
+        if scale < 1:
+            rgb = rgb.resize(
+                (int(rgb.width * scale), int(rgb.height * scale)),
+                Image.Resampling.LANCZOS,
+            )
+        output = _get_light_image_preprocessor()(rgb)
+
+    if output.mode != "RGBA":
+        output = output.convert("RGBA")
+    output_np = np.array(output)
+    alpha = output_np[:, :, 3]
+    bbox = np.argwhere(alpha > 0.8 * 255)
+    if bbox.size == 0:
+        return output.resize((518, 518), Image.Resampling.LANCZOS).convert("RGBA")
+
+    crop_bbox = (
+        int(np.min(bbox[:, 1])),
+        int(np.min(bbox[:, 0])),
+        int(np.max(bbox[:, 1])),
+        int(np.max(bbox[:, 0])),
+    )
+    center = ((crop_bbox[0] + crop_bbox[2]) / 2, (crop_bbox[1] + crop_bbox[3]) / 2)
+    size = max(crop_bbox[2] - crop_bbox[0], crop_bbox[3] - crop_bbox[1])
+    size = int(size * 1.2)
+    padded_bbox = (
+        center[0] - size // 2,
+        center[1] - size // 2,
+        center[0] + size // 2,
+        center[1] + size // 2,
+    )
+    return output.crop(padded_bbox).resize((518, 518), Image.Resampling.LANCZOS).convert("RGBA")
+
+
+def preprocess_image_only(image_input: Optional[Image.Image]):
+    if image_input is None:
+        return None, None, "Upload an input image."
+    started_at = time.time()
+    rgba = _preprocess_image_rgba_light(image_input)
+    elapsed = time.time() - started_at
+    print(f"[HyShape] lightweight preprocess done in {elapsed:.1f}s", flush=True)
+    return rgba, rgba, f"Image preprocessed in {elapsed:.1f}s."
+
+
+def ensure_geometry_pipeline() -> Any:
+    global GEOMETRY_PIPELINE
+    if GEOMETRY_PIPELINE is not None:
+        return GEOMETRY_PIPELINE
+
+    with _MODEL_LOCK:
+        if GEOMETRY_PIPELINE is not None:
+            return GEOMETRY_PIPELINE
+
+        from hy3dshape.pipelines import Hunyuan3DDiTFlowMatchingPipeline  # pyright: ignore[reportMissingImports]
+
+        device = _runtime_device()
+        hy_id = os.environ.get("NEAR_HUNYUAN_PRETRAINED", "tencent/Hunyuan3D-2.1")
+        started_at = time.time()
+        print(f"[HyShape] Loading geometry pipeline from {hy_id!r}...", flush=True)
+        geometry_pipeline = Hunyuan3DDiTFlowMatchingPipeline.from_pretrained(hy_id, device="cpu")
+        print(f"[HyShape] from_pretrained done in {time.time() - started_at:.1f}s", flush=True)
+        move_started_at = time.time()
+        geometry_pipeline.to(device)
+        print(f"[HyShape] moved geometry pipeline to {device} in {time.time() - move_started_at:.1f}s", flush=True)
+        GEOMETRY_PIPELINE = geometry_pipeline
+        print(f"[HyShape] geometry pipeline ready in {time.time() - started_at:.1f}s total", flush=True)
+        return GEOMETRY_PIPELINE
+
+
+@GPU
+@torch.inference_mode()
+def generate_mesh(
+    image_input: Optional[Image.Image],
+    req: gr.Request,
+    progress=gr.Progress(track_tqdm=True),
+):
+    started_at = time.time()
+    print(
+        "[HyShape] generate_mesh callback entered "
+        f"(cuda_available={torch.cuda.is_available()}, session={getattr(req, 'session_hash', 'shared')})",
+        flush=True,
+    )
+    progress(0.05, desc="Entered GPU callback")
+
+    if image_input is None:
+        raise gr.Error("Please upload an input image.")
+
+    session_dir = ensure_session_dir(req)
+    rgba = _ensure_rgba(image_input)
+    if rgba.size != (518, 518):
+        rgba = _preprocess_image_rgba_light(rgba)
+
+    rgba_path = session_dir / "input_preprocessed_rgba.png"
+    rgba.save(rgba_path)
+    mesh_rgb = _flatten_rgba_on_matte(rgba, (1.0, 1.0, 1.0))
+    mesh_rgb.save(session_dir / "input_processed.png")
+
+    progress(0.2, desc="Loading Hunyuan geometry")
+    geometry_pipeline = ensure_geometry_pipeline()
+
+    progress(0.6, desc="Generating geometry")
+    mesh_started_at = time.time()
+    mesh = geometry_pipeline(image=mesh_rgb)[0]
+    print(f"[HyShape] geometry generation done in {time.time() - mesh_started_at:.1f}s", flush=True)
+
+    mesh_path = session_dir / "hyshape_mesh.glb"
+    mesh.export(mesh_path)
+    total_elapsed = time.time() - started_at
+    print(f"[HyShape] generate_mesh total: {total_elapsed:.1f}s", flush=True)
+    return rgba, str(mesh_path), f"HyShape mesh ready in {total_elapsed:.1f}s."
+
+
+def build_app() -> gr.Blocks:
+    example_images = [
+        [str(path)]
+        for path in sorted((APP_DIR / "assets/example_image").glob("*.png"))
+        if not _path_is_git_lfs_pointer(path)
+    ]
+
+    with gr.Blocks(title="HyShape ZeroGPU Probe", delete_cache=None) as demo:
+        gr.Markdown(
+            """
+## HyShape ZeroGPU Probe
+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.
+            """
+        )
+
+        with gr.Row(equal_height=False):
+            with gr.Column(scale=1, min_width=360):
+                image_input = gr.Image(
+                    label="Input Image",
+                    type="pil",
+                    image_mode="RGBA",
+                    value=str(DEFAULT_IMAGE) if DEFAULT_IMAGE.exists() else None,
+                    height=400,
+                )
+                mesh_button = gr.Button("Generate Mesh", variant="primary")
+                clear_button = gr.Button("Clear Cache", variant="secondary")
+
+                if example_images:
+                    gr.Examples(
+                        examples=example_images,
+                        inputs=[image_input],
+                        label="Example Images",
+                    )
+
+            with gr.Column(scale=2, min_width=560):
+                status_md = gr.Markdown("Ready.")
+                processed_preview = gr.Image(
+                    label="Preprocessed RGBA",
+                    interactive=False,
+                    height=320,
+                )
+                mesh_viewer = gr.Model3D(
+                    label="Generated Mesh",
+                    interactive=False,
+                    height=520,
+                )
+
+        demo.unload(end_session)
+
+        image_input.upload(
+            preprocess_image_only,
+            inputs=[image_input],
+            outputs=[image_input, processed_preview, status_md],
+        )
+
+        mesh_button.click(
+            generate_mesh,
+            inputs=[image_input],
+            outputs=[processed_preview, mesh_viewer, status_md],
+        )
+
+        clear_button.click(
+            clear_session_dir,
+            outputs=[status_md],
+        ).then(
+            lambda: (None, None),
+            outputs=[processed_preview, mesh_viewer],
+        )
+
+    return demo
+
+
+demo = build_app()
+demo.queue(max_size=2)
+
+
+if __name__ == "__main__":
+    import argparse
+
+    parser = argparse.ArgumentParser()
+    parser.add_argument(
+        "--host",
+        type=str,
+        default=os.environ.get("GRADIO_SERVER_NAME", "0.0.0.0"),
+    )
+    parser.add_argument(
+        "--port",
+        type=int,
+        default=int(os.environ.get("PORT", os.environ.get("GRADIO_SERVER_PORT", str(DEFAULT_PORT)))),
+    )
+    parser.add_argument("--share", action="store_true")
+    args = parser.parse_args()
+
+    demo.launch(
+        server_name=args.host,
+        server_port=args.port,
+        share=args.share,
+    )

docs/plans/2026-03-25-hyshape-zerogpu-diagnostic.md

@@ -0,0 +1,85 @@
+# HyShape ZeroGPU Diagnostic App Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Add an alternate `app_hyshape.py` entrypoint that isolates the Hunyuan geometry path so ZeroGPU failures can be distinguished from NeAR and gsplat issues.
+
+**Architecture:** Build a standalone minimal Gradio app instead of importing the full `app.py` stack. Reuse the same lightweight image preprocessing behavior and lazy geometry loading pattern, but exclude SLaT generation, NeAR rendering, HDRI processing, and gsplat warmup. Add very early callback logging so Space logs show whether execution reached Python code before any failure.
+
+**Tech Stack:** Python 3.10, Gradio, `spaces.GPU`, Pillow, NumPy, PyTorch, `hy3dshape`
+
+---
+
+### Task 1: Create the standalone diagnostic entrypoint
+
+**Files:**
+- Create: `app_hyshape.py`
+- Check: `app.py`
+
+**Step 1: Define the minimal runtime surface**
+
+Describe a standalone app that only supports:
+- image upload and lightweight preprocessing
+- lazy Hunyuan geometry pipeline loading
+- mesh generation and export to a session cache
+- status logging focused on ZeroGPU callback entry and model load timing
+
+**Step 2: Keep imports and startup intentionally small**
+
+Ensure the new entrypoint:
+- does not import `NeARImageToRelightable3DPipeline`
+- does not reference HDRI, gsplat, or SLaT code paths
+- defers heavy geometry imports until the loader runs
+
+**Step 3: Add the minimal UI**
+
+Include:
+- one image input
+- one preprocess preview
+- one mesh viewer
+- one generate button
+- one clear-cache button
+- optional example image loading if example PNGs exist
+
+**Step 4: Add callback-entry diagnostics**
+
+Log, at minimum:
+- when the GPU callback is entered
+- whether CUDA is available at callback entry
+- geometry loader start/end timing
+- mesh generation total timing
+
+### Task 2: Add a regression architecture test
+
+**Files:**
+- Create: `tests/test_app_hyshape_architecture.py`
+
+**Step 1: Add static checks**
+
+Verify the diagnostic entrypoint:
+- only uses the geometry loader in `generate_mesh`
+- does not reference `ensure_near_pipeline`
+- does not reference `ensure_gsplat_ready`
+- contains the early callback-entry log marker
+
+**Step 2: Keep the test lightweight**
+
+Use AST or source-level assertions only so the test does not import heavy ML dependencies.
+
+### Task 3: Verify the diagnostic entrypoint locally
+
+**Files:**
+- Check: `app_hyshape.py`
+- Check: `tests/test_app_hyshape_architecture.py`
+
+**Step 1: Run the focused test**
+
+Run the architecture test file directly with Python's standard library test runner.
+
+**Step 2: Run lint diagnostics**
+
+Check the newly created files for obvious static-analysis regressions.
+
+**Step 3: Prepare the Space switch instruction**
+
+Record that Hugging Face Space can be pointed at the diagnostic app by changing `README.md` front matter from `app_file: app.py` to `app_file: app_hyshape.py`.

tests/test_app_hyshape_architecture.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+import ast
+import unittest
+from pathlib import Path
+
+
+APP_PATH = Path(__file__).resolve().parents[1] / "app_hyshape.py"
+
+
+def _load_tree() -> ast.Module:
+    return ast.parse(APP_PATH.read_text(encoding="utf-8"))
+
+
+def _get_function(tree: ast.Module, name: str) -> ast.FunctionDef:
+    for node in tree.body:
+        if isinstance(node, ast.FunctionDef) and node.name == name:
+            return node
+    raise AssertionError(f"Function {name!r} not found in app_hyshape.py")
+
+
+def _called_names(function_node: ast.FunctionDef) -> set[str]:
+    names: set[str] = set()
+    for node in ast.walk(function_node):
+        if isinstance(node, ast.Call):
+            if isinstance(node.func, ast.Name):
+                names.add(node.func.id)
+            elif isinstance(node.func, ast.Attribute):
+                names.add(node.func.attr)
+    return names
+
+
+class AppHyShapeArchitectureTests(unittest.TestCase):
+    def test_hyshape_app_does_not_reference_near_or_gsplat_paths(self) -> None:
+        source = APP_PATH.read_text(encoding="utf-8")
+
+        self.assertNotIn("NeARImageToRelightable3DPipeline", source)
+        self.assertNotIn("ensure_near_pipeline", source)
+        self.assertNotIn("ensure_gsplat_ready", source)
+
+    def test_generate_mesh_only_uses_geometry_loader(self) -> None:
+        generate_mesh = _get_function(_load_tree(), "generate_mesh")
+        called = _called_names(generate_mesh)
+
+        self.assertIn("ensure_geometry_pipeline", called)
+        self.assertNotIn("ensure_near_pipeline", called)
+        self.assertNotIn("ensure_gsplat_ready", called)
+
+    def test_generate_mesh_contains_early_callback_log_marker(self) -> None:
+        source = APP_PATH.read_text(encoding="utf-8")
+
+        self.assertIn("[HyShape] generate_mesh callback entered", source)
+
+
+if __name__ == "__main__":
+    unittest.main()