Validation and diagnostics: fail usefully

A stitch compiler should be difficult to surprise and easy to interrogate. That does not mean it will predict every thread break or every wrinkle. It means that each stage checks its assumptions, records what it changed, and explains suspicious output in terms the user can act on.

A preview that merely looks plausible is not validation. The compiler should inspect geometry, continuous paths, discrete stitches, schedules, machine commands, encoded bytes, and—when possible—the resulting stitch-out.

14.1 A diagnostic is structured data

Treat diagnostics as part of the compiler API rather than as strings printed by whichever function noticed a problem.

Diagnostic {
  code: "SATIN_LOCAL_WIDTH_ABOVE_PROFILE"
  severity: ERROR | WARNING | NOTE
  stage: "sample-satin"
  message: "The column reaches 13.4 mm near the upper-left bend."
  sourceObjectIds: ["leaf-border"]
  primitiveId: "satin-12"
  stitchRange: [1842, 1907]?
  observed: { localWidthMm: 13.4 }
  expected: { maxPreferredWidthMm: 10.0 }
  confidence: 0.91
  suggestedActions: [
    "Split the satin column",
    "Permit split stitches",
    "Change this segment to a fill border"
  ]
}

Useful diagnostics have five properties:

Stable identity. A code can be tested, filtered, translated, and documented.
Provenance. The message identifies the source object and generated range involved.
Evidence. It reports the measured value and the threshold that triggered the message.
Actionability. It offers remedies that preserve as much design intent as possible.
Honest confidence. A certain format overflow is not presented the same way as a heuristic pucker warning.

Severity and confidence are different. “The path leaves the hoop” can be a high-confidence error. “This dense corner may pucker on this material” can be a medium-confidence warning.

14.2 Validate at every representation boundary

Different errors become visible at different stages. Waiting until the final command list makes the explanation worse.

Artwork and geometry checks

Check for:

non-finite coordinates;
singular or nearly singular transforms;
zero-length paths and collapsed curve segments;
open paths used where closed regions are required;
self-intersections and ambiguous winding;
invalid holes or holes outside their parent component;
components below the minimum meaningful area;
details smaller than the selected thread-and-needle profile can express;
geometry outside the design or hoop envelope.

A tiny component is not automatically an error. It may be a deliberate dot. The compiler should ask whether a feasible primitive exists for it.

Semantic and primitive checks

Check for:

cycles in the layer DAG;
mutually contradictory start, end, or direction constraints;
satin rails that cross or change correspondence unexpectedly;
a fill region with no valid interior after inset or compensation;
an underlay that extends outside its permitted support region;
an appliqué sequence missing a placement, tack-down, or cutting stop;
disconnected lace components that are meant to be free-standing;
unsupported combinations of stitch type and target machine.

Continuous-path checks

Check for:

paths outside the permitted region;
unintended self-intersections;
discontinuities and unjoined endpoints;
curvature too high for the requested sampling policy;
gaps between neighboring rows;
excessive overlap or near-coincident rows;
paths that terminate in structurally weak locations;
contour branches that were silently discarded.

Discrete-stitch checks

Check stitch lengths

\ell_i = \|p_{i+1}-p_i\|,

turning angles

\alpha_i = \cos^{-1}\!\left( \frac{(p_i-p_{i-1})\cdot(p_{i+1}-p_i)} {\|p_i-p_{i-1}\|\,\|p_{i+1}-p_i\|} \right),

and local penetration concentrations. Report distributions rather than only averages. A design with a pleasant mean stitch length can still contain fifty dangerous micro-stitches in one corner.

Good summary statistics include:

minimum, maximum, median, and selected percentiles of stitch length;
fraction below the preferred minimum and above the preferred maximum;
maximum and percentile turning angle;
count of duplicate and near-duplicate penetrations;
total stitch, jump, trim, stop, and color-change counts;
longest jump and longest untrimmed travel;
penetration density percentiles;
estimated thread consumption and sewing time.

14.3 Coverage and concentration maps

Two heatmaps are especially useful: coverage distance and penetration concentration.

Let $\Gamma$ be the union of top-thread stitch segments in a filled region $\Omega$ . Define the distance to the nearest thread segment as

c(x)=\min_{q\in\Gamma}\|x-q\|.

For a tolerance $\tau$ , an approximate uncovered area is

A_{\text{miss}}(\tau) = \mu\bigl(\{x\in\Omega:c(x)>\tau\}\bigr),

where $\mu$ is area. This is not a full optical model—thread has thickness, loft, and occlusion—but it is a useful geometric check.

For needle concentration, place a smoothing kernel $K_\sigma$ at every penetration:

\rho_\sigma(x) = \sum_i K_\sigma(x-p_i).

A Gaussian kernel is convenient:

K_\sigma(r) = \frac{1}{2\pi\sigma^2} \exp\!\left(-\frac{\|r\|^2}{2\sigma^2}\right).

High values of $\rho_\sigma$ reveal corners, joins, repeated passes, and row endpoints that may perforate or stiffen the substrate. Use more than one $\sigma$ : a small radius finds needle-point clusters, while a larger radius finds generally overworked areas.

14.4 Boundary and registration error

For a desired region $\Omega$ and a predicted visible stitched region $\widehat{\Omega}$ , useful shape metrics include symmetric-difference area

E_{\Delta} = \mu(\Omega\triangle\widehat{\Omega}),

intersection over union

\operatorname{IoU}(\Omega,\widehat{\Omega}) = \frac{\mu(\Omega\cap\widehat{\Omega})} {\mu(\Omega\cup\widehat{\Omega})},

and directed boundary distances. A one-sided distance is important because “the stitch extends beyond the artwork” and “the stitch leaves an uncovered gap” are different production defects even when their absolute magnitudes match.

For overlapping regions $$A$$ and $$B$$ , measure the post-deformation overlap margin along their shared boundary rather than only comparing their original vector shapes.

14.5 Validate the schedule as a state machine

The schedule has state, not just geometry. Track at least:

active position;
needle up or down, where the target distinguishes it;
attached or detached thread state;
active color or needle;
whether a secure start or end is required;
active hoop or fixture state;
pending operator action.

A simple validator can symbolically execute the command IR and flag transitions such as:

sewing before a required color is selected;
a trim when the thread is already detached;
a long jump with attached thread and no permitted travel strategy;
a color change that violates a target’s needle limits;
a stop that the selected backend cannot represent faithfully;
an END followed by executable commands;
coordinates that become invalid only after relative encoding.

State-machine validation catches a class of bugs that no line preview will show.

14.6 Decode what you encode

Never certify an export by looking only at the pre-encoding stitch plan. The backend may:

quantize coordinates;
split long movements;
remove or merge commands;
translate stops into color changes;
reorder metadata;
impose color-block limits;
wrap or clamp an out-of-range delta;
discard information that the source format cannot express.

The safe test is:

\text{Machine IR} \xrightarrow{\text{encode}} \text{bytes} \xrightarrow{\text{decode}} \widehat{\text{Machine IR}},

then compare the semantic behavior of the two programs. Byte-for-byte round trips are often impossible because formats permit several equivalent encodings. Compare positions, command classes, color blocks, stop semantics, and final state instead.

Render previews from $\widehat{\text{Machine IR}}$ , not from the richer pre-lowered plan. That is the program the machine will actually receive.

14.7 Physical regression testing

The final oracle is a stitch-out. Build a repeatable test process rather than relying on memory and anecdotes.

A useful physical regression suite includes:

straight runs at several lengths and angles;
circles and tight corners;
satin columns at several widths and curvatures;
fills at several row spacings and directions;
adjacent color regions with controlled overlap;
small text and isolated details;
repeated penetrations and dense junctions;
representative underlay combinations;
long jumps, trims, stops, and color changes;
one or two real production motifs.

Use the same thread, needle, stabilizer, hooping process, and machine settings when comparing compiler versions. Photograph or scan the result with fiducials, register it to the expected geometry, and store measurements with the build artifact.

A regression record might contain:

TestRun {
  compilerVersion
  machineProfileVersion
  materialProfileVersion
  designHash
  encodedFileHash
  environmentNotes
  registeredImage
  measuredBoundaryDisplacement
  threadBreaks
  operatorInterventions
  visualRatings
}

Machine embroidery contains uncertainty, so do not treat a single run as perfect truth. Repeated trials reveal variance and distinguish a systematic compiler defect from an unlucky thread event.

14.8 Avoid the magical quality score

A single number is tempting and usually misleading. A program with fewer trims may have worse registration. A program with perfect coverage may be too stiff. A program with fewer stitches may lose the character of the artwork.

Prefer a small quality vector:

Q = ( q_{\text{feasibility}}, q_{\text{geometry}}, q_{\text{mechanics}}, q_{\text{appearance}}, q_{\text{efficiency}}, q_{\text{confidence}} ).

The UI can summarize these dimensions, but preserve the underlying measurements. Experts need to know why a design is risky, not merely that it scored 73.

References

References and further reading

The following sources are a practical starting point rather than an exhaustive bibliography. The embroidery-specific literature is relatively small, so adjacent work in computational fabrication, direction-field design, cloth mechanics, and graph routing is essential.

For the central embroidery-path problem, begin with Liu et al. on direction-aware streamlines and Tian et al. on spiral paths. For the mathematical machinery behind fields, continue with direction-field and vector-field processing references. For the material side, the cloth-modeling and computational-embroidery papers show why geometry alone is not enough. For real implementation semantics, inspect the official Ink/Stitch documentation and pyembroidery source.

Margaret Ellen Seehorn, Gene S.-H. Kim, Aashaka Desai, Megan Hofmann, and Jennifer Mankoff, “Enhancing Access to High Quality Tangible Information through Machine Embroidered Tactile Graphics,” Proceedings of the ACM Symposium on Computational Fabrication (SCF ’22), Article 23, 2022. https://doi.org/10.1145/3559400.3565586

Gabriel Cirio, Jorge López-Moreno, David Miraut, and Miguel A. Otaduy, “Yarn-Level Simulation of Woven Cloth,” ACM Transactions on Graphics 33, no. 6, Article 207, 2014. https://doi.org/10.1145/2661229.2661279

Georg Sperl, Rosa M. Sánchez-Banderas, Manwen Li, Chris Wojtan, and Miguel A. Otaduy, “Estimation of Yarn-Level Simulation Models for Production Fabrics,” ACM Transactions on Graphics 41, no. 4, Article 65, 2022. https://doi.org/10.1145/3528223.3530167

⁴

Qiming Tian, Yupin Luo, and Dongcheng Hu, “Spiral-Fashion Embroidery Path Generation in Embroidery CAD Systems,” Computer-Aided Design 38, no. 2, pp. 125–133, 2006. https://doi.org/10.1016/j.cad.2005.08.004

⁵

Zhenyuan Liu, Michal Piovarči, Christian Hafner, Raphaël Charrondière, and Bernd Bickel, “Directionality-Aware Design of Embroidery Patterns,” Computer Graphics Forum 42, no. 2, pp. 397–409, 2023. https://doi.org/10.1111/cgf.14770

⁶

Xiangjia Chen, Guoxin Fang, Wei-Hsin Liao, and Charlie C. L. Wang, “Field-Based Toolpath Generation for 3D Printing Continuous Fibre Reinforced Thermoplastic Composites,” Additive Manufacturing 49, Article 102470, 2022. https://doi.org/10.1016/j.addma.2021.102470

⁷

Kate S. Glazko, Alexandra A. Portnova-Fahreeva, Arun Mankoff-Dey, Afroditi Psarra, and Jennifer Mankoff, “Shaping Lace: Machine Embroidered Metamaterials,” Proceedings of the 9th ACM Symposium on Computational Fabrication (SCF ’24), 2024. https://doi.org/10.1145/3639473.3665792

⁸

Ink/Stitch, “Tatami Stitch (Fill Stitch),” official documentation. https://inkstitch.org/docs/stitches/fill-stitch/

⁹

Fernando de Goes, Mathieu Desbrun, and Yiying Tong, “Vector Field Processing on Triangle Meshes,” ACM SIGGRAPH 2016 Course Notes, 2016; and Felix Knöppel, Keenan Crane, Ulrich Pinkall, and Peter Schröder, “Globally Optimal Direction Fields,” ACM Transactions on Graphics 32, no. 4, Article 59, 2013. Course notes; direction-field paper

¹⁰

Jack Edmonds and Ellis L. Johnson, “Matching, Euler Tours and the Chinese Postman,” Mathematical Programming 5, pp. 88–124, 1973. https://doi.org/10.1007/BF01580113

¹¹

Ink/Stitch, “Tools: Stroke—Redwork,” official documentation. The tool’s routing goal is to traverse every path exactly twice. https://inkstitch.org/docs/stroke-tools/

¹²

Ink/Stitch, “Commands,” official documentation. https://inkstitch.org/docs/commands/

¹³

Huamin Wang, James F. O’Brien, and Ravi Ramamoorthi, “Data-Driven Elastic Models for Cloth: Modeling and Measurement,” ACM Transactions on Graphics 30, no. 4, Article 71, 2011. https://doi.org/10.1145/2010324.1964966

¹⁴

Ink/Stitch, “Satin Column,” official documentation. https://inkstitch.org/docs/stitches/satin-column/

¹⁵

Abhinit Sati, Ioannis Karamouzas, and Victor B. Zordan, “DIGISEW: Anisotropic Stitching for Variable Stretch in Textiles,” Proceedings of the ACM Symposium on Computational Fabrication (SCF ’21), Article 3, 2021. https://doi.org/10.1145/3485114.3485121

¹⁶

Yu Jiang, Narjes Pourjafarian, Alice Haynes, and Jürgen Steimle, “Embrogami: Shape-Changing Textiles with Machine Embroidery,” Proceedings of the 37th Annual ACM Symposium on User Interface Software and Technology (UIST ’24), 2024. https://doi.org/10.1145/3654777.3676431

¹⁷

Ayesha Nabila, Hua Ma, and Junichi Yamaoka, “4D Embroidery: Implementing Parametric Structures in Textiles for Sculptural Embroidery,” UbiComp/ISWC ’22 Adjunct, pp. 88–90, 2022. https://doi.org/10.1145/3544793.3560358

¹⁸

Xinling Chen, Michael McCool, Asanobu Kitamoto, and Stephen Mann, “Embroidery Modeling and Rendering,” Proceedings of Graphics Interface 2012, pp. 131–139, 2012. https://doi.org/10.5555/2305276.2305299

¹⁹

EmbroidePy, “pyembroidery,” an open-source Python library for reading and writing embroidery formats. https://github.com/EmbroidePy/pyembroidery

²⁰

Ink/Stitch, “Tack and Lock Stitches,” official documentation. https://inkstitch.org/docs/stitches/lock-stitches/