# TRELLIS.2 image-to-3D service

The HTTP service that `OSHUN_TRELLIS_3D_URL` points at — the missing server for
the `trellis-provider.ts` client (a prior self-audit found the client had **no
in-repo implementation**, so the "open" 3D path resolved a client with nothing
answering it). This service does **not** re-implement TRELLIS: it wraps the
already-real CLI runner `libs/isis/3d-inference-local/src/models/
trellis2_image_to_3d_runner.py`, tracks async tasks, and serves the mesh.

## Contract (matched to `trellis-provider.ts`)

| Method | Path | Response |
|---|---|---|
| `POST` | `/generate` | `{ success, task_id, estimated_time }` |
| `GET` | `/task/{id}` | `{ data: { task_id, status, progress, stage?, output?, metrics?, error? } }` |
| `POST` | `/upload` (multipart `file`) | `{ image_token }` |
| `GET` | `/health` | `{ status, gpu_available, model_loaded, version }` |
| `GET` | `/files/{id}/{name}` | the rendered mesh bytes (what `mesh_url` points at) |

`status ∈ pending | processing | generating_sparse | generating_slat | complete | failed`.
The client polls `/task/{id}` until `complete` (with `output.mesh_url`) or `failed`.

## Honest limits

- **Image-to-3D only.** The wrapped runner is single-image; `mode:"text"` fails
  loud (422). `multi_image` uses the first view.
- **Geometry (obj/ply), not textured glb.** The runner emits geometry; the
  service maps the requested format onto obj/ply and only sets `output.texture_url`
  when the runner actually produces a texture — no fabricated PBR/textures.
- **GPU/weights are real probes.** `/health` reports `gpu_available` from
  `torch.cuda.is_available()` and `model_loaded` from the weights dir existing —
  never hard-coded.

## Build / run

```bash
# context = repo root (the runner is copied from libs/)
docker build -f docker/runpod/trellis3d/Dockerfile -t oshun/trellis3d:latest .
docker run --gpus all -p 8080:8080 -v /path/to/TRELLIS.2-4B:/models/trellis2 oshun/trellis3d:latest
# then: OSHUN_TRELLIS_3D_URL=http://<host>:8080
```

## Test

The HTTP layer is contract-tested with no GPU (inference injected; the real
runner-CLI construction is verified with `subprocess.Popen` monkeypatched):

```bash
cd docker/runpod/trellis3d
pip install -r requirements.txt pytest httpx
pytest test_server.py -q
```
