docs: document image tracing endpoint

2026-08-08 14:51:40 +08:00
parent 445dbc1781
commit dc8127dba1
3 changed files with 53 additions and 5 deletions
@@ -157,4 +157,25 @@ headers, which would block three.js `TextureLoader` / `GLTFLoader` in the
 browser. Routing asset fetches through the proxy makes them loadable.

 **Alternatives considered:** Loading assets directly in the browser. Rejected —
-CORS failures on common Workshop hosts would break the viewers.
+CORS failures on common Workshop hosts would break the viewers.
+
+## D13 — Server-side image tracing to a mesh-ready shape
+
+**Decision:** The proxy exposes `GET /trace?url=...`, which fetches an image,
+traces it into a vector shape, and returns the result BSON-encoded. Tracing is
+configurable: `mode` (`alpha` default, `bw`, `color`) selects how the region is
+derived, and `format` (`shape` default, `svg`) selects the response. The
+`shape` format returns a parsed `{ outline, holes }` polygon matching
+`@tts/mesh`'s `Shape` interface.
+
+**Context:** The user wants to build a mesh from an image (e.g. a token or tile
+art) using `@tts/mesh`. vtracer only returns SVG, but the mesh package consumes
+`{ outline, holes }`. Tracing on the server keeps the SVG-to-shape parsing out
+of the browser and lets the BSON response carry a ready-to-extrude shape.
+`sharp` decodes the image to RGBA so alpha/luminance masks can be built before
+feeding vtracer's `convertPixels`.
+
+**Alternatives considered:** Returning only the raw SVG and parsing in the web
+app near `@tts/mesh`; tracing by color only (no alpha). Rejected — server-side
+parsing yields a shape the mesh package can consume directly, and alpha-based
+tracing (the default) is the common case for token/tile art.