Spaces:
Running
Running
| title: projtex · Projection Texturing API | |
| emoji: 🎨 | |
| colorFrom: green | |
| colorTo: yellow | |
| sdk: docker | |
| app_port: 7860 | |
| pinned: false | |
| license: mit | |
| short_description: Agent-first API to texture 3D meshes with Qwen-Image / Fibo | |
| models: | |
| - Qwen/Qwen-Image-2.1-Turbo | |
| - Qwen/Qwen-Image-2.1 | |
| - briaai/Fibo-2.0-edit-turbo | |
| tags: | |
| - 3d | |
| - texturing | |
| - mcp-server | |
| - agents | |
| - image-editing | |
| # projtex: projection texturing API (agent-first) | |
| Send a 3D mesh and a prompt; get back the mesh with a baked colour texture (GLB). The service: | |
| 1. generates images from virtual cameras, each conditioned on what is already painted; | |
| 2. checks every image against the geometry; | |
| 3. projects the images onto the mesh and blends them in texture space; | |
| 4. bakes the result into the mesh's UVs. | |
| Three image models are available, through Hugging Face Spaces: | |
| - **Qwen-Image-2.1-Turbo** (8 steps) via [hugging-apps/qwen-qwen-image-2-1-turbo](https://huggingface.co/spaces/hugging-apps/qwen-qwen-image-2-1-turbo) (default: fastest, least GPU quota); | |
| - **Qwen-Image-2.1** (full model, 40 steps) via the official [Qwen/Qwen-Image-2.1](https://huggingface.co/spaces/Qwen/Qwen-Image-2.1) (`"backend": "qwen-space"`); | |
| - **Bria Fibo 2.0 Edit Turbo** via [briaai/Fibo-2.0-editing](https://huggingface.co/spaces/briaai/Fibo-2.0-editing) (`"backend": "fibo-space"`). | |
| Designed for agents: | |
| * **Asynchronous jobs.** `POST /api/jobs` returns at once. Poll `GET /api/jobs/{id}`; every status includes | |
| `progress`, quality `summary`, file URLs and a `next` list of concrete follow-up calls. | |
| * **Three equivalent interfaces:** | |
| * REST with OpenAPI at [`/docs`](/docs); | |
| * remote **MCP** (streamable HTTP) at `/mcp`; | |
| * an agent guide at [`/llms.txt`](/llms.txt). | |
| * **Inputs agents can produce:** a local file uploaded as raw bytes (`POST /api/uploads` -> `upload_id`, then a | |
| plain JSON job), `mesh_base64`, a public `mesh_url`, or a built-in `sample`. GLB from Blender or three.js | |
| (`GLTFExporter`), glTF with embedded data, OBJ, PLY, STL or a zip. | |
| * **Outputs that drop back into your scene:** the GLB keeps your objects (names, transforms), materials (names, | |
| metallic/roughness/alpha) and orientation; every material's base colour uses one baked texture. When your UVs | |
| are kept, the albedo PNG also fits your original model. Inside-out surfaces are detected and flipped. | |
| * **Honest progress and quality:** queue position and ETA while waiting; a `verdict` (good / usable / needs work) | |
| with coverage measured over what cameras can see (the underside is reported apart). | |
| * **A quality loop as API calls:** regenerate views, disable views, fill gaps, local retouch (repair / | |
| replace / upscale), pick 3D points from pixels, and re-bake. | |
| * **Free dry runs** with `"backend": "mock"`, and **bring-your-own images** with `"backend": "external"`. | |
| * **Flat errors** `{"error", "hint"}`. | |
| ## Quick start | |
| ```bash | |
| BASE=https://townbox-projection-texturing.hf.space | |
| curl -s --data-binary @house.glb -H 'content-type: model/gltf-binary' $BASE/api/uploads | |
| # -> {"upload_id": "up_...", ...} | |
| curl -s -X POST $BASE/api/jobs -H 'content-type: application/json' -H "X-HF-Token: $HF_TOKEN" \ | |
| -d '{"upload_id":"up_...","prompt":"white clapboard siding, grey shingle roof; dark green door"}' | |
| # -> {"job_id": "...", "state": "queued", "poll_after_seconds": 15, "next": [...]} | |
| curl -s $BASE/api/jobs/<job_id> | |
| # when "state" is "done": files.textured_glb, files.contact_sheet, summary.verdict, output, next | |
| ``` | |
| Try it without a mesh: `{"sample": "lantern", "prompt": "black wrought iron, weathered oak post, warm glass"}`. | |
| Terrain and ground: `POST /api/terrain {"upload_id": "up_...", "prompt": "an alpine valley in early summer"}` (or a | |
| `heightmap`, and your own `layers`) returns `files.terrain_glb` (the ground with a top-down colour map) and | |
| `files.bundle_zip` (splat maps, seamless detail textures, `blender_terrain.py`, `three_terrain.js`). See the | |
| "Terrain and ground" section of /llms.txt. | |
| PBR materials: add `"pbr": true` to a texture job (or POST /api/jobs/{id}/pbr afterwards) for | |
| `files.textured_pbr_glb` with a de-lit base colour and a metallicRoughness texture (roughness, metallic maps from a | |
| LoRA on Qwen-Image-Edit-2511, run on the caller's ZeroGPU quota). | |
| MCP client configuration: | |
| ```json | |
| {"mcpServers": {"projtex": {"type": "http", "url": "https://townbox-projection-texturing.hf.space/mcp", | |
| "headers": {"X-HF-Token": "hf_..."}}}} | |
| ``` | |
| Tools: | |
| * `texture_mesh`, `texture_terrain`, `get_job` (with a preview image) and `view_image`; | |
| * the quality loop: `regenerate_views`, `disable_views`, `fill_gaps`, `retouch`, `undo_retouch`, `bake`, | |
| `pick_point`; | |
| * `submit_view_image` (bring your own images); | |
| * `service_info` and `guide`. | |
| ## Quota: who pays for generation | |
| Image generation runs on ZeroGPU Spaces and spends the **caller's** daily GPU quota, about 30 s per view. | |
| * **Your token:** send it as `X-HF-Token` (or the `hf_token` field) so your own quota is used. It stays in | |
| memory for that job only and is never written to disk, logged or returned. | |
| * **No token:** the job runs as the visitor identity the Hub forwards, if present, otherwise as the shared | |
| anonymous quota (about 2 GPU-minutes per day). `GET /api/identity` shows which applies to your requests. | |
| * **No quota needed:** the `mock` and `external` backends. | |
| ## What runs here | |
| The CPU part of [projtex](https://huggingface.co/spaces/townbox/projection-texturing/tree/main/projtex) runs in | |
| this container, with software OpenGL: | |
| * mesh import and UV repair; | |
| * camera planning (objects, characters with face close-ups, 360° environment probes); | |
| * validation of every generated view (rejects re-framed outputs); | |
| * texel-space fusion weighted by angle and depth; | |
| * push-pull hole filling, leave-one-out consistency checks, local retouch layers; | |
| * GLB export. | |
| Limits: | |
| * meshes: 60 MB, 600k triangles; | |
| * texture size: 1024, 2048 or 4096; | |
| * 8 operations run at once (the CPU-heavy parts share 2 CPU slots), the rest are queued; | |
| * jobs expire after 12 h or when the Space restarts. | |
| ## Licences | |
| * Code: MIT. | |
| * Qwen-Image-2.1 and Qwen-Image-2.1-Turbo outputs: Qwen research licence. | |
| * Fibo 2.0 Edit Turbo outputs: CC BY-NC 4.0 (non-commercial). | |
| * Samples: Avocado and Lantern are CC0 (Khronos glTF-Sample-Assets). The head is the Lee Perry-Smith scan, | |
| CC-BY 3.0, by Infinite-Realities. | |
| Inspired by the projection-texturing workflow shown by @alexfredo87. This is an independent implementation. | |