# Threadsmith Digitizer

> Turn shapes, SVG paths, text or a whole project into embroidery stitches with stats and preview. Digitizes vector artwork into machine embroidery: running, bean, satin (with pull compensation, auto split and short stitches), tatami fill with stagger and graded density, contour fill and motif runs, plus underlay. Returns stitch counts, trims, colour changes, thread and bobbin estimates, sewing time, hoop fit, a density check and a thread-look SVG preview — the same engine as the Threadsmith app.

Part of usefulweb.site (https://usefulweb.site/). Results are deterministic calculations from the inputs and the listed assumptions; the API returns exactly what the web page shows.

## Use it
- Human interface: https://threadsmithdigitize.usefulweb.site/ (interactive tool at https://threadsmithdigitize.usefulweb.site/tool)
- JSON API: POST https://threadsmithdigitize.usefulweb.site/api/v1/calculate with a JSON object of inputs (schema: https://threadsmithdigitize.usefulweb.site/api/v1/tool)
- OpenAPI: https://threadsmithdigitize.usefulweb.site/openapi.json
- MCP (Streamable HTTP): https://threadsmithdigitize.usefulweb.site/mcp - tool `threadsmith_digitize`

## Inputs
- source (select): What to digitize
- shape (select): Shape
- widthMm (number): Shape width
- heightMm (number): Shape height
- pathD (textarea): Path data - SVG path syntax in millimetres (y down, 0,0 = hoop centre). Closed paths (Z) become fills, open paths become lines.
- svg (textarea): SVG markup - paths, rect, circle, ellipse, line, polyline, polygon and transforms are imported; text, images and gradients are skipped with a warning.
- fitWidth (number): Scale SVG to width - Optional. Default: the SVG’s own physical size (px at 96 dpi).
- text (text): Text - A–Z, a–z, 0–9 and . , ! ? - _ ' " : ; ( ) / & + # * =
- textSize (number): Letter height (capitals)
- font (select): Font style
- project (textarea): Project JSON - A .threadsmith.json project (see the app’s project schema).
- stitchType (select): Stitch type
- angle (number): Fill angle
- spacing (number): Row spacing / satin density
- stitchLength (number): Stitch length
- satinWidth (number): Satin column width (lines)
- pullComp (number): Pull compensation
- underlay (select): Underlay
- color (text): Thread - #rrggbb or a built-in thread name such as ruby, emerald, gold, navy.
- hoop (select): Hoop
- spm (integer): Machine speed
- includeStitches (boolean): Include the stitch list in the result - Adds result.stitchList ([x, y, type] in mm) for chaining into threadsmith-stitch-file.

## Method
- Shapes are flattened to polygons (Bézier curves within 0.04 mm); closed shapes are regions (even-odd, holes allowed), open paths are lines.
- Tatami: scanlines at the fill angle every row-spacing; intervals are split into blocks that can be sewn back and forth, ordered nearest-first, and penetrations sit on a staggered grid (1/3 offset by default) so no visible columns form.
- Satin: zig-zag between the edges every density step (rows perpendicular to the shape’s principal axis); columns along lines measure spacing on the outer edge and shorten every other inner stitch on tight curves; stitches longer than the max width are split with interleaved penetrations.
- Contour fill and edge-walk underlay use an exact Euclidean distance transform of the rasterised shape and marching-squares iso-lines, so insets stay valid for concave shapes and holes.
- Sequencing: objects grouped by colour (first appearance) and visited nearest-first; gaps up to 1.2 mm are sewn, gaps below the trim distance are jumped, longer gaps get tie-off, trim, jump and tie-in.
- Thread estimate = sewn length + 0.8 mm take-up per penetration + 5 % waste; bobbin ≈ ⅓ of the sewn length; time = stitches ÷ speed + 4 s per trim + 20 s per colour change.

## Limits
- Estimates assume average fabric and settings; always test-stitch on the real fabric and stabiliser. Thread names are generic colours, not brand shade numbers.