Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

docs(forge): document the in-browser mesh tools, the Open in OrcaSlicer and Bambu Studio handoff, and the /api/slicer STL and 3MF route

nirholas187b79a6d01d
diff --git a/docs/api-reference.md b/docs/api-reference.md
index 0fcfd3aac..a9ce1d58b 100644
--- a/docs/api-reference.md
+++ b/docs/api-reference.md
@@ -2135,6 +2135,51 @@ model's creator through the in-app bell (`comment` type, social category) when
the model has an attributed creator. Authors can delete their own comments
only.
+### Slicer file: `GET /api/slicer/:id/model.stl`
+
+```
+GET /api/slicer/<uuid>/model.stl → binary STL, auto-sized
+GET /api/slicer/<uuid>/model.3mf → 3MF package with colour
+GET /api/slicer/<uuid>/<N>mm/model.stl → longest edge exactly N mm (5 to 500)
+GET /api/slicer/<uuid>/<N>mm/model.3mf
+If-None-Match: "<etag>" # optional: 304 when unchanged
+→ 200 content-type: model/stl | model/3mf
+ content-disposition: attachment; filename="<prompt-slug>[-Nmm].stl"
+ x-slicer-size-mm: 77.6 x 20.1 x 100.0
+ x-slicer-scale: real | auto | requested
+ etag: "slc-<hash>"
+```
+
+A finished public or unlisted creation, converted on the fly into a file a
+3D-printing slicer opens ready to slice. The path ends in a literal
+`model.stl` and carries no query string on purpose: the "Open in OrcaSlicer"
+and "Open in Bambu Studio" deep links (`orcaslicer://open?file=<url>`,
+`bambustudio://open?file=<url>`) hand the slicer this URL, and slicers pick
+the importer from the last path segment. Any HTTP client can use it the same
+way, with CORS open to every origin.
+
+The file is print-ready, not just converted: rotated from glTF's Y-up to the
+slicer's Z-up, in millimetres, resting on the bed at Z = 0 and centred on the
+plate. A model whose real size is 10 to 250 mm keeps it (`x-slicer-scale:
+real`); anything else is scaled to a 100 mm longest edge (`auto`); a `<N>mm`
+segment sets the longest edge exactly (`requested`). Geometry comes from the
+same loader and exporters as the Materialize print API, capped at 1.5 million
+triangles.
+
+Responses are immutable per id, format and size: `cache-control: public,
+max-age=3600, s-maxage=86400, stale-while-revalidate=604800` plus a strong
+ETag. Conversions (cache misses) are rate limited to 30 per 5 minutes per IP.
+Errors: `400 validation_error` (id not a UUID, format not stl/3mf, size out of
+range), `404 creation_not_found` (missing, unfinished or private), `413
+too_large` / `too_complex` (over the size or triangle cap), `422
+invalid_model` / `no_geometry`, `502 fetch_failed` (the stored GLB could not
+be read), `429` with `retry-after`.
+
+```bash
+curl -sLo helmet.stl https://three.ws/api/slicer/<uuid>/model.stl
+curl -sLo helmet-80mm.3mf https://three.ws/api/slicer/<uuid>/80mm/model.3mf
+```
+
### Agent-forged gallery feed — `GET /api/forged`
```
diff --git a/docs/forge.md b/docs/forge.md
index 0e691064c..ca612e07d 100644
--- a/docs/forge.md
+++ b/docs/forge.md
@@ -187,7 +187,7 @@ stills; it never reports a recording that did not happen.
3. For text, type a prompt like `a weathered brass diving helmet`. For photos, add one to six images of the same object from different angles (front, back, left, right, top, three-quarter); each uploads straight to object storage via a presigned URL and the public URLs are fused with multi-view conditioning.
4. Optionally open the quality controls and pick a tier (Draft, Standard, High) and an engine. The default engine carries a **FREE** pill. Down lanes are disabled with the reason shown.
5. Click Generate. A real elapsed-driven progress line runs against the catalog's ETA estimate for the chosen path, tier, and engine.
-6. When the model lands, orbit it in the viewer, view it in AR, download it in any of seven formats (see [Download formats](#download-formats)), or run the post-generation tools (stylize, optimize, Game-Ready retopology, split). Press `R` (or click **Reel**) to render a shareable video and stills of it without leaving the page.
+6. When the model lands, orbit it in the viewer, view it in AR, download it in any of seven formats (see [Download formats](#download-formats)), or run the post-generation tools (stylize, optimize with in-browser repair, smoothing and decimation (see [Mesh tools](#mesh-tools-repair-smooth-decimate)), Game-Ready retopology, split). Send it to a 3D printer from the format menu's slicer rows (see [Open in a slicer](#open-in-a-3d-printing-slicer)). Press `R` (or click **Reel**) to render a shareable video and stills of it without leaving the page.
7. Keep going on the same result: **Rig for animation** adds a humanoid skeleton (POST `/api/forge?action=rig`) and hands off to Pose Studio or IRL placement; **Restyle materials** re-skins the surface with a free-text instruction or a preset chip (chrome, wood, gold, neon, marble, rust) via `/api/material-studio`, keeping the mesh untouched; **Iterate** makes a shape-changing edit from a plain-language instruction ("make the helmet red", "add a backpack") via `/api/forge-iterate` (the same conversational core the `refine_model` MCP tool uses) and keeps every version in a branchable lineage strip; **Place IRL** opens `/irl?avatar=<glb_url>` to anchor the model in AR at a real-world location.
## Download formats
@@ -247,6 +247,62 @@ curl -sX POST https://three.ws/api/forge-remesh \
A job that fails because of the file itself (an ASCII FBX, a corrupt one)
reports `status: "failed"` with an `error` that says what to re-export.
+## Mesh tools: repair, smooth, decimate
+
+The **Optimize** panel under a finished model, and the **Edit mesh** section
+on every model page at `/m/<id>`, edit the mesh in your browser. Nothing is
+uploaded: the GLB is read with glTF-Transform and the work runs in a Web
+Worker, so the page stays responsive on a 500k-triangle model.
+
+| Operation | What it does | Controls |
+|---|---|---|
+| Repair | Welds coincident vertices, removes collapsed, zero-area and duplicate faces, makes winding consistent across each shell, flips shells that face inward, and rebuilds normals with hard edges split at the crease angle. | Crease angle (0 to 180 degrees, default 60) |
+| Smooth | Taubin (volume-preserving, the default) or plain Laplacian smoothing. Vertices that share a position move together, so UV seams never tear, and UVs, textures and materials are untouched. Open borders can be pinned. | Method, iterations (1 to 50), strength lambda (0.05 to 1), keep open borders fixed |
+| Decimate | meshoptimizer simplification to a target, preserving UV seams first and relaxing them only if the budget cannot otherwise be reached. | Keep percentage or an exact target triangle count, with a live "before to after" preview |
+
+Every edit reports what it did in numbers (vertices welded, faces re-wound,
+points moved, shape error) and the before and after triangle count. Edits
+stack: each one starts from the previous result, the breadcrumb shows the
+chain, **Undo** (or Ctrl+Z inside the panel) steps back one edit, and
+**Reset to original** returns to the stored model. The viewer and the
+Download button follow the edited mesh, and **Download GLB** in the panel
+saves it with the edit chain in the filename.
+
+Browser formats (GLB, OBJ, STL, PLY, USDZ) export the edited mesh. Server
+work (quad remesh, low-poly, FBX and 3MF conversion, and the slicer files
+below) starts from the saved model, because the edit only exists in your
+browser; the format menu says so instead of silently converting the original.
+
+## Open in a 3D-printing slicer
+
+The format menu's **Open in OrcaSlicer** and **Open in Bambu Studio** rows,
+and the **3D print** action on a model page, send a saved model straight to a
+slicer. The slicer downloads a print-ready file from
+`/api/slicer/<id>/model.stl` (or `/<N>mm/model.3mf`): Z-up, in millimetres,
+resting on the bed and centred on the plate. A model whose real size is 10 to
+250 mm keeps it; anything else arrives with a 100 mm longest edge, and the
+model page's size picker (50 to 200 mm) asks for an exact size. The full
+route contract is in [api-reference.md](api-reference.md#slicer-file-get-apisliceridmodelstl).
+
+| Slicer | How it opens | Notes |
+|---|---|---|
+| OrcaSlicer | `orcaslicer://open?file=<url>` | Opens the file directly. |
+| Bambu Studio | `bambustudio://open?file=<url>` | Asks you to trust three.ws the first time. |
+| PrusaSlicer | Download STL, then File > Import | Its `prusaslicer://` handler only accepts Printables and Thingiverse links, so there is no direct button. |
+
+If nothing happens after a click (the slicer is not installed, or the browser
+blocked the handler), the panel says so and offers the install page plus
+**Download STL** and **Download 3MF** links, which work with every slicer.
+The slicer rows appear once the model is saved, and they always send the
+saved model: mesh tool edits are local, so after an edit the row reports
+"sent (saved model, not your edits)". To print an edit, download it as STL
+from the format menu and import it into the slicer by hand.
+
+```bash
+# The same file the slicer receives, at a 120 mm longest edge.
+curl -sLo model.stl https://three.ws/api/slicer/<id>/120mm/model.stl
+```
+
## Examples
Forge's read and generate surface is plain HTTP. No key is required for the free lanes.