StitchCraft

Machine embroidery for VectorCraft, in Rust. StitchCraft turns vector art into machine embroidery files — PES for Brother machines first, then DST and more — with running and bean stitch, satin columns, tatami, contour and meander fills, and more.

How it is built:

• It never crashes. Every input is untrusted, every loop is bounded, every problem is a coded, explained diagnostic.
• It is deterministic. The same design gives the same file on every computer, so bugs reproduce and previews match the sew-out.
• It is proven. Behaviour is specified as requirements, checked by a conformance suite on every change, and sewn on a real machine at every milestone.
• Its docs cannot drift. Reference pages and pictures are generated from the code and regenerated on every pull request.

Where to go

• Embroidering? Start with the user guide and embroidery basics.
• Building StitchCraft? Read the technical design, then the roadmap.
• Contributing? See contributing.

Status: StitchCraft sews the strokes of an SVG design and writes PES and DST files. A stroke is sewn in running stitch or manual stitch, with bean stitch where it is set. Milestone M4 is under way: the engine sews a satin column’s underlays and top stitches, and stitch plan sews the satins of an SVG from M8, when it reads Ink/Stitch’s settings. Fills come in M5. The roadmap has every step.

User guide

StitchCraft writes machine embroidery files from SVG files and VectorCraft documents. It also reads, draws and converts the files of other embroidery software. The guide follows the Diátaxis structure, with a section for each stitch type.

StitchCraft makes the pictures and the command output in this guide when the docs are built. The reference pages are generated from its code, and CI fails when any of them is out of date.

Install StitchCraft

StitchCraft has no packaged releases yet. Build the stitch command from its source on Linux, macOS or Windows. It takes a few minutes.

Build it

Install Rust with rustup, then get the source and build it:

git clone https://github.com/KaboomFox/stitchcraft
cd stitchcraft
cargo install --locked --path apps/stitchcraft-cli

The repository names the Rust version it is built with, and rustup fetches that version the first time. cargo puts stitch in its bin folder, which rustup adds to your PATH.

Check it

stitch --version

It prints stitch and its version number.

To update StitchCraft, run git pull in the stitchcraft folder and the cargo install line again.

The VectorCraft plug-ins

The plug-ins say how each object of a VectorCraft drawing sews, and show its stitches. There are 3, one for each kind of stitch, and 2 more that write PES and DST files from VectorCraft’s File › Export, from VectorCraft 0.14. 3 filters change the drawing: one keeps a design’s settings and machine with the document and one draws a test sheet, from VectorCraft 0.16, and one makes lines into satin columns, from VectorCraft 0.17. All are built from the same source. In the stitchcraft folder:

rustup target add wasm32-unknown-unknown
cargo build -p stitchcraft-vc-plugin --release --target wasm32-unknown-unknown --features fill

The build writes target/wasm32-unknown-unknown/release/stitchcraft_vc_plugin.wasm. Copy it into a folder for plug-ins as stitchcraft-fill.wasm. Build again with --features stroke, --features satin, --features pes, --features dst, --features settings, --features testsheet and --features stroke-to-satin, and copy the file each time, as stitchcraft-stroke.wasm, stitchcraft-satin.wasm, stitchcraft-pes.wasm, stitchcraft-dst.wasm, stitchcraft-settings.wasm, stitchcraft-testsheet.wasm and stitchcraft-stroke-to-satin.wasm. VectorCraft 0.13 and earlier refuse the exporters.

In VectorCraft’s desktop app, choose that folder in Edit › Preferences › Plug-ins & Scratch Disks › Additional Plug-ins Folder, which is under Performance & Storage up to VectorCraft 0.14. VectorCraft installs the plug-ins in it whenever it starts, all but Stroke to Satin. It asks for more work than a filter usually may do, which VectorCraft lets you allow when you install it on its own: choose Object › Plug-ins › Install Plug-in… and pick stitchcraft-stroke-to-satin.wasm. VectorCraft asks you first, and once you allow it, keeps it and installs it again when it starts. The effects are under Effect › Plug-ins, the formats in File › Export › Export As, and the filters under Object › Plug-ins. In VectorCraft on the web, open each file with File › Open instead, once each time VectorCraft is opened. Embroider a VectorCraft design shows how to use them.

Next

Sew your first test sheet, or turn an SVG into a PES file. The command line reference lists every command.

Your first sew-out on a Brother

You will sew StitchCraft’s orientation and scale sheet, TS-01, on a Brother machine such as the PE800, and check that its size and direction are exactly right. It takes about twenty minutes.

You need

• StitchCraft, installed.
• A Brother embroidery machine that reads PES files from a USB stick, and a hoop that sews at least 120 × 120 mm, such as the PE800’s 5 × 7 in hoop.
• Medium-weight woven cotton, medium tear-away stabilizer, a 75/11 embroidery needle, 40 wt polyester thread (black shows the lines best), white bobbin thread.
• A ruler or calipers with millimetres.

1. Write the file

$ stitch testsheet TS-01 -o TS-01.pes
TS-01 · Orientation and scale
  file      TS-01.pes (PES v1, 1587 bytes)
  sha256    854cde9f533e3b6567afb570a0eb3d4547e7813f5649da97d27be104f8cd18c6
  profile   brother-pe800-5x7 (Brother PE800 with its 5 × 7 in hoop)
  size      120.0 × 120.0 mm
  stitches  274 stitches, 7 jumps, 6 trims, 0 colour changes, 0 stops
  threads   1. Black (#000000), shown as Brother PEC 20 "Black"
after sewing, check:
  - The F reads normally: not mirrored, not upside down, not turned.
  - Each arm of the cross measures 100.0 ± 0.5 mm end to end, horizontally and vertically.
  - The corner squares measure 10.0 mm on every side.
  - Ticks are 10 mm apart; the long ticks mark the ends and the centre.

That is real output: this page is regenerated from StitchCraft itself, so the checksum is the one your file will have. The checksum is how a sew-out report names exactly the bytes that were sewn. Every test sheet is in the test sheets reference; stitch testsheet --list lists them too.

2. Look at it first

$ stitch preview TS-01.pes -o TS-01.png
TS-01.png · 992 × 992 pixels
  from      TS-01.pes · PES (#PES0001) · "TS-01"
  style     realistic, 8 pixels per millimetre

The picture is drawn from the file itself, at the exact positions the machine will use, so this is what you should see in the hoop. Add --style simple to see every stitch, needle hole, trim and jump instead: the way to check a design before you sew it.

3. Load it on the machine

Copy TS-01.pes to a USB stick, plug it into the machine and select the design. The machine should show it at 120 × 120 mm, with an upright “F” in the top-left quarter. If it does not list the file at all, stop here and report that — it is the most important thing this sheet tests.

4. Hoop and sew

Hoop the fabric and stabilizer drum-tight, centre the design, attach the hoop, and sew. The machine sews the cross first, then the “F”, then the four corner squares, trimming between parts if it can.

5. Check

Measure the sew-out against the TS-01 checks. stitch testsheet printed the same list when it wrote the file.

6. Tell us

File a Sew-out report on GitHub with photos of the front and back (a ruler in view), your measurements, and anything odd (machine testing).

Turn an SVG into a PES file

In this tutorial you save a small design as SVG and plan it for a Brother machine. Then you look at what it will sew, and sew it. The design is a red star inside a blue ring, 44 mm across.

You need

• StitchCraft, installed.
• A text editor, or a drawing program that saves SVG, such as Inkscape.
• To sew it: the machine and materials of your first sew-out.

1. Save the design

Save this text as badge.svg:

<svg xmlns="http://www.w3.org/2000/svg" width="50mm" height="50mm" viewBox="0 0 50 50">
  <!-- A red star inside a blue ring, 44 mm across. The star sews first. -->
  <polygon id="star" fill="none" stroke="#c8102e" stroke-width="0.4"
           points="25,10 28.53,20.15 39.27,20.36 30.71,26.85 33.82,37.14
                   25,31 16.18,37.14 19.29,26.85 10.73,20.36 21.47,20.15"/>
  <circle id="ring" cx="25" cy="25" r="22" fill="none" stroke="#1f4e9c" stroke-width="0.4"/>
</svg>

StitchCraft sews each shape’s stroke as a line of running stitch, in the stroke’s colour. It reads the design’s size from width, height and viewBox, and here one unit is 1 mm. Shapes are sewn in the order the file lists them, and the star comes first.

2. Plan it

$ stitch plan badge.svg -o badge.pes --preview badge.png
badge.svg
  file      badge.pes (PES v1, 1498 bytes)
  sha256    5fea2f6734fadacdc1f3f1a7268bd964d3ab6c4bf1ba3b9f8fd6d10a4aae0d8c
  profile   brother-pe800-5x7 (Brother PE800 with its 5 × 7 in hoop)
  size      44.0 × 44.0 mm
  stitches  124 stitches, 2 jumps, 1 trim, 1 colour change, 0 stops
  threads   1. unnamed (#c8102e), shown as Brother PEC 5 "Red"
            2. unnamed (#1f4e9c), shown as Brother PEC 2 "Blue"
  preview   badge.png (384 × 384 pixels)

stitch plan writes the machine file and, with --preview, a picture of it. It plans for the brother-pe800-5x7 profile, the PE800 with its 5 × 7 in hoop, unless --profile names another. Each colour is a thread, and the PES file shows it as the nearest Brother palette colour that no other thread of the design has. The machine stops between the red and the blue for you to change the thread.

3. Look at it

The preview shows the embroidery as it will sew:

The simple style, from stitch preview badge.pes -o badge-simple.png --style simple, shows each needle point:

The stitches are spread evenly along each straight edge, and every corner of the star has a needle point. The grey dashes are the frame’s move from the star to the ring, after the colour change.

4. Sew it

Load badge.pes and sew it as in your first sew-out. Thread red first, and blue when the machine stops.

When StitchCraft warns

StitchCraft says what it changes or leaves out of a design. This one from StitchCraft’s tests has a fill of 2 rectangles and 2 lines that nearly touch:

$ stitch plan strokes.svg -o strokes.pes --preview strokes.png --report strokes.json
strokes.svg
  file      strokes.pes (PES v1, 2840 bytes)
  sha256    d0ce3f4cb7843412b2ab0d4aeab07385fdf20b16a7e77cac3cefcf0b4b9193a3
  profile   brother-pe800-5x7 (Brother PE800 with its 5 × 7 in hoop)
  size      60.0 × 45.0 mm
  stitches  556 stitches, 6 jumps, 5 trims, 3 colour changes, 0 stops
  threads   1. unnamed (#c00000), shown as Brother PEC 5 "Red"
            2. unnamed (#0040c0), shown as Brother PEC 21 "Ultramarine"
            3. unnamed (#c00000), shown as Brother PEC 5 "Red"
            4. unnamed (#00a000), shown as Brother PEC 37 "Leaf Green"
  preview   strokes.png (512 × 392 pixels)
  report    strokes.json
warning SC-W0307 (svg:patch:fill): This fill's area falls into 2 parts that are sewn one after another, with a jump between each.
  hint: To choose the order the parts are sewn in, break the fill apart into one element for each part.
info SC-I0504: A needle point less than the shortest stitch (0.3 mm) from a needle point next to it was left out.

• SC-W0307 names the fill, whose 2 rectangles are sewn one after the other, with a jump between them.
• SC-I0504 says a needle point too close to the one before was left out, where the lines nearly touch.

stitch explain with a code tells you more, and diagnostic codes lists them all. --report writes the file’s counts, size and SHA-256, the threads and the messages as JSON, for scripts.

Next

Stitch types shows what each stitch type does and the parameters that change it.

A patch in VectorCraft

In this tutorial you draw a round patch in VectorCraft and choose how each part of it sews, with the StitchCraft plug-ins showing the stitches as you go. Then you write the machine file and sew it. The patch is 30 mm across. It has a blue disc of fill, with a white star of running stitch on it, inside a gold satin border.

You need

• VectorCraft, in a version the compatibility page lists, with the StitchCraft plug-ins installed.
• StitchCraft’s command line, installed.
• To sew it: the machine and materials of your first sew-out.

Sizes here are in points, VectorCraft’s own unit: 72 points make an inch, and about 2.8 a millimetre. A field reads a size typed with its unit, such as 80 pt, whichever unit it shows.

1. Draw the disc and fill it

Choose File › New, and make the document 108 pt wide and 108 pt high. Choose the Ellipse tool and click near the artboard’s top left corner. In the Ellipse dialog, make the circle 80 pt wide and 80 pt high. Give it a blue fill and no stroke. A fill sews in the colour of its object’s fill.

With the circle selected, choose Effect › Plug-ins › StitchCraft Fill:

The dialog holds Ink/Stitch’s settings for a fill in sections, each with its label and unit. Rest the pointer on a label for its help, and the button after a field opens its page. Set Angle to 45, and choose OK. If the dialog is taller than your screen, see below.

The circle now shows the rows the fill sews, at 45 degrees. VectorCraft lets a plug-in do only so much work for a preview, and a larger fill, such as a disc more than about 30 mm across, shows its outline instead of its rows. stitch export --preview shows every stitch, whatever the size.

2. Draw the star

Choose the Star tool and click in the middle of the disc. Make Radius 1 26 pt, Radius 2 11 pt and Points 5. Give the star no fill and a white stroke. A line sews in the colour of its object’s stroke. Choose Effect › Plug-ins › StitchCraft Stroke, and OK. Its settings sew the line in running stitch, 2.5 mm a stitch.

3. Draw the border

A satin column is drawn as its 2 edges, its rails, joined into one compound path (satin columns in VectorCraft). Lock the disc and the star first, and Select All then takes only the rails: choose Select › All, then Object › Lock › Selection.

With the Ellipse tool, draw 2 more circles, one 84 pt across and one 70 pt across. Choose Select › All, then Object › Align › Horizontal Align Center and Object › Align › Vertical Align Center. Join the circles with Object › Compound Path › Make. Give the compound path no fill and a gold stroke, and choose Effect › Plug-ins › StitchCraft Satin, then OK.

4. Centre it

Choose Object › Unlock All and Select › All. Align everything again with Object › Align › Horizontal Align Center, then Vertical Align Center. The patch is done, and VectorCraft shows the stitches the plug-ins preview:

The objects sew in the order they were drawn. The disc sews first and the star next, and the border sews last, over the edges of both.

5. Write the machine file

Save the document as round-patch.vectorcraft, and run stitch export on it:

$ stitch export round-patch.vectorcraft -o round-patch.pes --preview round-patch.png
round-patch.vectorcraft
  file      round-patch.pes (PES v1, 4751 bytes)
  sha256    c06c3defb172d4e8e33096eaa48fbc7a898c25dfe4f83cc8b555c192fe792363
  profile   brother-pe800-5x7 (Brother PE800 with its 5 × 7 in hoop)
  size      29.6 × 29.6 mm
  stitches  1633 stitches, 3 jumps, 2 trims, 2 colour changes, 0 stops
  threads   1. unnamed (#1f4e9c), shown as Brother PEC 2 "Blue"
            2. unnamed (#ffffff), shown as Brother PEC 29 "White"
            3. unnamed (#d9a400), shown as Brother PEC 11 "Deep Gold"
  preview   round-patch.png (269 × 269 pixels)

round-patch.png shows what the machine will sew:

6. Sew it

Load round-patch.pes and sew it as in your first sew-out. Thread blue first, white when the machine stops, and gold when it stops again.

Dialogs taller than the screen

From VectorCraft 0.14 the rows of a dialog taller than the window scroll, and a section’s heading folds its rows away. The satin’s dialog is taller than most screens.

VectorCraft 0.12 and 0.13 don’t scroll a plug-in’s dialog, and list every setting under its Ink/Stitch name. The fill’s and the satin’s dialogs are taller than most screens there, and the stroke’s is taller than the window VectorCraft opens with. Their first rows, or the OK button, can be out of sight. Make VectorCraft’s window as tall as the screen allows, and click a field you can see. Tab and Shift+Tab move to the others, and Enter applies the dialog.

Next

Embroider a VectorCraft design shows how to leave objects out and mark where a shape starts and ends. It also explains what stitch export says.

How-to guides

Each guide solves one problem:

• Check a machine file before sewing with stitch inspect and stitch preview
• Convert between machine formats with stitch convert
• Fit a design to the hoop when it is larger than the hoop or the comfort zone
• Embroider a VectorCraft design with the plug-ins and stitch export
• Make satin columns and keep presets in VectorCraft with VectorCraft’s own commands and Graphic Styles
• Report a bug with a bundle that reproduces it (stitch bug-report)

Planned, each with the milestone that brings its feature:

Check a machine file before sewing

StitchCraft reads PES, PEC and DST files from any software. It can describe a file and draw what the machine will sew, before you spend thread on it. The examples use test sheet TS-02, written with stitch testsheet TS-02 -o TS-02.pes.

Describe the file

$ stitch inspect TS-02.pes --profile brother-pe800-5x7
TS-02.pes · PES (#PES0001) · "TS-02"
  sha256    7c9e1a79353ef17172d1125172635b7f37bce80a1328c936c5eafa436bfff90b
  size      120.0 × 70.0 mm
  stitches  93 stitches, 17 jumps, 16 trims, 2 colour changes, 1 stop
  extent    x -60.0 to 60.0 mm, y -35.0 to 35.0 mm from where the machine starts
  lengths   stitches from 2.50 to 2.50 mm
  threads   1. Red (#ed171f), shown as Brother PEC 5 "Red"
            2. Blue (#0a55a3), shown as Brother PEC 2 "Blue"
            3. Emerald Green (#00673e), shown as Brother PEC 54 "Emerald Green"
            4. Emerald Green (#00673e), shown as Brother PEC 54 "Emerald Green" — a stop: keep the same thread
  profile   brother-pe800-5x7 (Brother PE800 with its 5 × 7 in hoop)
            0 stitches longer than 12 mm, 0 shorter than 0.3 mm

• size is the width and height of the stitching.
• stitches counts the needle points, and the jumps, trims, colour changes and stops between them.
• extent gives the lowest and highest x and y of the stitching, from where the machine starts.
• lengths gives the shortest and the longest stitch, to a hundredth of a millimetre, and how many stitches do not move at all, when a file has any.
• threads lists the colour blocks in sewing order. Each colour is stored as a Brother palette colour in a PES file, which the line names. After a stop you sew on with the same thread.
• profile appears with --profile, with the number of stitches longer than the machine’s longest stitch and shorter than its shortest. stitch profiles lists the machines. A file does not say which stitches lock the thread, and StitchCraft’s lock stitches are as short as 0.2 mm on purpose. The line also counts the short stitches 0.2 mm or longer, which may be locks.

Look at it

$ stitch preview TS-02.pes -o TS-02.png --style simple
TS-02.png · 992 × 592 pixels
  from      TS-02.pes · PES (#PES0001) · "TS-02"
  style     simple, 8 pixels per millimetre

The simple style draws each stitch as a thin line with a dot at each needle point. A red cross marks a trim and a blue square a stop. Grey dashes show where the frame travels after a cut, and dashes in the thread’s colour show a jump thread left on the fabric.

Without --style simple, the picture shows the finished embroidery, with loose jump threads where they will be. The rendering design has the whole legend.

What to look for

• A design larger than the hoop, or than the machine’s comfort zone: see fit the hoop.
• Jump threads where you expected trims. Each one has to be cut by hand after sewing.
• Thread colours. The machine shows each block in its palette colour, and it sews whichever thread you load.

Convert between machine formats

stitch convert reads a PES, PEC or DST file and writes it as PES or DST. The output file’s extension picks the format, or --format names it. Each format records some things the other cannot, and the command says what changed.

PES to DST

DST is the format most commercial machines read. Here test sheet TS-02 is converted and the new file read back:

$ stitch convert TS-02.pes -o TS-02.dst
TS-02.pes · PES (#PES0001) → DST
  file      TS-02.dst (DST, 1085 bytes)
  sha256    88d453b2512bb535f9dd2205cbb0be753a5eb9b1700ae9abf2e88062fabff927
  size      120.0 × 70.0 mm
  stitches  93 stitches, 46 jumps, 14 trims, 3 colour changes, 0 stops
  threads   1. Red (#ed171f)
            2. Blue (#0a55a3)
            3. Emerald Green (#00673e)
            4. Emerald Green (#00673e) — a stop: keep the same thread
$ stitch inspect TS-02.dst
TS-02.dst · DST · "TS-02"
  sha256    88d453b2512bb535f9dd2205cbb0be753a5eb9b1700ae9abf2e88062fabff927
  size      120.0 × 70.0 mm
  stitches  93 stitches, 46 jumps, 14 trims, 3 colour changes, 0 stops
  extent    x -60.0 to 60.0 mm, y -35.0 to 35.0 mm from where the machine starts
  lengths   stitches from 2.50 to 2.50 mm
  threads   1. thread 1 (#000000)
            2. thread 2 (#000000)
            3. thread 3 (#000000)
            4. thread 4 (#000000)
            (DST stores no colours: each block is a pause for the next thread)

• Colours. A DST file records where the colour changes are, without the colours. The machine pauses at each colour change, and you load the next thread yourself. Note the thread list before you convert.
• Stops. DST has one pause command, for colour changes and stops alike. The stop in TS-02 reads back as a third colour change.
• Trims. DST has no trim command either. StitchCraft writes a trim as 3 short jumps that end where they started, and a machine set to cut at 3 jumps in a row cuts there.
• Long jumps. A DST record moves the frame at most 12.1 mm, and a longer jump takes several records. A jump longer than 24.2 mm takes 3 or more, and a machine set to 3 cuts the thread there too. SC-I0605 counts these extra cuts. After a tie-off they save you cutting the jump thread by hand. Without one, the end of the stitching can pull out.
• Jumps in a PES file. StitchCraft flags every jump in a PES file as a trim, as Ink/Stitch does, so TS-02 reads back with a trim before each of them, and its DST file cuts there. Only a PES file with plain jumps, as some other programs write, gets the extra cuts that SC-I0605 counts.

DST to PES

A PES file needs a colour for each thread, and a DST file has none to give. Each thread becomes a black placeholder, and SC-W0604 says so. The PES file gives each a Brother colour of its own, the nearest to black still free, from Black to Dark Gray, Dark Brown and on. The machine shows a new colour at each thread change, and pauses there as the DST file did. The colours it shows mean nothing. Load the threads the design’s author gives.

The machine formats design describes how each format is written and read.

Fit a design to the hoop

Each machine profile is a machine with one of its hoops, and its hoop size is the largest area the machine sews in that hoop. The reference Brother PE800 has a profile for each of its 3 hoops. The 5 × 7 in hoop sews 130 × 180 mm, the 4 × 4 in hoop 100 × 100 mm and the small hoop 20 × 60 mm. Commands plan for the 5 × 7 in hoop unless --profile names another.

Larger than the hoop

Here a border is 210 mm long, and stitch plan ends with an error instead of writing the file:

$ stitch plan wide.svg -o wide.pes
error SC-E0701: The design is 210.0 × 0.0 mm, but the Brother PE800 with its 5 × 7 in hoop sews at most 130 × 180 mm.
  hint: Scale the design down, or split it into parts sewn in separate hoopings.
  more: stitch explain SC-E0701
nothing was written
(exit status 1)

The exit status is 1. Scale the design down, or split it into parts that are sewn in separate hoopings. When turning the design by 90° makes it fit, the error offers that instead.

A smaller hoop

Name the hoop’s profile, and StitchCraft checks the design against that hoop. Test sheet TS-10B fills the 5 × 7 in hoop, so the 4 × 4 in hoop is too small for it:

$ stitch testsheet TS-10B --profile brother-pe800-4x4 -o TS-10B.pes
error SC-E0701: The design is 130.0 × 180.0 mm, but the Brother PE800 with its 4 × 4 in hoop sews at most 100 × 100 mm.
  hint: Scale the design down, or split it into parts sewn in separate hoopings.
  more: stitch explain SC-E0701
nothing was written
(exit status 1)

stitch profiles lists every profile with its hoop.

Larger than the comfort zone

A profile may also have a comfort zone: the part of the hoop where the fabric is taut enough for the stitches to land where they should. A design larger than it is still written, with a warning. stitch explain says more about any code:

$ stitch explain SC-W0702
SC-W0702: Design is larger than the comfort zone

The design fits the hoop but is larger than the profile's comfort zone: the area where this
machine and hoop sew most accurately. Near the hoop's edge fabric is held less firmly, so large
designs pucker and shift more.

The file was written. Rotate the design if the message says that brings it inside the comfort
zone, use a firmer stabilizer, or scale the design down.

The built-in profiles have no comfort zone yet. A sew-out that shows a hoop’s edges sewing badly would give its profile one.

Embroider a VectorCraft design

Draw the design in VectorCraft, and say how each object sews with the StitchCraft plug-ins, which show its stitches as you work. Then write the machine file with VectorCraft’s File › Export › Export As, from VectorCraft 0.14, or with stitch export from the saved document. Both write the same file.

Choose each object’s stitches

With the plug-ins installed, select an object and choose Effect › Plug-ins › StitchCraft Fill, StitchCraft Stroke or StitchCraft Satin. The dialog holds Ink/Stitch’s settings for that kind of stitch, and the object shows its stitches in place of its art. The thread is the colour of the object’s fill for a fill, and of its stroke for a stroke or a satin column.

From VectorCraft 0.14 each setting has a label and its unit, in the sections of the parameter reference. Rest the pointer on a label for its help, or press the button after the field for its page in the reference. A setting shows only when it applies: a satin’s staggers show for staggered splits. VectorCraft before 0.14 lists every setting, each under its Ink/Stitch name.

An object without a StitchCraft effect sews as Ink/Stitch sews a shape of an SVG file. Its fills are filled, and its strokes are sewn as running stitch. With stitch export --auto, StitchCraft chooses its stitches by width instead, as for a picture traced into shapes.

• A line up to 1 mm wide runs, or up to the narrowest satin stroke the document keeps (below). From 0.5 mm wide it is a triple run, each stitch sewn 3 times.
• A line up to 7 mm wide is a satin column as wide as drawn, its round or square caps included.
• A wider line, or a fill, is a tatami fill. A part of a fill no wider than the narrowest satin stroke anywhere runs along its middle, as so narrow a line does.

Objects are sewn in the order they are drawn, the bottom one first. Satin columns and presets in VectorCraft shows how to draw a column with 2 rails, and how to keep settings in graphic styles.

Leave out what isn’t to be sewn

Name an object or a layer stitch:ignore, by double-clicking its name in the Layers panel, and it is left out with everything in it. Placement lines, notes and pictures to trace stay in the drawing this way. A note can follow the name after a space, as in stitch:ignore placement line. Upper and lower case are read alike. A hidden object is left out too.

VectorCraft’s preview can’t see names. An object named stitch:ignore that a StitchCraft effect sews, its own or its group’s, still shows its stitches there, and stitch export leaves it out.

Write the machine file

With the exporters installed, choose File › Export › Export As, and PES embroidery (StitchCraft) or DST embroidery (StitchCraft) as the format. Once the file is picked, a dialog shows 2 options:

• Digitize automatically, which chooses the stitches of the objects without a StitchCraft effect by their width, as stitch export --auto does.
• Machine, the machine and hoop the design is planned for: document, the one the document keeps (below), or brother-pe800-5x7 when it keeps none, unless another is chosen. stitch profiles lists them.

The design takes the file’s name, which machines show. What stitch export would say about the design shows with the export’s warnings, one line for each message. When one of them is an error, nothing is written, and VectorCraft says the first. VectorCraft lets an export run for a while, and stops one that needs more: stitch export writes it.

Or save the document, and run stitch export on it. This patch has a fill, a satin border, a curve of running stitch and 2 squares in a group that a graphic style’s fill effect sews. Its placement line is named stitch:ignore placement line:

$ stitch export patch.vectorcraft -o patch.pes --preview patch.png
patch.vectorcraft
  file      patch.pes (PES v1, 6656 bytes)
  sha256    6236ce2cb1bc9db739830a38a457cff67689195f86e1200e79b846240d943457
  profile   brother-pe800-5x7 (Brother PE800 with its 5 × 7 in hoop)
  size      50.0 × 54.0 mm
  stitches  2466 stitches, 5 jumps, 4 trims, 3 colour changes, 0 stops
  threads   1. unnamed (#bf0000), shown as Brother PEC 5 "Red"
            2. unnamed (#0033b3), shown as Brother PEC 21 "Ultramarine"
            3. unnamed (#008033), shown as Brother PEC 56 "Moss Green"
            4. unnamed (#e6b31a), shown as Brother PEC 11 "Deep Gold"
  preview   patch.png (432 × 464 pixels)
info SC-I0811 (vc:10): The object "stitch:ignore placement line" is named stitch:ignore, and is left out with everything in it.
  hint: Rename it to stitch it.
warning SC-W0807 (vc:4): The object "stitch:start" marks where the shape grouped with it starts, and is not stitched. StitchCraft doesn't yet start a shape at a marker: it chooses where.
warning SC-W0807 (vc:7): A group "Dots" has fills or strokes of its own, which VectorCraft paints what it holds with. They are not stitched as shapes of their own, and give their thread and stroke to the StitchCraft effects they paint.
  hint: Make objects of them with Object › Expand Appearance.

stitch export writes the file for the machine --profile names, or else the one the document keeps, or else brother-pe800-5x7, and --preview adds a picture. It is stitch plan by another name, which reads an SVG file the same way and takes the same options.

StitchCraft reads documents of up to 64 MiB. Pictures embedded to trace from can make one larger: place them with Link checked in VectorCraft’s Place dialog, and VectorCraft saves a small preview of each in the document instead.

Keep the design’s settings and machine with it

From VectorCraft 0.16, a document can keep the machine it is for, and the 3 settings Ink/Stitch keeps with a design for all of its objects. With the plug-ins installed, choose Object › Plug-ins › StitchCraft Design Settings, set them, and press OK:

• Machine, the machine and hoop the design is planned for, brother-pe800-5x7 by default.
• Shortest jump, Shortest stitch and Narrowest satin stroke, in millimetres. Rest the pointer on a label for what each does.

The document saves them. The exporters and stitch export plan the design for the machine it keeps, unless the export’s Machine option or --profile names another. They use its settings as they use an SVG file’s design settings. Whatever is selected, the filter leaves every object as it is.

VectorCraft opens the dialog at the defaults each time, not at what the document keeps, so set all 4 when you run it again. A live effect isn’t given what the document keeps. The stitches shown as you work are planned for brother-pe800-5x7 with the default settings, and a longer shortest stitch shows only in the machine file and in stitch export --preview. A setting that StitchCraft can’t read keeps its default, and stitch export says so (SC-W0812).

Draw a test sheet

The test sheets drawn as designs, TS-02B to TS-09, can start from VectorCraft 0.16 and later. With the plug-ins installed, choose Object › Plug-ins › StitchCraft Test Sheet, pick the sheet, and press OK. Rest the pointer on Sheet for what each one tests. The sheet is drawn in the middle of the artboard, each shape with its StitchCraft effect and settings, and shows its stitches. Write it as any design, with File › Export › Export As. Selected objects stay as they are, and the sheet goes above them, in their group or layer.

The sheet sews as stitch testsheet writes it, moved. A fill’s rows lie where the document’s origin puts them, so they may fall a little elsewhere across a shape, and look the same. The threads keep their colours but not their names in the Brother palette, and the machine file is the same. StitchCraft Stroke, Satin and Fill must be installed: VectorCraft gives a new object only the effects of installed plug-ins. TS-01, TS-02 and TS-10A to TS-10C are drawn stitch by stitch, and come from stitch testsheet alone.

Read what it says

Each line under the summary names an object by its id in the document, such as vc:10, and says what was done with it. In the patch, the placement line is left out, as its name asks (SC-I0811). The start marker isn’t applied yet (below). The group’s own gold fill, which the graphic style put on it, isn’t sewn as a shape of its own, and gives the squares their thread. Other messages name what isn’t sewn as it is drawn, with the VectorCraft command that makes it sewable, such as Type › Create Outlines for text (SC-W0807). The diagnostic codes page explains each code, as stitch explain SC-W0807 does.

Start and end markers

A small path named stitch:start or stitch:end, grouped with a fill or a satin column, marks where the fill or the column is to start or end, as Ink/Stitch’s starting and ending positions do. A marker is never sewn, and a group or a layer is never a marker. StitchCraft doesn’t start or end a shape at one yet, and chooses where, as the patch’s start marker shows.

When it sews wrong

stitch bug-report design.vectorcraft --says "what is wrong" writes a bundle that includes the document. Report a bug says what to do with it.

Satin columns and presets in VectorCraft

The StitchCraft plug-ins add their effects to VectorCraft’s Effect › Plug-ins menu, and VectorCraft’s own commands do the rest of what a design needs.

Make a satin column VectorCraft can show

A satin column drawn as one path sews as wide as its stroke. From VectorCraft 0.14 StitchCraft Satin shows its stitches as wide as the object’s stroke. Before 0.14 VectorCraft gives an effect the path but not its stroke, and StitchCraft Satin leaves such a path as it is and says why (SC-I0810). It does so too for an object without a stroke of its own, such as a path a group’s stroke paints. The file still sews it. To see its stitches in VectorCraft then, draw the column with 2 rails:

1. Draw the column’s 2 edges as 2 paths.
2. Select both and choose Object › Compound Path › Make (Cmd+8).
3. With the compound path selected, choose Effect › Plug-ins › StitchCraft Satin.

Apply the effect after joining the rails. VectorCraft 0.10.0 and later keep the appearance of the path at the back, and earlier versions that of the path in front, which may not be the one with the effect. From 0.10.0, VectorCraft may also reverse the front path, and always does for 2 straight rails. The column turns it back (reverse_rails, automatic). A reversed ring also starts somewhere else, so of 2 rings the second starts at its node nearest the first’s start. The stitches are the same whatever node the rails were drawn from and whichever way they run.

Add a rung

Rungs set the angle of the stitches along the column. With the Pen tool, add a line across both rails where the stitches should run. Select it with the column, and choose Object › Compound Path › Make. From VectorCraft 0.10.0 the column, behind the line, keeps its effect. Before 0.10.0 the compound path takes the line’s appearance: apply StitchCraft Satin to it again.

Make a line into a satin column

From VectorCraft 0.17, Object › Plug-ins › StitchCraft Stroke to Satin makes each selected line into a satin column drawn with its 2 rails and rungs, as Ink/Stitch’s Stroke to Satin does. The line is the column’s centre line, and its stroke gives the column’s width: the topmost stroke that paints, as StitchCraft Satin follows. The rails and rungs are those StitchCraft makes of a satin column drawn as one path when it sews it. So the column sews as the line did with the satin effect, and its rails and rungs can then be edited.

1. Give each line a stroke as wide as the column.
2. Select the lines, and choose Object › Plug-ins › StitchCraft Stroke to Satin.

Each line becomes a compound path of its rails and rungs, without a fill, its stroke the line’s colour, one pixel wide. It has StitchCraft Satin with the line’s satin settings, or the defaults, in the place of the line’s StitchCraft effects, and keeps the line’s other effects. A path of several lines makes a column of each. A satin column already drawn with rails is left as it is. When a line can’t be made into a column, nothing changes, and VectorCraft says why (SC-E0814), for a path without a stroke, or a line whose column would sew less than the line: one too short or tight for its width, or one that crosses itself.

Making the rails of a curved line takes more work than a filter usually may do. So Stroke to Satin asks for more when it is installed, and VectorCraft asks you first, then runs it in the background with Cancel. StitchCraft Satin must be installed too. VectorCraft 0.15 and 0.16 run it with the time any filter gets, and stop it on most curved lines. Before 0.15 it asks for a newer VectorCraft (SC-E0813).

Keep settings as a preset

A graphic style keeps an appearance, StitchCraft’s effects included:

1. Select an object whose StitchCraft effect is set as you like it.
2. Choose Window › Graphic Styles › New Graphic Style.
3. Select other objects and click the style in the Graphic Styles panel.

Each object gets a copy of the effect, with the style’s parameters, and sews with them. A style applied to a group or a layer puts its effects on the group, and every path inside it sews with them. The style’s fills and strokes go on the group too, and VectorCraft paints them over the group’s contents. Each path inside sews in the colour on top, the style’s fill for a fill effect and the style’s stroke for a satin column, which follows its width. Where the style has no paint of that kind, or lets the path show through it, the path’s own paint of that kind gives the colour, and with none on either, the topmost paint of the other kind does. A path without paint under a style without any is invisible and isn’t sewn. To show the paths’ own colours over the style’s, drag the Contents row above the style’s fills and strokes in the Appearance panel. Keep StitchCraft’s effects at one level, though. A path that has its own StitchCraft effect inside such a group, or sits inside 2 such groups, is drawn as one effect run on the stitches of the other. It sews as the nearest effect says, and the command line warns about it (SC-W0807). Alt-clicking a style adds its effects to the object’s own, and an object with 2 fill effects sews twice.

Give each StitchCraft effect an object of its own. An object with 2 sews each on its shape, but VectorCraft draws the second on the stitches of the first, so the preview isn’t what is sewn, and the command line warns about it (SC-W0807). For a fill with an outline, copy the shape, choose Edit › Paste in Front, and give the shape behind a fill effect and the copy in front a stroke effect.

Turn a preview into paths

Object › Expand Appearance turns what an effect shows into ordinary objects, with strokes outlined. Those objects are the shapes the preview draws, and they sew differently from the effect. Expand a copy for a picture of the stitches, and keep the original to sew.

Draw a test sheet

Embroider a VectorCraft design shows how to draw a test sheet into a document from VectorCraft 0.16, and stitch testsheet writes every sheet.

Report a bug

When StitchCraft gets a design wrong, a maintainer needs one file to see what you saw: a bug-report bundle. Write one when:

• the stitches differ from the design
• a message is unclear
• StitchCraft crashes

Write the bundle

Run stitch bug-report with the design, an SVG file or a VectorCraft document, and the profile and format you sew with, and --auto if you planned it with --auto:

stitch bug-report design.svg --profile brother-pe800-4x4 --says "the zigzag's corners are rounded"

It plans the design exactly as stitch plan does and writes design.bug-report.json next to it (-o names another file). The bundle holds:

• your design file, whole, or a VectorCraft document’s JSON without the pictures after it, and the design name the machine file’s label holds;
• the profile, the format (--format pes|dst, the profile’s own by default) and the version of StitchCraft, and whether the shapes without settings were digitized automatically (--auto);
• a digest of the plan’s stitches, and the machine file’s size and digest;
• the messages, or the crash’s message;
• what you wrote with --says.

It holds your design. Share it only where you are happy for the design to be seen.

Report it

Open an issue at https://github.com/KaboomFox/stitchcraft/issues. Say what you expected and what you got, and attach the bundle. GitHub takes .json files up to 25 MB. Zip a larger one first.

When StitchCraft finds the bug itself

StitchCraft checks each plan before writing a machine file. If a check fails (SC-E0009) or StitchCraft crashes, stitch plan (or stitch export) writes the bundle for you in place of the machine file. The bundle goes next to the file you named, as design.bug-report.json for design.pes. The command says where it is and ends with exit status 4. Attach that bundle to an issue.

For maintainers: replay a bundle

stitch bug-report --replay design.bug-report.json

This plans the bundled design again with the bundled profile and format, and compares everything the bundle recorded:

design.bug-report.json: written by StitchCraft 0.1.0 on windows x86_64, replayed by 0.1.0 on linux x86_64
  design        same: design.svg (sha256 …)
  plan          same: 118 stitches, 4 jumps, 0 trims, 2 colour changes, 0 stops (sha256 …)
  machine file  same: 1725 bytes (sha256 …)
  diagnostics   same: 2
reproduced

StitchCraft gives the same plan, bit for bit, for the same design, profile, format and version on every platform, so with the version that wrote the bundle, the replay reproduces it. With another version, what differs is listed under then: and now:: that is how to tell whether a bug is fixed. The exit status is 1 when the bundle does not reproduce. The design is in the bundle’s design.svg field, ready to save and open, or in design.svg_hex as hexadecimal when the file is not UTF-8 text, as a Latin-1 SVG is not. Of a VectorCraft document, the bundle keeps the part StitchCraft reads, in design.vectorcraft: its JSON, without the images and other data VectorCraft keeps after it. Compressed documents are kept whole, in design.vectorcraft_hex. A bundle also names the commit StitchCraft was built from, when it was built from a git checkout, which stitch --version shows too: until the first release, every build says the same version.

Anyone can attach a bundle to an issue. The replay writes each character from it that a terminal would act on as an escape, such as \u{1b} for the one that starts a terminal’s control sequences.

Stitch types

StitchCraft turns each element of a design into stitches of one type. In an SVG file an element is the stroke or the fill of a shape, and each sews in its own thread colour.

Every element also gets lock stitches where its stitching starts and ends, and a trim or a stop after it when it asks for one. An element of a type that is not sewn yet is left out, and SC-W0011 names it. The roadmap says what each milestone adds.

Setting parameters

A parameter belongs to one element. Ink/Stitch stores parameters in the SVG file as attributes, such as inkstitch:running_stitch_length_mm="1.5", and StitchCraft’s parameters have the same names and defaults.

stitch plan does not read these attributes yet, and every element sews with the defaults. SC-W0802 says so when a file has them. The SVG reader reads them from milestone M8, and the VectorCraft plug-in sets them from M6. Ink/Stitch’s trim and stop commands are read today.

The pictures on these pages set parameters on the engine directly, to show what each one does.

Running stitch

A running stitch is a line of single stitches along a path. StitchCraft sews each stroke of an SVG design with it, unless the stroke’s stroke_method names another stitch. Use it for outlines, fine details and lettering at small sizes.

The pictures on this page are drawn by StitchCraft’s own engine and renderer, from the designs in docs/fixtures/. Each dot is a needle point, and orange rings mark the lock stitches at each end. Each parameter is set per element, and setting parameters says what stitch plan reads today.

Stitch length

running_stitch_length_mm sets how long each stitch is, 2.5 mm by default. Between 2 corners the stitches are spread evenly, and none is longer than the stitch length.

1.5 mm

2.5 mm

4 mm

Short stitches follow a curve closely and make more needle holes. Long stitches are quicker to sew and show more of each stitch. With a list of lengths, such as 2.5 1, the stitches take the lengths one after another along the path.

Corners and curves

Where the path turns by more than 30°, StitchCraft puts a needle point on the corner, and the line keeps its shape. Along a curve, a stitch strays from the curve by at most running_stitch_tolerance_mm, 0.2 mm by default. With a long stitch length the tolerance shows. Here a half disc is sewn in stitches up to 6 mm long. Both corners of its straight side get a needle point in every panel. The tolerance sets how closely the stitches follow the curve.

0.1 mm	0.5 mm	2 mm

At 2 mm the curve is sewn in 3 straight stitches, and the half disc comes out as a trapezoid. At 0.1 mm StitchCraft sews the curve in more stitches, still all of one length, until each keeps within 0.1 mm of it, and the curve comes out round.

Bean stitch and repeats

bean_stitch_repeats sews each stitch more than once, for a bolder line. At 1 each stitch is sewn 3 times, there, back and there again, and at 2 it is sewn 5 times. With a list such as 1 0, the stitches alternate between bold and plain.

repeats sews the whole path more than once. At 2 the needle goes there and back, and at 3 there, back and there again. With an even number the stitching ends where it started.

Random stitch length

Rows of running stitch close together line their needle points up across the rows, and the eye sees stripes. enable_random_stitch_length varies each stitch’s length by up to random_stitch_length_jitter_percent, 10 % by default, and the stripes go.

even

random

The stitching still ends on each corner. random_seed sets where the random lengths start. The same element and seed give the same stitches every time, on every computer, and elements alike given the same seed vary alike. Left empty, each element varies its own way.

Manual stitch

With stroke_method set to manual_stitch, each node of the path is a needle point and nothing else is. A curve gives only its end node. Use it to place stitches by hand, or to sew a stitch file that was traced as a path.

running stitch	manual stitch

max_stitch_length_mm splits a hand-placed stitch that is longer into equal parts. Bean stitch applies to manual stitch, and repeats do not.

The shortest stitch

A stitch shorter than the shortest stitch the machine sews well hammers one hole. StitchCraft never sews one. The shortest stitch is the machine profile’s, 0.3 mm on the reference Brother, or the element’s own min_stitch_length_mm when that is longer. A part of the path too short for a stitch is left out, and SC-W0401 names it. A stitch length below twice the shortest stitch is raised to that, and SC-W0402 says so.

Parameters

The reference lists each parameter with its range and default, on a page for each group:

• running stitch
• repeats and bean stitch
• the stroke method
• the settings every stitch type shares, with manual stitch’s longest stitch

Zigzag stroke

A zigzag stroke crosses a path from side to side and back, as wide as the stroke’s line. Set an element’s stroke_method to zigzag_stitch for it. Use it for a light border, a couched look, or a stem too thin for a satin column.

In VectorCraft, set the StitchCraft Stroke effect’s stroke_method to zigzag_stitch, and stitch export sews it. VectorCraft’s live effect shows the object as it is drawn, as wide as the zigzag, since VectorCraft does not tell a plug-in a stroke’s width. stitch plan reads Ink/Stitch’s settings from SVG files from milestone M8 (setting parameters).

The pictures are drawn as the running stitch’s are, from docs/fixtures/zigzag.svg, a wave drawn 3 mm wide.

Spacing

zigzag_spacing_mm is how far it is along the path from one stitch to the next that crosses the same way, a zig and a zag together, 0.4 mm by default. The needle points are spread evenly along the path, in a whole number of zigs and zags, so the zigzag starts and ends on the same side.

0.4 mm

1 mm

2 mm

Ink/Stitch takes a list of spacings and sews the first, and so does StitchCraft.

Width and pull compensation

The zigzag is as wide as the stroke’s line. Thread pulls the fabric in along each stitch, and a zigzag sews narrower than it is drawn. stroke_pull_compensation_mm takes each side further out by its value. One value widens both sides. With 2, the first is for the left of the way the path goes and the second for its right. A negative value makes the zigzag narrower.

Angle

zigzag_angle turns every stitch away from square to the path, from −89° to 89°. A positive angle turns the stitches clockwise as the drawing shows them. On a curve the turned stitches point like the spokes of a wheel.

0°

45°

−45°

Repeats and bean stitch

repeats sews the zigzag more than once, every other time backwards, and bean_stitch_repeats sews each stitch more than once, as for a running stitch.

A closed path

A path that ends where it starts ends its zigzag on its first needle point, and the line closes without a gap.

The shortest stitch

Across a zigzag much narrower than the shortest stitch the machine sews well, its stitches are too short, and StitchCraft leaves their needle points out when it finishes the plan (SC-I0504). A part of the path that is one point is left out, and SC-W0401 names it.

Parameters

The reference lists each parameter with its range and default:

• zigzag stroke
• repeats and bean stitch
• the stroke method

E-stitch

An E-stitch edges appliqué. A row of stitches runs along one edge of a band, its spine, and at each step a spike reaches across the band and comes back, like a row of E’s laid end to end. It is the blanket stitch, which holds an appliqué’s raw edge down with far less thread than a satin column. Ink/Stitch’s documentation suggests it for appliqué on clothes for small children. Set an element’s satin_column on and its satin_method to e_stitch for it.

Draw it as a satin column, with 2 rails along the band’s edges. The spine runs along the first rail, and the spikes go across to the second. Rungs across the rails, where they turn, keep the spikes square to the band.

In VectorCraft, join the 2 rails with Object › Compound Path › Make and apply the StitchCraft Satin effect to them, with its satin_method set to e_stitch. The effect shows its stitches, and stitch export sews them. An SVG file’s Ink/Stitch settings are read from milestone M8 (setting parameters).

The pictures are drawn from docs/fixtures/e-stitch.svg, a curved band 4 mm wide.

Spacing

zigzag_spacing_mm is how far apart the spikes are, 0.4 mm by default as for a satin column. An E-stitch wants it wider: 2 or 3 mm leaves the fabric between the spikes showing.

1 mm

2 mm

3 mm

Which edge

The spine runs along the first rail, the first subpath the path draws. swap_satin_rails puts it on the other rail, and the spikes then point the other way. Put the spine on the appliqué’s outer edge, over the raw edge of its fabric.

Rails swapped

Long spikes and long steps

Spikes longer than max_stitch_length_mm are split as a satin column’s stitches are, and each spike comes back down through the needle holes of its own splits. A step of the spine longer than the longest stitch is split only if the spacing as set is longer than the longest stitch, as in Ink/Stitch, so a step that random_zigzag_spacing_percent lengthens past it is sewn in one stitch. A stitch longer than 12 mm may snag, and SC-W0209 names it.

Leaning stitches

Without enough rungs, the points of the 2 rails pair up by length alone, and where one rail runs on ahead of the other the spikes lean along the band. Where they lean more than 45° from square to it, SC-W0208 names the place to add a rung. Every satin method gives both warnings.

Parameters

An E-stitch reads every setting of a satin column, from its underlays and compensation to its random variation and where it starts and ends. The reference lists each one with its range and default:

• satin column
• the settings every element shares

S-stitch

An S-stitch is a satin column sewn one way at a time. At each step one stitch crosses the band, the next crosses back, and between them the needle runs a short way along an edge. Its thread draws S’s laid end to end. Split by a longest stitch, its stitches lie across the band in rows that follow it, the look of a fill that bends with the shape. Turn an element’s satin_column on and choose s_stitch as its satin_method.

Draw it as a satin column, with 2 rails along the band’s edges and rungs across them where they turn. The first stitch goes from the second rail to the first, and swap_satin_rails starts it from the other.

In VectorCraft, make the 2 rails one path with Object › Compound Path › Make, give it the StitchCraft Satin effect, and set the effect’s satin_method to s_stitch: VectorCraft draws the stitches, and stitch export sews them. StitchCraft reads the same settings from an SVG file’s Ink/Stitch attributes from milestone M8 (setting parameters).

The pictures are drawn from docs/fixtures/s-stitch.svg, a curved band 6 mm wide.

Spacing

zigzag_spacing_mm is how far apart the stitches across are, 0.4 mm by default. Each goes the other way from the one before. A satin column at the same spacing crosses the band twice as often, as its needle comes back across between its stitches. A finer spacing covers the band more closely.

1 mm

0.4 mm

Split stitches

With max_stitch_length_mm set, a stitch across longer than it is split, as a satin column’s stitches are. By default the splits of neighbouring stitches line up, in rows along the band. The staggered split method moves each stitch’s splits along from the last one’s. The rows then slant, and the needle holes of neighbouring stitches no longer line up.

Default

Staggered

A step along an edge is never split, however long, as in Ink/Stitch. Where the spacing is wider than the longest stitch, the steps are longer than it.

Leaning and long stitches

Where the stitches lean more than 45° from square to the band, without enough rungs, SC-W0208 names the place to add one, and SC-W0209 names a top stitch longer than 12 mm, which may snag. Every satin method gives both.

Parameters

Every satin column setting applies to an S-stitch too, its underlays, compensation and random variation included. The reference gives each one’s range and default:

• satin column
• the settings every element shares

Zigzag satin

A zigzag satin is a satin column sewn as a zigzag. Every stitch slants across the band, from a point on one edge to a point on the other half the spacing along, and the next slants back. Turn an element’s satin_column on and choose zigzag as its satin_method. It is drawn, and set up in VectorCraft, as an S-stitch is, with zigzag in place of s_stitch. Its first stitch goes from the first rail to the second, and swap_satin_rails starts it from the other.

The pictures use the S-stitch’s band, docs/fixtures/s-stitch.svg.

Spacing

zigzag_spacing_mm is how far apart the zigzag’s points are along each edge, 0.4 mm by default, as for a satin column. The 2 edges take turns, half the spacing apart, and the needle crosses the band as often as a satin column’s does. A finer spacing covers the band more closely.

1 mm

0.4 mm

Beside a satin column

A satin column’s stitches across go square to the band, and each stitch back slants to the next one across. Every stitch of a zigzag satin slants, half as far along the band as a satin column’s stitch back.

Zigzag satin

Satin column

Split stitches

With max_stitch_length_mm set, a stitch longer than it is split, as a satin column’s stitches are, and split_method says where the splits go. By default each stitch splits into its own fewest equal parts, where a satin column’s stitch back splits into as many as the stitch across before it, as in Ink/Stitch.

Underlays

A zigzag satin sews a satin column’s underlays. Its contour underlay stops where the zigzag’s points stop on each edge, so that it stays under the stitches, as Ink/Stitch’s does. After an odd centre walk Ink/Stitch’s stops elsewhere, as the contour_underlay reference says.

Leaning and long stitches

A zigzag satin gives the 2 warnings of every satin method, which the S-stitch page describes. SC-W0208 measures how the rails pair up, where a satin column’s stitches across would go. The slant every zigzag stitch has by design, the more the wider the spacing and the narrower the band, is left out of it.

Parameters

Every satin column setting applies to a zigzag satin too, its underlays, compensation and random variation included. The reference gives each one’s range and default:

• satin column
• the settings every element shares

Lock stitches, trims and stops

A lock, or tie, is a few small stitches where stitching starts (the tie-in) or ends (the tie-off). It stops the thread from pulling out when the machine cuts it or jumps to the next part. StitchCraft adds the locks an element’s settings call for, and a trim or a stop after an element that sets trim_after or stop_after.

Where locks go

The needle sews straight on from one part of a design to the next when nothing separates them: the same thread, and a gap of at most 3 mm (the collapse length) or the element’s min_jump_stitch_length_mm. There it sews no locks. Anywhere else the stitching ends with a tie-off, the needle jumps, and the next part starts with a tie-in.

• ties chooses which ends get a lock. By default both ends do. It can also choose the start or the end alone, or neither.
• force_lock_stitches adds the tie-off at the end of each part, even where the next part is close enough to sew on.
• Manual stitch gets locks only when force_lock_stitches is set, because its needle points are placed by hand.

Lock shapes

lock_start and lock_end choose the shape at each end. The default, the half stitch, goes forth and back twice over half the first stitch, and the stitching covers it. back_forth does the same over steps of lock_start_scale_mm and lock_end_scale_mm, 0.7 mm by default.

The drawn shapes are larger. lock_start_scale_percent and lock_end_scale_percent size them, 100 % by default. Each picture shows an 8 mm line with the shape at both ends:

arrow	bowtie	cross	star

simple	triangle	zigzag	half_stitch

The shapes are StitchCraft’s own designs, sized to hide under the stitching they secure. A file from Ink/Stitch that names a shape gets StitchCraft’s shape of that name.

A custom lock (custom) is your own steps, written in lock_custom_start and lock_custom_end as numbers in sizes of the scale in millimetres. Positive steps go into the stitching. 1 -1 1 -1 goes forth and back twice, as back_forth does. The steps follow the stitching round its corners.

Every lock stitch is at least 0.2 mm long, to keep the needle out of the hole it has just left. StitchCraft lengthens a step or enlarges a drawn lock that would be smaller, and SC-W0502 says so.

Trims and stops

• trim_after cuts the thread after the element, with a tie-off before the cut.
• stop_after pauses the machine after the element, while you place appliqué fabric or check the work. When the design has a stop position, the frame moves there before each stop.

A PES file marks a trim on the jump after it. Some Brother machines are reported to ignore that mark, and test sheet TS-02 checks what the reference machine does. DST has no trim command. StitchCraft writes a trim there as 3 short jumps that end where they started, and a DST machine set to cut at 3 jumps in a row cuts there. The machine formats design says how each format records a trim.

Parameters

Common parameters lists each of these settings with its range and default.

Embroidery basics

Machine embroidery is drawing with thread under tension on fabric that moves. Almost every setting in StitchCraft exists because of one of the effects below. Terms in bold are in the glossary.

Stitches are straight lines between holes

The machine moves the hoop and drops the needle: each stitch is a straight segment between two needle penetrations. A curve is a chain of short stitches; the shorter they are, the smoother the curve but the more holes the fabric takes. Too short (under about 0.3–0.5 mm) and the needle hits the same hole, which shreds thread and fabric; too long (beyond about 7 mm on exposed satin, 12 mm anywhere) and stitches snag and sag.

Three stitch families

• Running stitch — a dotted line of single stitches, for outlines, details and travel underneath. Bean stitch sews each stitch three (or more) times for a bold line.
• Satin — stitches swing side to side between two edges, making the glossy band seen in lettering and borders. Good from about 1.5 mm to 8–10 mm wide.
• Fill — rows of running stitches covering an area. Tatami offsets the needle points from row to row so no lines show.

The fabric fights back: pull and push

Thread under tension pulls the fabric together across the stitch direction: a satin column ends up narrower than drawn, a fill shorter across its rows. The same stitches push fabric outward along the stitch direction, so columns grow at their ends. Pull compensation widens what is sewn so the result matches what was drawn. How much depends on fabric, stabilizer, density and thread — which is why machine test sheet TS-07 exists.

Underlay: the foundation

Underlay is a light layer sewn first: it tacks fabric to stabilizer, lifts the top stitches so they look full, and stops fabric texture poking through. Satins use centre-walk, contour or zigzag underlay; fills use a sparse fill at a cross angle.

Density

Row spacing (fills) and zigzag spacing (satins) set density. Denser covers better but stiffens the fabric, adds stitches and time, and increases pull. Around 0.4 mm suits most 40 wt thread on woven fabric; small text and knits want different values.

Stabilizer and hooping

Stabilizer backs the fabric so it does not distort. Tear-away suits stable wovens; cut-away suits knits and dense designs. Hoop the fabric drum-tight without stretching it. Most “the design is wrong” problems on the machine are stabilizer or hooping problems; the test-sheet protocol keeps these constant so we test the design, not the setup.

Jumps, trims and locks

Moving from one place to another without sewing is a jump; cutting the thread is a trim. Before a trim or colour change the thread is secured with a lock stitch (tie-off), and after it with a tie-in, so nothing unravels. Short moves are cheaper sewn as travel stitches hidden under later stitching.

Hoops and their fields

A hoop keeps the fabric drum-tight, and the machine sews only inside the hoop’s field, which is smaller than its frame. The reference Brother PE800’s 5 × 7 in hoop sews at most 130 × 180 mm, and its 4 × 4 in hoop 100 × 100 mm. The fabric is most stable near the centre, and large dense designs pull more. A design sews best in the smallest hoop it fits. StitchCraft stops with an error at a design larger than the hoop it plans for, and warns beyond a profile’s comfort zone where the profile has one.

Reference

Most reference pages are generated from the code they describe, so they cannot drift from it: cargo xtask docs rewrites them, and CI fails when one is stale.

Command line

stitch is StitchCraft’s command-line tool. Each section shows the command’s own --help.

stitch

stitch: the StitchCraft command-line tool

Usage: stitch <COMMAND>

Commands:
  plan        Plan a design, an SVG file or a VectorCraft document, for a machine and write the machine file, with a picture and a report if asked [alias: export]
  testsheet   Write a machine-checkpoint test sheet (docs/src/plan/machine-testing.md)
  inspect     Read a machine file (PES, PEC or DST) and describe it: size, stitches, threads, stitch lengths
  preview     Draw a machine file (PES, PEC or DST) as a picture of what it will sew (PNG)
  convert     Write a machine file (PES, PEC or DST) in another format
  profiles    List the built-in machine profiles
  explain     Explain a diagnostic code, such as SC-W0702
  bug-report  Write a bug-report bundle that reproduces what StitchCraft does with a design, or replay one
  help        Print this message or the help of the given subcommand(s)

Options:
  -h, --help
          Print help

  -V, --version
          Print version

Exit status: 0 done (warnings allowed) · 1 the design or file has errors (nothing written) · 2 usage
error · 3 a file could not be read or written · 4 a bug in StitchCraft (a bug-report bundle is written
where it can be: see `stitch bug-report`).

stitch plan

Plan a design, an SVG file or a VectorCraft document, for a machine and write the machine file, with a picture and a report if asked

Usage: stitch plan [OPTIONS] --output <OUTPUT> <DESIGN>

Arguments:
  <DESIGN>
          The design: an SVG file, or a VectorCraft document (.vectorcraft)

Options:
  -o, --output <OUTPUT>
          The machine file to write

  -p, --profile <PROFILE>
          The machine profile (see `stitch profiles`); by default the one a VectorCraft document keeps, which StitchCraft's Design Settings filter sets, or else the reference machine, which `stitch profiles` lists first

      --format <FORMAT>
          The file format; by default the output file's extension decides

          Possible values:
          - pes: Brother PES, version 1
          - dst: Tajima DST

      --preview <PREVIEW>
          Also draw a picture of what the file will sew (PNG)

      --report <REPORT>
          Also write a report of the plan and what was said about it (JSON), even when nothing else is written

      --auto
          Digitize automatically the shapes that have no settings: StitchCraft chooses the stitches of each by its width (docs/src/design/image-to-embroidery.md). A shape with settings is left to them

      --sort-colours
          Sew the shapes with settings in the order StitchCraft chooses too, as --auto sews the shapes it digitizes: shapes that overlap keep their paint order, and each thread then sews as long as it can, the nearest shape next (docs/src/design/image-to-embroidery.md)

  -h, --help
          Print help (see a summary with '-h')

stitch testsheet

Write a machine-checkpoint test sheet (docs/src/plan/machine-testing.md)

Usage: stitch testsheet [OPTIONS] [SHEET]

Arguments:
  [SHEET]
          The sheet, such as TS-01 (see --list)

Options:
      --list
          List the test sheets and exit

  -p, --profile <PROFILE>
          The machine profile to check the sheet against (see `stitch profiles`); by default the one for the hoop the sheet is sewn in

  -o, --output <OUTPUT>
          The file to write

      --format <FORMAT>
          The file format; by default the output file's extension decides

          Possible values:
          - pes: Brother PES, version 1
          - dst: Tajima DST

  -h, --help
          Print help (see a summary with '-h')

stitch inspect

Read a machine file (PES, PEC or DST) and describe it: size, stitches, threads, stitch lengths

Usage: stitch inspect [OPTIONS] <FILE>

Arguments:
  <FILE>
          The machine file

Options:
  -p, --profile <PROFILE>
          Also check the design against a machine profile (see `stitch profiles`)

  -h, --help
          Print help

stitch preview

Draw a machine file (PES, PEC or DST) as a picture of what it will sew (PNG)

Usage: stitch preview [OPTIONS] --output <OUTPUT> <FILE>

Arguments:
  <FILE>
          The machine file

Options:
  -o, --output <OUTPUT>
          The picture to write (PNG)

      --style <STYLE>
          How the picture looks

          Possible values:
          - realistic: The finished embroidery on fabric, with the jump threads the machine leaves for you to cut
          - simple:    Every stitch, needle hole, move, trim and stop, for checking a design
          
          [default: realistic]

      --scale <SCALE>
          Pixels per millimetre
          
          [default: 8]

  -h, --help
          Print help (see a summary with '-h')

stitch convert

Write a machine file (PES, PEC or DST) in another format

Usage: stitch convert [OPTIONS] --output <OUTPUT> <FILE>

Arguments:
  <FILE>
          The machine file to read

Options:
  -o, --output <OUTPUT>
          The file to write

      --format <FORMAT>
          The file format; by default the output file's extension decides

          Possible values:
          - pes: Brother PES, version 1
          - dst: Tajima DST

  -h, --help
          Print help (see a summary with '-h')

stitch profiles

List the built-in machine profiles

Usage: stitch profiles

Options:
  -h, --help
          Print help

stitch explain

Explain a diagnostic code, such as SC-W0702

Usage: stitch explain <CODE>

Arguments:
  <CODE>
          The code

Options:
  -h, --help
          Print help

stitch bug-report

Write a bug-report bundle that reproduces what StitchCraft does with a design, or replay one.

The bundle is one file to attach to an issue, and it holds the design. With --replay, plan a bundle's design again and compare; the exit status is 1 when it does not reproduce.

Usage: stitch bug-report [OPTIONS] [DESIGN]

Arguments:
  [DESIGN]
          The design StitchCraft gets wrong: an SVG file, or a VectorCraft document (.vectorcraft)

Options:
      --replay <REPLAY>
          Replay this bundle instead: plan its design again, with the profile and format it names, and say whether everything comes out the same

  -o, --output <OUTPUT>
          The bundle to write; by default next to the design, as DESIGN.bug-report.json

  -p, --profile <PROFILE>
          The machine profile (see `stitch profiles`); by default the one a VectorCraft document keeps, which StitchCraft's Design Settings filter sets, or else the reference machine, which `stitch profiles` lists first

      --format <FORMAT>
          The file format; by default the profile's

          Possible values:
          - pes: Brother PES, version 1
          - dst: Tajima DST

      --says <SAYS>
          What goes wrong, in your words; it goes into the bundle

      --auto
          Digitize automatically the shapes that have no settings: StitchCraft chooses the stitches of each by its width (docs/src/design/image-to-embroidery.md). A shape with settings is left to them

      --sort-colours
          Sew the shapes with settings in the order StitchCraft chooses too, as --auto sews the shapes it digitizes: shapes that overlap keep their paint order, and each thread then sews as long as it can, the nearest shape next (docs/src/design/image-to-embroidery.md)

  -h, --help
          Print help (see a summary with '-h')

stitch help

Print this message or the help of the given subcommand(s)

Usage: stitch help [COMMAND]...

Arguments:
  [COMMAND]...
          Print help for the subcommand(s)

Machine profiles

A profile holds the facts about one machine and hoop that decide what StitchCraft may ask of it. Its values are machine facts: they change only with a sew-out report that justifies them, and each profile says where its values come from. stitch profiles prints the same list.

brother-pe800-5x7

Brother PE800 with its 5 × 7 in hoop

Evidence. Machine: the owner of the reference machine (2026-10-10). Field: Brother’s 5 × 7 in hoop for the PE800, 130 × 180 mm. Stitch limits and trim support: common Brother home-machine values, to be confirmed by machine checkpoints MC-1 and MC-2 (test sheets TS-01 to TS-04 and TS-10).

brother-pe800-4x4

Brother PE800 with its 4 × 4 in hoop

Evidence. Hoop: the owner’s (2026-10-10). Field: Brother’s 4 × 4 in hoop, 100 × 100 mm. The rest as for brother-pe800-5x7.

brother-pe800-small

Brother PE800 with its small hoop

Evidence. Hoop: the owner’s, sold as 1 × 2.5 in (2026-10-10). Field: Brother’s small hoop, 2 × 6 cm, upright as the 5 × 7 in’s until test sheet TS-10C confirms it. The rest as for brother-pe800-5x7.

File formats

The machine-file formats StitchCraft writes. How each is encoded, and why, is in the machine formats design.

Test sheets

Designs drawn in code for the machine checkpoints, each for one hoop of the reference machine. Write one with stitch testsheet <id> -o <id>.pes. The command checks it against the profile of that hoop, or the one --profile names, and prints what to check after sewing it, as listed here. The pictures are previews: they show what the machine will sew, including jump threads it leaves for you to cut. In VectorCraft, the Test Sheet filter draws a sheet drawn as a design into a document (how).

TS-01 — Orientation and scale

120.0 × 120.0 mm · 274 stitches, 7 jumps, 7 trims, 0 colour changes, 0 stops

Hoop: the Brother PE800 with its 5 × 7 in hoop, profile brother-pe800-5x7.

Threads: Black.

After sewing, check:

• The F reads normally: not mirrored, not upside down, not turned.
• Each arm of the cross measures 100.0 ± 0.5 mm end to end, horizontally and vertically.
• The corner squares measure 10.0 mm on every side.
• Ticks are 10 mm apart; the long ticks mark the ends and the centre.

TS-02 — Colour changes, a stop, jumps and trims

120.0 × 70.0 mm · 93 stitches, 17 jumps, 8 trims, 2 colour changes, 1 stop

Hoop: the Brother PE800 with its 5 × 7 in hoop, profile brother-pe800-5x7.

Threads: Red, Blue, Emerald Green, Emerald Green (stop).

After sewing, check:

• The machine stops for red → blue and blue → green, and once more in the middle of the green line (the stop).
• Left half (red, a trim before every jump): for each row (gaps of 2, 5, 15, 30 mm, top to bottom), was the thread between the two dashes cut?
• Right half (blue, jumps without trims, which a PES file flags as trims too): did every dash sew? For each row, and between rows, was the thread cut?
• Any loose loops, knots or bird’s nests on the back, and where.

TS-02B — TS-02 drawn as a design: trims elements ask for

120.0 × 70.0 mm · 230 stitches, 17 jumps, 8 trims, 2 colour changes, 1 stop

Hoop: the Brother PE800 with its 5 × 7 in hoop, profile brother-pe800-5x7.

Drawn as a design, which VectorCraft’s Test Sheet filter draws too.

Threads: Red, Blue, Emerald Green, Emerald Green (stop).

After sewing, check:

• The machine stops for red → blue and blue → green, and once more in the middle of the green line (the stop), and cuts the thread at each.
• Left half (red; every dash but the last asks for a trim after it): the machine cuts no jump, so its rows (gaps of 2, 5, 15, 30 mm, top to bottom) are joined by threads. Did every dash stay sewn while the machine went on to the next?
• Right half (blue; no trims): the 2 mm gap is sewn across, and threads join the other dashes and the rows. Did every dash stay sewn?
• Each dash starts and ends with a small lock. Snip the threads between the dashes, then pull each tail gently: does the dash hold?
• Any loose loops, knots or bird’s nests on the back, and where.

TS-03 — Running stitch: lengths, bean stitch, curves, the shortest stitch

60.0 × 78.0 mm · 588 stitches, 15 jumps, 15 trims, 0 colour changes, 0 stops

Hoop: the Brother PE800 with its 5 × 7 in hoop, profile brother-pe800-5x7.

Drawn as a design, which VectorCraft’s Test Sheet filter draws too.

Threads: Blue.

After sewing, check:

• Running stitch lines (top five; 1.5, 2.0, 2.5, 3.0 and 4.0 mm): the stitches of each line are even; ten stitches, counted inside the small lock at each end, measure 15, 20, 25, 30 and 40 mm.
• Bean stitch lines (next two; each stitch sewn three and five times): solid and raised, with no gaps.
• Circles (6 mm across; tolerance 0.1, 0.2 and 0.5 mm, left to right): round, with fewer and straighter stitches to the right.
• Short stitches placed by hand (bottom five; 0.3, 0.4, 0.5, 0.7 and 1.0 mm, each with a small back-and-forth lock at both ends): which lines sew cleanly, with no thread breaks, knots or bunching on the back? The shortest clean one is the machine’s shortest stitch; if the 0.3 mm line is clean, it is 0.3 mm or less: the sheet has no shorter line.

TS-04 — Lock stitches: do they hold, and do they show?

110.0 × 64.5 mm · 623 stitches, 27 jumps, 27 trims, 0 colour changes, 0 stops

Hoop: the Brother PE800 with its 5 × 7 in hoop, profile brother-pe800-5x7.

Drawn as a design, which VectorCraft’s Test Sheet filter draws too.

Threads: Red.

After sewing, check:

• Rows, top to bottom: half stitch, arrow, back and forth, bowtie, cross, star, simple, triangle, zigzag. Each line has its lock at both ends and was trimmed after, but the machine cuts no jump: snip the threads between the lines, then pull each tail gently. Does the lock hold, or does the line come undone?
• Columns, left to right, are small, medium and large: the half stitch on first stitches of 1, 1.5 and 2.5 mm, back and forth at 0.5, 0.7 and 1.0 mm, the others at 70, 100 and 150 %.
• Rows 1, 3, 5, 7 and 9 are sewn left to right and the others right to left: a line’s start is the end it was sewn from.
• Which locks show from the front, and how much (1 hidden to 5 obvious)?
• Any thread breaks or knots at the locks, and where.

TS-05 — Satin width ladder: spacing, width and pull

91.0 × 76.0 mm · 3440 stitches, 30 jumps, 30 trims, 0 colour changes, 0 stops

Hoop: the Brother PE800 with its 5 × 7 in hoop, profile brother-pe800-5x7.

Drawn as a design, which VectorCraft’s Test Sheet filter draws too.

Threads: Blue.

After sewing, check:

• Rows, top to bottom, are at zigzag spacings of 0.3, 0.4 and 0.5 mm, and the columns of each row are 1 to 10 mm wide, left to right.
• Coverage: in which columns does the fabric show between the stitches? Rate each row 1 (bare) to 5 (solid).
• Width: measure the 2, 6 and 10 mm columns of each row across, halfway down. How much narrower than drawn are they?
• Edges: straight and crisp, or wavy? From which width on do the long stitches lie loose or catch?
• Any puckering round the columns, thread breaks, or loops on the back, and where.

TS-06 — Satin underlays side by side

62.0 × 30.0 mm · 966 stitches, 5 jumps, 5 trims, 0 colour changes, 0 stops

Hoop: the Brother PE800 with its 5 × 7 in hoop, profile brother-pe800-5x7.

Drawn as a design, which VectorCraft’s Test Sheet filter draws too.

Threads: Red.

After sewing, check:

• Columns, left to right: no underlay, a centre walk, a contour, a zigzag, and a contour with a zigzag, each 6 mm wide.
• Edges: rate each column 1 (ragged) to 5 (crisp).
• Loft: rate each column 1 (flat) to 5 (full and raised).
• Does any underlay show past the top stitches, at the edges or at the ends?
• Measure each column across, halfway down, and note any puckering round it.

TS-07 — Fill and outline registration at 3 pull compensations

126.2 × 126.0 mm · 13527 stitches, 6 jumps, 6 trims, 1 colour change, 0 stops

Hoop: the Brother PE800 with its 5 × 7 in hoop, profile brother-pe800-5x7.

Drawn as a design, which VectorCraft’s Test Sheet filter draws too.

Threads: Red, Black.

After sewing, check:

• Circles: top left with no pull compensation, top right with 0.2 mm, bottom with 0.4 mm. Each red fill is 60 mm across, with a black running stitch along its edge.
• At 12 points round each circle, as the hours of a clock: does fabric show between the fill and the outline, or does the fill reach past it? Measure the largest gap and the largest overlap of each circle.
• Measure each fill across, left to right and top to bottom. How much less than 60 mm is it, and how much of that does the compensation make up?
• Any puckering round the circles, and where.

TS-08 — Fill density and angle

100.0 × 170.0 mm · 16248 stitches, 15 jumps, 15 trims, 0 colour changes, 0 stops

Hoop: the Brother PE800 with its 5 × 7 in hoop, profile brother-pe800-5x7.

Drawn as a design, which VectorCraft’s Test Sheet filter draws too.

Threads: Blue.

After sewing, check:

• Rows, top to bottom, are at row spacings of 0.25, 0.3, 0.4, 0.5 and 0.6 mm, and the columns at angles of 0°, 45° and 90°, left to right. Each square is 30 mm wide.
• Coverage: in which squares does the fabric show between the rows? Rate each row of squares 1 (bare) to 5 (solid).
• At 0.25 mm the rows lie nearer each other than the machine’s shortest stitch of 0.3 mm. In the 0° and 90° squares, whose edges meet the rows square on, each row’s first needle point is left out: does a sliver of fabric show at the rows’ starts, along those edges? The 45° square’s rows end 0.35 mm apart along its edges and keep their starts.
• Stiffness: rate each row of squares 1 (soft) to 5 (stiff as card). Is there puckering round any square, or furrows where needle points line up?
• Measure the 0° and the 90° square at 0.4 mm across, both ways. How much less than 30 mm are they?

TS-09 — Fill underlay, travel and gap-filling rows round holes

66.0 × 114.0 mm · 7780 stitches, 6 jumps, 3 trims, 0 colour changes, 0 stops

Hoop: the Brother PE800 with its 5 × 7 in hoop, profile brother-pe800-5x7.

Drawn as a design, which VectorCraft’s Test Sheet filter draws too.

Threads: Emerald Green.

After sewing, check:

• Top to bottom: without underlay, with Ink/Stitch’s default underlay, and with the underlay and 2 gap-filling rows. Each is a 50 × 30 mm rectangle with a square hole and a round hole, and a bar 6 mm to its right that belongs to the same fill.
• Travel: does any running stitch between rows show on top of the fill? Where?
• The bar: was the thread to it cut, or does a jump thread run to it? Does the fill hold at both ends of that jump?
• Holes: are their edges clean, with no row across them and no fabric showing round them?
• Where the rows round a hole meet again, does a gap open along a row? Does the bottom copy, with gap-filling rows, close it?
• How the 3 copies differ in stiffness, and any puckering.

TS-10A — Hoop size: the 4 × 4 in hoop, a 100 × 100 mm frame

100.0 × 100.0 mm · 195 stitches, 4 jumps, 4 trims, 0 colour changes, 0 stops

Hoop: the Brother PE800 with its 4 × 4 in hoop, profile brother-pe800-4x4.

Threads: Blue.

After sewing, check:

• With the 4 × 4 in hoop on the machine: does the machine take the file and sew it, without asking for a larger hoop?
• The frame measures 100.0 × 100.0 mm (± 0.5 mm), the F at the top left.

TS-10B — Hoop size: the 5 × 7 in hoop, a 130 × 180 mm frame

130.0 × 180.0 mm · 283 stitches, 4 jumps, 4 trims, 0 colour changes, 0 stops

Hoop: the Brother PE800 with its 5 × 7 in hoop, profile brother-pe800-5x7.

Threads: Blue.

After sewing, check:

• With the 5 × 7 in hoop on the machine: does the machine take the file and sew it?
• The frame measures 130.0 × 180.0 mm (± 0.5 mm), tall side top to bottom, the F at the top left.

TS-10C — Hoop size: the small hoop, a 20 × 60 mm frame

20.0 × 60.0 mm · 92 stitches, 4 jumps, 4 trims, 0 colour changes, 0 stops

Hoop: the Brother PE800 with its small hoop, profile brother-pe800-small.

Threads: Blue.

After sewing, check:

• With the small hoop on the machine: does the machine take the file and sew it, without asking for a larger hoop?
• If it asks for a larger hoop, turn the design a quarter turn on the machine’s screen. Does it take it then?
• The frame measures 20.0 × 60.0 mm (± 0.5 mm), tall side top to bottom, the F at the top left.

Diagnostic codes

Every problem StitchCraft reports has a code. E codes are errors (nothing is written), W codes are warnings (the file is written), I codes are information. stitch explain <code> prints the same explanation in the terminal. Codes are never reused.

SC-E0004

Error — Budget exhausted

A budget limits how much work StitchCraft may spend on one element, and how many stitches one design may have, so that no input can make it run for hours or run out of memory — on the command line or inside VectorCraft’s live preview.

When planning, an element that needs more work than its budget was skipped and the rest of the design was planned: simplify the element (fewer nodes, wider spacing, a smaller area) or split it into several elements. A design that needs more stitches than its limit was not planned, and the message names the element where it ran out: widen the spacing of its largest elements, lower their repeats or bean stitch, or split the design into several files. When reading a file or drawing a preview, nothing was produced: simplify the drawing, or split it into several files.

SC-E0005

Error — Preview too large

Preview images have a size limit, so that drawing one never runs out of memory. At the scale asked for, this design’s preview would be larger, so no image was written.

Use a smaller scale: the message says the largest that fits. A design that runs more than 10 metres from the hoop centre cannot be previewed at any scale.

SC-E0009

Error — Internal check failed

StitchCraft checks every stitch plan against its own rules before writing a machine file. One of those checks failed, which means StitchCraft has a bug: the file was not written, so nothing wrong reaches your machine. stitch plan writes a bug-report bundle instead, next to the file it was asked for. An export in VectorCraft writes nothing, and stitch bug-report of the saved document writes the bundle.

Please attach the bundle to an issue; the message names the rule that failed. The bundle holds your design, so that the bug can be reproduced.

SC-E0010

Error — Nothing to stitch

The design has no stitches: it is empty, or every element was skipped (see the other messages). StitchCraft never writes an empty machine file, because some machines refuse or mishandle them.

Add an element with an embroidery stitch type, or fix the errors reported for the elements.

SC-W0011

Warning — Stitch type not sewn yet; element skipped

The element’s stitch type is one this version of StitchCraft does not sew yet, so the element was skipped; the rest of the design is planned. Running and manual stitches are sewn from milestone M3, satin columns from M4, tatami fills from M5, and zigzag strokes and the other satin methods from M7. The other stitch types follow (docs/src/plan/roadmap.md), but for Ink/Stitch’s legacy fill, which is sewn as a tatami fill (SC-W0314).

The message names the stitch type. Choose one StitchCraft sews, or sew the element with another tool for now.

SC-E0012

Error — Bug-report bundle could not be replayed

stitch bug-report --replay was given a file that is not a bug-report bundle it can replay: not JSON, not a bundle, a bundle format newer than this StitchCraft, or one that names a profile or a format this StitchCraft does not have. Nothing was replayed.

The message says what is wrong. A bundle written by a newer StitchCraft needs that version or a later one; a bundle changed by hand, or by an email program, needs the original file.

SC-E0101

Error — Parameter has the wrong type or an unknown choice

A parameter’s value could not be understood: a number where a word was expected, a choice that is not one of the parameter’s options, or a list with the wrong number of values. The element was not stitched: guessing could sew something you did not ask for.

The message names the parameter, the value and what the parameter accepts. The parameter reference lists every parameter with its accepted values.

SC-W0102

Warning — Parameter clamped to its allowed range

A parameter’s value is outside the range StitchCraft accepts, so the nearest allowed value was used, and the element was stitched with it. Values outside the range are impossible (a negative length) or beyond what machines sew reliably.

The message names the parameter, your value and the range. Change the value to remove the warning.

SC-W0105

Warning — Unknown parameter preserved but ignored

The design carries a parameter StitchCraft does not know: one from a newer version of StitchCraft or Ink/Stitch, or one for a stitch type StitchCraft does not support yet. It was kept, so saving the design does not lose it, but it does not change the stitches.

The Ink/Stitch compatibility page says when each Ink/Stitch parameter is supported.

SC-E0201

Error — Satin column has no rails

A satin column’s path has no subpath longer than a point, so it has no rails to sew between. The element was not stitched.

Draw the column as two rails, its edges, with rungs across both.

SC-W0202

Warning — Satin rails taken as the two longest subpaths

Where the subpaths of a satin column meet does not say which two are its rails, so the two longest were taken as the rails. The rule is Ink/Stitch’s: with one rung, the rails are the two subpaths that meet only one other, and with more rungs, the two that meet more than two others. With exactly two rungs across two rails, each of the four meets two others, as the strokes of a # do, and the rule cannot tell rails from rungs.

The message names the two subpaths taken, numbered from 1 in the order the path draws them. If they are not the rails, use three rungs or more, each crossing both rails once.

SC-W0203

Warning — Satin rung does not cross both rails

A rung of a satin column misses one of the rails, or both. It still says which points go together: where it misses a rail, the point of that rail nearest the rung is used, as in Ink/Stitch.

The message names the rung, numbered from 1 in the order the path draws it. Extend it across both rails, so that where it joins them is what you drew.

SC-W0205

Warning — Satin subpath is one point; left out

A subpath of a satin column is one point, a stray node, so it is neither a rail nor a rung. It was left out.

The message names the subpath, numbered from 1 in the order the path draws it. Delete the node, or if it was meant as a rung, draw the rung across both rails.

SC-W0206

Warning — Satin contour underlay too short for its insets; it keeps its length

A satin column’s contour underlay stops short of the column’s start and end by its inset, but a side of it is so short that this would leave less than half a CSS pixel (0.13 mm), so that side runs to the column’s ends, as in Ink/Stitch.

The message gives the insets at each end. Lower contour_underlay_inset_mm, or turn the contour underlay off for so short a column.

SC-W0207

Warning — Satin rung crosses a rail more than once; left out

A rung of a satin column crosses a rail more than once, so it does not say which point of one rail goes with which point of the other, and it was left out. The column is sewn without it.

The message names the subpath, numbered from 1 in the order the path draws it. Redraw the rung as a straight line across both rails.

SC-W0208

Warning — Satin stitches lean more than 45° from square to the column; add a rung here

The stitches of a satin column lean more than 45° from square to the column, to a tenth of a degree: they go further along it than across it. The column runs halfway between its 2 rails. Without rungs, or with too few, a column’s stitches follow its rails’ lengths alone, and where one rail runs on ahead of the other they lean. Every satin method says so, at the middle of each stretch of stitches that lean. Ink/Stitch does not.

The message gives how many stitches lean and the most any of them leans. Add a rung across the column at the place named, square to it, and the stitches follow it.

SC-W0209

Warning — Satin stitch longer than 12 mm; it may snag

A top stitch of a satin column is longer than 12 mm, as the column sews it. A stitch that long floats loose over the fabric, where it snags and sags. Every satin method says so once, at the middle of its longest top stitch, and its underlays and travel do not count. Ink/Stitch does not say so.

The message gives the stitch’s length. Set max_stitch_length_mm to split long stitches, make the column narrower, or sew the shape as a fill. Finalize splits a stitch longer than the machine’s longest stitch anyway (SC-I0703).

SC-W0210

Warning — Satin rails without rungs have different numbers of nodes

A satin column’s path draws no rungs, so its rails’ nodes pair up instead, as in Ink/Stitch: the 2nd node of one rail with the 2nd of the other, and on in order. Its rails have different numbers of nodes, so the rail with more has nodes that pair with none, and between them the stitches follow the rails’ lengths alone.

The message gives both counts. Add rungs across the column, or give both rails the same number of nodes.

SC-W0211

Warning — Satin push compensation too long for a rail; that rail keeps its length

A satin column’s push compensation, taken off a rail at the column’s start and end, would leave less than half a CSS pixel (0.13 mm) of it, so that rail keeps its length, as in Ink/Stitch. A negative value at the other end still lengthens it.

The message gives the push compensation at each end. Lower push_compensation_mm, or lengthen the column.

SC-W0212

Warning — Satin column drawn as one path too narrow; sewn as a stroke

A satin column is drawn as one path, its centre line, and its stroke is no wider than the design’s min_satin_stroke_width_mm (1 mm unless the design sets it). A column that narrow is sewn as a stroke, by the element’s stroke settings, as in Ink/Stitch: a running stitch unless they say otherwise.

The message gives the stroke’s width and the limit. Widen the stroke to sew a satin column, or draw the column with 2 rails.

SC-W0213

Warning — Parts of a satin column drawn as one path left out

A satin column drawn as one path, its centre line, is made into rails by offsetting the line by half the stroke’s width to each side. Where the line crosses itself or comes back near itself, the offsets split into several curves, and the line is cut in half, and the halves again, at most 20 times. Parts whose offsets still split are left out, and so are parts that turn so tightly that an offset vanishes. Ink/Stitch leaves out the same parts without a word. The rest of the column is sewn.

The message says how many parts were left out. Draw the column with 2 rails where its line crosses itself or turns more tightly than the column is wide, or make the stroke narrower.

SC-E0214

Error — Satin column drawn as one path could not be made into rails

A satin column drawn as one path, its centre line, could not be made into rails. Its offsets split however it is cut, an offset vanishes because the stroke is wider than the line’s turns allow, or the line is shorter than a CSS pixel. The column is not sewn.

Draw the column with 2 rails, or make the stroke narrower.

SC-W0215

Warning — Satin column too small for the shortest stitch; left out

A satin column is so small that every needle point of it lies within the shortest stitch of its first: a speck of a column, a few tenths of a millimetre across. Any stitch it could sew would be shorter than the machine sews well, would hammer one spot of the fabric and could break the thread, so it is left out, as a stroke that small is (SC-W0401). Ink/Stitch sews such a column. A zigzag satin 0.1 mm long or less is left out too, its underlays with it: its zigzag has one point and no stitch across. Ink/Stitch sews its underlays alone.

The message gives the shortest stitch, or says the column is too short for a stitch across. Draw the column larger, or delete it if it is a stray.

SC-E0216

Error — Satin column has no section to sew

A satin column’s rungs, or its push compensation, leave each of its sections with no length on one of its rails, so no stitch goes across it and the column is not sewn. A rung from the first rail’s start to the second rail’s end does this, and so does push compensation that takes off the parts of a short column’s rails where its rungs meet them. Ink/Stitch says such a column cannot be stitched.

Move the rungs so that each meets both rails away from their ends, or lower push_compensation_mm.

SC-W0303

Warning — Parts of a fill too small to sew left out

A fill is sewn in rows of stitches across each part of its area. A part of 0.21 mm² or less (3 square CSS pixels), a speck about half a millimetre across, is too small for a row, so it is left out, as Ink/Stitch leaves it out. Where every part is that small, the fill sews nothing. So does a fill that bounds no area at all: subpaths that are lines or points, or that its fill rule leaves empty, such as 2 copies of one square under the even-odd rule.

The message counts the parts left out and is placed at the first. Draw them larger, or sew them as a running stitch.

SC-W0304

Warning — Fill smaller than 1.4 mm²

This fill covers less than 1.4 mm² (20 square CSS pixels). Rows of stitches packed into so small an area pile up, and a running stitch round it or a satin column across it usually sews it better. Ink/Stitch gives the same advice. The fill is kept as drawn.

SC-W0305

Warning — Fill part too thin for rows; sewn round its outline

A fill is sewn in rows of stitches the row spacing apart, and a part of it so thin that no row crosses it gets none. Such a part is sewn as a running stitch round its outline instead, as Ink/Stitch sews it.

The message counts the parts. Make them wider, set a smaller row_spacing_mm, or sew them as a stroke or a satin column.

SC-I0306

Info — Nonzero fill rule fills a part inside that the even-odd rule leaves empty

A fill’s fill rule says which parts of it are filled where its subpaths lie inside each other or overlap. Under the rule nonzero, SVG’s default, a part that the subpaths wind round twice the same way is filled; the even-odd rule leaves it empty. StitchCraft fills it, as the drawing shows it. Ink/Stitch takes every subpath but the largest as a hole, whatever the fill rule. Where such a part lies inside the fill, away from its edge, the same file leaves it empty in Ink/Stitch.

To leave the part empty in both, set the fill rule to even-odd, or draw the inner subpath the other way round.

SC-W0307

Warning — Fill in parts that are apart; each sewn on its own

A fill whose area falls into separate parts, such as one drawn as several shapes side by side, or an outline that crosses itself, is sewn one part after another: each part’s rows on their own, with a jump to the next, which the plan may trim. Ink/Stitch warns about such fills too.

To choose the order the parts are sewn in, break the fill apart into one element for each part.

SC-I0308

Info — Fill underlay too thin for rows; sewn round the outline

A fill’s underlay is sewn in rows fill_underlay_row_spacing_mm apart, 3 times the row spacing unless set. On a part so thin across those rows that none crosses it, that layer of underlay is sewn as a running stitch round the part’s outline instead, as Ink/Stitch sews it, and the top rows are sewn over it as usual.

The message counts the layers, and each part has one for each underlay angle. To sew the underlay in rows, set a smaller fill_underlay_row_spacing_mm or another fill_underlay_angle. To sew no underlay, turn fill_underlay off.

SC-W0309

Warning — Fill’s expand shrinks a part away; sewn at its own size

A fill’s top rows are sewn on each part grown by expand_mm, or shrunk where it is negative. A part too thin for that much shrinking, which wears it away entirely, is sewn at its own size instead, as Ink/Stitch sews it, and Ink/Stitch warns of it too.

The message counts the parts. Make expand_mm nearer 0.

SC-W0310

Warning — Fill’s underlay inset shrinks a part away; underlay over all of it

A fill’s underlay is sewn on each part shrunk by fill_underlay_inset_mm. A part too thin for that much shrinking, which wears it away entirely, has its underlay sewn over all of it instead, as Ink/Stitch sews it, and Ink/Stitch warns of it too.

The message counts the parts. Set a smaller fill_underlay_inset_mm, or turn fill_underlay off.

SC-W0312

Warning — Fill’s pull compensation below 0; read as 0

A fill’s rows reach past its edge by its pull compensation, which makes up for the thread pulling the fabric in. Ink/Stitch reads a fill’s pull_compensation_mm or pull_compensation_percent below 0 as 0, so that the rows reach the edge and no less, and so does StitchCraft. A satin column reads the same settings below 0 as narrower.

The message names the settings. Set them to 0 or more; to keep the rows inside the edge, use a negative expand_mm.

SC-I0313

Info — Fill drawn twice along its edge; Ink/Stitch fills the part left empty

Two subpaths of a fill run along each other at its edge, around a part that its fill rule leaves empty. A notch drawn as a hole whose sides lie on the outline is one, and a shape drawn twice is another. StitchCraft leaves the part empty, as the drawing shows it. Ink/Stitch repairs such a shape by merging each stretch drawn twice into one, which fills the part, and the same file then sews it filled in Ink/Stitch.

To sew it alike in both, draw the outline round the empty part instead of a subpath along it.

SC-W0314

Warning — Legacy fill sewn as a tatami fill without underlay

Ink/Stitch’s legacy fill is its first fill method, which it keeps for its older files: it gives the method to a fill whose auto_fill is off. StitchCraft does not sew it, and sews such a fill as a tatami fill with the same settings and no underlay, as legacy fill sews none. Its rows and their needle points are a tatami fill’s, as in Ink/Stitch. Ink/Stitch sews a legacy fill’s rows in stretches that join, each on its own and back and forth; its flip starts the rows from the other side, and its reverse sews the fill backwards. A tatami fill routes its rows and joins them with travel stitches, and StitchCraft keeps flip and reverse without reading them (SC-W0105).

To sew the fill alike in both, set its fill method to tatami fill and turn fill_underlay off.

SC-W0401

Warning — Path too small for the shortest stitch; skipped

A part of a stroke is too small for the shortest stitch the machine sews well, so it was left out: one stitch that short would hammer one spot of the fabric and could break the thread. The part is a single point (a stray node), shorter than the shortest stitch, or longer but curled up so that all of it lies within the shortest stitch of its ends: a tiny closed loop, say.

The message gives the part’s length and the shortest stitch. Enlarge the part, join it to its neighbour, or delete it if it is a stray.

SC-W0402

Warning — Stitch length below twice the shortest stitch; raised

A running stitch’s length, a stroke’s or that of one of a satin column’s underlays, is shorter than twice the shortest stitch, so it was lengthened to twice the shortest stitch. Stitches are spread evenly between corners; at half the length or more, every stitch then stays at or above the shortest stitch, whatever the distance between corners.

The message names the parameter and gives both lengths. Use a longer stitch length, or a shorter minimum if your machine sews shorter stitches well.

SC-W0403

Warning — Hand-placed stitch shorter than the shortest stitch; point left out

Hand-placed stitches (manual stitch) shorter than the shortest stitch the machine sews well: the needle point that made each one too short was left out, so the stitch before it runs on to the next point. A part’s last point is always kept; the one before it goes instead.

The message gives how many and the shortest of them. Move the nodes apart, or delete the extra ones.

SC-W0404

Warning — Hand-placed stitch longer than max_stitch_length_mm; kept for the shortest stitch

Hand-placed stitches (manual stitch) sewn longer than max_stitch_length_mm. A stitch longer than that is split into equal parts no longer than it, but never into parts shorter than the shortest stitch the machine sews well, which here took fewer parts: a shorter stitch would hammer one spot and could break the thread. Ink/Stitch splits such a stitch into the fewest parts no longer than the setting, however short they are.

The message gives how many stitches are longer and the longest of them. Set max_stitch_length_mm to at least twice the shortest stitch: every split then leaves parts long enough.

SC-W0405

Warning — Zigzag stitch shorter than the shortest stitch; the zigzag sews narrower

A zigzag stroke’s stitches shorter than the shortest stitch the machine sews well, across a zigzag too narrow for its spacing. Finishing leaves out a needle point of each such stitch, as it leaves out any point that near the one before it (SC-I0504), so the zigzag sews narrower there. Where every stitch is that short, every other point goes, and the zigzag sews as a line along one side. Ink/Stitch’s shortest stitch is 0.1 mm by default, and it sews such a zigzag as it is.

The message gives how many stitches are that short and the shortest. On a straight path, a stitch across a zigzag w wide at a spacing s is √(w² + (s/2)²) long. Make the zigzag wider, the stroke or its pull compensation, or space it out, until that is at least the shortest stitch.

SC-W0502

Warning — Lock stitch shorter than 0.2 mm; lengthened

A lock stitch would have been shorter than 0.2 mm, the shortest stitch a lock may have. The needle would go back into the hole it just left, which can cut the thread and does not lock it. Each such step of a lock made of steps (back and forth, or a custom lock written as numbers) was lengthened to 0.2 mm, and a drawn lock was enlarged until its shortest stitch is 0.2 mm long. A lock of steps follows the stitching. Where a sharp turn would fold it onto itself, it was sewn straight along the first (or last) stitch.

The message says which lock, and by how much. Set a larger lock size (lock_start_scale_mm, lock_end_scale_mm) or scale (lock_start_scale_percent, lock_end_scale_percent), or write longer custom steps.

SC-W0503

Warning — Custom lock cannot be sewn as written

The lock is set to custom, but its shape cannot be sewn as written. A custom lock is numbers separated by spaces, the steps the needle takes along the stitching in sizes of lock_*_scale_mm, or an SVG path that draws it. StitchCraft sews the numbers. It does not sew a drawn custom lock yet, and sews the half stitch in its place. Parts that are not numbers, and steps longer than 10 m, are left out. If no step is left, the half stitch is sewn instead.

The message says what was wrong. Write the lock as numbers, such as 1 -1 1 -1, or choose another lock shape.

SC-I0504

Info — Stitches shorter than the shortest stitch merged

Needle points less than the shortest stitch from a needle point next to them were left out, so the stitch before each runs on to the next and none is shorter than the machine sews well. This happens where one element’s stitching runs straight on into the next and they nearly touch: the stitch between them is whatever is left of the gap. A point that stays, such as a lock point or the last point before a jump, trim or stop, leaves out the points before it that it is too near, and a stitch into or out of a lock point may be as short as 0.2 mm. Where small elements are sewn over each other, a point that stays can go too, when it comes within the shortest stitch of another that stays. Nothing visible changes, but across a zigzag too narrow for the shortest stitch, which SC-W0405 names.

The message gives how many points were left out and the shortest stitches that applied to them. Nothing needs doing. If the count is large, check for elements drawn on top of each other.

SC-W0505

Warning — Trim or stop after an element that sews nothing; left out

The element is set to trim or stop after it (trim_after, stop_after, or Ink/Stitch’s trim and stop commands), but it sews no stitch, so there is no place for the trim or the stop: it is left out, as Ink/Stitch leaves it out. Another message says why the element sews nothing.

Make the element sew, or set the trim or stop on the element before it.

SC-E0601

Error — Too many colour changes for the file format

The file format can record only a limited number of colour changes and stops (PES: 255). This design has more, so the file was not written.

Merge elements that use the same thread so they sew in one block, or remove stops.

SC-E0602

Error — Design too large for the file format

The design’s coordinates or stitch data do not fit the fields of this file format, so the file was not written. Within a real hoop this does not happen; it points at a design that is far larger than any hoop, or at stray objects far from the rest of the design.

Check the design’s size and remove stray objects.

SC-E0603

Error — Machine file could not be read

The machine file could not be read: it is not in the format its name or first bytes suggest, it ends early, or a record in it makes no sense. StitchCraft reads every file as if it could be damaged or hostile, so a bad file is reported, never half-read in silence.

The message says where reading stopped. If the machine sews the file, it may be a format variant StitchCraft does not know yet: please report it with the file.

SC-W0604

Warning — Thread colours unknown

The file stores no thread colours (DST files never do: they only say where the machine pauses for the next thread), so every thread has a black placeholder colour in previews. A PES file converted from this one names each thread by the Brother colour nearest black that is still free (Black, Dark Gray, Dark Brown and so on), which says nothing of the threads the design needs.

The stitches are not affected. Load the threads the design needs, in the order the design’s author gives; StitchCraft cannot know them.

SC-I0605

Info — Long jumps cut in DST

DST has no trim command: machines cut the thread when they meet three or more jump records in a row (a machine setting; three is the common one), and a jump longer than 24.2 mm takes three or more records. So the thread will be cut before such a jump, although the plan does not trim there. With a tie-off before the jump the cut is usually welcome: there is no jump thread to clip by hand.

Nothing to do. Where an element’s ties are off, turn them on so its stitching holds when it is cut, or sew a PES file, where only trims cut. A machine set to another number of jump records cuts before other jumps: see its DST setting.

SC-W0606

Warning — Threads share a Brother colour

A PES file names each thread by a colour of the Brother palette, which has 61 thread colours. StitchCraft gives each different thread a colour of its own, the nearest one still free, so the machine asks for each thread change. A design with more different threads than that has some share a colour, and the machine shows that colour for each of them: at a change between 2 of them it shows the thread already in the machine, as for a stop.

Load the threads in the order the report lists them, rather than by the colours the machine shows. Or use fewer different threads: merge those of nearly the same colour.

SC-E0701

Error — Design does not fit the hoop

The design is wider or taller than the machine’s hoop, so the machine cannot sew it in one hooping (most machines refuse the file). A design that fits the hoop can still reach past its edge where it is placed: its origin, which goes to the hoop’s centre, can lie far from its middle, and its stop position, where the frame goes before each stop, can lie outside the hoop.

If the message says the design fits when turned 90 degrees, rotate it. Otherwise scale it down, or split it into parts that are sewn in separate hoopings. Where it reaches past the edge from where it is placed, move its origin nearer its middle, or its stop position nearer the design.

SC-W0702

Warning — Design is larger than the comfort zone

The design fits the hoop but is larger than the profile’s comfort zone: the area where this machine and hoop sew most accurately. Near the hoop’s edge fabric is held less firmly, so large designs pucker and shift more.

The file was written. Rotate the design if the message says that brings it inside the comfort zone, use a firmer stabilizer, or scale the design down.

SC-I0703

Info — Stitches longer than the machine’s longest stitch; split

Stitches longer than the machine’s longest stitch were split into equal parts, each no longer than it: a long stitch placed by hand, say, or a custom lock’s long step. A long loose stitch snags and sags; the machine may refuse it.

To choose where the needle goes down instead, add nodes (manual stitch) or set max_stitch_length_mm.

SC-E0801

Error — SVG could not be read

The SVG file could not be read: it is not well-formed XML, its root is not an <svg> element, its size or viewBox does not read or makes no sense, or it is larger than StitchCraft reads, its style sheets included. Nothing was stitched.

The message says what is wrong and, for XML errors, where. Open the file in a vector editor and save it again as plain SVG.

SC-W0802

Warning — SVG feature ignored

Part of the SVG uses a feature that StitchCraft does not stitch, so that part is left out or simplified: text that is not converted to paths, raster images, clones (<use>), nested <svg> elements, style sheet rules with selectors StitchCraft does not read, or a gradient or pattern used as a colour. Values that do not read are named too. A colour that does not read is ignored, as a viewer ignores it, and one of Ink/Stitch’s design settings keeps its default. A line that --auto sews across its width, as a satin column or a fill, is as wide as its transforms stretch it on average, so a transform that stretches it more one way than the other, and draws it wider one way, is named too.

The message names the element and what was done. Convert text and clones to paths in the editor (in Inkscape: Path › Object to Path, Edit › Clone › Unlink Clone), and give shapes plain colours.

SC-I0805

Info — Object left out, as the file asks

An object or a layer is left out because the file asks for it: an Ink/Stitch “ignore object” or “ignore layer” command, or the object’s Ink/Stitch setting ignore_object. Designs keep templates, placement lines and notes this way, in the drawing but out of the sew-out, and Ink/Stitch leaves them out too.

The message names what was left out and why. To stitch it, delete the command’s symbol, or turn the setting off in Ink/Stitch’s parameters.

SC-W0804

Warning — Element geometry invalid or out of range

An element’s geometry cannot be used: its path data or its list of points has an error (the path is stitched up to the error, as SVG viewers draw it), its transform is not valid (it is skipped with everything inside it), it draws nothing, or it lies more than 10 metres from the document’s origin, beyond what machine files can record (it is skipped). A stroke width, join or miter limit that does not read is named as well, and ignored as a viewer ignores it, and so is an empty width, height or viewBox of the drawing, or an aspect ratio that does not read. A stroke too wide to measure is skipped.

The message names the element. Check its path data, points and transform, or remove stray objects far from the design.

SC-W0803

Warning — VectorCraft file from a newer format version; read best-effort

The .vectorcraft file comes from a newer VectorCraft: its format version is newer than the newest StitchCraft reads. StitchCraft reads it as that version, usually all of a design’s paths and paints, where older versions of VectorCraft refuse the file.

The message gives the file’s format version and the newest StitchCraft reads. Compare the stitches with the drawing, or save a copy in that format from the newer VectorCraft: File › Save a Copy, then the Version in VectorCraft Options.

SC-E0806

Error — VectorCraft file could not be read

The .vectorcraft file could not be read: it is not a VectorCraft document (its JSON does not read, it names another format, or it holds no document), the data VectorCraft keeps after its JSON is damaged, or it unpacks to more JSON than StitchCraft reads. Nothing was stitched.

A StitchCraft live effect or filter gives this message when what VectorCraft passes it does not read as VectorCraft’s plug-in ABI v1 says, which a VectorCraft with another plug-in ABI would do. The effect leaves the object as it is, and the filter changes nothing.

The message says what is wrong and, for JSON errors, where. Open the file in VectorCraft and save it again. For a plug-in, install the StitchCraft plug-ins made for that version of VectorCraft.

SC-W0807

Warning — VectorCraft object or feature not stitched

Part of the VectorCraft document is not stitched: text, images, symbols, objects VectorCraft computes as it draws them (blends, envelopes, meshes, repeats, placed documents and Intertwine objects), a kind of object StitchCraft does not read, clipping and opacity masks, VectorCraft’s own effects, a brush’s art, a StitchCraft effect it cannot use, or a group’s or a layer’s own fills and strokes. A gradient is sewn in its first colour, and a pattern, or a colour that does not read, in black. An object that StitchCraft effects reach from more than one level, its own and a group’s around it, or 2 groups’, sews as the nearest say: VectorCraft runs each on the stitches the one before drew, which no machine sews. A start or end marker, an object named stitch:start or stitch:end, is never stitched, and StitchCraft does not yet start or end a shape where one says. A name that begins with stitch: and names no marker StitchCraft reads is said too, as is a group or a layer named as a marker, which only a shape can be: the name is ignored. A satin column, a zigzag or a fill made of a stroke is as wide as the stroke all along and centred on its path, so a stroke aligned inside or outside a closed path is said, as is a width profile, and round or square caps where the stitches end at the path’s end.

The message names the object and what was done. In VectorCraft, Type › Create Outlines makes paths of text, and Object › Expand of blends, envelopes, repeats and placed documents. Break Link to Symbol makes paths of a symbol, and Object › Expand Appearance of what effects and brushes draw.

SC-W0808

Warning — VectorCraft geometry unusable

An object’s geometry cannot be used, and the object, or the stroke, is left out: a coordinate or a stroke’s width is not a number, the object draws nothing, or it lies more than 10 metres from the document’s origin, beyond what machine files can record. A StitchCraft stroke or satin effect takes a width that is not a number as 0. A StitchCraft live effect leaves such an object as it is, with this message as the plug-in’s last error.

The message names the object. Check its anchors, or remove stray objects far from the design.

SC-I0809

Info — VectorCraft layer or guide left out, as it does not print

A layer or a guide is left out because VectorCraft does not print it: a template layer, a layer whose Print option is off, or a guide. VectorCraft shows them, dimmed or as guides, and keeps them out of what it prints and exports; StitchCraft keeps them out of the sew-out.

The message names the layer or the guide. To stitch a layer, turn its Template option off, or its Print option on, in VectorCraft’s Layer Options.

SC-I0810

Info — VectorCraft live effect leaves the object as it is

A StitchCraft live effect draws the object it is applied to as its stitches, or as much of them as its preview level shows. It leaves the object as it is when it cannot show them, and VectorCraft shows this message as the plug-in’s last error. The object sews no stitch, or its preview level needs more work than VectorCraft lets a live effect do. Or it is as wide as its stroke, a satin column drawn as one path or a zigzag stroke, and VectorCraft gives the effect no stroke: before 0.14, for an object without one, or where the stroke is a group’s. Or the effect sits on one of the object’s fills or strokes, which stitch export doesn’t use. When another message says why an object sews no stitch, the effect shows that message instead.

The message says which. A satin column drawn as one path, and a zigzag stroke, sew as wide as the stroke that paints them when exported with stitch export. To see their stitches in VectorCraft, give the object a stroke as wide as they are, or draw a satin column’s 2 rails and join them with Object › Compound Path › Make. Apply StitchCraft’s effects to the object itself, not to one of its fills or strokes. For a preview that needs more work, the hint names a cheaper level to set the effect’s preview_level to.

SC-I0811

Info — VectorCraft object left out, as its name asks

An object or a layer is left out because its name asks for it: the name is stitch:ignore, alone or followed by white space and a note, in any mix of upper and lower case. Designs keep placement lines, templates and notes this way, in the drawing but out of the sew-out, as Ink/Stitch’s ignore commands keep them. Everything in a group or a layer so named is left out with it.

The message names what was left out. To stitch it, rename it in VectorCraft’s Layers panel.

SC-W0812

Warning — VectorCraft design setting ignored

A design setting that StitchCraft’s Design Settings filter keeps with a VectorCraft document does not read: a length that is not a number of 0 or more, or a machine this StitchCraft doesn’t have, as a document from a newer one may name. The setting keeps its default, and the design is planned for the machine --profile or the export names, or else for the reference machine, the Brother PE800’s 5 × 7 in hoop.

The message names the setting and what it holds. To set it again, choose Object › Plug-ins › StitchCraft Design Settings in VectorCraft, which keeps every setting anew.

SC-E0813

Error — VectorCraft too old for the filter

A StitchCraft filter needs what the VectorCraft that ran it doesn’t give a filter, so it declined to run, and nothing changed. StitchCraft Design Settings keeps a document’s design settings and machine as data VectorCraft keeps with a document for a filter, from 0.16. Stroke to Satin and Test Sheet give the objects they make StitchCraft’s effects, as effect records VectorCraft keeps from 0.15. Test Sheet tells such a VectorCraft by what it gives every filter from 0.16, since a 0.15 with nothing selected looks as 0.14 does.

The message names the version the filter needs. Update VectorCraft to it or later. Until then, the export’s Machine option and stitch export --profile name the machine, the design settings keep their defaults, a satin column is drawn with its 2 rails and joined with Make Compound Path, and stitch testsheet makes the test sheets.

SC-E0814

Error — VectorCraft line not made into a satin column

StitchCraft’s Stroke to Satin filter makes each selected line into a satin column drawn with rails and rungs, which sews as the line does with the satin effect. It changed nothing, because nothing was selected, or one of the lines can’t be made so: its path has no stroke to take the column’s width from, or can’t be used, its rails can’t be made or would leave parts of it out, as SC-E0214 and SC-W0213 say of a satin column drawn as one path, or the column would be read back with other rails or rungs, as one whose rails cross each other is.

The message names the object. Select the lines, give the path a stroke as wide as the column, draw that column with its 2 rails, or leave the object out of the selection.

SC-I0901

Info — Shapes digitized automatically

--auto digitized the design’s shapes that have no settings: StitchCraft chose each one’s stitches by its width, measured to the micrometre. An area is a tatami fill, and a part of it narrower than the design’s narrowest satin stroke (min_satin_stroke_width_mm, 1 mm unless the design sets it) everywhere is a running stitch along its centre line. A line no wider than that is a running stitch, a line up to 7 mm wide a satin column as wide as the line, and a wider line a tatami fill of the area it paints. A running stitch is tripled from 0.5 mm wide. A line whose every part a satin column cannot follow is filled too (SC-I0902), and counted as a fill. An area whose every part runs is counted as a running stitch, and any other as a fill.

The message counts the shapes by the stitches they sew as. To sew a shape another way, give it settings: in VectorCraft, apply a StitchCraft effect to it. A shape with settings is not digitized automatically.

SC-I0902

Info — Line a satin column cannot follow; filled

--auto sews a line up to 7 mm wide as a satin column along its path, but a satin column cannot follow this part of the line: it turns more tightly than the line is wide, so the column’s edges would fold over themselves, or it is shorter than a CSS pixel, or it is a dot that the line’s round or square cap draws. The area it paints is filled instead, as a line wider than 7 mm is.

The message says which. To sew it as a satin column, draw the line with gentler turns or narrower, or draw the column with 2 rails and give it settings.

SC-W0903

Warning — Line too wide to fill; left out

--auto fills the area a line paints when the line is wider than 7 mm, or when a satin column cannot follow it, and the area this line paints would reach more than 10 metres from the design’s origin, beyond what machine files can record. It is left out. A stroke that wide is usually a mistake in the file.

The message gives the line’s width. Check the line’s stroke width.

SC-I0904

Info — Areas reach under the shapes sewn after them

--auto makes each automatic area reach 0.4 mm under the shapes sewn after it, from where it touches them. The thread pulls stitches in from the edges of their shape, and without the overlap fabric shows between shapes that only meet. Where an area sewn after it covers part of it, as in a trace that stacks its colours, the covered part is cut away, 0.4 mm inside the covering area’s edge, and sewn once. A satin column or a line sewn after an area goes over it, and the area is sewn whole under it. The running stitch along a narrow part of an area covers that part: the areas sewn before it reach under it, and when the areas sewn after it cover the part whole it sews nothing.

The message counts the areas that reach under others and those cut away. An area that the areas sewn after it cover whole sews nothing, and the message names it, as it does a narrow part’s line. It also names an area whose neighbours need more work to find than the budget allows it, which neither reaches under them nor is cut away, and a satin column whose area needs more, which the areas before it don’t reach under, and which keeps its place in paint order beside the shapes near it. To sew a shape as it is drawn, give it settings: in VectorCraft, apply a StitchCraft effect to it.

SC-I0905

Info — Speck merged into a neighbour

--auto takes an automatic area smaller than 1 mm², or a part of one that small, for a speck the trace left. It is too small to sew, and would sew a knot. It is merged into the automatic area it shares the longest edge with, which may be the rest of its own area, and no hole shows where it was. A speck that shares no edge with an automatic area is left out.

The message gives the speck’s area and says where it went: into a neighbour, back to the rest of its area, or nowhere, as when finding its neighbours needs more work than the budget allows it. To sew it as it is, give it settings: in VectorCraft, apply a StitchCraft effect to it. A larger Noise in VectorCraft’s Image Trace leaves such specks out of the trace.

SC-W0906

Warning — Background left out

--auto takes the lowest shape of the design for the picture’s background when it is an automatic area, other shapes are drawn on it, and it covers the whole design, its holes aside, to within 0.5 mm of each side. It is left out. A background is usually the fabric’s own colour, and sewing it doubles the stitches and stiffens the design. A background that needs more work to find than the budget allows is sewn, and the message says so.

To sew it, give it settings: in VectorCraft, apply a StitchCraft effect to it. Ignore White in VectorCraft’s Image Trace leaves a white background out of the trace.

SC-I0907

Info — Elements sewn in an order of their own

--auto sews the automatic elements in an order of its own, and --sort-colours every element. Shapes that overlap as drawn keep their paint order, the lower one first, and a satin column or a line that borders a fill sews after it, over its edge. Within those rules each thread sews as long as an element of it is free to sew, and the next element is the nearest. Elements with settings keep their order among themselves unless --sort-colours is given, and nothing moves across a stop.

The message says how many thread changes the order has, and how many paint order has. It also names an element whose neighbours need more work to find than the budget allows, which keeps its place in paint order as an element with a stop after it does, and a line whose paint can’t be found, which keeps its place beside the shapes near it. SC-I0904 names a satin column whose paint can’t be found. And it names the elements left in paint order when choosing the order needs more work than the budget allows. To keep shapes in their paint order among themselves, give them settings and leave --sort-colours off: in VectorCraft, apply a StitchCraft effect to each.

Parameters

Every setting a design element can carry, by the key a design stores it under. A parameter that Ink/Stitch also has keeps Ink/Stitch’s key, meaning and default, so files move between the two tools unchanged (compatibility contract). Where StitchCraft reads or sews one otherwise, its entry says how, and below is how reading any value differs.

StitchCraft never falls back to a default in silence. A value it cannot use is an error that says what is accepted (SC-E0101); a value outside its range is clamped, with a warning (SC-W0102); a key it does not know is kept unchanged, with a warning (SC-W0105).

Writing values

Designs store every value as text, the same way for every host:

• Lengths are millimetres. They may carry a unit right after the number: 2.5, 2.5mm, 0.1in and 7pt are all accepted, and 2.5 mm is not.
• Angles are degrees (45, 45° or 45deg), turned into the range from −180 (exclusive) to 180.
• Percentages may end in %.
• On or off is true or false, in any case. yes, y, t and 1 are on too, and no, n, f, 0 and off off. on is an error, since Ink/Stitch reads it as off.
• Lists (several lengths, numbers or angles) are separated by spaces: 2.5 1.2. A comma separates nothing and is no decimal point, so 2.5,1.2 and 3,5 are errors that say so. An angle in a list may end with one comma (0, 90), as older files write a fill’s underlay angles.
• Seeds are a number or any text. Elements given the same seed vary alike; empty means “derive it from the element”, so every element differs but every run is the same.
• Empty text, or spaces alone, is not set: the parameter takes its default, as in Ink/Stitch. Spaces, tabs and line ends round a value are left out, as Ink/Stitch strips them.

An element reads only the settings its stitch type uses, and only those its other settings show: a running stitch reads no zigzag spacing, and no length variation while random stitch length is off. A setting it does not read is kept with the element, unchecked, and changes nothing.

Programs that store values as JSON (and the JSON Schema that describes them) use numbers, true/false, strings and arrays instead, and null for an empty value.

Where reading differs from Ink/Stitch

• DEV-PRM-001. A value StitchCraft cannot read refuses its element (SC-E0101), and the rest of the design is sewn. Ink/Stitch sews such a value as the parameter’s default, or a toggle as off, without a word: it sews 3,5 for running_stitch_length_mm as 2.5 mm stitches, and a toggle of on as off. A toggle reads yes, y, true, t and 1 as on here, as Ink/Stitch does, and only their opposites and off as off. StitchCraft reads a tab, or several spaces, between a list’s values as one space, where Ink/Stitch sews a list with a tab between values as its default, and a fill’s underlay angles with 2 spaces between them too. It also reads a unit right after a number, mm, in or pt after a length, a degree sign or deg after an angle and a percent sign after a percentage, where Ink/Stitch sews the default.
• DEV-PRM-002. Every number a parameter takes keeps to a range of StitchCraft’s, given in the parameter’s reference entry. A value outside it is clamped into it, with SC-W0102. Ink/Stitch sets a floor for most of its numbers and few ceilings, so many of these ranges are narrower than its own: repeats has no ceiling there and stops at 100 here.
• DEV-PRM-003. An optional length below 0 is read as not set, as 0 is, and SC-W0102 says so. Ink/Stitch reads it as a length and sews what that gives: with a min_jump_stitch_length_mm below 0, it ties off, jumps and ties in between every 2 groups of stitches.
• DEV-PRM-004. A list takes at most 16 values and a pair 2, and no value may be longer than 4,096 bytes: more refuses the element (SC-E0101), whose message quotes the start of a long value. Ink/Stitch reads a list of any length, takes the first 2 values of a longer pair, and reads text of any length.

Groups

Every parameter

Common parameters

Settings every stitch type shares: lock stitches where the element’s stitching starts and ends, a trim or a stop after it, the shortest stitch and jump, the longest stitch, and where random variation starts. Plan assembly sews the locks, trims and stops, and finalize holds each element’s stitches to its shortest stitch.

Applies to every stitch type.

Lock stitches

ties

Lock stitches. Where the element gets lock stitches: a few tiny stitches that stop the thread from unravelling where its stitching starts and ends.

• Accepts: one of 0 (At the start and the end), 1 (At the start), 2 (At the end), 3 (None)
• Default: 0
• Ink/Stitch: same key, meaning and default

force_lock_stitches

Always lock. Lock the end of every group of stitches, and jump to the next, even where the needle would otherwise go straight on to it. The end lock is sewn even where ties leaves it out, manual stitch gets the locks it otherwise goes without, and a fill whose top rows expand_mm cuts into pieces locks each piece on its own.

• Accepts: true or false, in any case, or yes, y, t or 1 for true and no, n, f, 0 or off for false
• Default: false
• Ink/Stitch: same key, meaning and default

lock_start

Start lock. The shape of the lock stitches at the start. The half stitch goes back and forth over the first half of the first stitch, which hides it. The other shapes are larger and grip more.

• Accepts: one of half_stitch (Half stitch), arrow (Arrow), back_forth (Back and forth), bowtie (Bowtie), cross (Cross), star (Star), simple (Simple), triangle (Triangle), zigzag (Zigzag), custom (Custom)
• Default: half_stitch
• Ink/Stitch: same key; StitchCraft differs:
  • DEV-LCK-001. Each Ink/Stitch lock id is accepted, with StitchCraft’s own shapes behind the ids and the same intent. The half stitch goes forth and back twice over half the first stitch, and back_forth twice over one step, where Ink/Stitch’s go out two steps and back. The drawn shapes are new. A custom lock drawn as an SVG path sews the half stitch, with SC-W0503, until M8.

lock_custom_start

Custom start lock. The steps a custom start lock takes along the stitching before it starts, as numbers separated by spaces, each a number of lock_start_scale_mm. Positive steps go into the stitching. The last step ends where the stitching starts, and 1 -1 1 -1 goes forth and back twice. Ink/Stitch also takes an SVG path that draws the lock. StitchCraft does not sew those yet, and sews the half stitch in its place (SC-W0503).

• Accepts: text of at most 4096 bytes
• Default: empty
• Shown when lock_start is custom
• Ink/Stitch: same key; StitchCraft differs:
  • DEV-LCK-002. Locks of steps follow the stitching round its corners, as Ink/Stitch’s custom steps do. They differ in 5 places. Past the end of stitching shorter than the lock, they go straight on from the last stitch, where Ink/Stitch puts the rest of the lock on the last needle point. Where following a sharp turn would sew a stitch shorter than 0.2 mm, the lock is sewn straight along the first (or last) stitch, with SC-W0502, where Ink/Stitch follows the turn. A step shorter than 0.2 mm is lengthened to 0.2 mm, with SC-W0502, where Ink/Stitch sews it as it is. A custom step of 0 is left out, with SC-W0503, where Ink/Stitch sews a stitch in place for it. And a custom step longer than 10 m, the data model’s reach, is left out with SC-W0503.

lock_start_scale_mm

Start lock size. How long each step of a start lock made of steps (back and forth, or custom) is.

• Accepts: a length from 0.1 to 10 mm
• Default: 0.7
• Shown when lock_start is back_forth or custom
• Ink/Stitch: same key, meaning and default

lock_start_scale_percent

Start lock scale. How large a drawn start lock is, in percent of its own size: at 100 % it reaches about 1.4 mm along the stitching.

• Accepts: a percentage from 10 to 500
• Default: 100
• Shown when lock_start is arrow, bowtie, cross, star, simple, triangle, zigzag or custom
• Ink/Stitch: same key, meaning and default

lock_end

End lock. The shape of the lock stitches at the end. The half stitch goes back and forth over the last half of the last stitch, which hides it. The other shapes are larger and grip more.

• Accepts: one of half_stitch (Half stitch), arrow (Arrow), back_forth (Back and forth), bowtie (Bowtie), cross (Cross), star (Star), simple (Simple), triangle (Triangle), zigzag (Zigzag), custom (Custom)
• Default: half_stitch
• Ink/Stitch: same key; StitchCraft differs:
  • DEV-LCK-001. Each Ink/Stitch lock id is accepted, with StitchCraft’s own shapes behind the ids and the same intent. The half stitch goes forth and back twice over half the first stitch, and back_forth twice over one step, where Ink/Stitch’s go out two steps and back. The drawn shapes are new. A custom lock drawn as an SVG path sews the half stitch, with SC-W0503, until M8.

lock_custom_end

Custom end lock. The steps a custom end lock takes along the stitching after it ends, as numbers separated by spaces, each a number of lock_end_scale_mm. Positive steps go back into the stitching. The first step starts where the stitching ends, and 1 -1 1 -1 goes back and forth twice. Ink/Stitch also takes an SVG path that draws the lock. StitchCraft does not sew those yet, and sews the half stitch in its place (SC-W0503).

• Accepts: text of at most 4096 bytes
• Default: empty
• Shown when lock_end is custom
• Ink/Stitch: same key; StitchCraft differs:
  • DEV-LCK-002. Locks of steps follow the stitching round its corners, as Ink/Stitch’s custom steps do. They differ in 5 places. Past the end of stitching shorter than the lock, they go straight on from the last stitch, where Ink/Stitch puts the rest of the lock on the last needle point. Where following a sharp turn would sew a stitch shorter than 0.2 mm, the lock is sewn straight along the first (or last) stitch, with SC-W0502, where Ink/Stitch follows the turn. A step shorter than 0.2 mm is lengthened to 0.2 mm, with SC-W0502, where Ink/Stitch sews it as it is. A custom step of 0 is left out, with SC-W0503, where Ink/Stitch sews a stitch in place for it. And a custom step longer than 10 m, the data model’s reach, is left out with SC-W0503.

lock_end_scale_mm

End lock size. How long each step of an end lock made of steps (back and forth, or custom) is.

• Accepts: a length from 0.1 to 10 mm
• Default: 0.7
• Shown when lock_end is back_forth or custom
• Ink/Stitch: same key, meaning and default

lock_end_scale_percent

End lock scale. How large a drawn end lock is, in percent of its own size: at 100 % it reaches about 1.4 mm along the stitching.

• Accepts: a percentage from 10 to 500
• Default: 100
• Shown when lock_end is arrow, bowtie, cross, star, simple, triangle, zigzag or custom
• Ink/Stitch: same key, meaning and default

Trims and stops

trim_after

Trim after. Cut the thread after this element, even if the next one starts close by.

• Accepts: true or false, in any case, or yes, y, t or 1 for true and no, n, f, 0 or off for false
• Default: false
• Ink/Stitch: same key, meaning and default

stop_after

Stop after. Pause the machine after this element: to add an appliqué fabric, or to check the work.

• Accepts: true or false, in any case, or yes, y, t or 1 for true and no, n, f, 0 or off for false
• Default: false
• Ink/Stitch: same key, meaning and default

Shortest stitch and jump

min_stitch_length_mm

Shortest stitch. Stitches shorter than this are merged into their neighbours, so the needle does not hammer one hole. Empty: the larger of the document’s setting and the machine’s minimum.

• Accepts: a length from 0 to 10 mm, or empty (0 or less counts as empty)
• Default: empty
• Ink/Stitch: same key and default; StitchCraft differs:
  • DEV-PRM-003. An optional length below 0 is read as not set, as 0 is, and SC-W0102 says so. Ink/Stitch reads it as a length and sews what that gives: with a min_jump_stitch_length_mm below 0, it ties off, jumps and ties in between every 2 groups of stitches.
  • DEV-FIN-001. StitchCraft fits every stitch to the machine: it leaves out needle points less than their element’s shortest stitch from the one before, never less than the machine’s (0.3 mm on the Brother), keeping the ends of each run of stitches and its lock points unless a stitch to one would fall short, and splits stitches longer than the machine’s longest. Ink/Stitch drops stitches no longer than the element’s own shortest stitch, else 0.1 mm, and splits nothing. Along an edge square to them, a tatami fill’s rows nearer each other than the shortest stitch hand over in a stitch too short, so the next row’s first needle point is left out and a sliver at its start shows: a bar 5 mm wide at 0.25 mm on the Brother is 97 % covered. Along an edge at 45°, their ends lie 0.35 mm apart, and the handovers stay.

min_jump_stitch_length_mm

Shortest jump. A move to the next element no longer than this is sewn straight on, without lock stitches or a jump. Empty: the document’s setting.

• Accepts: a length from 0 to 20 mm, or empty (0 or less counts as empty)
• Default: empty
• Ink/Stitch: same key and default; StitchCraft differs:
  • DEV-PRM-003. An optional length below 0 is read as not set, as 0 is, and SC-W0102 says so. Ink/Stitch reads it as a length and sews what that gives: with a min_jump_stitch_length_mm below 0, it ties off, jumps and ties in between every 2 groups of stitches.

Longest stitch

max_stitch_length_mm

Longest stitch. Manual stitch splits a stitch longer than this into equal parts, and a satin column splits it as its split method says. Empty, every stitch is sewn whole. A tatami fill sews its rows in stitches this long.

• Accepts: a length from 0.1 to 25 mm, or empty (0 or less counts as empty); for fills, a length from 0.1 to 25 mm, empty being the default
• Default: empty, and 4 for fills
• Applies to: Manual stitch, Satin column, E-stitch, S-stitch, Zigzag satin, Tatami fill
• Ink/Stitch: same key and default; StitchCraft differs:
  • DEV-PRM-003. An optional length below 0 is read as not set, as 0 is, and SC-W0102 says so. Ink/Stitch reads it as a length and sews what that gives: with a min_jump_stitch_length_mm below 0, it ties off, jumps and ties in between every 2 groups of stitches.
  • DEV-RUN-006. No hand-placed stitch is shorter than the shortest stitch. A node closer than that to the needle point before it is left out (SC-W0403), and a stitch longer than max_stitch_length_mm is split into no more parts than keep each at the shortest stitch or longer (SC-W0404). Ink/Stitch splits such a stitch into the fewest equal parts no longer than max_stitch_length_mm, however short they are, and its plan later leaves out stitches of at most 0.1 mm (its default), without a word.

Random variation

random_seed

Random seed. Where random variation starts: a running stitch’s random lengths, a satin column’s random widths and spacing, and a tatami fill’s random lengths. The same seed gives the same stitches, another seed others, and elements alike given one seed vary alike. Empty, each element gets its own.

• Accepts: a number or any text, or empty to derive it from the element
• Default: empty
• Applies to: Running stitch, Ripple stitch, Satin column, E-stitch, S-stitch, Zigzag satin, Tatami fill
• Ink/Stitch: same key and default; StitchCraft differs:
  • DEV-RUN-005. A running stitch’s random lengths are drawn from StitchCraft’s generator (SplitMix64, seeded from random_seed, or from the element’s id when it has none), so the values differ from Ink/Stitch’s for the same seed. They are placed otherwise too. StitchCraft draws a stitch’s length and its span’s phase from 2 numbers, starts a phase only where a span starts, and scales each span’s stitches to end on its corner. Ink/Stitch draws one number for both a stitch’s length and its phase, starts a new phase after each stitch the tolerance shortened as well, and leaves what is left before a corner as the last stitch. Both key each span’s draws by its place in its subpath; StitchCraft’s keys hold the subpath’s place in the path too, where Ink/Stitch’s start again in each subpath, so subpaths drawn alike sew alike there.
  • DEV-SAT-002. Random satin widths, spacing and splits are drawn from StitchCraft’s generator (SplitMix64, seeded from random_seed, or from the element’s id when it has none), so the values differ from Ink/Stitch’s for the same seed. The ranges are Ink/Stitch’s, and so is when a width or a spacing is drawn. Ink/Stitch draws each stitch’s splits from a generator of the stitch’s own, where StitchCraft draws them from the element’s, in the order the stitches are sewn.
  • DEV-FILL-004. A tatami fill’s random stitch lengths are drawn from StitchCraft’s generator (SplitMix64, seeded from random_seed, or from the element’s id when it has none), in the order its row segments are sewn, so the values differ from Ink/Stitch’s for the same seed. The ranges are Ink/Stitch’s: the first point a share of the longest stitch from the segment’s start, and each next one a stitch on, longer or shorter by up to the jitter.

Stroke parameters

How a stroke is sewn.

Applies to Running stitch, Ripple stitch, Zigzag stitch, Manual stitch.

Stroke

stroke_method

Method. The stitch the path is sewn with. A running stitch goes along it and a zigzag across it, and manual stitch puts a needle point on each of its nodes. Ripple stitch arrives in a later version, and until then an element set to it is skipped (SC-W0011).

• Accepts: one of running_stitch (Running stitch), ripple_stitch (Ripple stitch), zigzag_stitch (Zigzag stitch), manual_stitch (Manual stitch)
• Default: running_stitch
• Ink/Stitch: same key, meaning and default

Running parameters

Running stitch: single stitches along the path, for outlines, details and travel.

Applies to Running stitch, Ripple stitch.

Running stitch

running_stitch_length_mm

Stitch length. How long each stitch is. Between corners the stitches are spread evenly, so each one is at most this long. Several lengths separated by spaces sew as a repeating pattern: “2.5 1” sews long, short, long, short. The stitches that join a satin column’s underlays are no longer than the first length.

• Accepts: 1 to 16 lengths from 0.1 to 25 mm, separated by spaces
• Default: 2.5
• Applies to: Running stitch, Ripple stitch, Satin column, E-stitch, S-stitch, Zigzag satin, Tatami fill
• Ink/Stitch: same key and default; StitchCraft differs:
  • DEV-RUN-003. No running stitch is shorter than the shortest stitch, measured straight: corners keep their needle before other points do, a stitch a drop makes too long is split, and lengths below twice the shortest stitch are raised (SC-W0402). A satin column’s travel length is raised the same way, for the straight stitches that join its parts as for its line to the start and the end. Where a satin column’s parts meet nearer than the shortest stitch, the needle’s way between them gives way to the next part’s first point, and so does an underlay’s last point or the column’s start, which moves there; beside a top stitch’s end, which stays where it is, the next part’s points that near it give way instead. Ink/Stitch’s running stitch has no shortest stitch, and it joins a satin column’s parts as they are; its plan later drops stitches of at most 0.1 mm (its default), keeping the stitch before.
  • DEV-SAT-005. A satin column’s travel, and a tatami fill’s, take the first of the lengths running_stitch_length_mm gives. Ink/Stitch reads a satin’s or a fill’s value as one number, and sews a value of several with 2.5 mm, the default.

running_stitch_tolerance_mm

Curve tolerance. How far a stitch may stray from a curve. A smaller tolerance follows curves more closely, with more and shorter stitches. A satin column’s way to its start and from its end keeps to it too.

• Accepts: a length from 0.01 to 5 mm
• Default: 0.2
• Applies to: Running stitch, Ripple stitch, Satin column, E-stitch, S-stitch, Zigzag satin, Tatami fill
• Ink/Stitch: same key; StitchCraft differs:
  • DEV-SAT-006. A satin column’s and a tatami fill’s running_stitch_tolerance_mm defaults to 0.2 mm, the value Ink/Stitch sews when a file sets none. Ink/Stitch’s settings window shows 0.1 mm.

enable_random_stitch_length

Random stitch length. Vary the stitch lengths at random instead of spreading them evenly, or in a tatami fill, instead of placing the needle points on the stagger grid. Lines and rows sewn close together then do not line their needle holes up, which avoids moiré patterns.

• Accepts: true or false, in any case, or yes, y, t or 1 for true and no, n, f, 0 or off for false
• Default: false
• Applies to: Running stitch, Ripple stitch, Tatami fill
• Ink/Stitch: same key, meaning and default

random_stitch_length_jitter_percent

Length variation. How much each stitch may be longer or shorter than the stitch length, in percent of it. A tatami fill’s stitch length is its longest stitch. Where the random lengths start is the element’s random_seed.

• Accepts: a percentage from 0 to 100
• Default: 10
• Shown when enable_random_stitch_length is true
• Applies to: Running stitch, Ripple stitch, Tatami fill
• Ink/Stitch: same key, meaning and default

Repeat parameters

Repeats and bean stitch: sewing a line more than once, for a bolder line or one that comes back.

Applies to Running stitch, Ripple stitch, Zigzag stitch, Manual stitch.

Repeats

repeats

Repeats. How many times to sew along the path: 2 goes there and back, 3 there, back and there again. An even number ends where the path starts, which suits a line that must come back.

• Accepts: a whole number from 1 to 100
• Default: 1
• Applies to: Running stitch, Ripple stitch, Zigzag stitch
• Ink/Stitch: same key, meaning and default

bean_stitch_repeats

Bean stitch. How many times to go back and forth over each stitch: 1 sews every stitch three times (there, back and there again), 2 five times. Several numbers separated by spaces are taken in turn along the stitches: “1 0” makes every other stitch bold.

• Accepts: 1 to 16 whole numbers from 0 to 10, separated by spaces
• Default: 0
• Ink/Stitch: same key, meaning and default

Zigzag stroke parameters

Zigzag stroke: stitches across the path from side to side, as wide as the stroke.

Applies to Zigzag stitch.

Zigzag stroke

zigzag_spacing_mm

Zigzag spacing. How far it is along the path from one stitch to the next that crosses the same way, a zig and a zag together. Ink/Stitch takes several spacings separated by spaces, and sews the first.

• Accepts: 1 to 16 lengths from 0.01 to 100 mm, separated by spaces
• Default: 0.4
• Ink/Stitch: same key, meaning and default

stroke_pull_compensation_mm

Pull compensation. How much further out than half the stroke’s width the needle goes on each side, to make up for the thread pulling the fabric in. 2 values set the 2 sides: the left of the way the path goes, then the right. Negative values make the zigzag narrower.

• Accepts: a length from -10 to 10 mm, or 2 separated by a space
• Default: 0
• Ink/Stitch: same key, meaning and default

zigzag_angle

Zigzag angle. Turns every stitch away from square to the path, in degrees: positive turns clockwise as the drawing shows it. On a curve the turned stitches point like the spokes of a wheel.

• Accepts: an angle from -89 to 89 degrees
• Default: 0
• Ink/Stitch: same key, meaning and default

Satin parameters

Satin column: a band of stitches between two rails.

Applies to Satin column, E-stitch, S-stitch, Zigzag satin.

Satin column

satin_column

Satin column. Sew the path as a satin column. Two of its subpaths are the rails, the column’s edges, and the others are rungs across both, which say which point of one rail goes with which of the other. Without rungs, the rails’ nodes pair up instead. A path of 1 subpath is the column’s centre line: the column is as wide as the stroke, and turns its corners as the stroke’s join does. Off, the path is sewn as a stroke, by its stroke_method.

• Accepts: true or false, in any case, or yes, y, t or 1 for true and no, n, f, 0 or off for false
• Default: false
• Applies to: Running stitch, Manual stitch, Zigzag stitch, Ripple stitch, Satin column, E-stitch, S-stitch, Zigzag satin
• Ink/Stitch: same key, meaning and default

satin_method

Method. How the column is sewn. A satin column sews stitches straight across it, from one rail to the other and back. An E-stitch sews a spike across the column at each pair and a spine along its first rail between them, an edge for appliqué. An S-stitch sews one stitch across at each pair, every other one the other way, with a step along a rail between them: split by a longest stitch, they cover the column in rows, as a fill does. A zigzag satin sews a zigzag between the rails, every stitch slanting half the spacing along.

• Accepts: one of satin_column (Satin column), e_stitch (E-stitch), s_stitch (S-stitch), zigzag (Zigzag satin)
• Default: satin_column
• Ink/Stitch: same key, meaning and default

zigzag_spacing_mm

Zigzag spacing. The distance from one pair of needle points across the column to the next. A satin column goes across and back in one spacing, an E-stitch sews a spike every spacing, and an S-stitch a stitch across, each the other way from the one before. In a zigzag satin the needle goes across and back in one spacing too, its points on the 2 rails half a spacing apart. It is measured across the column at its outside edge. On a curve the stitches lie closer together at the inside edge.

• Accepts: a length from 0.01 to 10 mm
• Default: 0.4
• Ink/Stitch: same key, meaning and default

Rails

reverse_rails

Reverse rails. Which rails are sewn against the way they are drawn, so that both run the same way. Automatic reverses the second rail when it runs against the first.

• Accepts: one of automatic (Automatic), none (Neither), first (The first), second (The second), both (Both)
• Default: automatic
• Ink/Stitch: same key, meaning and default

swap_satin_rails

Swap rails. Make the second rail the first. The column starts on its first rail, and each stitch across it goes from the first rail to the second.

• Accepts: true or false, in any case, or yes, y, t or 1 for true and no, n, f, 0 or off for false
• Default: false
• Ink/Stitch: same key, meaning and default

Start and end

start_at_nearest_point

Start at nearest point. Start near where the elements before left the needle: on the line between the rails, or on the column’s edge when only that is close, then along the line under the column to its start. It saves a jump and a trim.

• Accepts: true or false, in any case, or yes, y, t or 1 for true and no, n, f, 0 or off for false
• Default: true
• Ink/Stitch: same key, meaning and default

end_at_nearest_point

End at nearest point. End near where the next element starts: the column is sewn up to the end point, along the line under it to its end, and back, and ends on its edge nearest the next element.

• Accepts: true or false, in any case, or yes, y, t or 1 for true and no, n, f, 0 or off for false
• Default: true
• Ink/Stitch: same key, meaning and default

running_stitch_position

Running stitch position. Where the line the needle follows to the start and to the end runs, in percent of the way from the first rail to the second: 50 is the middle.

• Accepts: a percentage from 0 to 100
• Default: 50
• Ink/Stitch: same key, meaning and default

Compensation

push_compensation_mm

Push compensation. How much shorter the column is made at its start and its end. Satin stitches push the fabric out along the column, so it comes out longer than drawn, and this makes up for it. Negative values lengthen the column. 2 values set the start, then the end.

• Accepts: a length from -10 to 10 mm, or 2 separated by a space
• Default: 0
• Ink/Stitch: same key, meaning and default

Random variation

random_width_decrease_percent

Random width decrease. How much narrower than the compensated column a stitch may come out on each side, chosen at random for each stitch, in percent of the column’s width there. A ragged edge looks like fur or grass. 2 values set the first rail’s side, then the second’s.

• Accepts: a percentage from 0 to 100, or 2 separated by a space
• Default: 0
• Ink/Stitch: same key, meaning and default

random_width_increase_percent

Random width increase. How much wider than the compensated column a stitch may come out on each side, chosen at random for each stitch, in percent of the column’s width there. 2 values set the first rail’s side, then the second’s.

• Accepts: a percentage from 0 to 100, or 2 separated by a space
• Default: 0
• Ink/Stitch: same key, meaning and default

random_zigzag_spacing_percent

Random zigzag spacing. How much the distance to each stitch may differ from the zigzag spacing, chosen at random, in percent of the spacing, longer or shorter.

• Accepts: a percentage from 0 to 100
• Default: 0
• Ink/Stitch: same key, meaning and default

Short stitches

short_stitch_inset

Short stitch inset. How far a crowded needle point is moved in along its stitch, in percent of the stitch’s width. On the inside of a tight curve the needle points of a rail crowd together, and the thread piles up there. Moving some of them in spreads them out. Points that crowd one after another take turns with several values separated by spaces.

• Accepts: 1 to 16 percentages from 0 to 50, separated by spaces
• Default: 15
• Ink/Stitch: same key, meaning and default

short_stitch_distance_mm

Short stitch distance. How close a needle point may come to the last one left in place on its rail before it is moved in. 0 moves none.

• Accepts: a length from 0 to 5 mm
• Default: 0.25
• Ink/Stitch: same key, meaning and default

Split stitches

split_method

Split method. How stitches longer than the longest stitch (max_stitch_length_mm) are split. Default splits each into the fewest equal parts no longer than it. Simple splits at whole multiples of it from the stitch’s start. Staggered moves those splits along from one stitch to the next, so the needle holes of neighbouring stitches do not line up in a row.

• Accepts: one of default (Default), simple (Simple), staggered (Staggered)
• Default: default
• Ink/Stitch: same key, meaning and default

random_split_jitter_percent

Split jitter. How far each split may move at random, in percent of a part, either way. With a random split phase, how much each part’s length may vary instead.

• Accepts: a percentage from 0 to 100
• Default: 0
• Shown when split_method is default
• Ink/Stitch: same key, meaning and default

random_split_phase

Random split phase. Start each stitch’s splits at a random distance from its start, and space them by the longest stitch, instead of dividing the stitch evenly. The needle holes of neighbouring stitches then fall apart, at the cost of a few more stitches.

• Accepts: true or false, in any case, or yes, y, t or 1 for true and no, n, f, 0 or off for false
• Default: false
• Shown when split_method is default
• Ink/Stitch: same key, meaning and default

min_random_split_length_mm

Shortest split stitch. With a random split phase, also split stitches longer than this but no longer than the longest stitch. 0 splits every stitch. Empty: the longest stitch.

• Accepts: a length from 0 to 25 mm, or empty
• Default: empty
• Shown when split_method is default
• Ink/Stitch: same key, meaning and default

split_staggers

Staggers. How many stitches the staggered splits take to come back to where they started. A fraction draws diagonals that show less than whole numbers do.

• Accepts: a number from 0.01 to 100
• Default: 4
• Shown when split_method is staggered
• Ink/Stitch: same key, meaning and default

Centre walk underlay

center_walk_underlay

Centre walk underlay. Sew a running stitch along the middle of the column first, there and back. It holds the fabric still along the column, and suits narrow columns. The other underlays and the top stitches follow it.

• Accepts: true or false, in any case, or yes, y, t or 1 for true and no, n, f, 0 or off for false
• Default: false
• Ink/Stitch: same key, meaning and default

center_walk_underlay_stitch_length_mm

Centre walk stitch length. How long each stitch of the centre walk is. Between corners its stitches are spread evenly, so each one is at most this long.

• Accepts: a length from 0.1 to 25 mm
• Default: 3
• Ink/Stitch: same key and default; StitchCraft differs:
  • DEV-RUN-003. No running stitch is shorter than the shortest stitch, measured straight: corners keep their needle before other points do, a stitch a drop makes too long is split, and lengths below twice the shortest stitch are raised (SC-W0402). A satin column’s travel length is raised the same way, for the straight stitches that join its parts as for its line to the start and the end. Where a satin column’s parts meet nearer than the shortest stitch, the needle’s way between them gives way to the next part’s first point, and so does an underlay’s last point or the column’s start, which moves there; beside a top stitch’s end, which stays where it is, the next part’s points that near it give way instead. Ink/Stitch’s running stitch has no shortest stitch, and it joins a satin column’s parts as they are; its plan later drops stitches of at most 0.1 mm (its default), keeping the stitch before.

center_walk_underlay_stitch_tolerance_mm

Centre walk tolerance. How far a centre walk stitch may stray from the middle of the column on a curve. A smaller tolerance follows curves more closely, with more and shorter stitches.

• Accepts: a length from 0.01 to 5 mm
• Default: 0.2
• Ink/Stitch: same key; StitchCraft differs:
  • DEV-SAT-004. The centre walk underlay keeps within center_walk_underlay_stitch_tolerance_mm of its line, and follows points that far apart. Ink/Stitch declares that parameter but uses running_stitch_tolerance_mm in its place, the tolerance of the satin’s travel to its start and end. Both are 0.2 mm unless a file sets them.

center_walk_underlay_repeats

Centre walk repeats. How many times the centre walk is sewn: 2 goes there and back, 3 there, back and there again. An odd number ends at the column’s end, and the rest of the column is then sewn from its end.

• Accepts: a whole number from 1 to 100
• Default: 2
• Ink/Stitch: same key, meaning and default

center_walk_underlay_position

Centre walk position. Where the centre walk runs, in percent of the way from the first rail to the second: 50 is the middle.

• Accepts: a percentage from 0 to 100
• Default: 50
• Ink/Stitch: same key, meaning and default

Contour underlay

contour_underlay

Contour underlay. Sew a running stitch along each edge of the column, a little inside it, after any centre walk. It holds the edges still and keeps them crisp.

• Accepts: true or false, in any case, or yes, y, t or 1 for true and no, n, f, 0 or off for false
• Default: false
• Ink/Stitch: same key and default; StitchCraft differs:
  • DEV-SAT-011. After an odd centre walk, which turns a zigzag satin’s run round, StitchCraft stops the contour underlay’s sides where it stops them without one: at the zigzag’s last point on the first rail, and its first and last on the second, in the order the column places them. Ink/Stitch looks for those points in the order the top stitches are sewn, after it has turned them round, and finds the first points where it means the last. Its first side is not cut, and its second shrinks to a stub: on a column 10 mm long and 4 mm wide at a zigzag spacing of 2 mm, 0.2 mm long.

contour_underlay_stitch_length_mm

Contour stitch length. How long each stitch of the contour is. Between corners its stitches are spread evenly, so each one is at most this long.

• Accepts: a length from 0.1 to 25 mm
• Default: 3
• Ink/Stitch: same key and default; StitchCraft differs:
  • DEV-RUN-003. No running stitch is shorter than the shortest stitch, measured straight: corners keep their needle before other points do, a stitch a drop makes too long is split, and lengths below twice the shortest stitch are raised (SC-W0402). A satin column’s travel length is raised the same way, for the straight stitches that join its parts as for its line to the start and the end. Where a satin column’s parts meet nearer than the shortest stitch, the needle’s way between them gives way to the next part’s first point, and so does an underlay’s last point or the column’s start, which moves there; beside a top stitch’s end, which stays where it is, the next part’s points that near it give way instead. Ink/Stitch’s running stitch has no shortest stitch, and it joins a satin column’s parts as they are; its plan later drops stitches of at most 0.1 mm (its default), keeping the stitch before.

contour_underlay_stitch_tolerance_mm

Contour tolerance. How far a contour stitch may stray from its line on a curve. A smaller tolerance follows curves more closely, with more and shorter stitches.

• Accepts: a length from 0.01 to 5 mm
• Default: 0.2
• Ink/Stitch: same key, meaning and default

contour_underlay_inset_mm

Contour inset. How far inside each rail the contour runs, so that it does not show past the top stitches. It also stops short of the column’s start by the first rail’s value and of its end by the second’s. 2 values set the first rail’s side, then the second’s.

• Accepts: a length from -10 to 10 mm, or 2 separated by a space
• Default: 0.4
• Ink/Stitch: same key, meaning and default

contour_underlay_inset_percent

Contour inset (% of width). More inset, in percent of the column’s width at each point, added to the length above. 2 values set the first rail’s side, then the second’s.

• Accepts: a percentage from -100 to 100, or 2 separated by a space
• Default: 0
• Ink/Stitch: same key, meaning and default

Zigzag underlay

zigzag_underlay

Zigzag underlay. Sew a sparse zigzag across the column, to its end and back, before the top stitches. It lifts them off the fabric and makes a wide column look fuller.

• Accepts: true or false, in any case, or yes, y, t or 1 for true and no, n, f, 0 or off for false
• Default: false
• Ink/Stitch: same key, meaning and default

zigzag_underlay_spacing_mm

Zigzag underlay spacing. How far apart the zigzag’s points on each rail are, each way.

• Accepts: a length from 0.01 to 10 mm
• Default: 3
• Ink/Stitch: same key, meaning and default

zigzag_underlay_inset_mm

Zigzag underlay inset. How far inside each rail the zigzag’s points are. Empty: half the contour’s inset, which puts them between the contour and the edge. 2 values set the first rail’s side, then the second’s.

• Accepts: a length from -10 to 10 mm, or 2 separated by a space, or empty
• Default: empty
• Ink/Stitch: same key, meaning and default

zigzag_underlay_inset_percent

Zigzag underlay inset (% of width). More inset, in percent of the column’s width at each point, added to the length above. Empty: half the contour’s. 2 values set the first rail’s side, then the second’s.

• Accepts: a percentage from -100 to 100, or 2 separated by a space, or empty
• Default: empty
• Ink/Stitch: same key, meaning and default

zigzag_underlay_max_stitch_length_mm

Zigzag underlay longest stitch. Split zigzag stitches longer than this into equal parts. Empty: none is split.

• Accepts: a length from 0.1 to 25 mm, or empty (0 or less counts as empty)
• Default: empty
• Ink/Stitch: same key and default; StitchCraft differs:
  • DEV-PRM-003. An optional length below 0 is read as not set, as 0 is, and SC-W0102 says so. Ink/Stitch reads it as a length and sews what that gives: with a min_jump_stitch_length_mm below 0, it ties off, jumps and ties in between every 2 groups of stitches.

Pull parameters

Pull compensation: how far a satin column’s stitches and a tatami fill’s rows reach past the shape’s edge, to make up for the thread pulling the fabric in.

Applies to Satin column, E-stitch, S-stitch, Zigzag satin, Tatami fill.

Pull compensation

pull_compensation_mm

Pull compensation. How far each end of every stitch reaches past the shape’s edge: a satin column’s stitches past its rails, and a fill’s rows past its outline and its holes. The thread pulls the fabric in along the stitches as it sews, so a shape comes out smaller than drawn, and this makes up for it. 2 values set the 2 ends: a satin’s first rail’s side, then the second’s, or the end each fill row starts from at the fill’s angle, then the other (at 0°, the left end, then the right). Negative values make a satin narrower; a fill reads them as 0, as Ink/Stitch does.

• Accepts: a length from -10 to 10 mm, or 2 separated by a space
• Default: 0
• Ink/Stitch: same key and default; StitchCraft differs:
  • DEV-FILL-009. A fill’s pull compensation lengthens each top row at its ends, and the part keeps its holes and its pieces as drawn. Ink/Stitch rebuilds the part round the lengthened rows instead: each is widened by half the row spacing and 0.01 px with round ends, the widened rows are joined, and the outline is smoothed. Its rows then reach past the compensation by up to half a row spacing, less what the smoothing takes off. A hole of less than a row spacing squared, or one the widened rows close over, is filled. Where the widened rows fall into pieces, only the largest is kept, so a part whose rows a neck too thin for a row divides loses all but its largest side.

pull_compensation_percent

Pull compensation (%). More pull compensation, in percent of each stitch’s length, added to the length above: a satin’s stitches reach out by a share of the column’s width there, and a fill’s rows by a share of each row’s length, so wide parts and long rows reach further. 2 values set the 2 ends, as above. A fill reads negative values as 0, as Ink/Stitch does.

• Accepts: a percentage from -100 to 100, or 2 separated by a space
• Default: 0
• Ink/Stitch: same key and default; StitchCraft differs:
  • DEV-FILL-009. A fill’s pull compensation lengthens each top row at its ends, and the part keeps its holes and its pieces as drawn. Ink/Stitch rebuilds the part round the lengthened rows instead: each is widened by half the row spacing and 0.01 px with round ends, the widened rows are joined, and the outline is smoothed. Its rows then reach past the compensation by up to half a row spacing, less what the smoothing takes off. A hole of less than a row spacing squared, or one the widened rows close over, is filled. Where the widened rows fall into pieces, only the largest is kept, so a part whose rows a neck too thin for a row divides loses all but its largest side.

Fill parameters

How a fill is sewn.

Applies to Tatami fill, Circular fill, Contour fill, Cross stitch, Guided fill, Linear gradient fill, Meander fill, Tartan fill, Legacy fill.

Fill

fill

Sew the fill. Whether the fill is sewn. Off, it sews nothing, and the shape’s outline, if it has one, is sewn as its stroke settings say. The element before it still ends near it, as Ink/Stitch’s does.

• Accepts: true or false, in any case, or yes, y, t or 1 for true and no, n, f, 0 or off for false
• Default: true
• Ink/Stitch: same key, meaning and default

fill_method

Fill method. The stitch the area is filled with. A tatami fill sews rows of running stitches across it, and a fill set to Ink/Stitch’s legacy fill is sewn as a tatami fill without underlay (SC-W0314). The other methods arrive in later versions; until then an element set to one is skipped (SC-W0011).

• Accepts: one of tatami_fill (Tatami fill), circular_fill (Circular fill), contour_fill (Contour fill), cross_stitch (Cross stitch), guided_fill (Guided fill), linear_gradient_fill (Linear gradient fill), meander_fill (Meander fill), tartan_fill (Tartan fill), legacy_fill (Legacy fill)
• Default: tatami_fill
• Ink/Stitch: same key and default; StitchCraft differs:
  • DEV-FILL-014. A fill whose fill_method is legacy_fill is sewn as a tatami fill without underlay (SC-W0314), its rows routed and joined by travel stitches as a tatami fill’s are, from near the needle to near the next element. Ink/Stitch’s legacy fill sews each stretch of rows that join on its own, back and forth, with no travel stitches between stretches; its flip starts the rows from the other side, and its reverse sews the whole fill backwards. StitchCraft keeps both settings without reading them (SC-W0105).

Tatami parameters

Tatami fill: rows of running stitches across the fill’s area, the needle points of neighbouring rows offset so that they never line up. Ink/Stitch’s default fill.

Applies to Tatami fill.

Rows

angle

Angle. The direction of the rows, in degrees counter-clockwise from horizontal: 0 sews horizontal rows and 90 upright ones.

• Accepts: an angle in degrees
• Default: 0
• Ink/Stitch: same key, meaning and default

row_spacing_mm

Row spacing. How far apart the rows are, measured square to them. Rows closer together cover the fabric more fully, and pull it in more.

• Accepts: a length from 0.1 to 100 mm
• Default: 0.25
• Ink/Stitch: same key and default; StitchCraft differs:
  • DEV-FILL-012. A point of a part’s outline within 1e-9 mm of a row lies on it, and a row within 1e-9 mm of the part’s far side lies on that side and is left out. Each row lies a whole number of row spacings past the part’s first row, multiplied out. Ink/Stitch adds the row spacing in CSS pixels from row to row, and cuts each row with the part exactly, once the part is put on a grid of 1e-10 pixels. So a row on a side runs along it, crosses the part a hair beside it or misses it as the numbers round, and a part can have a row a hair inside its far side.

end_row_spacing_mm

End row spacing. The spacing of the last rows, for a fill that fades: from the first row the spacing changes steadily towards it, reaching it the part’s height away, in each part of the fill. Empty, every row is the row spacing from the next.

• Accepts: a length from 0.1 to 100 mm, or empty (0 or less counts as empty)
• Default: empty
• Ink/Stitch: same key; StitchCraft differs:
  • DEV-FILL-003. With end_row_spacing_mm, the step from row to row changes from the row spacing to the end spacing over the part’s height, measured from the first row, and stays at the end spacing beyond it. Ink/Stitch carries the change on past the height, which reaches the rows within a row spacing of the part’s far side when the first row lies before the part. With an end spacing smaller than the row spacing, over a part a few rows tall, the steps then shrink towards 0 and the rows pile up short of the far side without end.
  • DEV-PRM-003. An optional length below 0 is read as not set, as 0 is, and SC-W0102 says so. Ink/Stitch reads it as a length and sews what that gives: with a min_jump_stitch_length_mm below 0, it ties off, jumps and ties in between every 2 groups of stitches.

expand_mm

Expand. How far past the drawn edge the top rows reach: each part is grown by this much, with round corners, before its rows are laid. The thread’s pull opens gaps between fills sewn side by side, and this closes them. Negative values pull the rows in from the edge.

• Accepts: a length from -10 to 10 mm
• Default: 0
• Ink/Stitch: same key and default; StitchCraft differs:
  • DEV-FILL-008. Where fill_underlay_inset_mm, or a negative expand_mm, cuts a part into pieces, the pieces are sewn in order of their point of least x, and of least y among pieces level with each other, each with its least x within a nanometre of the one before. GEOS gives them in the order it walks its graph, which Ink/Stitch sews them in. Of 2,000 random polygons grown or shrunk, 85 gave 2 or more pieces, and 81 of those came in the same order; the 4 others had a sliver among their pieces. For pieces level at their least x, GEOS’s order turns on where the ring’s points start: 2 squares one above the other, shrunk apart, give the lower first when the ring is listed from the bottom and the upper first when it is listed from the top, and 310 of 400 random such shapes, listed from random points, gave the lower first. Each piece’s top rows start at the point nearest the needle after the piece before, where Ink/Stitch starts every piece’s top rows nearest the needle as it was before the first.

gap_fill_rows

Gap-filling rows. Rows sewn again where the fill leaves a stretch of more than 3 rows for another: that many rows past the stretch’s last row, back and forth, before the needle travels on. The rows on the far side are sewn later, and the fabric between can be pulled apart by then; these close the gap. Rounded up to an even number, so the needle comes back to where the stretch ended.

• Accepts: a whole number from 0 to 100
• Default: 0
• Ink/Stitch: same key and default; StitchCraft differs:
  • DEV-FILL-010. Each gap-fill row is the next row of the grid past the stretch’s last row, the stretch of its segment beside the gap-fill row before it, or the last row for the first, so it stops at the part’s edge, and the rows stop where the part ends. Ink/Stitch repeats the last row, moved a spacing further each time and keeping its length, so a repeat can run outside the part; its spacing is the distance between the last 2 rows, where the grid’s rows follow the end row spacing. The hops between gap-fill rows and the way back are running stitches kept inside the part as travel is, where Ink/Stitch stitches them as rows, straight.

Stitches

staggers

Staggers. How many rows the needle points take to come back to where they started. Along each row they lie the longest stitch (max_stitch_length_mm) apart, a staggers-th of a stitch along from the row before’s, so that neighbouring rows never line them up. A fraction draws diagonals that show less than whole numbers do. A negative number staggers the rows the other way, and 0 counts as 1, which lines every row’s points up, as in Ink/Stitch.

• Accepts: a number from -100 to 100
• Default: 4
• Ink/Stitch: same key, meaning and default

skip_last

Skip last stitch. Leave out the needle point at the end of each row. It lies close to the start of the next row, and leaving it out lowers the stitch count and the density along the fill’s edge.

• Accepts: true or false, in any case, or yes, y, t or 1 for true and no, n, f, 0 or off for false
• Default: false
• Ink/Stitch: same key, meaning and default

Travel

underpath

Underpath. Travel between rows runs inside the fill, under rows sewn after it, which hide it. Off, the needle travels along the fill’s outline, where the travel can show along the edge.

• Accepts: true or false, in any case, or yes, y, t or 1 for true and no, n, f, 0 or off for false
• Default: true
• Ink/Stitch: same key and default; StitchCraft differs:
  • DEV-FILL-011. With underpath off, or in a part the gratings of lines miss, the needle travels between 2 points of one ring the shorter way round it, by length, and on a tie the way that does not pass the ring’s start. Ink/Stitch’s travel along the outline counts nodes instead: its graph has a node every CSS pixel along the outline’s sides, and at their corners and the rows’ ends, and its edges carry no length, so the way with fewer nodes is taken. That is about the shorter way, but a way past many short sides, as round a curve drawn in short pieces, has more nodes for its length, and the way with fewer nodes can be the longer.
  • DEV-FILL-013. In a part the gratings of lines miss, with underpath on, the needle travels along the part’s rings, as with underpath off. Ink/Stitch also travels along the outline there, but it smooths every way it travels with underpath on, as it smooths a way under the rows: the way cuts the outline’s corners inside the part, and is kept inside it where it leaves it.

Underlay

fill_underlay

Underlay. Sew underlay before the top rows: rows of stitches farther apart than the top rows, square to them unless set otherwise. It holds the fabric still while the fill is sewn and lifts the top rows, so less fabric shows between them.

• Accepts: true or false, in any case, or yes, y, t or 1 for true and no, n, f, 0 or off for false
• Default: true
• Ink/Stitch: same key, meaning and default

fill_underlay_angle

Underlay angle. The direction of the underlay’s rows, in degrees counter-clockwise from horizontal. Several angles separated by spaces sew a layer of underlay at each, one after another. Empty: square to the top rows, at the fill’s angle plus 90°.

• Accepts: 1 to 16 angles in degrees, separated by spaces, or empty
• Default: empty
• Ink/Stitch: same key, meaning and default

fill_underlay_row_spacing_mm

Underlay row spacing. How far apart the underlay’s rows are, measured square to them. Empty: 3 times the row spacing.

• Accepts: a length from 0.1 to 100 mm, or empty (0 or less counts as empty)
• Default: empty
• Ink/Stitch: same key and default; StitchCraft differs:
  • DEV-PRM-003. An optional length below 0 is read as not set, as 0 is, and SC-W0102 says so. Ink/Stitch reads it as a length and sews what that gives: with a min_jump_stitch_length_mm below 0, it ties off, jumps and ties in between every 2 groups of stitches.

fill_underlay_max_stitch_length_mm

Underlay longest stitch. How far apart the needle points along the underlay’s rows are. Empty: the fill’s longest stitch (max_stitch_length_mm).

• Accepts: a length from 0.1 to 25 mm, or empty (0 or less counts as empty)
• Default: empty
• Ink/Stitch: same key and default; StitchCraft differs:
  • DEV-PRM-003. An optional length below 0 is read as not set, as 0 is, and SC-W0102 says so. Ink/Stitch reads it as a length and sews what that gives: with a min_jump_stitch_length_mm below 0, it ties off, jumps and ties in between every 2 groups of stitches.

fill_underlay_inset_mm

Underlay inset. How far inside the fill’s edge its underlay stops: each part is shrunk by this much, with round corners, before the underlay’s rows are laid, so that none of the underlay shows beyond the top rows. Negative values let it reach past the edge.

• Accepts: a length from -10 to 10 mm
• Default: 0
• Ink/Stitch: same key and default; StitchCraft differs:
  • DEV-FILL-008. Where fill_underlay_inset_mm, or a negative expand_mm, cuts a part into pieces, the pieces are sewn in order of their point of least x, and of least y among pieces level with each other, each with its least x within a nanometre of the one before. GEOS gives them in the order it walks its graph, which Ink/Stitch sews them in. Of 2,000 random polygons grown or shrunk, 85 gave 2 or more pieces, and 81 of those came in the same order; the 4 others had a sliver among their pieces. For pieces level at their least x, GEOS’s order turns on where the ring’s points start: 2 squares one above the other, shrunk apart, give the lower first when the ring is listed from the bottom and the upper first when it is listed from the top, and 310 of 400 random such shapes, listed from random points, gave the lower first. Each piece’s top rows start at the point nearest the needle after the piece before, where Ink/Stitch starts every piece’s top rows nearest the needle as it was before the first.

fill_underlay_skip_last

Skip last underlay stitch. Leave out the needle point at the end of each underlay row, as skip_last does for the top rows.

• Accepts: true or false, in any case, or yes, y, t or 1 for true and no, n, f, 0 or off for false
• Default: false
• Ink/Stitch: same key, meaning and default

underlay_underpath

Underlay underpath. Travel between the underlay’s rows runs inside the fill, under the underlay rows sewn after it. Off, the needle travels along the fill’s outline.

• Accepts: true or false, in any case, or yes, y, t or 1 for true and no, n, f, 0 or off for false
• Default: true
• Ink/Stitch: same key, meaning and default

Glossary

VectorCraft compatibility

The VectorCraft releases the StitchCraft plug-ins work with. Each passed both levels of the compatibility gate: the plug-in contract, in VectorCraft’s own plug-in host, and the end-to-end scenarios, in which VectorCraft’s command line applies the effects, saves, and StitchCraft sews what it saved. The gate checks VectorCraft’s latest release, its latest pre-release, its release branch and its main every day. A release that passes is added here by the pull request that adopts it.

The plug-ins speak VectorCraft’s plug-in ABI v1. Pull requests are checked against VectorCraft 0.18.0, the release the gate pins in compat/vectorcraft.toml.

Design documents

These pages are the specification StitchCraft is built from. They describe behaviour and algorithms in our own words and never carry Ink/Stitch’s code (ADR-0012).

Reading order

1. Technical design document — the whole system in 25 minutes.
2. Architecture — crates, layers, where code goes.
3. Data model, parameter registry, diagnostics.
4. Engine pipeline, the stitch generators and image to embroidery.
5. Machine formats and rendering previews.
6. VectorCraft integration, the plug-in features RFC and the compatibility gate.
7. Quality: conformance, determinism, guardrails, docs pipeline.
8. File compatibility: SVG input and the Ink/Stitch compatibility contract.
9. Decisions: ADRs.

Keeping these pages true

• A design page changes in the same PR as the behaviour it describes. The comment <!-- implements: … --> below its title names the source files it describes. cargo xtask docs for PATH lists the pages for a file. cargo xtask docs --check fails when a branch changes those files and leaves the page as it was, unless a commit message on the branch says Design-reviewed: <page>.
• Pages cite requirement ids (REQ-…) and diagnostic codes (SC-…); the docs check fails on unknown ids.
• Facts about Ink/Stitch and VectorCraft name the commit they were checked against.

StitchCraft — Technical Design Document

StitchCraft turns vector art into machine embroidery. It is two things that ship together:

1. An engine — host-agnostic Rust crates that turn shapes plus embroidery parameters into a stitch plan and encode it as machine files (PES for Brother first, then DST, EXP, JEF, VP3 …).
2. A VectorCraft plug-in — the engine inside VectorCraft, ArtCraft’s open-source, clean-room Illustrator written in Rust, so embroidery is designed where the art is drawn.

It covers the common machine-embroidery stitch types (running, bean, satin, tatami fill, contour, meander, ripple, …) and reads the embroidery parameters Ink/Stitch stores in SVG files, so designs move between the tools. Its quality bar: it never crashes, it produces the same file on every platform, and every behaviour is pinned by a conformance suite and by sew-outs on a real machine.

1. Goals

Non-goals for 1.0

• An Inkscape extension.
• Photo stitch: photographs sewn in blended colours. Pictures of flat colour, such as logos, clip art and drawings, are digitized automatically from M13 (image to embroidery).
• Sending files to machines over USB/Wi-Fi; the output is a file you copy to the machine.
• A standalone GUI. The GUI is VectorCraft; the CLI renders previews to PNG.

2. Target machine and the first user

The first production target is a Brother PE800, a home embroidery machine whose largest hoop, 5 × 7 in, sews at most 130 × 180 mm, loading PES files (ADR 0013). It becomes the built-in profile brother-pe800-5x7, the reference profile, with one profile for each of its other hoops: brother-pe800-4x4 (100 × 100 mm) and brother-pe800-small (20 × 60 mm).

Profiles are data (see data model); adding a machine never touches the engine.

3. Background

3.1 File compatibility with Ink/Stitch

Ink/Stitch, a GPL-3.0 extension for Inkscape, stores its embroidery settings in SVG files as inkstitch:<name> attributes. StitchCraft reads and writes the same attribute names, values and defaults, so a design moves between the tools unchanged. Those names, types and defaults are facts listed in the compatibility contract; where StitchCraft’s behaviour differs on purpose, the deviations ledger (conformance/deviations.toml) says how and why. StitchCraft is an independent project and contains no Ink/Stitch code, documentation text or data files (ADR-0001).

3.2 VectorCraft, the host

VectorCraft (MIT OR Apache-2.0, Rust 2024, ~290,000 lines) is a clean-room Illustrator. What matters here (details and file references in VectorCraft integration):

• Plug-in ABI v1: sandboxed WebAssembly modules run by wasmi with no imports. Two kinds: object filters (one undo step) and live effects (rewrite one object’s geometry whenever it is drawn). Parameters come from a manifest schema (number, int, bool, choice; at most 64).
• Live-effect parameters are stored per object in the document as {"id": "plugin.<id>", "params": {…}} — so embroidery settings can live on the art today, with no VectorCraft change.
• Limits that shape our design: 50 M instructions per call (+4,000 per input byte), 5 s per live-effect run, input is geometry only (no paint), no file-format plug-ins, no panels.
• Everything is a command, reachable from the UI, a JSON control channel, an MCP server and a headless CLI (vectorcraft-cli run --in f --cmd … --export out.png), which our tests and screenshot pipeline drive.

3.3 Licence and clean room

Ink/Stitch is GPL-3.0; VectorCraft forbids GPL code in its tree. StitchCraft is MIT OR Apache-2.0 and never copies GPL code: the design docs in this folder describe behaviour (inputs, outputs, parameters, algorithms) in our own words, and implementers work from these docs. Ink/Stitch’s source may be read to understand its behaviour, never copied or transliterated. Parameter names are kept identical to Ink/Stitch’s SVG attributes because that is the interoperability contract. See ADR-0001 and ADR-0012.

4. Requirements

4.1 Functional scope by phase

The full milestone and step list is in the roadmap.

4.2 Non-functional requirements

5. Architecture

 Hosts / adapters                   Engine                                      Outputs
┌────────────────────┐      ┌───────────────────────────────────────┐      ┌──────────────────┐
│ SVG (Ink/Stitch)   │─┐    │ normalize ─▶ validate ─▶ generate     │      │ PES / DST / …    │
│ .vectorcraft file  │─┼──▶ │   per element (StitchGroup)           │ ──▶  │ PNG preview      │
│ VectorCraft plug-in│─┘    │ ─▶ assemble plan (order, travel,      │      │ JSON report      │
└────────────────────┘      │    ties, trims, colours) ─▶ finalize  │      │ plug-in geometry │
        Design              │    (profile limits) ─▶ StitchPlan     │      └──────────────────┘
                            └───────────────────────────────────────┘
                                    + Diagnostics at every stage

The workspace is split into layered crates; a crate may depend only on lower layers, enforced by cargo xtask layers:

Details, dependency rules and the reasoning are in architecture.

6. Key decisions

7. Data model (summary)

Full types in data model.

• Units: millimetres as f64, y pointing down (same as SVG and VectorCraft). Adapters convert (pt × 25.4/72, SVG user units through the viewBox). Encoders quantize absolute positions to 0.1 mm once, so long designs never drift.
• Design (engine input): ordered Elements — id (stable host id), shape (Region, Path or Satin), thread, params (ParamSet), commands (start/end points, trim, stop, ignore) — plus design settings (collapse length, minimum stitch length, origin) and a machine profile.
• StitchPlan (engine output): colour blocks of stitches; every stitch has a position, a kind (Normal, Jump, Trim, Stop, ColorChange, End) and provenance (element id and role: underlay, top, travel, lock) used by previews, reports and diagnostics.
• Diagnostics: SC-E… errors and SC-W… warnings with element, location, message and a fix hint; each code has a generated explanation page (diagnostics).

8. Engine pipeline (summary)

Detailed in engine pipeline.

1. Normalize each element. Curves are flattened to tolerance, and each fill’s region is built by its fill rule. Degenerate pieces are dropped with a diagnostic.
2. Validate parameters against the registry (type, range, applicability) and shapes against the stitch type (e.g. a satin needs two rails).
3. Generate a StitchGroup per element with its stitch type’s generator. Generators are pure functions of (shape, typed params, seed, budget) — no globals, no I/O.
4. Assemble the plan: keep document order, connect groups (travel inside a region, or tie-off → jump/trim → tie-in), insert colour changes and stops, apply commands.
5. Finalize against the profile: split stitches above the maximum, merge below the minimum, check the hoop and colour limits.
6. Check invariants (the same checker the conformance suite uses) before any file is written.

9. Stitch generators (summary)

Generators follow Ink/Stitch’s stitch placement, worked out from its behaviour and from published algorithms such as an Eulerian path through a fill’s rows, or offset curves for a contour fill’s rings. Each generator’s page cites them. Where one differs, conformance/deviations.toml says how and why.

10. Machine formats

PES (v1 header + PEC block) and DST first, then EXP, JEF, VP3, XXX, U01. Writers quantize once, encode commands per the format’s rules and validate against limits (displacement per record, colour count). Readers are bounded and fuzzed. pyembroidery (MIT) is used in CI as an independent oracle: it must read our files back to the same stitches. Details: formats.

11. Robustness

• Shipped code has no unwrap, expect, panic!, unreachable!, todo!, unimplemented!, and no unchecked indexing on data; enforced by workspace lints (adopted from VectorCraft).
• Every generator receives a work budget (stitch count, iterations); running out returns a diagnostic and the partial-free result “nothing for this element”, never a hang. Budgets are counted in work units, not wall time, so they are deterministic.
• Degradation is explicit: when a fill is too small for rows, the outline fallback is emitted with SC-W0305; when travel cannot stay inside a region, the plan uses tie-off + trim + tie-in and says so — never a silent straight line across the design.
• Parsers cap sizes and counts before allocating; files are untrusted.

12. Determinism

Ordered collections only (BTreeMap, Vec), transcendental functions from libm, a documented seeded PRNG (SplitMix64) with seeds derived from element id and the random_seed parameter, absolute quantization at encode time, and golden files compared byte for byte on every operating system CI tests on. Details: determinism.

13. VectorCraft integration (summary)

Three phases (full design in VectorCraft integration):

1. ABI v1, no upstream change (M6). Plug-ins dev.stitchcraft.running, .satin and .fill are live effects: applying one stores the embroidery parameters on the object and draws a lightweight stitch preview. VectorCraft’s own commands make satin columns of 2 paths, add rungs and bake previews, and its Graphic Styles keep embroidery settings as presets. Machine files come from stitch export design.vectorcraft. (The namespace is one constant, changed in one place once the project has a domain.)
2. Plug-in features, proposed upstream. An RFC for the ArtCraft team proposed exporter plug-ins, rich parameter schemas (labels, units, groups, conditions), a display-only overlay channel for real stitch previews, budget classes and document-level plug-in data. Every item is generic, not embroidery-specific. VectorCraft took most of them into ABI v1, in 0.14.0 to 0.17.0, and M6.8 to M6.12 use them. M9, after 1.0, proposes the rest: overlays, heavy live effects and the objects beside a live effect’s object.
3. In-tree crate, optional. Because the engine is MIT/Apache and host-agnostic, VectorCraft (or a fork) can embed it natively with panels and a simulator.

14. Testing and conformance (summary)

Conformance-first (conformance): requirements have IDs; cases are data files; the runner reports a requirement × case matrix.

Plus unit tests, property tests (proptest), snapshot tests (insta), CLI-in-docs tests (trycmd), mutation testing (cargo-mutants) and coverage ratchets.

15. Documentation (summary)

mdBook site organised by Diátaxis (tutorials, how-to, reference, explanation) plus these design docs. Reference pages are generated from the code and CI fails if they are stale; stitch images are rendered by our renderer from conformance fixtures; VectorCraft UI screenshots are produced by scripted scenarios through VectorCraft’s control channel and compared on every PR. A label on the PR regenerates them. Details: docs pipeline.

16. Security and supply chain

cargo-deny (licences allow-list with GPL denied, advisories, duplicate versions), unsafe forbidden outside the audited ABI module, fuzzed parsers, pinned toolchain, Dependabot for crates and Actions, least-privilege workflow tokens.

17. Release and versioning

SemVer per crate; the plug-in’s version and its VectorCraft ABI version are reported in its manifest. Changelogs from conventional commit scopes (release-plz, M12). Plug-in .wasm files and CLI binaries are attached to GitHub Releases with checksums. A release requires: green gates, compatibility gate green for the current VectorCraft stable, and the machine checkpoint for that milestone signed off.

18. Risks

19. Open questions

1. Exact Brother model (affects PES version and trim support) — answered at MC-1 at the latest.
2. Final project name and plug-in id namespace (working name StitchCraft; plug-in ids derive from one constant).
3. ArtCraft’s appetite for the RFC’s open proposals and for embroidery in-tree. Ask on their Discord before M9. VectorCraft adopted the rest from 0.14.
4. Where the repository lives on GitHub (needed for the docs site URL and badges).

Architecture

This page is the map of the code: which crate owns what, which way dependencies point, and where a new piece of code belongs. If you are about to add a file and are not sure where, the decision table at the end answers it.

Principles

1. The engine knows nothing about hosts. It never sees SVG, VectorCraft, files or the network. Hosts adapt their documents into a Design and consume a StitchPlan.
2. Pure core, effects at the edges. Generators are deterministic functions of their inputs. File I/O, clocks, environment variables and terminals live only in apps and xtask.
3. One source of truth per concept. Parameters live in the registry, diagnostics in the diagnostics registry, machine profiles in profile data. Everything else (UI schemas, CLI flags, docs pages, test strategies) is generated from them.
4. Layering is enforced, not suggested. cargo xtask layers fails the build when a crate reaches up or sideways.
5. Small modules with one job. Files over 800 lines warn and over 1,500 fail (cargo xtask filesize); a stitch type is a module, not a branch in a big match.

Crates and layers

L3  stitchcraft-svg          stitchcraft-vectorcraft        (adapters)
      │                         │
L2  stitchcraft-engine ◀───────┘     stitchcraft-formats   stitchcraft-render
      │                                  │                     │
L1  stitchcraft-plan ◀──────────────────┴─────────────────────┘
      │
L0  stitchcraft-core ◀── stitchcraft-params

apps:  stitchcraft-cli (bin `stitch`)   stitchcraft-vc-plugin (wasm32 cdylib)
test:  stitchcraft-testkit (dev-dependency only)
tools: stitchcraft-xtask (`xtask/`, run as `cargo xtask`)

Intra-layer edges are allowed only where listed (stitchcraft-params → stitchcraft-core). The table lives in xtask/src/layers.rs and is append-only, like VectorCraft’s.

Why this split

• plan below engine and formats lets the formats crate encode and decode plans without pulling in geometry and generators; a file converter (stitch convert a.dst b.pes) links only L0–L2 formats code.
• params at L0 because both the engine (typed views) and the adapters (attribute mapping) need it, and because docs/UI generation must not depend on algorithms.
• Adapters at L3 so the engine can be tested without any host, and a new host (another editor, a web service) is one crate, not a refactor.
• Two apps because the CLI needs the filesystem and threads while the plug-in must stay inside a sandbox with no imports.

External dependencies

Dependencies are added deliberately and recorded in the crate’s README section “Dependencies”. cargo-deny enforces the licence allow-list (MIT, Apache-2.0, BSD-2/3, ISC, Zlib, Unicode) and denies GPL/AGPL/LGPL.

The engine’s geometry is its own, with no crate for curves, regions, offsets, nearest points or graphs: spike M0.7 accepted that (ADR-0005). Versions above are those Cargo.toml asks for (2026-10-17), and Cargo.lock is the truth.

Hosts: ports and adapters

The engine exposes one entry point and one input type:

pub fn plan(design: &Design, profile: &MachineProfile, budget: &Budget) -> PlanOutcome;   // since M3.8

pub struct PlanOutcome {
    pub plan: Option<StitchPlan>,   // None when nothing could be sewn
    pub diagnostics: Vec<Diagnostic>,
    // per-element groups, for previews and reports, arrive with the VectorCraft plug-in (M6)
}

The machine profile is an input because the shortest stitch a generator may sew is the machine’s, and finalizing (M3.9) fits the plan to the machine’s longest stitch and hoop.

and a per-element entry point, which plan calls for each element and live previews call for one:

pub fn generate(element: &Element, settings: &DesignSettings, profile: &MachineProfile,
                neighbours: &Neighbours, budget: &Budget) -> Generation;   // since M3.8

pub struct Generation {
    pub generated: Option<Generated>,   // the element's stitch groups; None when it is skipped
    pub diagnostics: Vec<Diagnostic>,
}

A live preview sees one object, so it has no neighbours, and it sews on the reference machine.

Adapters only translate:

A future in-tree VectorCraft crate would be a fifth adapter calling the same two functions.

Errors and diagnostics

• Diagnostics describe problems with the user’s design (a satin with three rails, a fill smaller than its row spacing, a design larger than the hoop). They are values, collected, coded and shown; planning continues where it can.
• Errors (Result<_, XxxError>) describe failures to do the work (a file is truncated, a budget is exhausted, an I/O failure). Each crate has one thiserror enum; apps turn errors into diagnostics or exit codes.
• Nothing below the apps prints, exits or panics.
• A bug in StitchCraft is neither. It shows as a failed plan check (SC-E0009) or as a panic despite the lints. The command line catches it and ends with exit status 4. For stitch plan it also writes a bug-report bundle that reproduces the bug (determinism). A VectorCraft exporter declines with it, so VectorCraft doesn’t write the file.
• The command line’s own promises. A command refuses outputs that name the same file as each other, or as a file it reads (REQ-CLI-007), and writes each file under a temporary name of its own, created new and synced before it is renamed into place (REQ-CLI-006). Built for WASI, as cargo xtask wasm --goldens runs it, a program has no process id, so there the names count from 0. What it prints of a file it wrote is the file read back (REQ-CLI-008, stitchcraft_formats::read_back, which the VectorCraft exporters call too). A closed standard output keeps a command’s exit status, any other error writing it ends with 3 (REQ-CLI-009), and help and errors are coloured only on a terminal (REQ-CLI-010).

Feature flags

Kept minimal: stitchcraft-engine/experimental exposes generators whose status is experimental in the registry (they appear in docs with a badge); stitchcraft-formats/<format> flags exist only if a format pulls a heavy dependency (none planned). No flag may change the output of a stable generator.

WebAssembly constraints

Everything in layers L0 to L3 must build for wasm32-unknown-unknown, which cargo xtask wasm checks. That target has no threads, file system, clocks, environment, processes or randomness from the OS, and std’s calls for them build there but fail or panic when run, so clippy.toml keeps library crates from calling them. The plug-in is built in release with the workspace’s profile (thin LTO, one codegen unit), and on wasm32-unknown-unknown a panic aborts. That is one more reason the no-panic rule is absolute: the module stops, and VectorCraft reports the plug-in as failed.

Where does my code go?

Data model

The types every crate shares. Code sketches are illustrative (ignore); the crates’ rustdoc is the API reference once the types exist. Invariants listed here are checked in code (constructors return Result) and by conformance level L0.

Units and coordinates (stitchcraft-core)

/// A length in millimetres. Always finite; construction from untrusted input is checked.
pub struct Mm(f64);

/// A point in millimetres, y pointing down (SVG and VectorCraft convention).
pub struct Point { pub x: f64, pub y: f64 }

• Internal unit: millimetres. Embroidery parameters are specified in mm and machine files use 0.1 mm, so mm keeps the numbers people read and the numbers we compute the same.
• Host units are converted at the adapter: VectorCraft points ×25.4/72; SVG user units through the root viewBox/width/height, with CSS pixels at 96 per inch.
• Quantization happens once, in the encoder, on absolute positions: round_half_even(x * 10). Deltas are differences of quantized absolutes, so rounding never accumulates.
• Axis conventions per format are the encoder’s job (DST is y-up). Test sheet TS-01 (an asymmetric “F” with a ruler) proves orientation and scale on the machine.

Engine input: Design (stitchcraft-engine)

Hosts translate their documents into a Design (stitchcraft_engine::design), so the engine never sees a host document and every host gets the same stitches for the same design. Since M3.3:

pub struct Design {                  // checked by Design::new
    elements: Vec<Element>,
    pub settings: DesignSettings,
    pub sort_colours: bool,          // since M13.3: the elements with settings sew in the order StitchCraft chooses too
}

pub struct Element {
    pub id: ElementId,               // stable host id: "svg:path123:fill", "vc:42:fill"
    pub name: Option<String>,        // the name the user gave it (Inkscape's label)
    pub shape: Shape,
    pub thread: Thread,
    pub params: ParamSet,            // as the host stores them; validated against the registry when planned
    pub automatic: bool,             // since M13.1: a shape without settings, read with --auto, whose stitches StitchCraft chooses
}

pub struct Reading {                 // since M13.1: what every host's reader is asked
    pub auto: bool,                  // --auto
    pub sort_colours: bool,          // since M13.3: --sort-colours, which the reader passes on (Design::read_as)
}

pub struct DesignSettings {          // since M3.8; read from an Ink/Stitch file since M4.8, its commands from M8,
                                     // and from a VectorCraft document since M6.11
    pub collapse_len: Mm,            // 3 mm: same-thread moves no longer than this are sewn on, not jumped
    pub min_stitch_len: Option<Mm>,  // the design's shortest stitch, for elements that set none
    pub origin: Option<Point>,       // where the hoop's centre goes; None: the centre of the stitches
    pub stop_position: Option<Point>,// where the frame moves before each stop; None: it stays
    pub min_satin_stroke_width: Mm,  // 1 mm: a satin column drawn as one path no wider is sewn as a stroke (M4.8)
}

pub enum Shape {
    Stroke { path: Path, width: Mm, join: Join, cap: Cap },  // an outline: running stitch and the other stroke methods
    Fill { path: Path, rule: FillRule },           // an area: its boundary, and which parts are inside
}

pub enum Join { Miter { limit: f64 }, Round, Bevel }   // a stroke's corners; Join::UNSET is a miter limited at 5
pub enum Cap { Butt, Round, Square }                  // since M13.1: how a stroke ends where an open subpath ends

pub struct Path { pub subpaths: Vec<Subpath> }   // in millimetres, y down
pub struct Subpath { pub start: Point, pub segments: Vec<Segment>, pub closed: bool }
pub enum Segment { Line(Point), Quad(Point, Point), Cubic(Point, Point, Point) }

Elements are in the host’s paint order, bottom first. They sew in that order unless the design has automatic elements or sort_colours is set: since M13.3 automatic digitizing then chooses the order (image to embroidery). Curves keep their control points, and the generators flatten them with the tolerance their parameters give.

A host reads 3 of the settings by Ink/Stitch’s names, collapse_len_mm, min_stitch_len_mm and min_satin_stroke_width_mm: an SVG file’s metadata, and since M6.11 the data a VectorCraft document keeps for StitchCraft’s Design Settings filter. SETTINGS lists them with the label and help that filter’s dialog shows, and Setting::get and Setting::set read and write each in millimetres. A shortest stitch of 0 is None, which leaves it to the machine.

A stroke’s width and join, since M4.8, are as the host draws them: in SVG, stroke-width scaled by the transforms, and stroke-linejoin with stroke-miterlimit (SVG input). Only a satin column drawn as one path uses them, as its width and its corners. Shape::stroke(path) makes a stroke that says nothing of either: 1 CSS pixel wide, with Join::UNSET. Its cap, since M13.1, is SVG’s stroke-linecap or VectorCraft’s cap, Butt when nothing sets it. Ink/Stitch sews no cap, and neither does an element with settings. An automatic element’s stitches follow it (image to embroidery).

An automatic element is a shape without settings that the user asked StitchCraft to digitize: the readers mark it when Reading::auto is set, and the engine turns it into ordinary elements with the settings its width calls for before anything is generated (stitchcraft_engine::auto).

Documents repeat ids, so adapters make theirs unique with stitchcraft_core::Labels, which gives a label repeated in a document ~2, ~3 and so on, in every adapter alike.

Invariants, checked by Design::new: element ids are unique, and every point is finite and within ±10,000 mm, as far as machine-file coordinates go. No stroke is narrower than 0, a miter limit is a finite number of at least 1, and the settings’ lengths are not negative. Adapters drop what they cannot represent with a diagnostic of their own, so a failed check is a bug in the adapter (SC-E0009). Design::moved gives the design moved by an offset, every point of its elements and its origin and stop position, checked the same way. VectorCraft’s Test Sheet filter draws a test sheet in the middle of the artboard with it (REQ-VC-015).

Commands attached to elements come with M8, for Ink/Stitch’s command symbols such as start and end points. Trims and stops are the element parameters trim_after and stop_after, and the origin and stop position are design settings (M3.8).

Region

A fill’s region is not part of the design: the normalizer builds it from the fill’s path and fill rule, since M5.1 (stitchcraft_engine::normalize::region):

pub struct Region { pub parts: Vec<Polygon> }   // in the order the drawing reaches them
pub struct Polygon { pub outline: Vec<Point>, pub holes: Vec<Vec<Point>> }   // closed rings, in millimetres

Each ring starts at its point that comes first in the drawing, and repeats it at its end. Outlines turn clockwise and holes counter-clockwise in y-up axes, and in those axes the region lies on the right of every ring. Parts of 3 square CSS pixels (0.21 mm²) or less are left out, with SC-W0303. The fills design builds the region step by step.

SatinShape

A satin column’s path is recognized, since M4.1, as one of 2 shapes (stitchcraft_engine::normalize::satin):

pub enum Shape {
    Rails(Satin),   // 2 rails as polylines, and what pairs their points: rungs, or the rails' nodes
    CentreLine { line: Vec<Point>, closed: bool },  // one subpath, flattened; closed when the path ends with Z
}

A centre line is made into a Satin of its own, its rails offset from the line by the stroke’s width and join (stitchcraft_engine::normalize::centre_line, since M4.9). How rails and rungs are recognised from a host path, and made from a centre line, is part of the satin design.

Parameters

ParamSet maps registry keys to typed values; generators receive typed views (TatamiParams { row_spacing: Mm, angle: Deg, … }) produced by the registry. See parameter registry.

Engine output: StitchPlan (stitchcraft-plan)

pub struct StitchPlan {
    pub blocks: Vec<ColorBlock>,       // sewing order; a thread change between blocks, the end after the last
    pub elements: Vec<ElementId>,      // what `ElementRef`s point at
}

pub struct ColorBlock {
    pub thread: Thread,
    pub stitches: Vec<Stitch>,
}

pub struct Stitch {
    pub at: Point,                     // where the needle is after this entry (mm, y down, hoop centre = 0,0)
    pub kind: StitchKind,
    pub origin: Provenance,
}

pub enum StitchKind { Normal, Jump, Trim, Stop }

pub struct Provenance {
    pub element: Option<ElementRef>,   // index into `elements`; None for plan-level entries
    pub role: Role,                    // Top, Underlay, Travel, Lock, Command
}

• Colour changes and the end are structure, not entries. The machine changes thread between two blocks and ends after the last one, so a plan cannot misplace either; encoders write exactly one colour change between blocks and one end.
• Trim and Stop happen where the needle is; their at repeats the needle position so every entry has one (bounds, previews and reports never special-case commands), and the invariant checker verifies it. Encoders decide how a format expresses them. PEC puts a trim flag on every jump after the first move, and records a stop as a change to the same thread. DST spells a trim as a run of jumps. See formats.
• The origin is the centre of the hoop, where the needle starts, above the fabric. The first Normal stitch is the first time it goes down.
• PlanBuilder appends entries with the needle tracked; PlanStats counts stitches, jumps, trims, stops and thread changes for reports.
• A plan does not name a profile: it is checked against one, invariants::check(&plan, &profile).

Plan invariants

Conformance level L0 checks these on every plan the suite produces. A violation is a bug in whatever built the plan: the command line reports it as SC-E0009 and writes nothing. “While sewing” means the previous movement was a Normal stitch with no trim since — the stitch lays thread between two holes, and its length is what the machine and fabric feel; the first stitch after a jump, a trim or a thread change starts a new run. A length or a position within LENGTH_SLACK (10⁻⁹ mm) of a limit counts as at it, at the hoop’s edge as for a stitch’s length, so rounding cannot push a stitch placed exactly at a limit past it. Generators place stitches by the same test, and so does the check that a design fits the hoop.

REQ-PLAN-004, a tie-off before a trim and a tie-in after it, is retired. Whether they belong there depends on the elements’ lock settings, which a plan does not hold. Assembly’s cases check it with the settings (REQ-ASM-003, REQ-LCK-001).

Threads and palettes

pub struct Thread {
    pub color: Rgb,                  // what the user chose
    pub name: Option<String>,        // shown to the operator
}

Palettes are static tables (the Brother PEC palette first) of PaletteEntry { index, name, color, matchable }. Nearest-colour matching uses CIEDE2000 in CIELAB (D65), through stitchcraft_core::math so it is deterministic, with ties going to the lower index; it is tested against the 34 reference pairs of Sharma, Wu & Dalal (2005). Entries that are not threads — Brother’s applique steps 62–64 — are never matched. A format that names threads by entries gives a design’s threads theirs together (Palette::assign, REQ-THREAD-002). Different threads get different entries while they last, the nearest pairs first, and a thread read from such a file gets its own (formats, PES). Each table names its source in its module docs and in a row of NOTICE. The PEC palette is the one MIT-licensed pyembroidery publishes, with entries 62 and 63 from its fork pystitch. Thread catalogues (brand and number) arrive with M11.

Machine profiles

pub struct MachineProfile {
    pub id: &'static str,            // "brother-pe800-5x7"
    pub name: &'static str,          // "Brother PE800 with its 5 × 7 in hoop"
    pub hoop: Size,                  // 130 × 180 mm
    pub comfort: Option<Size>,       // None — a warning beyond it, not an error
    pub format: FormatId,            // PesV1 | Dst
    pub max_stitch: Mm,              // 12.0
    pub min_stitch: Mm,              // 0.3
    pub trims: TrimSupport,          // Command | LongJumps(Mm) | None
    pub palette: PaletteId,          // BrotherPec
    pub evidence: &'static str,      // where the values come from
}

Profiles are data in stitchcraft-plan/src/profiles/, listed by stitch profiles and documented by generated reference pages. A profile’s values are machine facts: changing one requires a machine-testing record that justifies it (machine testing), and evidence says where each value comes from. Format limits that are not machine facts (the most colour changes a format records) live on FormatId, so the invariant checker and the encoders read the same number.

A profile is a machine with one hoop, so a machine with 3 hoops has 3 profiles. profiles::REFERENCE is the reference machine’s, the Brother PE800 with its 5 × 7 in hoop (ADR 0013). Code that means the machine the checkpoints run on imports it rather than naming a hoop: the command line plans for it unless --profile names another or a VectorCraft document keeps one (integration). Each test sheet names the profile of the hoop it is sewn in.

check_fit(bounds) turns the design’s size into SC-E0701 (larger than the hoop) or SC-W0702 (larger than the comfort zone), with “rotate 90°” as a one-click fix when turning the design would fit (REQ-PRF-002).

Budgets

pub struct Budget {
    pub max_stitches: u32,           // per design, default 2,000,000
    pub max_work: u64,               // abstract work units per element, and once more for assembly
}

Work units are counted per inner loop iteration (scanline crossings, graph edge visits, offset steps) so a budget behaves identically on every machine. Each element has the work budget to itself, and so does working out what it offers the element before it to end near. Exhaustion there yields SC-E0004 for the element, and other elements still plan. Assembly and finalize share the budget once more, and running out there plans nothing. SC-E0004 then says so for the whole design.

Work bounds time, not memory: a unit can make a point, and 500 million points are gigabytes. A few settings multiply an element’s needle points. 10 mm of zigzag at the smallest spacing, sewn 100 times with bean stitch 10, is 4.2 million. So the stitch limit bounds what generators hold as well (REQ-GEN-004):

• A generator spends a stitch for each needle point as it makes it, and for each one a pass after the first or bean stitch sews again.
• What it lays out before sewing it must fit in the stitches left, though it spends none on it: a satin column’s pairs, say, or a fill’s row segments.
• Once done, it settles at the needle points it gives. Some it made were dropped on the way, such as points too close together, and some were copied, such as an E-stitch’s way back down its spike.

So a generator never holds much more than the stitches left, and it may stop a little short of the limit where it made many more points than it keeps. Each element is given the stitches the elements before it left. The first that needs more ends planning there, with SC-E0004 naming it: the design cannot be sewn within its limit, and making the rest would only fill memory.

Parameter registry

A parameter is declared once for the stitch types that read it, next to the generator that uses it. Everything else that needs to know about parameters is generated from that declaration:

                        ┌──▶ typed params struct used by the generator
                        ├──▶ validation (types, ranges, applicability) with coded diagnostics
params! { … }  ─────────┼──▶ VectorCraft plug-in manifests (schema per plug-in, ≤ 64 params)
(in the generator)      ├──▶ CLI: `stitch params`, `--param key=value`
                        ├──▶ SVG mapping (`inkstitch:<key>` attributes, read and write)
                        ├──▶ reference docs pages + JSON Schema (generated, checked in CI)
                        └──▶ proptest strategies for conformance and fuzzing

Nothing about a declaration is written twice, so its label, help, range and default cannot drift apart between the code, the docs and the user interfaces. The diagram is the design’s aim. Generated outputs says which outputs exist today and which steps add the others.

Declaring parameters

Parameters are declared with a macro_rules! macro (no proc-macro crate, so contributors read plain Rust and builds stay fast). The field name is the key; the doc comment is the help text, written for an embroiderer. The real declaration of the settings every stitch type shares, in crates/stitchcraft-engine/src/common.rs, starts like this:

params! {
    /// Settings every stitch type shares: lock stitches where the element's stitching starts and
    /// ends, a trim or a stop after it, and the shortest stitch and jump.
    pub struct CommonParams for StitchType::ALL;

    "Lock stitches" {
        /// Where the element gets lock stitches: …
        ties: Choice = "0", label "Lock stitches",
            options ["0" => "At the start and the end", "1" => "At the start", "2" => "At the end", "3" => "None"];

        /// The shape of the lock stitches at the start. …
        lock_start: Choice = "half_stitch", label "Start lock", choices LOCKS,
            origin Origin::InkStitchDeviates { deviation: "DEV-LCK-001" };

        /// The shape of a custom start lock: …
        lock_custom_start: Text = "", label "Custom start lock", when lock_start == "custom";

        /// How long each step of a start lock made of steps (back and forth, or custom) is.
        lock_start_scale_mm: Length = "0.7", label "Start lock size", range (0.1, 10.0),
            when lock_start in SIZED_IN_MM;
        …
    }
}

Each parameter is key: Kind = "default", label "Label", followed by what its kind needs and what is not the usual: range (min, max) for numbers and lists, options [...] or choices CONST for choices, applies when it covers fewer stitch types than its struct, defaults [Family::Fill => "4"] when a family of stitch types has a default of its own, when other == "value" (or when other in VALUES, a list of them) when a user interface shows it, and an element reads it, only then, origin (default Origin::InkStitch) and stability (default Stability::Stable). A combination a kind does not take does not compile. Defaults are written as a design stores them, so they are checked by the same code as a design’s values. The grammar is in the macros module’s documentation.

The macro expands to:

• the typed struct, pub struct CommonParams { pub ties: &'static str, pub lock_start_scale_mm: Mm, … }, each field’s type given by its kind (kinds module), so a field and its validation cannot disagree;
• CommonParams::SPECS (a const slice of ParamSpec) and CommonParams::GROUP;
• CommonParams::from_set(&ParamSet) -> Result<Validated<CommonParams>, Vec<Diagnostic>>: every parameter read from its text or its default, with the clamping warnings beside the values;
• CommonParams::from_set_as(&ParamSet, StitchType): the same as an element sewn as that stitch type reads it, with its family’s own defaults and only the parameters it uses (The parameters an element reads). The engine reads an element’s settings with it.

The registry itself is stitchcraft_engine::registry::PARAMETERS, a plain const list of every declaration’s GROUP in the engine, next to the generators (no life-before-main tricks; adding a generator’s parameters is one line there). stitchcraft-params knows no stitch algorithm.

ParamSpec

pub struct ParamSpec {
    pub key: &'static str,          // registry key == Ink/Stitch attribute name when one exists
    pub label: &'static str,        // short UI label (English source string, translation key)
    pub help: &'static str,         // the doc comment; `help()` gives the Markdown
    pub kind: Kind,                 // with its limits: range, options, maximum length
    pub default: &'static str,      // as a design stores it; "" for an empty optional value
    pub family_defaults: &'static [(Family, &'static str)], // a family's own default: `default_for`, `in_family`
    pub group: &'static str,        // UI and docs section
    pub applies_to: &'static [StitchType],
    pub visible_when: Option<Condition>,   // another key of the declaration and the values it shows and reads this for: lock_custom_start only for lock_start custom
    pub stability: Stability,       // Stable | Experimental | Deprecated { use_instead }
    pub origin: Origin,             // InkStitch | InkStitchDeviates { deviation } | StitchCraft
}

InkStitchDeviates names its entry in the deviations ledger (conformance/deviations.toml), which says what differs and why; the reference pages show that entry, so a deviation is described once. A since version and a registry schema version arrive with the first release, together with migrations.

Kinds and validation

Invalid values never fall back silently to defaults: the element gets SC-E0101 (not a value of the kind; the element cannot be stitched) or SC-W0102 (clamped into range), with the key, the value and what is accepted. Keys the registry does not know are kept, so they round-trip, and reported once as SC-W0105. Parsing lives in one place (value module), so every host reads text the same way: an SVG attribute, a command-line key=value, a VectorCraft effect record.

SC-W0102 names the value used, or for a list what the list is read as, since an element may sew only some of a list’s values: a zigzag stroke sews its first spacing.

The ranges are StitchCraft’s. Ink/Stitch sets a floor for most of its numbers and few ceilings, so many ranges here are narrower, and a value outside one is clamped where Ink/Stitch would sew it (DEV-PRM-002). A list holds at most 16 values, a pair 2, and no value is longer than 4,096 bytes, which bounds what reading one costs before any budget is charged. Longer text is SC-E0101, and its message quotes the value’s first 64 characters (DEV-PRM-004).

Empty text, or spaces alone, is not set, whatever the kind, and the parameter takes its default (REQ-PRM-002). Ink/Stitch strips every value and reads an empty one so, and its settings window stores a field the user clears as empty text. A value is stripped of the white space round it before it is read, whatever its kind, text included. A custom lock’s numbers with a tab or a line end round them are numbers here, as there. Spaces separate the values of a list or a pair, as Ink/Stitch splits them. A comma separates nothing and is no decimal point, so text with one is SC-E0101, with a hint to use spaces and points. Ink/Stitch reads 3,5 or 45,90 as the default instead, without a word (DEV-PRM-001). Ink/Stitch leaves out one comma at the end of each of a fill’s underlay angles, for older files, and so does StitchCraft for an angle of any list.

The parameters an element reads (REQ-PRM-004)

An element reads only the parameters its stitch type uses. Any other parameter takes its default, and so does one whose when is false for the element. Its text is kept and not checked. Ink/Stitch reads a setting only where its stitch type uses it, and a path keeps a satin’s settings when its stroke goes back to running stitch: that path must still sew, with nothing said of what it does not read. A when is read from the other parameter’s value on the element, or its default, as the element reads that parameter. So the audit requires the other parameter to be of the same declaration and never hidden itself. It must also apply to every stitch type the hidden one applies to. A host that checks a whole set, such as a settings panel, reads every parameter with from_set, declaration by declaration. It reads only the declarations of the families it shows: the satin column’s declaration of zigzag_spacing_mm cannot read a zigzag stroke’s 2 spacings (rule 7).

Completeness (REQ-PRM-001)

A declaration that compiles can still be wrong: an empty range, a default outside it, a repeated option, a condition on a parameter that does not exist or that an element could not read it by. stitchcraft_params::audit lists every such problem, and the engine’s req_prm_001_every_registered_parameter_is_complete test requires the list to be empty. cargo xtask docs --check adds the cross-checks with outside data. A parameter of Ink/Stitch origin must be in the compatibility contract with a compatible type and the default Ink/Stitch sews, and one of StitchCraft’s own must not take an Ink/Stitch key. Deviations must name ledger entries, and the lock and method identifiers must equal Ink/Stitch’s.

Naming rules

1. If Ink/Stitch has the parameter with the same meaning, use its attribute name verbatim (row_spacing_mm). This keeps SVG files compatible with no mapping table.

2. If our meaning differs, keep the name, mark origin: InkStitchDeviates, and record the difference in the deviations ledger (conformance/deviations.toml). An entry that changes how other keys of Ink/Stitch’s read or sew lists them under params, and each key’s reference entry shows it.

3. New parameters follow the same style: snake_case, a unit suffix for lengths (_mm), percentages (_percent) and angles where Ink/Stitch does (angle alone for row angles).

4. Never reuse a removed key with a new meaning.

5. Defaults are part of the contract. For a parameter of Ink/Stitch origin the registry default is the value Ink/Stitch sews for an SVG that omits the attribute, and the file stitches the same way in both tools. That value is the default Ink/Stitch’s settings window shows, except for the few parameters its code reads with another value. The contract records those as fallback, and conformance/inkstitch/check_params.py compares every one of its getters with the contract. Better starting values for new objects come from presets and machine profiles, never from changing a default.

6. A key belongs to its stitch types. Ink/Stitch gives some keys to several elements with their own defaults: max_stitch_length_mm is empty on manual stitch and satin columns and 4 mm on fills. The contract is per key and stitch type, so the contract page matches a declaration with the rows for the stitch types it applies to, and a declaration for a stitch type Ink/Stitch does not give the key is reported. A key is declared once for a family (rule 7), and a family whose default differs gets its own with defaults, as fills do for max_stitch_length_mm. A family with a default of its own needs a value (ParamSpec::in_family). There an empty value means its default. A length of 0 or less is raised to the least the key accepts instead of counting as empty, as Ink/Stitch reads a fill’s longest stitch. Elsewhere an optional value left empty is no value. The engine reads an element’s settings with its family’s defaults (from_set_as). The contract page compares each row with the default of the row’s family. The reference page lists each family’s default and what the family accepts, and the JSON Schema gives the defaults under x-stitchcraft.family_defaults.

7. A family’s own kind and range. Some of Ink/Stitch’s keys differ by more than their default from one family to another. Its zigzag_spacing_mm is a list for a zigzag stroke and one number for a satin column, and a meander fill reads it as a number that defaults to 0. Its ripple stitch reads a staggers of 0 as no stagger, but a tatami fill’s range starts at 0.01. Such a key is declared again for the family that reads it its own way, in a declaration for that family’s stitch types (REQ-PRM-005). The registry’s audit lets a key have one declaration for each family at most, and an element reads the key as its family’s declaration says. find_for finds a family’s declaration, and find the first, which is the only one for every other key. The JSON Schema gives such a key any of its declarations’ schemas, each with the stitch types it applies to. The index lists the key once for each declaration, under its group, and the contract compares each declaration with the rows of Ink/Stitch’s for its stitch types. Every declaration of one of Ink/Stitch’s keys has an Ink/Stitch origin. The reference pages show a ledger entry that names the key with each declaration.

   An SVG node’s fill and its stroke read the same settings. A key of Ink/Stitch’s is never one of StitchCraft’s own, even for a family Ink/Stitch does not give it, because that family would read a value written for Ink/Stitch’s meaning. A node’s fill may also read a value that only its stroke’s declaration can read, such as a zigzag stroke’s 2 spacings read by a meander fill. Ink/Stitch sews that fill with its default, and StitchCraft would refuse it (DEV-PRM-001). The meander fill’s step (M7.8) chooses between the two.

Generated outputs

Splitting for VectorCraft ABI v1

VectorCraft took at most 64 parameters per plug-in, with no groups or conditional visibility, until 0.14. The plug-in crate builds one plug-in per stitch family for that (stroke, satin, fill), each with only the parameters that apply to it; the shared lock/trim parameters are included in each. A test fails if any family’s manifest exceeds 64 parameters or 64 KiB, so adding a parameter that would break the limit is caught in the PR, not by a user. A parameter has one value, of a kind every release takes. A parameter that needs a text, a seed or several values keeps its default in VectorCraft (manifests). VectorCraft 0.14 adopted richer schemas from the RFC: labels, units, help, groups and conditions, texts and lists, and 256 parameters, 64 of them outside groups. Releases before it ignore the labels, units, help, groups and conditions, and refuse the rest. Each manifest gives a parameter the registry’s label, unit, help and group, and the conditions of its declaration’s applies_to and visible_when (M6.10, dialogs). A parameter’s help page is its entry on the reference page of its declaration, which ParamGroup::slug names for the docs generator and the plug-in alike. VectorCraft shows help as plain text, so stitchcraft_core::text::plain takes the marks out of the Markdown.

Presets

A preset is a named partial ParamSet ("denim", "knit, light") stored as a TOML file in a presets directory of the parameters crate. The same code as user input validates it, and a generated page documents it. In VectorCraft, users can also save appearance (including embroidery live effects) as Graphic Styles. Applying one copies its effect records into each object, and a design sews them (integration, REQ-VC-006).

Versioning and migration

The registry has a schema version. A breaking change (renamed key, changed unit) ships a migration function vN → vN+1 and a conformance case with an old-format input. Unknown keys from newer files are preserved on round trips where the host allows it, and reported once as SC-W0105.

Diagnostics

A diagnostic is a problem with the user’s design or input, explained in the user’s terms, with a stable code. Diagnostics are values: the engine collects them and keeps planning whatever it can. Errors in the Rust sense (Result) are reserved for failures to do the work at all (architecture).

pub struct Diagnostic {
    pub code: Code,                  // SC-W0702
    pub severity: Severity,          // Error | Warning | Info
    pub element: Option<ElementId>,  // which object
    pub at: Option<Point>,           // where on the canvas (mm)
    pub message: String,             // one sentence, specific: "Design is 162 × 148 mm; …"
    pub fix: Option<Fix>,            // a hint, or a machine-applicable fix
}

Codes

SC- + E (error: this element, or the design, cannot be stitched), W (warning: stitched, but probably not what you want) or I (info) + four digits grouped by area:

Codes are never reused. A retired code keeps its page with “retired in vX”.

The registry

All codes live in one table in stitchcraft-core: the registry! block in src/diag.rs, which defines the Code enum. Each entry is one line — variant, id, severity, title — and its doc comment is the long explanation (Markdown: what it means, why it matters for the sew-out, how to fix it), so the text users read is also the code’s rustdoc. Tests reject an entry whose id is malformed or duplicated, whose letter disagrees with its severity, or whose explanation is missing. From that table:

• cargo xtask docs generates the diagnostics index (one page per code, like rustc’s error index);
• stitch explain SC-W0702 prints the explanation in the terminal;
• in VectorCraft, the plug-in shows each message after its code, for the user to look up in the index or with stitch explain;
• cargo xtask conformance fails when a code has no diag_sc_<code>_<what> test that produces it from real input and checks the text a user reads, or when such a test names a code that is not registered (conformance); the registry’s own tests fail when a code has no explanation.

That last rule is what keeps error paths alive: a message that no test ever renders can ship with a typo in its formatting and nobody sees it until a user does.

Writing good messages

• Say what is wrong and by how much: “Rows are 0.25 mm apart but the region is only 0.18 mm tall.”
• Name the object and point at the place.
• Offer the fix in embroidery terms: “Use a running stitch for parts this thin, or widen the shape.”
• No blame, no internal names (LineString, GEOS), no stack traces.

As text

A diagnostic reads the same wherever StitchCraft prints it. Its Display is the severity, the code and the message: warning SC-W0702: Design is 190.0 × 150.0 mm; …. Diagnostic::headline adds the object it is about, as in warning SC-W0307 (svg:patch:fill): The area falls into 2 parts., and the command line prints that, with the fix on the line below. Diagnostic::one_line puts the fix after the headline, for a host that shows each diagnostic as one line of text, as VectorCraft shows an export’s warnings.

Fixes

Fix::Hint(String) is advice. Fix::Apply(Edit) is a change the host can apply with one click and undo (for example “rotate the design 90°” for SC-W0702 when the rotated bounds fit, or “drop the dangling rung” for SC-W0203). Applied fixes go through the host’s command system so they are undoable.

Initial codes

Codes referenced by the design docs; each is registered in the milestone that implements it. A registered code must keep its row here, with the same severity and a title that starts with the registry’s (cargo xtask docs --check), so a code allocated for one thing cannot be registered for another.

SVG input

The SVG adapter, stitchcraft-svg, turns an SVG file into a Design and a list of warnings. It reads what an SVG viewer draws, in millimetres, and reports what it leaves out. The engine never sees SVG (architecture).

What becomes an element

• Shapes. Each <path>, <rect>, <circle>, <ellipse>, <line>, <polyline> and <polygon> that paints becomes one element per paint. A fill becomes an area and a stroke becomes an outline. A <line> has no fill.
• Where a shape starts. A running stitch starts where its path starts and runs the way it runs, and each basic shape starts and runs as Ink/Stitch reads it. A circle or an ellipse starts at its top and turns left on screen. SVG 2 starts it at its right and turns the other way, which only dashes or markers would show.
• Order. Elements follow document order, which is SVG’s paint order and the sewing order. A shape’s fill is sewn before its stroke, as Ink/Stitch sews them, and the outline covers the fill’s edge. When paint-order paints the stroke first, SC-W0802 says the fill is sewn first.
• Groups. <g>, <a> and <switch> pass their transform and style to their children. A <switch> draws only its first child whose conditions pass, as a viewer does. Ink/Stitch sews every child of a switch, and drops the transforms of the switch and of the elements above it (DEV-SVG-004).
• Ids. An element’s id is svg:<label>:fill or svg:<label>:stroke. The label is the SVG element’s id, or <tag>@<n> for the n-th element of that kind. A repeated id gets ~2, ~3 and so on (stitchcraft_core::Labels, as in the VectorCraft adapter). The adapter’s own diagnostics name the SVG element as svg:<label>.
• Names. An inkscape:label becomes the element’s name.
• Automatic elements. Read with --auto (Reading::auto), a shape with no attribute in Ink/Stitch’s namespace is an automatic element, whose stitches StitchCraft chooses by its width (image to embroidery, REQ-AUTO-001). The trim and stop of Ink/Stitch’s commands attached to it still apply. A shape with any inkstitch: attribute is not automatic: it sews as its settings say once they are read (M8), and with the defaults until then. Read with --sort-colours (Reading::sort_colours), the design’s shapes with settings sew in the order StitchCraft chooses too (image to embroidery, REQ-AUTO-011).

Geometry and units

• The root’s width, height, viewBox and preserveAspectRatio map user units to millimetres. A user unit is a CSS pixel, 1/96 inch, unless they say otherwise. A root with only a width or only a height takes the other from its viewBox’s shape, as SVG 2 sizes an image, and a percentage counts as missing. Ink/Stitch takes both sides from the viewBox, in pixels, when either is missing (DEV-SVG-009).
• A viewer ignores a root width, height or viewBox that is empty, and a preserveAspectRatio that does not read. The adapter ignores them too, and SC-W0804 names each. A width, height or viewBox that does not read could put the design at any size, and the file is refused (SC-E0801). So is a size of 0 or less, and a viewBox with no area, in which a viewer draws nothing.
• Transforms compose through every ancestor. The matrices use stitchcraft_core::math, so the result is the same on every platform (determinism).
• Path data is read as SVG viewers draw it, arcs included. An error in the data, or in the list of points of a <polyline> or <polygon>, ends the path at the error, and SC-W0804 names it. inkex skips what is not a number in a list of points, and Ink/Stitch sews the rest (DEV-SVG-010).
• A path has the subpaths a viewer draws. A move-to with nothing drawn after it is no subpath, and a command that draws after a closepath starts a new subpath where the closed one started. inkex keeps such a move-to as a subpath of one point and runs the closed subpath on, so Ink/Stitch can count other subpaths, which tell a satin column’s rails from its rungs (DEV-SVG-011).
• An arc becomes cubic curves as inkex, which Ink/Stitch reads files with, cuts it: in equal pieces, one more than the whole quarter turns it makes. Manual stitch puts a needle point on each piece’s end, as Ink/Stitch’s does. inkex counts the quarter turns in floating point, and its rounding can cut an arc of a whole number of quarter turns into one piece fewer (DEV-SVG-002).
• A <circle> or an <ellipse> starts at its top and goes round anticlockwise on screen, as inkex draws it, so a stroke round it starts and runs as Ink/Stitch’s does.
• A <rect> with one radius rounds its corners with it, and one with a radius of 0 has square corners. An <ellipse> with one radius is a circle of that radius. That is how SVG 2 draws them. inkex rounds a rect whose rx or ry is 0 with the other, and takes an ellipse’s missing radius as 0 (DEV-SVG-006).
• Positions are exact to within a micrometre (REQ-SVG-001). Any path data reads without failing the adapter, and fuzzing checks it (REQ-SVG-002).
• A length may have spaces around it. One that does not read is 0, as in a viewer, and SC-W0804 names it. A percentage is of the viewport’s width, height or diagonal over √2, an em is 16 user units and an ex 8, as with a viewer’s default font. inkex reads them as 0 in a shape’s attributes (DEV-SVG-005).

Colour and visibility

• fill, stroke, color and currentColor give the thread colour. A gradient gives its first colour and a pattern its fallback colour, each with a warning. A gradient of one colour, such as an Inkscape swatch, gives that colour without one. A gradient without stops paints nothing, as in a viewer, and so does a reference to an element the file does not have, unless a colour is written after it. Ink/Stitch sews such a fill in black (DEV-SVG-007).
• Colours read as editors write them. Keywords such as currentcolor may be in any case. An ICC colour after the sRGB one, which Inkscape’s colour-managed picker writes, is left for the sRGB colour.
• Properties come from presentation attributes (fill="red"), the rules of style sheets and the style attribute, in the order of CSS’s cascade, as in a viewer (REQ-SVG-006). A rule overrides a presentation attribute, and the style attribute overrides a rule. Of 2 rules, the more specific one applies (more ids, then more classes, then an element name), and of 2 as specific, the later one. An !important declaration overrides all of these. A paint, colour, stroke width, join or miter limit that does not read gives way to the next declaration, as in CSS. When none of an element’s paints reads, the inherited paint stays, and SC-W0802 names the value. inkex takes the declaration the cascade puts first whether it reads or not, and Ink/Stitch sews a fill whose colour does not read in black and leaves such a stroke out (DEV-SVG-008). display, visibility, opacity, fill-opacity, stroke-opacity, fill-rule and paint-order are read as inkex reads them, from the declaration the cascade puts first. A value there that does not read is ignored, and the declarations after it are not used, where a viewer would use the next one.
• Style sheets are the <style> elements of the file, wherever they are, whose type is CSS. Illustrator and CorelDRAW write a drawing’s colours as classes there. The adapter reads a rule whose selector is an element name or * followed by classes and ids, such as rect, .cls-1, #logo or path.st0.st1. It reads a list of such selectors, such as .a, .b, as well. One SC-W0802 names the other selectors, such as g > rect or a:hover, and the at-rules, such as @media and @import. What they set is not used. Ink/Stitch reads styles through inkex, which applies more kinds of selector.
• display: none hides an element and everything in it. A hidden or fully transparent paint is left out, as a viewer leaves it out. visibility hides a paint, and so does an opacity of 0 on its element or above it. A fill-opacity or stroke-opacity of 0 makes its paint clear, as does a colour that is transparent or has an alpha of 0. Ink/Stitch leaves out only what display hides and a fill whose fill-opacity is written 0 (DEV-SVG-003). The insides of <defs>, <symbol>, <marker>, <pattern>, <clipPath> and <mask> are never drawn.

Stroke width and join

A stroke’s width and join give a satin column drawn as one path its width and its corners (single-path satin). Other strokes are sewn along their paths, however wide they are drawn. Both are read as Ink/Stitch reads them (REQ-SVG-004), except an automatic element’s join, read as SVG draws it. Its cap matters only to an automatic element, whose stitches cover the line as it is drawn (REQ-AUTO-003).

• Width. The width is stroke-width, inherited, 1 user unit when nothing sets it. It is a length in the shape’s own user units, as in a viewer, and a percentage is of the viewport’s diagonal over √2. The transforms down to the shape scale it by the average of how far they stretch the x and y axes. That is exact when they scale both axes alike. Under an uneven scale or a skew, a viewer draws the stroke wider one way than the other, and the average is the middle way. An automatic line sewn across its width is then as wide as that average all along. SC-W0802 names such a line (REQ-AUTO-005). The transforms scale a stroke with vector-effect: non-scaling-stroke too, as Ink/Stitch scales it, though a viewer does not.
• Join. round and bevel are read as they are named. A miter join is limited by stroke-miterlimit, 4 when nothing sets it, as SVG says. Any other join, or none, is a miter limited at 5, as in Ink/Stitch. SVG 2’s miter-clip and arcs count as other joins. An automatic element’s corners follow the drawing instead (REQ-AUTO-004). There, a join that is not set is SVG’s initial miter, limited by stroke-miterlimit, and so are miter-clip and arcs, which few viewers draw.
• Cap. stroke-linecap, inherited, butt when nothing sets it: butt, round or square, in any case. Ink/Stitch sews no cap, and reads none.
• Values that do not read. A width, join or limit that does not read is ignored, as a viewer ignores it, and SC-W0804 names it. A cap that does not read is ignored too, without a word: it changes nothing for a shape with settings. A negative width and a limit below 1 do not read. A stroke too wide to measure, such as 1e308in, is left out with SC-W0804. Its fill is still sewn.

Ink/Stitch reads a width in %, em or ex as 0, and a join written in capitals as no join at all. The adapter reads them as a viewer draws them (DEV-SVG-001).

Ink/Stitch objects

An Ink/Stitch SVG has 3 kinds of object that Ink/Stitch reads and does not sew. The adapter sews none of them (REQ-SVG-003).

• Commands. The trim and stop commands turn on the object’s trim_after and stop_after. The ignore_object and ignore_layer commands leave out an object or a layer, as the inkstitch:ignore_object setting does when it says yes in one of Ink/Stitch’s words, which a toggle reads too, and SC-I0805 lists each object left out. The starting_point and ending_point commands, which place where Ink/Stitch starts and ends a fill or a satin column, are not applied yet (REQ-GEN-001), and SC-W0802 names each one on an object a viewer shows. The command table gives what the adapter does with each of the 12 commands.
• Connectors tie a command to its object.
• Helper paths have one of Ink/Stitch’s start markers. They steer the stitches of other objects.

SC-W0802 reports a connector that ties no command, a helper path, and a command that the adapter does not apply yet. The module docs of crates/stitchcraft-svg/src/inkstitch.rs describe how the adapter finds these objects, with the Ink/Stitch files they were read from.

Design settings

Ink/Stitch keeps 3 settings for the whole design in the file’s first <metadata> element: collapse_len_mm, min_stitch_len_mm and min_satin_stroke_width_mm. Each is an element of Ink/Stitch’s namespace whose text is the value in millimetres, and the first of each name counts. They become the design’s collapse length, shortest stitch and narrowest satin stroke (REQ-SVG-005). SC-W0802 names a value that is not a number of 0 or more, and the design keeps its default. The defaults are in the data model. The settings’ names, with the label and help a dialog shows, are listed once in stitchcraft_engine::design::SETTINGS, which a VectorCraft document’s settings are read with too (integration).

Reports

• SC-W0802 reports a feature that is not stitched. Text, images, clones, nested <svg> elements and the style sheet rules that are not read are such features. So are clipping, masks, filters, markers and the Ink/Stitch settings that are not read yet. Clipping is planned for M8.
• SC-W0804 reports geometry that cannot be used:
  • path data or a list of points with an error, stitched up to the error
  • a transform that does not parse, left out with its contents
  • an element that draws nothing
  • a point more than 10 m from the origin
  • a stroke width, join or miter limit that does not read, and a stroke too wide to measure
  • an empty root width, height or viewBox, and a root preserveAspectRatio that does not read
• SC-E0801 refuses a file that is not SVG, or that is larger than the adapter reads. It refuses a file whose size cannot be used too: a root width, height or viewBox that does not read, a size of 0 or less, or a viewBox with no area.

Text and limits

A file is UTF-8 text, or ISO-8859-1 when its XML declaration says so, which the adapter turns into UTF-8. A file in any other encoding is refused when it has a byte outside ASCII.

A file is at most 64 MiB with a million XML nodes, and its style sheets have at most a million selectors, declarations and at-rules. Illustrator declares its namespaces as XML entities, and an entity whose value is plain text is read. A file is refused when an entity’s value holds markup or other entities, or when its references would expand the file past 64 MiB. Without these rules a small file could need a large amount of memory. Only the document type declaration’s internal subset, <!DOCTYPE svg [ … ]>, declares entities: a declaration in a comment or in character data declares nothing. A name declared twice counts at its longer value. XML keeps the first declaration, and the limit must hold whichever the parser keeps. Reading charges the budget for each XML node, path segment and 8 bytes of a transform, point list or style sheet. Each element is charged for its classes, the style sheet rules tested against it and the declarations it takes (budgets).

Engine pipeline

From a Design to a checked StitchPlan. Each stage is a module in stitchcraft-engine with its own tests; stages communicate only through the types in the data model.

Design ──▶ 0 auto ──▶ 1 normalize ──▶ 2 validate ──▶ 3 generate (per element) ──▶ 4 assemble ──▶ 5 finalize ──▶ 6 check ──▶ StitchPlan
              │            │               │                 │                         │              │              │
              └────────────┴───────────────┴───── diagnostics accumulate at every stage ┴──────────────┴──────────────┘

0. Automatic digitizing

Since M13.1, before anything else, each element the host marked automatic, a shape without settings read with --auto, becomes the ordinary elements its width calls for, with the settings that say so (stitchcraft_engine::auto::digitized, image to embroidery).

• An area is sewn as it is, apart from its narrow parts: each becomes a running stitch along its centre line (M13.4), and the rest of the area the fill of its other parts.
• A line that runs is sewn as it is, tripled from 0.5 mm wide.
• A line sewn as a satin column becomes a column for each of its subpaths, or the fill of a subpath a column cannot follow (SC-I0902).
• A wider line becomes the fill of the area it paints.

Every stage after it sees only ordinary elements. A digitized shape sews, offers its neighbours what it offers and is said of as the same shape set by hand would be. SC-I0901 counts the shapes digitized. A design without automatic elements passes through unchanged and uncopied. Each automatic element has the budget’s work to itself, naming its parts included, and one that needs more is left out with SC-E0004 (REQ-GEN-002). Digitizing doesn’t add an error of its own (REQ-AUTO-006). What cannot be sewn as its width says is sewn otherwise or left out with a warning.

The digitized elements are then sewn as neighbours, in an order of their own. What overlaps keeps its paint order, and a line sews after the fill it borders. Then each thread sews as long as it can, the nearest element next (image to embroidery, SC-I0907). Elements with settings keep their order among themselves, unless --sort-colours is given. The switch brings a design without automatic elements through this stage too.

1. Normalize

Per element, independent of the others:

• Flatten curves with the element’s tolerance (a tenth of running_stitch_tolerance_mm for strokes, and a tenth of a CSS pixel for fills and satin columns, as Ink/Stitch flattens them). Curves are halved (de Casteljau) until each piece’s control points lie within the tolerance of its chord (stitchcraft_engine::normalize::stroke), using only arithmetic and square roots so that every platform gets the same points. kurbo’s adaptive flattening is not used for this: in 0.13 it calls powf (CubicBez::to_quads) and hypot (QuadBez::estimate_subdiv) from the platform’s maths library, whose last bits differ between systems (determinism). Corners, joins between segments that turn by more than 30°, are marked so running stitches land exactly on them; a curve’s own bend is never a corner.
• Regions: a fill’s subpaths are cut wherever they meet, and its fill rule says which faces between them are filled. The edges between filled and empty faces become outlines and holes, each turned one way, and parts too small to sew are left out with SC-W0303 (fills › Region, stitchcraft_engine::normalize::region).
• Satins: classify subpaths into rails and rungs (satin), or make them from a column’s centre line (single-path satin).
• Strokes: each subpath becomes its own path piece, in document order.
• Commands become hints (start/end/target points) on the element.

Adapters have already applied transforms and converted units, so normalization never sees host types.

2. Validate

• Parameters are read by the registry as the element’s stitch type reads them. Blank text takes the default, and a setting the stitch type does not use, or that its other settings hide, is kept unread (parameters). The rest are checked for type and range, and the generator receives a typed struct or nothing.
• Shapes are checked against the stitch type. A satin needs a subpath longer than a point (SC-E0201), a fill needs a non-empty region, and a running stitch needs a path longer than the minimum stitch length.
• An element with an error diagnostic is skipped; the rest of the design still plans. A design whose every element was skipped yields SC-E0010. stitch plan writes the machine file only when no error is said, as Ink/Stitch writes its file only when no element fails (REQ-CLI-003).

3. Generate

Each element becomes stitch groups (stitchcraft_engine::generate): the needle points of each part of it that a jump may separate from the next, in sewing order. A stroke gives one group per subpath, and a part too small for a stitch gives none (SC-W0401). The element’s own settings stay with the element, and assembly reads them there: its thread, locks, trim and stop.

The stitch type picks the generator. A stroke whose satin_column setting is on is a satin column, whatever its stroke_method says, as in Ink/Stitch. Its rails and rungs are recognized, what recognition finds is reported, and its satin_method picks the generator: the satin stitch, sewn from M4.2, the E-stitch, from M7.3, the S-stitch, from M7.4, and the zigzag satin, from M7.5. A satin column also reads the running stitch’s length (running_stitch_length_mm): the stitches that join its underlays are no longer than the first value. For any other stroke the generator is its stroke_method. running_stitch (the default) and manual_stitch are sewn from M3, and zigzag_stitch from M7.2, as wide as the stroke. A satin column drawn as one path no wider than the design’s min_satin_stroke_width is sewn as a stroke, with SC-W0212, as in Ink/Stitch (REQ-SAT-015). Wider, it is sewn between rails made from its line from M4.9 (REQ-SAT-016). A fill whose fill setting is off sews nothing, and nothing is said of it (REQ-FILL-003). Another fill’s region is built first, so what it leaves out and how it will be sewn are said (SC-W0303, SC-W0304, SC-I0306, SC-W0307) whatever comes next, and its fill_method picks the generator: the tatami fill, sewn from M5.4, which reads the running stitch’s length and tolerance for its travel between rows (the first of the lengths, as a satin column does), under the rows from M5.5, and sews its underlay before its top rows from M5.6. A fill set to Ink/Stitch’s legacy fill is sewn as a tatami fill without underlay, with SC-W0314: StitchCraft does not build that method (REQ-FILL-005). The other stroke, satin and fill methods are skipped with SC-W0011 until their milestones. An element whose parameters are wrong (SC-E0101) is skipped too, and the rest of the design still plans.

Each element is generated with the shortest stitch for it: the larger of the machine’s (the profile’s min_stitch) and the element’s min_stitch_length_mm, or the design’s shortest stitch when the element sets none. A satin column is given its longest stitch as well, the element’s max_stitch_length_mm, which its split stitches keep to.

A preview that cannot afford a fill’s stitches shows its top rows (stitchcraft_engine::generate::rows, from M6.3). The fill’s settings are read as for sewing it, and what they say is said the same, but only the region is built and the rows laid over it: no needle point is placed and no route is searched.

Rules every generator follows:

• Pure: output depends only on (normalized shape, typed params, neighbours, seed, budget).
• The needle before, the next element after. Elements are generated in sewing order (ADR 0014, REQ-GEN-003). Each is given the last needle point of the elements before it, whatever their thread, and what the next element offers to end near. That is its first point, or, when it starts at its own nearest point, its shape: a satin column’s rails or a tatami fill’s area. The offer comes from the next element’s shape and settings and the design’s, never its stitches, so nothing waits for a later element. A satin column and a tatami fill start and end by them (satin, fills), and explicit start and end commands will override them (REQ-GEN-001). Each ends near its next stitch, its point nearest the offer as Ink/Stitch’s geometry library finds it, a point of one shape inside the other’s area first (generators::next).
• Seeded randomness: each element’s generator is seeded from its random_seed, one of the settings every stitch type shares. When that is empty, a hash of its id seeds it. A seed replaces the id, as in Ink/Stitch. The PRNG is SplitMix64 from stitchcraft-core (determinism).
• Budgeted: every inner loop charges work units. Each element has the budget’s work to itself. One that runs out (SC-E0004) is skipped, and the others still plan. The stitch limit is for the whole design. Assembly and finalize share the budget’s work once more, and running out there plans nothing. SC-E0004 then says so for the whole design. A generator also spends the design’s stitches on the needle points it makes (budgets, REQ-GEN-004). Each element gets what the elements before it left, and the first that needs more ends planning, with SC-E0004 naming it.
• Roles: every stitch is tagged by its role. Assembly tags the stitches of groups as top and the lock stitches as lock. The jumps between groups are travel. Previews draw the lock stitches apart. A generator hands assembly its needle points without roles, so an element’s underlay, and the running stitches between its rows, are tagged top as well, until generators tag their own.

Generators are listed in algorithms.

4. Plan assembly

Groups are joined into colour blocks in the order the elements sew (host paint order, bottom first, or the order stage 0 chose), by stitchcraft_engine::assemble.

Ordering

• Assembly keeps the order the elements come in, so that embroidery stacking follows the art’s stacking. That is paint order, unless stage 0 put the automatic elements, or with --sort-colours every element, in an order chosen for few thread changes, in which a shape still sews after every shape it is drawn over, where they overlap by more than rounding leaves.
• A thread change starts a new colour block (REQ-ASM-001). Threads are compared by colour, as Ink/Stitch compares them: two names for one colour are one thread, and the block keeps the first.

Connecting consecutive groups

The needle sews straight on from one group to the next only when nothing separates them. With d the distance from where the needle is to the next group’s first needle point:

An element that sews nothing, because it is skipped or too small for a stitch, has no place for its trim or stop. Both are left out, as Ink/Stitch leaves them out, and SC-W0505 says so.

A jump lands where sewing resumes, on the tie-in’s first point or on the group’s first point when it has no tie-in, and the needle goes down there before the first stitch. The jump’s own thread is the machine’s business. The plan trims where an element’s trim_after is set, as Ink/Stitch’s does. A PES file also flags every jump as a trim, as pystitch writes Ink/Stitch’s (formats), and whether a machine cuts at a jump is its own setting. At MC-1 the reference machine cut the thread only at thread changes and stops.

Ink/Stitch (read at d59c9ab) joins groups the same way: one stitch from one group to the next within the collapse length, locks and a jump beyond it. It sews that stitch as it is; StitchCraft’s finalize splits it if it is longer than the machine’s longest stitch, which only a min_jump_stitch_length_mm beyond that length can cause.

Lock stitches (ties)

• A tie-in goes only at the start of a group that the needle jumps to, the design’s first included. A tie-off goes only at the end of a group that a jump, trim, stop or thread change follows, or that ends the design. Groups sewn on from one to the next are sewn without locks between them (REQ-LCK-001).
• ties says which of those an element’s groups get: both, the tie-in (before), the tie-off (after) or neither. force_lock_stitches adds the tie-off whatever ties says, never a tie-in. It also makes each group of the element end with a jump, and the tie-off is sewn there. That is Ink/Stitch’s rule (read at d59c9ab).
• Manual stitch is sewn without locks unless force_lock_stitches is set, because its points are placed by hand.
• A group with fewer than two needle points is sewn without locks: it has no stitch to lock.
• Lock stitches specifies the lock itself: its shape (lock_start, lock_end), its size and its shortest stitch (0.2 mm).

Origin and stop position

The finished plan is in hoop coordinates: the design’s origin goes to the hoop’s centre, (0, 0), where the needle starts. The origin is the design’s own (Ink/Stitch’s origin command, read from M8) or else the centre of the box around every point where the needle goes down (REQ-ASM-005). Assembly builds the plan in the design’s coordinates, and finalize moves it once it has left out the points the machine cannot sew, so the box is the finished plan’s, as in Ink/Stitch. A design’s stop position (Ink/Stitch’s stop position command) adds a jump to it before each Stop. At the stop position the frame is clear of the needle for an appliqué or a check, and sewing resumes with a jump back.

Commands

5. Finalize

Finalize fits the plan to the machine profile (stitchcraft_engine::finalize), and a plan that plan returns can be written as it is. Generators sew within the machine’s limits where their settings let them. What is left to fit comes from joining groups and from settings the machine cannot follow.

1. The shortest stitch of each needle point is its element’s: the one its generator used, so finalize never thins what the generator spaced. That is the element’s min_stitch_length_mm, else the design’s min_stitch_len, and never shorter than the machine’s (profile.min_stitch). Where one element’s stitching runs straight on into the next, the stitch between them can be anything up to the collapse length, 0 included. Within each run of stitches, from where the needle lands to the next jump, trim or stop, a needle point less than its shortest stitch from the one before is left out. The stitch then runs on to the next point. The run’s first and last points and lock points stay, and the points before them are left out instead. Elements sewn over each other can bring the last point or a lock point within the shortest stitch of one that stays before it, once the points between are left out. It is then left out itself, the points before it stay, and a trim or stop after it happens where the needle now is. So is a point where the needle already is, which would sew in place. Only the run’s first point always stays. A stitch into or out of a lock point is a lock stitch, whose shortest is 0.2 mm (REQ-PLAN-002). SC-I0504 says how many points were left out (REQ-FIN-001). The rule is one function, which a generator that joins pieces of its own also applies, as a tatami fill does to its rows and the travel between them, so that finalize finds nothing of its stitches to thin. A satin column joins its parts by rules of its own instead, since the end of a top stitch must not move (satin).
2. The longest stitch. A stitch longer than profile.max_stitch is split into the fewest equal parts no longer than it (SC-I0703, REQ-FIN-001). Such a stitch comes from a stitch placed by hand, a custom lock’s long step, a satin column wider than the machine’s longest stitch, a tatami fill whose max_stitch_length_mm is longer than it, or a move sewn on under a min_jump_stitch_length_mm that long. Each part counts against the design’s stitch budget.
3. The hoop’s centre. The fitted plan is moved so the design’s origin is at the hoop’s centre (origin, REQ-ASM-005).
4. Colour limits: colour changes and stops above what the profile’s format records → SC-E0601.
5. Hoop: a design larger than the hoop → SC-E0701, with a rotate-to-fit fix when rotating 90° would fit. When a design’s origin is far from its middle, a design smaller than the hoop can cross the hoop’s edge. That is SC-E0701 as well. So is a stop position past the edge, which the message names. The size is the stitches’ own. For a design that cannot be sewn, SC-E0701 is the only message about its size. Otherwise, larger than the comfort zone → SC-W0702 (REQ-FIN-002).
6. The end is the plan’s structure: the machine ends after the last block.