# Threadsmith Stitch File Writer

> Write Tajima DST or Melco EXP machine files from a stitch list or a Threadsmith project. Encodes stitches as a Tajima DST (512-byte header, balanced-ternary 3-byte records, jumps split to ≤ 12.1 mm, colour changes, trims as zero-sum jumps, END) or Melco EXP file. The file is decoded again to verify every stitch position before you download it.

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://threadsmithstitchfile.usefulweb.site/ (interactive tool at https://threadsmithstitchfile.usefulweb.site/tool)
- JSON API: POST https://threadsmithstitchfile.usefulweb.site/api/v1/calculate with a JSON object of inputs (schema: https://threadsmithstitchfile.usefulweb.site/api/v1/tool)
- OpenAPI: https://threadsmithstitchfile.usefulweb.site/openapi.json
- MCP (Streamable HTTP): https://threadsmithstitchfile.usefulweb.site/mcp - tool `threadsmith_stitch_file`

## Inputs
- format (select): File format
- stitches (textarea): Stitch list (JSON) - [[x, y], [x, y, "jump"], [x, y, "trim"], [x, y, "color"], …] in mm (y down), or {"cmds": […], "colors": [{"name", "hex"}]} from threadsmith-digitize.
- project (textarea): Or: Threadsmith project JSON - If given, the project is digitized first.
- label (text): Design label (DST header, 8 characters)

## Method
- Coordinates are rounded to 0.1 mm on absolute positions, so rounding never accumulates; each move becomes the difference to the previous rounded position.
- DST: each axis is written in balanced ternary with digits for 1, 3, 9, 27 and 81 (±121 max). Byte 3 = 0x03 | flags: 0x80 jump, 0xC0 colour change; END = 00 00 F3. Longer moves are split into equal records. Y is inverted (DST is y-up).
- Trims are written as three jumps (+2,+2) (−4,−4) (+2,+2) that cancel out — the convention machines use to trigger a trim after a run of jumps.
- Header: LA label, ST record count, CO colour changes, ±X/±Y extents in 0.1 mm, AX/AY end offset, MX/MY 0, PD ******, 0x1A, padded with spaces to 512 bytes.
- EXP: 2 signed bytes per stitch (±127), 0x80 0x04 dx dy jump, 0x80 0x01 colour change; trims as three zero-sum jumps.

## Limits
- DST and EXP carry no thread colours: set the needle/colour order on the machine using the colour list from Threadsmith. Test on scrap fabric first.