tribunal-kit 9.2.3 → 9.2.5

package/.agents/skills/huggingface-spaces/references/3d-generation.md

@@ -0,0 +1,98 @@
+# 3D generation Spaces
+
+Building a Space whose output is a 3D asset — image (occasionally text) in, downloadable and in-browser-viewable **mesh** (GLB/OBJ/PLY/STL) or **gaussian splat** (`.ply`/`.splat`) out. Read this whenever the user wants a Space/demo/playground for a 3D generation model, whether a stock checkpoint or their own finetuned variant. NeRF pipelines and world/scene models (HunyuanWorld, HY-World) are not covered.
+
+The standard workflow in `SKILL.md` applies (create → build → iterate → verify). This file is the 3D entry point; the sub-references below cover the 3D-specific deltas.
+
+## Sub-references
+
+| When to read | File |
+|---|---|
+| CUDA/C++ extension handling — prebuilt wheels, startup-compile tricks, the dominant failure mode | `[3d-cuda-extensions.md](3d-cuda-extensions.md)` |
+| Output formats (GLB/OBJ/PLY/STL, splats), viewers, orientation, preprocessing, temp-file patterns | `[3d-outputs.md](3d-outputs.md)` |
+| Model selection details and per-family recipes (TRELLIS, Hunyuan3D, TripoSR, SF3D, …) | `[3d-models.md](3d-models.md)` |
+| Gaussian-splat deliverables (TripoSplat, LGM) — pure-PyTorch splat decode | `[3d-gsplat.md](3d-gsplat.md)` |
+
+## What makes 3D Spaces different
+
+1. **Native extensions.** These models need CUDA/C++ extensions (nvdiffrast, rasterizers, marching cubes, texture bakers) that cannot compile at Space build time. Working Spaces use prebuilt wheels or startup-compile tricks — [`3d-cuda-extensions.md`](3d-cuda-extensions.md). Getting this wrong is the dominant failure mode.
+2. **Vendored model code.** None of the major 3D models are cleanly pip-installable; every official Space carries the model library as a source tree in the Space repo. There is no `diffusers`-style one-liner. (Don't trust PyPI lookalikes: `trellis-3d` ships the Python tree without the CUDA extensions or the real dependency set.)
+
+Both points make **"duplicate the official Space, then edit"** beat "assemble from scratch" here more than for any other model class.
+
+## Picking a model
+
+| Priority | Pick | Why | Reference |
+|---|---|---|---|
+| Best quality, PBR textures | **TRELLIS.2** | current quality bar; MIT; ≥24 GB (fits ZeroGPU large) | [`3d-models.md`](3d-models.md) |
+| Textured output, finetuning story | **Hunyuan3D-2.1** (2.0 for lighter/faster) | official training code → common finetune target; PBR paint stage; non-commercial license | [`3d-models.md`](3d-models.md) |
+| Speed / high-traffic / simplicity | **TripoSR** (untextured, MIT) or **SF3D** (textured, gated) | single forward pass, ~60s duration, tiny codebase | [`3d-models.md`](3d-models.md) |
+| Gaussians alongside mesh, multi-image input | **TRELLIS 1** | dual gaussian+mesh decoder; lighter than TRELLIS.2 | [`3d-models.md`](3d-models.md) |
+| Gaussian splats as the deliverable | **TripoSplat** (or LGM) | pure-PyTorch splat decode, no rasterizer needed; `gr.Model3D` renders splat `.ply` natively | [`3d-gsplat.md`](3d-gsplat.md) |
+
+**Check gating and license in Phase 0, not at first build.** `stabilityai/stable-fast-3d` and `stable-point-aware-3d` are gated (`gated: auto`) — the user must have accepted the license and the Space needs `HF_TOKEN` as a secret; verify access with `hf repos info` / `HfApi().model_info()` up front. `tencent/Hunyuan3D-*` is ungated but **non-commercial** — flag before the Space goes public. TRELLIS/TripoSR/TripoSplat/LGM are MIT. Apple SHARP is research-only (`apple-amlr`).
+
+If the model isn't covered by a reference file (Direct3D, TripoSG, Step1X-3D, a new release…), proceed by analogy with the user's agreement: find its official/most-liked *working* Space, fetch its actual files, and apply the same analysis — never guess a 3D dependency stack from memory.
+
+## Deployment path: duplicate vs build
+
+**Duplicate the official Space** (default for stock checkpoints, and for finetunes that are a `from_pretrained` swap — each reference file documents the swap):
+
+```python
+from huggingface_hub import HfApi
+api = HfApi()
+api.duplicate_repo("tencent/Hunyuan3D-2", to_id=f"{username}/my-hunyuan3d",
+                   repo_type="space", private=True, space_hardware="zero-a10g",
+                   space_secrets=[{"key": "HF_TOKEN", "value": hf_token}],  # only if a gated/private repo is involved
+                   exist_ok=True)
+```
+
+(`duplicate_space` is the deprecated older name.) Confirm the source Space is currently RUNNING first (`hf spaces info <id> --expand runtime`) — a paused/broken source means bitrot. Duplication copies *files only*; pass `space_hardware=`/`space_secrets=` explicitly. Then `hf download <repo> --repo-type space --local-dir .`, make the minimal edits (checkpoint repo-id, title/README, UI trims), and push back with `hf upload ... --repo-type space`. **Resist rewriting working extension-handling code you don't fully understand** — sitecustomize patches, `ctypes.CDLL` preloads, autotune caches, and `zero.startup()` calls all look redundant until removed.
+
+**Build from source** (custom UI, shape-only trims, no live official Space): start from the TripoSR skeleton (the ~200-line app documented in [`3d-models.md`](3d-models.md) — the cleanest template), vendor the model library tree from the official Space or GitHub, and follow [`3d-cuda-extensions.md`](3d-cuda-extensions.md). Budget more debugging iterations than an image-model Space.
+
+Either way, **fetch the official Space's live files first** (`https://huggingface.co/spaces/{id}/raw/main/{path}`) and treat them — not the reference files' pins — as source of truth. The reference files record what shipped as of mid-2026; the ZeroGPU runtime moves and official Spaces track it.
+
+## UI design
+
+Read [`3d-outputs.md`](3d-outputs.md) for formats, viewers, preprocessing, and temp-file patterns. Baseline image-to-3D UI:
+
+- **Input**: image upload → visible preprocessing preview (background removal + crop — show what the model actually receives) → generate.
+- **Controls**: only the knobs this model responds to. Seed + randomize always; then per family: sampler steps/guidance (TRELLIS, Hunyuan3D), marching-cubes resolution (TripoSR), remesh/vertex-count/texture-size (SF3D), decimation + texture size at extraction (TRELLIS.2). Don't surface every config field of a research codebase.
+- **Output**: `gr.Model3D` (untextured meshes, splats) or `LitModel3D` with HDR lighting (textured/PBR), plus `gr.DownloadButton`s for GLB and secondary formats. Two-stage models (TRELLIS) show a fast turntable preview before the slower GLB extraction.
+- **Examples**: 3–6 known-good images lifted from the official Space's assets, `cache_examples=True, cache_mode="lazy"`.
+
+## Verify: 3D-specific additions
+
+On top of the standard smoke test in `SKILL.md` §7:
+
+1. These apps expose **chained endpoints, not one `/predict`** — e.g. TripoSR: `/preprocess` (image → segmented image) then `/generate` (→ mesh files). `Client(...).view_api()` first, then call in sequence, feeding the first result into the second via `handle_file(...)`.
+2. **Validate the returned file, not its existence.** Meshes:
+
+   ```python
+   import trimesh
+   m = trimesh.load("out.glb", force="scene")
+   geoms = list(m.geometry.values()) if hasattr(m, "geometry") else [m]
+   assert geoms and sum(g.faces.shape[0] for g in geoms) > 0, "empty mesh"
+   ```
+
+   Gaussian splat `.ply` (no faces — check point count and splat attributes):
+
+   ```python
+   from plyfile import PlyData
+   v = PlyData.read("out.ply")["vertex"]
+   assert v.count > 1000, "suspiciously few gaussians"
+   assert {"f_dc_0", "opacity", "scale_0", "rot_0"} <= set(v.data.dtype.names), "not a gaussian ply"
+   ```
+
+3. **Look at it in the browser once.** Orientation (upright? facing forward?), texture presence, viewer lighting — the failure modes a programmatic check can't catch ([`3d-outputs.md`](3d-outputs.md) → Orientation).
+4. Startup-time extension compiles fail *silently* (app still boots, feature degrades) — grep the run log from the top even when everything looks green. Failure checklist: bottom of [`3d-cuda-extensions.md`](3d-cuda-extensions.md).
+
+## What to avoid
+
+- Assembling a TRELLIS/Hunyuan-class Space from scratch when a running official Space exists to duplicate.
+- Trusting reference-file version pins over the live official Space's files.
+- Compiling CUDA extensions via `requirements.txt` (no nvcc at build time), or `pip install`-ing PyPI lookalike packages for the model libraries.
+- Returning meshes/gaussians as in-memory objects from `@spaces.GPU` functions — write files, return paths.
+- Fixed output filenames (`output.glb`) — concurrent users clobber each other.
+- Declaring green after `RUNNING` + a returned file. Load the mesh, count faces/points, and look at it once.

package/.agents/skills/huggingface-spaces/references/3d-gsplat.md

@@ -0,0 +1,53 @@
+# Gaussian splatting reference
+
+Image-to-3D models whose output is a **gaussian splat** (a point cloud of oriented 3D gaussians) rather than a mesh. Deliverable file: gaussian `.ply` (the INRIA convention — the interchange format everything reads) and optionally `.splat` (antimatter15 32-byte records; smaller, no view-dependent color).
+
+| Model | Repo | License / gating | Official Space (working reference) |
+|---|---|---|---|
+| TripoSplat | `VAST-AI/TripoSplat` | **MIT, ungated** | `VAST-AI/TripoSplat` (ZeroGPU, running, Gradio 6) |
+| LGM | `ashawkey/LGM` (+ `dylanebert/LGM` diffusers port) | **MIT, ungated** | `dylanebert/LGM-mini` and `ashawkey/LGM` (ZeroGPU, running) |
+| Apple SHARP | `apple/Sharp` | **apple-amlr — research-only**, ungated | `notaneimu/ml-sharp-3d-viewer` (currently CPU; code is ZeroGPU-ready) |
+| Splatter Image | `szymanowiczs/splatter-image-v1` | MIT | `szymanowiczs/splatter_image` (ZeroGPU, running; old Gradio, minimal skeleton) |
+| Splatt3R (stereo pair → scene) | `brandonsmart/splatt3r_v1.0` | research code | `brandonsmart/splatt3r` (ZeroGPU, running) |
+
+TRELLIS 1 also exports gaussian `.ply` alongside its mesh — covered in `3d-models.md`.
+
+> **Verify against the live official Space before writing files.** Facts below are as of 2026-07.
+
+## The one decision that shapes everything: rasterize server-side or not?
+
+Rendering gaussians on the server needs a CUDA rasterizer (`diff-gaussian-rasterization` or `gsplat`). Prebuilt Blackwell (sm_120) wheel availability is narrow: the `multimodalart/zerogpu-blackwell-wheels` dataset (see [`requirements.md`](requirements.md)) ships `diff_gaussian_rasterization` with the **upstream Inria API only** (2-tuple return) — the ashawkey fork most LGM-family code imports (4-tuple with alpha+depth) has no wheel, and gsplat's own wheel index tops out at torch 2.4/cu124. Two viable shapes:
+
+**Shape A — no server-side rendering (default, strongly preferred).** The model decodes gaussians as plain PyTorch tensors; you write a `.ply` and let the *browser* render it. No CUDA extension at all — `requirements.txt` can be as small as `gradio, torch, torchvision, numpy, safetensors, pillow, tqdm` (TripoSplat's, in full). This is how every modern splat Space works (TripoSplat, SHARP, Splatt3R, Splatter Image; Splatt3R's requirements literally comment out the rasterizer dep).
+
+**Shape B — a real rasterizer (only for server-rendered orbit videos).** If the code uses the upstream Inria API, take the prebuilt wheel from `requirements.md`'s dataset and be done. `ashawkey/LGM` needs its fork, so its Space JIT-builds it — the GPU-worker bootstrap documented in `3d-cuda-extensions.md` Strategy 3: `@spaces.GPU(duration=600)` setup function at module import, `CUDA_HOME=/cuda-image/usr/local/cuda-13.0`, `TORCH_CUDA_ARCH_LIST="12.0"`, sitecustomize no-op of `_check_cuda_version`, `pip install --no-build-isolation --no-deps git+https://github.com/graphdeco-inria/diff-gaussian-rasterization.git`, then `ctypes.CDLL(".../libcudart.so.13", RTLD_GLOBAL)`. Copy it from `dylanebert/LGM-mini` verbatim. Don't take this on unless the user explicitly wants server-rendered video output.
+
+## Viewing splats
+
+- **`gr.Model3D` renders gaussian `.ply` and `.splat` natively** (Babylon.js; supported at least since Gradio 4.25, current in 6.x). Return the file path like any other output. `display_mode` is ignored for splats; `clear_color`, `camera_position`, `height` still apply. This is the zero-effort default — use it.
+- **Custom JS viewers** give better splat sorting and controls when the demo is the product: TripoSplat serves a Spark.js (`@sparkjsdev/spark`) viewer page in an iframe; ml-sharp vendors a static PlayCanvas SuperSplat build and serves it via `gr.set_static_paths(...)` + `gr.HTML` iframe with `/gradio_api/file=...` URLs. Only go here if `gr.Model3D`'s rendering visibly undersells the model.
+- Always add a `gr.DownloadButton` for the `.ply` — splat users take the file to their own viewer/engine.
+
+## Output writing
+
+Gaussian `.ply` (INRIA convention): binary little-endian, vertex props `x,y,z,nx,ny,nz,f_dc_0..2,(f_rest_*),opacity(logit),scale_0..2(log),rot_0..3(quat)`. Model codebases ship their own writer (`save_ply` in LGM/SHARP/TripoSplat) — use it; don't hand-roll unless porting.
+
+Optional `.splat` conversion for lighter downloads (~32 bytes/gaussian, drops view-dependent SH): TripoSplat's `triposplat.py::to_splat_bytes` is a complete pure-numpy reference — position f32×3, scale f32×3 (linear), RGBA u8×4 (`rgb = (f_dc·0.2820948 + 0.5)·255`, alpha = sigmoid(opacity)), quaternion u8×4 (`q·128+128`), records sorted by opacity×volume.
+
+Watch orientation here too: splat conventions differ from viewers' (TripoSplat applies `[[1,0,0],[0,0,-1],[0,1,0]]` on export). If the splat renders sideways in `gr.Model3D`, fix it at export, same as meshes.
+
+## ZeroGPU pickle discipline (bites harder here)
+
+Gaussian objects in these codebases are custom classes (often holding CUDA tensors or locks) — **they cannot cross the `@spaces.GPU` boundary**. Two proven patterns:
+
+- Do *everything* — preprocess, sample, decode, `.ply` write — inside one decorated function and return only path strings (TripoSplat, with an explicit comment to that effect).
+- Never decorate bound methods; wrap module-level functions (`spaces.GPU(duration=180)(predict_to_ply)` — ml-sharp, whose `ModelWrapper` holds a non-picklable `threading.RLock`).
+
+Durations: TripoSplat and LGM-mini run on the bare `@spaces.GPU` default 60s; SHARP uses 180. Splat decoding is fast — the multiview-diffusion stage (LGM) is what eats time.
+
+## Model-specific notes
+
+- **TripoSplat** — the current default pick: MIT, running official ZeroGPU Space, fp16 weights well within 48 GB, ~262k gaussians per generation, BiRefNet background removal built in. Caveat when duplicating: the official Space uses a fully custom Gradio 6 `gradio.Server` + `index.html` frontend, not `gr.Blocks` — its HTTP API is bespoke, so either keep it wholesale or rebuild a plain `gr.Blocks` + `gr.Model3D` UI around `TripoSplatPipeline` (the pipeline code is self-contained in `triposplat.py`/`model.py`). Weights download at startup via `hf download VAST-AI/TripoSplat --local-dir ckpts`.
+- **LGM** — image → 4 multiview images (ImageDream) → gaussians. `dylanebert/LGM-mini` is the clean diffusers-style duplicate target (both pipelines via `from_pretrained(..., trust_remote_code=True)`, output straight into `gr.Model3D`); `ashawkey/LGM` is the video-rendering variant (Shape B). Both carry an xformers→SDPA monkeypatch for Blackwell — keep it when duplicating (the `xformers 0.0.34` Blackwell wheel in `requirements.md`'s dataset makes the patch unnecessary if you modernize the requirements instead, but the patch is harmless).
+- **SHARP** — pip-installable (`sharp @ git+https://github.com/apple/ml-sharp.git@<sha>`), predicts a camera-space *scene* splat from one photo. Research-only license (`apple-amlr`) — tell the user before they build anything commercial. `preload_from_hub` in the frontmatter pre-bakes the checkpoint into the Space image.
+- **Splatter Image** — the minimal skeleton (~CVPR 2024, per-pixel gaussians, MIT): good template bones, but its Space pins Gradio 4.27 and a cu113 torch via `pre-requirements.txt` — modernize rather than copy pins.

package/.agents/skills/huggingface-spaces/references/3d-models.md

@@ -0,0 +1,227 @@
+# 3D models: TRELLIS / TRELLIS.2, TripoSR, Stable Fast 3D, SPAR3D, Hunyuan3D
+
+Per-family deployment recipes for mesh-generation models, distilled from the live files of their official Spaces. Gaussian splatting models live in [`3d-gsplat.md`](3d-gsplat.md); the overall workflow in [`3d-generation.md`](3d-generation.md).
+
+## TRELLIS family
+
+The TRELLIS family covers `microsoft/TRELLIS-image-large` (TRELLIS 1, ~1.2B) and `microsoft/TRELLIS.2-4B` (TRELLIS.2). Both are image-to-3D. Both are MIT licensed and ungated — no token needed to download weights.
+
+| Variant | Model repo | Output | VRAM | Official Space (working reference) |
+|---|---|---|---|---|
+| TRELLIS 1 | `microsoft/TRELLIS-image-large` (mirror: `JeffreyXiang/TRELLIS-image-large`) | Gaussians + mesh → textured GLB, gaussian `.ply` | ~16 GB | `trellis-community/TRELLIS` (ZeroGPU, running) |
+| TRELLIS.2 | `microsoft/TRELLIS.2-4B` | High-fidelity PBR-textured GLB | ≥24 GB | `microsoft/TRELLIS.2` (ZeroGPU, running) |
+
+There is no usable pip package (`trellis-3d` on PyPI ships only the pure-Python tree without the CUDA extensions or real dependency set; nothing exists for TRELLIS.2). **Both official Spaces vendor the library source (`trellis/` or `trellis2/`) directly in the Space repo.** Deploying means duplicating the official Space or copying its tree — not `pip install`.
+
+> **Verify against the live official Space before writing files.** Every pin below (torch/CUDA/Python versions, wheel URLs) reflects what the official Space shipped as of 2026-07 and tracks the ZeroGPU runtime, which changes. Fetch the current files first — `hf download <space-id> --repo-type space --local-dir .` or read `https://huggingface.co/spaces/<space-id>/raw/main/requirements.txt` — and treat those as source of truth.
+
+### TRELLIS.2 recipe (prebuilt-wheels strategy)
+
+The `microsoft/TRELLIS.2` Space compiles nothing: every CUDA extension is a prebuilt wheel whose tags match the ZeroGPU runtime exactly (`+torch2.11.0.cu130`, `cp312`, built for Blackwell sm_120). Its frontmatter pins `python_version: 3.12` and `sdk_version: 6.1.0`, and requirements.txt (as of 2026-07) is:
+
+```
+--extra-index-url https://download.pytorch.org/whl/cu130
+
+torch==2.11.0
+torchvision==0.26.0
+triton==3.6.0
+pillow==12.0.0
+imageio==2.37.2
+imageio-ffmpeg==0.6.0
+tqdm==4.67.1
+easydict==1.13
+opencv-python-headless==4.12.0.88
+trimesh==4.10.1
+transformers==4.57.3
+zstandard==0.25.0
+kornia==0.8.2
+timm==1.0.22
+git+https://github.com/EasternJournalist/utils3d.git@9a4eb15e4021b67b12c460c7057d642626897ec8
+https://github.com/adithyaxx/flash-attention/releases/download/v2.8.3/flash_attn-2.8.3+cu13torch2.11cxx11abiTRUE-cp312-cp312-linux_x86_64.whl
+https://github.com/LDYang694/Storages/releases/download/rtxpro6000/flex_gemm-1.0.0%2Btorch2.11.0.cu130-cp312-cp312-linux_x86_64.whl
+https://github.com/LDYang694/Storages/releases/download/rtxpro6000/nvdiffrast-0.4.0%2Btorch2.11.0.cu130-cp312-cp312-linux_x86_64.whl
+https://github.com/LDYang694/Storages/releases/download/rtxpro6000/nvdiffrec_render-0.0.0%2Btorch2.11.0.cu130-cp312-cp312-linux_x86_64.whl
+https://github.com/LDYang694/Storages/releases/download/rtxpro6000/cumesh-0.0.1%2Btorch2.11.0.cu130-cp312-cp312-linux_x86_64.whl
+https://github.com/LDYang694/Storages/releases/download/rtxpro6000/o_voxel-0.0.1%2Btorch2.11.0.cu130-cp312-cp312-linux_x86_64.whl
+```
+
+Wheel tags, torch pin, and `python_version:` must agree — see `3d-cuda-extensions.md` for the tag anatomy. TRELLIS.2 uses `flex_gemm` for sparse conv (no spconv).
+
+Module-level setup (order matters — env vars before any torch/trellis import):
+
+```python
+os.environ["PYTORCH_CUDA_ALLOC_CONF"] = "expandable_segments:True"
+os.environ["ATTN_BACKEND"] = "flash_attn"
+os.environ["FLEX_GEMM_AUTOTUNE_CACHE_PATH"] = os.path.join(..., "autotune_cache.json")
+
+pipeline = Trellis2ImageTo3DPipeline.from_pretrained("microsoft/TRELLIS.2-4B")
+pipeline.rembg_model = None   # official Space outsources rembg to briaai/BRIA-RMBG-2.0 via gradio_client
+pipeline.low_vram = False
+pipeline.cuda()
+```
+
+**Keep `autotune_cache.json` when duplicating.** The Space commits a pre-computed flex_gemm autotune cache so kernel autotuning doesn't re-run on every fresh ZeroGPU worker. Deleting it makes first-request latency much worse.
+
+GPU functions in the official Space: `@spaces.GPU(duration=120)` on generation (`pipeline.run(...)` with per-stage sampler params, `pipeline_type` of `512` / `1024_cascade` / `1536_cascade`) and `@spaces.GPU(duration=120)` on GLB extraction (`pipeline.decode_latent(...)` + `o_voxel.postprocess.to_glb(...)`). Generation and extraction are split into two GPU calls with latents passed between them as CPU numpy in `gr.State` — keep that split; it lets users re-extract at different decimation/texture sizes without regenerating.
+
+### TRELLIS 1 recipe (JIT-compile strategy)
+
+The `trellis-community/TRELLIS` Space demonstrates the other viable strategy: compile nvdiffrast + diff-gaussian-rasterization **at first boot on a GPU worker**, inside `@spaces.GPU(duration=600)`, using the nvcc that ZeroGPU mounts at runtime (`/cuda-image/usr/local/cuda-13.0`). Its requirements.txt (torch 2.8.0, `spconv-cu120==2.3.6`, `xformers`, `rembg`, no python_version pin → 3.10) installs everything that *can* come from PyPI; the JIT step handles the rest with:
+
+- `TORCH_CUDA_ARCH_LIST="12.0"` (Blackwell — nvcc can't probe a GPU that isn't attached yet)
+- a `sitecustomize.py` that no-ops `torch.utils.cpp_extension._check_cuda_version` (torch built for cu128, nvcc is 13.0)
+- `pip install --no-build-isolation ./extensions/nvdiffrast` (vendored source), then the mip-splatting `diff-gaussian-rasterization` from a shallow git clone
+- afterwards, `ctypes.CDLL("<cuda-libdir>/libcudart.so.13", mode=ctypes.RTLD_GLOBAL)` so the freshly built extensions find the CUDA 13 runtime
+
+Backend env vars, set at the very top of `app.py`: `SPCONV_ALGO=native`, `ATTN_BACKEND=xformers`. Because ZeroGPU is Blackwell, xformers must be forced onto Cutlass kernels (its Flash-Attn-3 dispatch crashes on sm_120) — the Space monkeypatches `xformers.ops.memory_efficient_attention` to default `op=(fmha.cutlass.FwOp, fmha.cutlass.BwOp)`. Don't drop that patch when duplicating.
+
+GPU functions: `@spaces.GPU(duration=120)` for generate-and-extract-GLB (single- and multi-image modes, 120-frame turntable preview video via `render_utils.render_video`, GLB via `postprocessing_utils.to_glb(gs, mesh, simplify=0.95, texture_size=1024)`); bare `@spaces.GPU` for gaussian `.ply` extraction. Viewer: `LitModel3D` from `gradio_litmodel3d==0.0.1` (installed at runtime with `--no-deps` if missing). The Space also sets `demo.launch(mcp_server=True)` — TRELLIS demos double as MCP servers; keep it.
+
+### Deploying a finetuned TRELLIS variant
+
+Both pipelines resolve everything from a `pipeline.json` at the model repo root, so a finetuned checkpoint that keeps the repo layout is a one-line swap:
+
+```python
+pipeline = TrellisImageTo3DPipeline.from_pretrained("user/my-finetuned-trellis")   # or Trellis2ImageTo3DPipeline
+```
+
+If the finetuned repo is private, pass the token via env (`HF_TOKEN` Space secret) — `from_pretrained` in the vendored trellis code goes through `huggingface_hub` and picks it up. If the user only has raw checkpoint files (no `pipeline.json`), copy `pipeline.json` + config layout from the base repo into their model repo first.
+
+### Picking between the two
+
+- **TRELLIS.2** — best quality, PBR materials, 3 resolution tiers; heavier (≥24 GB, fine on ZeroGPU large's 48 GB), Gradio 6, Python 3.12. Default choice for a new Space.
+- **TRELLIS 1** — lighter (~16 GB), dual gaussian+mesh output (the gaussian `.ply` path matters if the user wants splats), multi-image conditioning modes, and the community Space is a cleaner codebase to modify. Choose when the user wants gaussians, multi-image input, or minimal VRAM.
+
+### Durations and misc
+
+- Generation: `duration=120` is what both official Spaces use; TRELLIS.2 at 1536³ pushes ~60s of pure compute on H100-class hardware, so don't go below 120.
+- Call `torch.cuda.empty_cache()` at the end of each GPU function (both Spaces do) — sequential calls on a warm worker otherwise accumulate.
+- TRELLIS.2's mesh simplify cap: `mesh.simplify(16777216)` — nvdiffrast's face-count limit.
+- Preprocessing (alpha-bbox crop, resize to ≤1024, background removal) runs on CPU outside the GPU function.
+
+## Mesh workhorses: TripoSR, Stable Fast 3D, SPAR3D, Hunyuan3D
+
+Two groups in this file. The **fast tier** (TripoSR, SF3D, SPAR3D): single-forward-pass image-to-mesh, seconds per generation, small VRAM, simple codebases — pick when the user wants a snappy demo, a high-traffic public Space (short `@spaces.GPU` durations = less quota per click and better queue priority), or can accept lower fidelity than TRELLIS.2. And **Hunyuan3D-2/2.1** (Tencent): two-stage — a flow-matching DiT generates the shape, then an optional multiview-diffusion "Paint" stage textures it — pick when the user wants textured output and TRELLIS.2 doesn't fit, or when they finetuned a Hunyuan3D DiT (the 2.1 release includes official training code, so finetuned shape checkpoints are common).
+
+| Model | Repo | Output | License / gating | Official Space |
+|---|---|---|---|---|
+| TripoSR | `stabilityai/TripoSR` | untextured mesh (OBJ + GLB) | **MIT, ungated** | `stabilityai/TripoSR` (ZeroGPU, running) |
+| Stable Fast 3D (SF3D) | `stabilityai/stable-fast-3d` | UV-unwrapped **textured** GLB | stabilityai-ai-community, **gated (auto)** | `stabilityai/stable-fast-3d` (ZeroGPU, running) |
+| SPAR3D | `stabilityai/stable-point-aware-3d` | textured GLB + editable point cloud | stabilityai-ai-community, **gated (auto)** | `stabilityai/stable-point-aware-3d` (dedicated L4, **currently BUILD_ERROR** — reference code only) |
+| Hunyuan3D-2.0 | `tencent/Hunyuan3D-2` (subfolder `hunyuan3d-dit-v2-0`; also `-mini`, `-mv`) | GLB, RGB-textured (Paint 2.0) | tencent-hunyuan-community, **ungated, non-commercial** | `tencent/Hunyuan3D-2` (ZeroGPU, running) |
+| Hunyuan3D-2.1 | `tencent/Hunyuan3D-2.1` (subfolder `hunyuan3d-dit-v2-1`) | GLB, **PBR**-textured (Paint 2.1) | tencent-hunyuan-community, **ungated, non-commercial** | `tencent/Hunyuan3D-2.1` (ZeroGPU, **paused** — code is still the reference) |
+
+**Licenses and gating matter here.** The two Stability models are `gated: auto` — the deploying user must accept the license on the model page, and the Space needs their `HF_TOKEN` as a secret to download weights at startup; if the gate isn't accepted, `from_pretrained` fails with 401 at build — check before publishing. The Hunyuan models are ungated (no token needed) but the community license restricts commercial use — surface that before the user flips a Space public. TripoSR is MIT and needs nothing.
+
+> **Verify against the live official Space before writing files.** Pins below are as of 2026-07. Fetch current files via `https://huggingface.co/spaces/<id>/raw/main/<path>` first.
+
+### TripoSR — the minimal recipe (~200-line app)
+
+The simplest working 3D Space on the Hub, and the best starting skeleton for a from-scratch mesh demo. `tsr/` package vendored in the Space; frontmatter pins `python_version: 3.10.13`, `sdk_version: 4.20.1`.
+
+One CUDA extension, JIT-built at module import (marching cubes):
+
+```python
+subprocess.run(
+    shlex.split("pip install --no-build-isolation git+https://github.com/tatsy/torchmcubes.git"),
+    env={**os.environ, "TORCH_CUDA_ARCH_LIST": "12.0+PTX"},   # no GPU visible at startup — force Blackwell arch
+    check=True,
+)
+```
+
+requirements.txt carries the build toolchain for it (`scikit-build-core>=0.10`, `pybind11>=2.10`, `cmake`, `ninja`) plus `rembg`, `onnxruntime`, `trimesh`, `omegaconf`, `einops`, `transformers`, `Pillow`, `huggingface-hub`. No torch pin (base image). (A prebuilt `torchmcubes` Blackwell wheel now exists in the dataset described in [`requirements.md`](requirements.md) — cleaner than the JIT build when building fresh.)
+
+```python
+model = TSR.from_pretrained("stabilityai/TripoSR", config_name="config.yaml", weight_name="model.ckpt")
+model.renderer.set_chunk_size(131072)
+model.to(device)
+
+@spaces.GPU  # default 60s is plenty — the forward pass is ~1s
+def generate(image, mc_resolution):
+    scene_codes = model(image, device)
+    mesh = model.extract_mesh(scene_codes, resolution=mc_resolution)[0]
+    mesh = to_gradio_3d_orientation(mesh)   # axis fix — see 3d-outputs.md
+    ...  # export OBJ + GLB to NamedTemporaryFiles, return both paths
+```
+
+Preprocessing on CPU, outside the GPU function: `rembg` background removal → `resize_foreground(image, 0.85)` → composite onto gray. UI: input image + "marching cubes resolution" slider (32–320) + two `gr.Model3D` tabs (OBJ and GLB).
+
+### Stable Fast 3D — textured output, source-built extensions
+
+`sf3d/` vendored; frontmatter `python_version: 3.10.13`, `sdk_version: 4.41.0`. Two vendored extension source dirs built at module import (they're commented out in requirements.txt with a note — the "HF hack"):
+
+```python
+os.system(
+    'CPPFLAGS="-include utility" TORCH_CUDA_ARCH_LIST="12.0+PTX" USE_CUDA=1 '
+    "pip install -vv --no-build-isolation ./texture_baker ./uv_unwrapper"
+)
+```
+
+`texture_baker` is a torch CUDAExtension (the `CPPFLAGS="-include utility"` is required for its build), `uv_unwrapper` a plain C++ extension. Other deps of note: `open_clip_torch`, `rembg[gpu]`, `pynanoinstantmeshes` + `gpytoolbox` (remeshing), `gradio-litmodel3d==0.0.1`.
+
+```python
+model = SF3D.from_pretrained("stabilityai/stable-fast-3d",
+                             config_name="config.yaml", weight_name="model.safetensors")
+model.eval().to(device)   # gated repo — needs HF_TOKEN secret with accepted license
+
+@spaces.GPU  # default 60s
+def run(input_image, remesh_option, vertex_count, texture_size):
+    with torch.autocast(device_type=device, dtype=torch.bfloat16):
+        model_batch = create_batch(input_image)
+        ...
+    trimesh_mesh.export(tmp.name, file_type="glb", include_normals=True)
+```
+
+UI controls that earn their place: foreground ratio, remesh (None/Triangle/Quad), target vertex count, texture size (512–2048). Viewer: `LitModel3D` with selectable HDR environment maps — textured output deserves image-based lighting (see [`3d-outputs.md`](3d-outputs.md)).
+
+### SPAR3D — reference code only, don't duplicate blindly
+
+Two-stage: point-cloud diffusion → mesh, with a `gradio_pointcloudeditor` step so users can edit the intermediate point cloud before meshing. Distinctive UI idea worth stealing. But the official Space runs on **dedicated L4, not ZeroGPU** (no `import spaces`, torch pinned to 2.5.1, real nvcc assumed) and is currently in BUILD_ERROR. To deploy SPAR3D on ZeroGPU you'd port it: add `spaces`, drop the torch pin, apply the SF3D extension-build pattern (same vendored `texture_baker`/`uv_unwrapper` + a prebuilt `pynim` wheel), and decorate the two stages. Budget real debugging time; propose SF3D instead unless the user specifically needs the point-cloud editing stage. Its background removal uses `transparent-background` (InSPyReNet) rather than rembg.
+
+### Hunyuan3D-2 / 2.1 — textured two-stage generation
+
+Both official Spaces vendor the model code in the Space repo (`hy3dgen/` for 2.0; `hy3dshape/` + `hy3dpaint/` for 2.1) — there's a `setup.py` but nothing is pip-installed; imports resolve from cwd. Two native extensions are handled at module-import time in `gradio_app.py`:
+
+```python
+# custom_rasterizer: prebuilt CUDA wheel committed to the Space repo (no nvcc at build time)
+subprocess.run(shlex.split("pip install custom_rasterizer-0.1-cp310-cp310-linux_x86_64.whl"), check=True)
+# mesh painter: CPU-only pybind11 extension, compiled with plain g++ in seconds
+os.system("cd /home/user/app/hy3dpaint/DifferentiableRenderer && bash compile_mesh_painter.sh")
+```
+
+The cp310 wheel means Python 3.10 — pin `python_version: "3.10"` explicitly when duplicating so a runtime default bump can't break it.
+
+**Requirements notes (2.1)** — fully pinned; the non-obvious entries: `--extra-index-url https://download.blender.org/pypi/` + `bpy==4.0` (Blender-as-pip; installs headless with no display setup — see [`3d-outputs.md`](3d-outputs.md) → Headless Blender — though the Space's OBJ→GLB conversion actually runs on trimesh+pygltflib); `realesrgan==0.3.0` + `basicsr==1.4.2` (texture upscaling — needs the Space's `torchvision_fix.py` shim, applied at the top of `gradio_app.py` *and* again before the texgen import, because basicsr imports the removed `torchvision.transforms.functional_tensor`); `cupy-cuda12x`, `pymeshlab`, `xatlas`, `open3d`, `trimesh`, `pygltflib` (mesh stack); **no torch pin**; `pydantic==2.10.6` (gradio compat).
+
+**Model loading** (module level):
+
+```python
+from hy3dshape.pipelines import Hunyuan3DDiTFlowMatchingPipeline   # hy3dgen.shapegen on 2.0
+shape_pipe = Hunyuan3DDiTFlowMatchingPipeline.from_pretrained(
+    "tencent/Hunyuan3D-2.1", subfolder="hunyuan3d-dit-v2-1", use_safetensors=False,
+)  # 2.0: repo "tencent/Hunyuan3D-2", subfolder "hunyuan3d-dit-v2-0", use_safetensors=True, + .enable_flashvdm()
+
+# Texture stage — wrap in try/except and degrade to shape-only if it fails (official HAS_TEXTUREGEN pattern)
+from hy3dpaint.textureGenPipeline import Hunyuan3DPaintPipeline, Hunyuan3DPaintConfig
+paint_pipe = Hunyuan3DPaintPipeline(Hunyuan3DPaintConfig(max_num_view=8, resolution=768))
+```
+
+**GPU decorators**: `@spaces.GPU(duration=40–60)` shape-only; `@spaces.GPU(duration=90)` (2.0) / `@spaces.GPU(duration=180)` (2.1 PBR) shape+texture. VRAM (2.1, per its README): ~10 GB shape, ~21 GB texture, ~29 GB both — fits ZeroGPU large, but the full PBR path is the heaviest recipe in these references; don't shave the duration.
+
+**Output path gotcha (2.1)**: textured meshes export as **OBJ first, then convert to GLB** via the Space's `convert_utils` (obj2gltf with PBR materials) — direct GLB export from the paint pipeline core-dumps. Keep the conversion step when duplicating.
+
+**Serving quirk**: both official Spaces use a custom `<model-viewer>` HTML iframe + FastAPI `StaticFiles` + `gr.mount_gradio_app` + manual `uvicorn.run` instead of `demo.launch()` — which requires calling `from spaces import zero; zero.startup()` manually before uvicorn. **When building fresh rather than duplicating, skip all of this** — export a GLB, show it in `gr.Model3D`/`LitModel3D`, and let `demo.launch()` do its job. Only keep the iframe machinery when duplicating wholesale.
+
+**Local-run pattern worth copying**: 2.1's `gradio_app.py` defines a no-op `spaces.GPU` decorator when not running on Spaces (`ENV != "Huggingface"`), so the same file runs on a local GPU box unchanged.
+
+**Deploying a finetuned Hunyuan3D variant** — the official 2.1 release ships training code (`hy3dshape/` includes trainers and configs), so "I finetuned Hunyuan3D, make me a demo" is a real request. The shape pipeline resolves `subfolder` inside the model repo:
+
+```python
+shape_pipe = Hunyuan3DDiTFlowMatchingPipeline.from_pretrained(
+    "user/my-finetuned-hunyuan3d", subfolder="hunyuan3d-dit-v2-1",
+)
+```
+
+If the user's repo keeps the official layout (config + checkpoint under the dit subfolder), it's a repo-id swap; if they saved a bare checkpoint, mirror the base repo's subfolder structure into their repo first. Finetunes are almost always **shape-only** — keep the stock Paint stage from the base repo for texturing (it conditions on the input image, not the shape checkpoint). Private repo → `HF_TOKEN` Space secret.
+
+**Which Hunyuan variant**: **2.1** — PBR texturing, the one with official training code, the default for finetunes, heaviest. **2.0** — lighter, faster (flashvdm), RGB textures, official Space actually running today (known-good duplicate target); `-mini` and `-mv` (multiview-conditioned) subfolder variants live in the same repo. **Shape-only demo** (skip Paint entirely) — halves the dependency surface (no bpy/realesrgan/basicsr/cupy) and cuts duration to 40–60s; offer it when the user just wants geometry.

package/.agents/skills/huggingface-spaces/references/3d-outputs.md

@@ -0,0 +1,114 @@
+# Mesh outputs: formats, viewers, preprocessing
+
+## Formats
+
+**GLB is the default output format.** It's self-contained (geometry + materials + textures in one binary file), renders in every in-browser viewer, and is what all the major official 3D Spaces produce. Offer OBJ/PLY/STL as secondary downloads, not as the primary view.
+
+| Format | Carries | When to offer |
+|---|---|---|
+| GLB | geometry + normals + UVs + PBR materials + embedded textures | always — primary output |
+| OBJ (+MTL) | geometry, UVs; textures via sidecar files | DCC-tool users; note multi-file awkwardness in a web download |
+| PLY | geometry, vertex colors; also the container for gaussian splats (see `3d-gsplat.md`) | point clouds, vertex-colored meshes, splats |
+| STL | bare geometry | 3D-printing crowd |
+
+Conversion is trimesh one-liners — the Hunyuan3D Spaces expose exactly this as an "export" accordion:
+
+```python
+mesh = trimesh.load("out.glb")
+mesh.export("out.obj")   # or .ply / .stl — inferred from extension
+```
+
+Two exceptions to "just use trimesh":
+
+- **PBR materials**: trimesh's GLB export handles baseColor fine but degrades full PBR (metallic/roughness/normal maps). Hunyuan3D-2.1 exports OBJ then converts with obj2gltf specifically because its direct GLB export core-dumps — when a pipeline ships its own exporter (`to_glb`, `convert_utils`, `o_voxel.postprocess`), use it instead of round-tripping through trimesh.
+- **Normals**: pass `include_normals=True` on trimesh GLB exports (SF3D does) — missing normals render matte-black in some viewers.
+
+## Orientation
+
+The #1 "it works but looks wrong" bug. Model output conventions (often Z-up, or −Y-forward from the training renders) don't match the viewers' glTF convention (Y-up, +Z toward camera), so meshes come out lying face-down or backwards. TripoSR's fix:
+
+```python
+def to_gradio_3d_orientation(mesh):
+    mesh.apply_transform(trimesh.transformations.rotation_matrix(-np.pi/2, [1, 0, 0]))  # Z-up → Y-up
+    mesh.apply_transform(trimesh.transformations.rotation_matrix( np.pi/2, [0, 1, 0]))
+    return mesh
+```
+
+The exact rotation is per-model — copy it from the official Space's app (search for `rotation_matrix` or `apply_transform`). If output is mirrored, the model bakes a flipped X; TripoSR's OBJ export flips `mesh.vertices[:, 0]` back. Verify orientation visually during the smoke-test; it can't be caught from exit codes.
+
+## Viewers
+
+- **`gr.Model3D`** — built-in, zero extra deps, fine for untextured or baseColor meshes; also renders gaussian splat `.ply`/`.splat` natively (see `3d-gsplat.md`). Useful kwargs: `display_mode="solid"` (default point cloud rendering ruins meshes in some versions; ignored for splats), `clear_color=(0.25, 0.25, 0.25, 1.0)`, `height=...`. Default choice.
+- **`LitModel3D`** (`gradio_litmodel3d==0.0.1`, a Hub custom component) — adds image-based lighting with HDR environment maps. Worth the extra dep for **textured/PBR** output, where flat lighting hides the texture quality (SF3D and trellis-community both use it, SF3D with a selectable `.hdr` set). Textured model + plain `gr.Model3D` undersells the result.
+- **Custom `<model-viewer>` iframe + FastAPI static mount** — what the Hunyuan Spaces do. Maximum control, but requires abandoning `demo.launch()` for manual uvicorn plus a manual `spaces.zero.startup()` call. Don't build this fresh; only keep it when duplicating a Space that already has it.
+- **Turntable preview** — TRELLIS renders a 120-frame orbit video (`imageio.mimsave`, fps=15) shown in `gr.Video` *before* the user commits to GLB extraction; TRELLIS.2 uses a base64-JPEG JS orbiter. Good pattern when extraction is a separate, slower step; skip it for fast-tier models where the mesh is ready immediately.
+
+Always pair the viewer with `gr.DownloadButton` for the raw file — the viewer is a preview, the file is the deliverable.
+
+## Input preprocessing (image-to-3D)
+
+Every image-to-3D model expects a **segmented foreground object**, roughly centered, on neutral/transparent background. The shared recipe, run on CPU *outside* the GPU function:
+
+1. **Respect an existing alpha channel.** If the upload is RGBA with a real alpha, skip segmentation (TRELLIS checks this first).
+2. **Otherwise remove the background** — `rembg` (u2net, onnxruntime; the common choice), `transparent-background` (InSPyReNet; SPAR3D), or BiRefNet. TRELLIS.2 outsources to the `briaai/BRIA-RMBG-2.0` Space via `gradio_client` — fine for an official Space, but a fragile external dependency for a user Space; prefer local rembg.
+3. **Crop to the alpha bbox, resize** (≤1024 for TRELLIS-class, 512 for fast tier), **rescale the foreground** to ~85% of frame (`foreground_ratio` slider in the Stability Spaces), composite onto neutral gray or keep alpha.
+
+Show the preprocessed image in the UI before generation — users need to see what the model actually gets, and a bad segmentation explains a bad mesh. Loading the rembg session at startup (TRELLIS runs one dummy `preprocess_image` at boot) avoids a first-click latency spike.
+
+## Temp files and concurrency
+
+Handlers run concurrently; never write to fixed paths. The pattern used by the official Spaces:
+
+```python
+demo = gr.Blocks(delete_cache=(600, 600))   # sweep files older than 600s every 600s
+
+@demo.load(outputs=...)
+def start_session(req: gr.Request):
+    session_dir = os.path.join(TMP_ROOT, str(req.session_hash))
+    os.makedirs(session_dir, exist_ok=True)
+```
+
+or simply `tempfile.NamedTemporaryFile(suffix=".glb", delete=False)` per call (TripoSR/SF3D). Either works; never a bare `"output.glb"`.
+
+## Headless Blender (bpy / renders)
+
+Blender shows up in 3D Spaces two ways: as the **`bpy` pip module** (`--extra-index-url https://download.blender.org/pypi/` + `bpy==<pin>`; Hunyuan3D-2.1 pins `bpy==4.0` — which installs cleanly on ZeroGPU with no display setup, though that Space's actual GLB conversion runs on trimesh+pygltflib), or as a **standalone binary** driven by a render script (TRELLIS-dataset-toolkit-style turntables, rigging/preprocessing tools). Spaces containers have no display; the working patterns, all verified from running Spaces:
+
+- **pip `bpy` needs no xvfb.** Mesh ops, Cycles, and Workbench renders work headless — bpy creates its GL context via EGL/Mesa, not X11. The `packages.txt` seen in every working bpy demo Space (e.g. `radames/gradio-blender-bpy`) is just:
+
+  ```
+  libegl1-mesa-dev
+  libgl1-mesa-dev
+  ```
+
+  ZeroGPU gotcha: **`import bpy` takes 30–60 s** — never import it inside a `@spaces.GPU` function (it burns the duration budget and aborts the task). Import at module scope, or run a persistent bpy worker in the main process (`VAST-AI/SkinTokens` does file-based IPC to one).
+- **A modern Blender binary (≥3.4) needs no xvfb either**: download the tarball at startup, run `blender -b -noaudio --python script.py -- <args>` as a subprocess (`MajorDaniel/UniRig` on ZeroGPU). `packages.txt` then carries the binary's shared-lib deps: `libx11-6 libxi6 libxrender1 libxxf86vm1 libfontconfig1 libsm6 libxkbcommon0 libxkbcommon-x11-0 libgl1-mesa-glx`. Blender's manual is explicit that CLI/background rendering needs no display; a GPU Cycles subprocess must be launched from **inside** `@spaces.GPU` (it inherits the worker's CUDA), while display/env setup is process-global and belongs at module scope.
+- **Reach for Xvfb only when forced**: a pinned pre-3.4 Blender binary (no EGL headless support yet), EEVEE on legacy setups, or non-Blender GL stacks (Open3D/VTK offscreen, pyglet). On the **gradio SDK**, don't launch raw `Xvfb :99 &` — the container lacks the `/tmp/.X11-unix` permissions for it (UniRig documents this) — use `pyvirtualdisplay` at module scope, the pattern `gradient-spaces/GuideFlow3D` uses to render Cycles through Blender 3.0.1 headlessly. `packages.txt`:
+
+  ```
+  xvfb
+  libx11-6
+  libgl1
+  libxrender1
+  libxi6
+  libxkbcommon-x11-0
+  libsm6
+  ```
+
+  and at the very top of `app.py`, before anything touches Blender/GL (plus `pyvirtualdisplay` in requirements.txt):
+
+  ```python
+  if os.environ.get("DISPLAY") is None:
+      from pyvirtualdisplay import Display   # drives Xvfb with user-owned sockets
+      display = Display(visible=0, size=(1920, 1080))
+      display.start()
+      os.environ.setdefault("DISPLAY", f":{display.display}")
+  ```
+
+  On the **Docker SDK** you control the image: `xvfb-run -a -s '-screen 0 1024x768x24' <cmd>` (or `Xvfb :99 ... & export DISPLAY=:99`), adding Mesa software-GL env on CPU hardware (`LIBGL_ALWAYS_SOFTWARE=1`, `GALLIUM_DRIVER=llvm`).
+- **Keep Space renders on Cycles.** EEVEE is GPU-rasterization by design (no CPU path — headless EEVEE exists on Linux ≥3.4 via EGL, but under Xvfb/software-GL it crawls); Cycles renders fine on CPU or on CUDA inside `@spaces.GPU`.
+- **pyrender** (not Blender, but the same "needs GL" problem): use EGL, not Xvfb — `os.environ["PYOPENGL_PLATFORM"] = "egl"` with `libgl1-mesa-dev libglu1-mesa-dev freeglut3-dev mesa-common-dev` in packages.txt (`H-Liu1997/EMAGE` on ZeroGPU).
+
+## Examples
+
+`gr.Examples` with a handful of good input images makes or breaks first impressions of a 3D demo. Source them from the official Space's `assets/`/`examples/` dir (they're chosen to work well) or the model repo. On ZeroGPU use `cache_examples=True, cache_mode="lazy"`. Objects that demo well: single centered objects with clear silhouettes — figurines, shoes, furniture, vehicles. Objects that demo poorly: scenes, flat images, humans (most mesh models aren't trained for them), thin structures.

package/.agents/skills/huggingface-spaces/references/buckets.md

@@ -0,0 +1,89 @@
+# Persistent storage with Buckets
+
+Spaces are stateless. All data is wiped on restart / rebuild. For state that must survive (user uploads, generations, dynamic feeds, logs, growing databases): mount an HF **Bucket** — S3-like object storage living at `hf://buckets/<ns>/<bucket>`.
+
+Buckets are paid (per-TB storage). Check `whoami.canPay` and confirm with the user before creating one. Pricing + free tier: https://huggingface.co/storage.
+
+Full docs: https://huggingface.co/docs/hub/storage-buckets.
+
+## Create + attach
+
+```bash
+hf buckets create <ns>/<bucket-name>                                # --private optional
+hf spaces volumes set <ns>/<space> -v hf://buckets/<ns>/<bucket-name>:/data
+```
+
+After this, writes to `/data/` in the Space are durable. Reads come from the bucket via the Xet storage backend.
+
+To make the bucket files publicly addressable: leave the bucket public. Public bucket files are served at `https://huggingface.co/buckets/<ns>/<bucket>/resolve/<path>` (HTTP 302 redirect to a signed CDN URL). The Space writes once and the public URL works forever — no streaming proxy needed.
+
+## Write-durable, read-fast pattern
+
+For a feed-style Space (e.g. a community jam where users save generations and browse a public timeline), don't re-scan disk on every request. Module-level disk scan → in-memory list → every write appends to both:
+
+```python
+import os, json, uuid
+from datetime import datetime, timezone
+
+BUCKET_ID = "<ns>/<bucket-name>"
+BUCKET_URL = f"https://huggingface.co/buckets/{BUCKET_ID}/resolve"
+_feed = []
+
+def _load_feed():
+    root = "/data/songs"
+    if not os.path.isdir(root):
+        return
+    for sid in os.listdir(root):
+        meta = f"{root}/{sid}/meta.json"
+        if os.path.isfile(meta):
+            _feed.append(json.load(open(meta)))
+    _feed.sort(key=lambda s: s["created_at"], reverse=True)
+
+_load_feed()                                       # one scan at startup
+
+@app.api(name="save", time_limit=60)
+def save(audio_bytes: bytes, title: str):
+    sid = uuid.uuid4().hex[:12]
+    d = f"/data/songs/{sid}"; os.makedirs(d, exist_ok=True)
+    open(f"{d}/audio.wav", "wb").write(audio_bytes)
+    meta = {"id": sid, "title": title,
+            "url": f"{BUCKET_URL}/songs/{sid}/audio.wav",
+            "created_at": datetime.now(timezone.utc).isoformat()}
+    json.dump(meta, open(f"{d}/meta.json", "w"))
+    _feed.insert(0, meta)                          # cache stays current — no re-scan
+    return meta
+
+@app.api(name="feed", concurrency_limit=10)
+def feed(): return _feed[:50]                      # zero disk I/O
+```
+
+Reference Space using this pattern: https://huggingface.co/spaces/victor/ace-step-jam
+
+## Anti-pattern: bucket as model-weights cache
+
+**Do NOT** `snapshot_download(..., local_dir="/data/weights")` and load checkpoints from there. Bucket I/O is S3-paced; reading a 22 GB `safetensors` from `/data` during `from_pretrained` stalls past any `@spaces.GPU` duration cap.
+
+For model weights, let HF Hub re-download to local container disk on each cold start. With `HF_HUB_ENABLE_HF_TRANSFER=1` (set in the runtime by default) this is fast — typically much faster than streaming the same bytes through bucket I/O at request time.
+
+Bucket I/O is fine for occasional metadata reads (the feed pattern above) or saving user information. It is *not* fine as the path your model loader streams gigabytes through every cold start.
+
+## Cache redirects
+
+`/home/user/.cache` is read-only on ZeroGPU. Redirect transient caches at the top of `app.py`, before any library import that uses them:
+
+```python
+import os
+os.environ.setdefault("HF_HOME", "/data/.cache/huggingface")   # or /tmp on non-bucket Spaces
+os.environ.setdefault("HF_MODULES_CACHE", "/tmp/hf_modules")
+os.environ.setdefault("MPLCONFIGDIR", "/tmp/matplotlib")
+```
+
+Missing redirections fail silently or at first matplotlib / transformers / diffusers import.
+
+## Write access from the Space
+
+The Space's `HF_TOKEN` secret needs write permission on the bucket. Set via Settings → Secrets in the Space UI, or `hf spaces secrets set <id> HF_TOKEN=<token>`.
+
+## Security note
+
+Public bucket files are publicly accessible forever at their resolve URL. **Don't write PII** to a public bucket. If you need durable but private storage (e.g. per-user history requiring an HF login), keep the bucket private and gate reads through your Space's own auth.