Eve library

TRELLIS.2 image-to-3D service

Other

Revision 1

On this page

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