# Stitching wovenart on a Brother embroidery machine

This turns a generated piece into thread. The sketch already computes real
needle paths; `embroider.py` packages them into a Brother `.PES` file plus a
universal `.DST`, a stitch-accurate `.png` preview, and a `.colors.txt`
thread-sequence sheet.

```
browser sketch  →  .stitchplan.json  →  embroider.py  →  .PES  →  machine
```

---

## 1. Prerequisites

- Python 3 with two packages:
  ```
  pip install pyembroidery pillow
  ```
- A Brother home embroidery machine that reads **PES** (PE / Innov‑ís / SE /
  PE‑Design lineage — SE600/SE700/SE1900/SE1950, PE800/PE900, Innov‑ís NS/NQ/
  Luminaire, etc.). DST is the fallback for any other machine.
- A USB stick (most Brother machines), or the machine's USB cable / wireless
  if it has it.

## 2. Export a stitch plan from the sketch

1. Open `index.html`, navigate to the piece you want (`←` / `→`).
2. Press **P** (or the **Stitch plan (.json)** button).
3. You get `wovenart_<token>_pieceNN.stitchplan.json`.

That file is the exact, reproducible needle path for that token hash.

## 3. Convert to a Brother file

```
python3 embroider.py wovenart_<token>_pieceNN.stitchplan.json --size-mm 130
```

It writes, next to the JSON:

| File          | Purpose                                                |
|---------------|--------------------------------------------------------|
| `*.pes`       | **Load this on a Brother machine.**                    |
| `*.dst`       | Universal fallback (no color info — follow the sheet). |
| `*.png`       | Stitch-accurate preview in the true target colors.     |
| `*.colors.txt`| **Print this.** The thread order to follow at the machine. |

Useful options:

- `--size-mm 130` — finished width/height of the (square) design. **Set this
  to your hoop's stitchable area, not the hoop's outer size** (see §4).
- `--max-stitch-mm 7` — long stitches are split so the machine never over-pulls.
- `--travel-mm 3` — gaps wider than this get a trim+jump; smaller gaps chain
  into continuous running stitches. Raise it for fewer trims on big designs.
- `--pes-version 1` — v1 has the widest Brother compatibility; try `6` only if
  your machine is recent and v1 misbehaves.
- `--out-dir out` — write the four files into `out/`.

## 4. Choose the size for your hoop

The design is square. Pick `--size-mm` from the *stitchable field* of your hoop:

| Hoop (sold as) | Stitchable field | Use `--size-mm` |
|----------------|-------------------|-----------------|
| 4" × 4"        | ~100 × 100 mm     | `100`           |
| 5" × 7"        | ~130 × 180 mm     | `130`           |
| 6" × 10"       | ~160 × 260 mm     | `160`           |
| 8" × 8" / large| ~200 × 200 mm     | `200`           |

The script prints the final extents and warns if it overflows. When in doubt,
go ~5 mm smaller than the field.

## 5. Fabric & stabilizer

These pieces are a **dense, fully-covered fill** (the whole square is worked).
Treat it like a small tapestry, not a light motif:

- Use a firm woven ground — quilting cotton, linen, or twill.
- Hoop with **two layers of cut-away stabilizer** (or one cut-away + one
  tear-away). Dense fills distort thin stabilizer.
- Hoop the fabric and stabilizer together, drum-tight, no slack.
- A topping isn't needed on woven fabric; add water-soluble topping only if you
  stitch onto a textured/knit ground.

## 6. Thread, and why the machine shows different colors

`*.colors.txt` lists the blocks **in stitching order**, each with the *true
target color* and the *name the machine will display*:

```
 1.  target floss #E6DCC0    machine shows: Beige (#EFE3B9)
 2.  target floss #8C2F24    machine shows: Amber Red (#B54B64)
 3.  target floss #2E3D56    machine shows: Peacock Blue (#134A46)
```

PES stores colors as **indices into Brother's built‑in thread chart**, so the
machine's on-screen swatch/name is only the nearest match — it will not be
exactly your floss. **Follow the sheet, not the screen:** at each color-change
prompt, mount the *target floss* for that block. The background field is
block 1 (it's the largest area, so it stitches first).

Standard 40‑wt machine embroidery polyester or rayon works well. Match the
target hex by eye against a thread card; exact brand numbers don't matter.

## 7. Load and stitch

1. Copy the `.pes` to the USB stick (root folder, or a short-named subfolder).
2. Insert it into the machine; select the design from USB.
3. Confirm it fits the mounted hoop; **do not auto-resize** (resizing changes
   stitch density — regenerate at the right `--size-mm` instead).
4. Optionally turn on automatic thread trim and jump-stitch trimming.
5. Stitch block 1. At each color-change stop, rethread per `*.colors.txt`.
6. Remove from the hoop, trim jumps, cut away excess stabilizer from the back.

## 8. Notes & good practice

- **Always test once on scrap** at your chosen size before the final fabric.
- It's a large stitch count (tens of thousands). Expect a real run time and
  several thread changes — this is normal for full-coverage work.
- Reproducibility: the same **token hash** always yields the same piece, so the
  `.PES` for a given token is stable. Note the token from the caption / filename.
- For a non-Brother machine, use the `.DST` and follow `*.colors.txt` for the
  color order (DST carries no color data).
- If a machine rejects PES v1, re-run with `--pes-version 6`. If stitches feel
  too long/short for your fabric, adjust `--max-stitch-mm`.