# Threadsmith Sequence Optimizer

> Reorder the stitch segments of a DST, PES, JEF or EXP file for fewer trims, jumps and colour stops. Reads an embroidery machine file (or a stitch list), splits it into the segments that are sewn without a jump or trim, and finds a sewing order with fewer trims, jumps and colour changes: segments may be sewn backwards, colour blocks with the same thread are merged, and segments whose stitches overlap keep their original order so the layering does not change. Every stitch is kept. You get the before/after counts, the sewing time saved and the optimised file in the same or another format, decoded again to prove that every penetration is still there.

Part of usefulweb.site (https://usefulweb.site/). Part of [Threadsmith](https://threadsmith.usefulweb.site/) (ownerApp: threadsmith). 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://threadsmithsequenceoptimizer.usefulweb.site/ (interactive tool at https://threadsmithsequenceoptimizer.usefulweb.site/tool)
- JSON API: POST https://threadsmithsequenceoptimizer.usefulweb.site/api/v1/calculate with a JSON object of inputs (schema: https://threadsmithsequenceoptimizer.usefulweb.site/api/v1/tool)
- OpenAPI: https://threadsmithsequenceoptimizer.usefulweb.site/openapi.json
- MCP (Streamable HTTP): https://threadsmithsequenceoptimizer.usefulweb.site/mcp - tool `threadsmith_sequence_optimizer`

## Inputs
- file (file): Embroidery file - Tajima .dst, Brother .pes, Janome .jef or Melco .exp.
- stitches (textarea): Or: stitch list (JSON) - Same format as threadsmith-stitch-file.
- colors (list): Thread colours in sewing order - Optional #rrggbb per colour block. DST and EXP files store no colours, so blocks are only merged when you give their colours (PES/JEF colours are read from the file).
- outputFormat (select): Write the optimised file as
- trimDistance (number): Trim gaps of at least - Shorter gaps are jumped without a trim.
- allowReverse (boolean): Allow sewing segments backwards
- mergeColors (boolean): Merge colour blocks with the same thread - Only blocks whose stitches do not overlap anything sewn in between are moved together.
- spm (integer): Machine speed
- label (text): Design label (DST/PES header)

## Method
- The file is decoded (DST balanced ternary, EXP bytes, PES via its PEC block, JEF) into stitches, jumps, trims and colour changes; a segment is a run of stitches between two jumps, trims or colour changes.
- Layering: segments whose stitches touch a common 1 mm cell keep their original order. All other segments may move, and within a thread they may be sewn backwards (jump to the last stitch, sew the same penetrations in reverse).
- Order: stay in the current thread while a segment of it is free, otherwise switch to a thread that can be finished completely (or has most free segments); the next segment is the cheapest connection — jump for gaps under the trim distance, trim + jump otherwise. A relocate pass moves single segments inside a thread run when that is cheaper.
- The file is rebuilt with one jump per gap (the writer splits long moves into format-legal records), trim + colour change between threads and END. The new order is only used when colour changes, trims and jumps are all no higher than in the input and at least one is lower.
- Jumps are counted as moves: several jump records that a format needs for one long move count once. Sewing time = stitches ÷ speed + 4 s per trim + 20 s per colour change + 0.15 s per jump.

## Limits
- Moving segments changes where the machine trims and ties off; check the new order in a viewer and test-stitch before production. Tie-in/tie-off stitches inside the file are kept as they are.