Stitch generators

A generator turns one normalized element into stitches. This folder specifies each one: what it must produce, how, which parameters steer it, what can go wrong, and the properties the conformance suite checks.

Travel and the joining of elements, and which ends get a lock, are part of plan assembly. Centre lines gives the middle of a narrow part of a shape, which automatic digitizing sews along.

The generator contract

pub trait Generator {
    type Shape;                  // StrokePath, SatinShape or Region
    type Params;                 // typed view generated by the parameter registry
    fn generate(
        &self,
        shape: &Self::Shape,
        params: &Self::Params,
        hints: &Hints,           // entry/exit/target points
        rng: &mut SplitMix64,
        budget: &mut Budget,
    ) -> Result<GroupStitches, GenerateError>;   // GenerateError -> coded diagnostic
}

• Pure and deterministic; no globals; no allocation proportional to anything but output and input size.
• Never panics; every index is checked; every loop charges the budget.
• Returns stitches tagged with roles, an entry and an exit point.
• Unusual inputs produce a coded diagnostic, a documented fallback, or both — never silence.

Property checklist (every generator)

Every generator page lists its specific properties; these apply to all of them and are checked automatically by stitchcraft-testkit for every generator registered:

1. Determinism: the same inputs give identical stitches; shuffling unrelated elements does not change this element’s stitches.
2. Finite and bounded: all coordinates finite and within the shape’s bounds expanded by the compensation parameters plus 0.05 mm.
3. Length limits: top stitches within the generator’s maximum length; no zero-length stitches.
4. Hints honoured: with start/end hints the first/last stitch lies within 0.1 mm of the nearest point of the shape to the hint (REQ-GEN-001).
5. Degenerate inputs: the shared degenerate corpus (zero-area, hair-thin, self-touching, collinear, duplicate points, 1-point paths, huge coordinates, 10⁶-vertex paths) never fails and never exceeds the budget without SC-E0004.
6. Monotonicity where meaningful: denser spacing never yields fewer stitches; larger shapes never yield fewer stitches.

Sources

Each page rests on embroidery practice (the terms every digitizer uses), published algorithms and papers, Ink/Stitch’s documentation and, where the documentation is silent, Ink/Stitch’s behaviour as its source shows it. Pages describe all of it in our own words and never copy code; a link to the source a statement rests on is welcome when it helps the next reader check it again (ADR-0012).