StitchProof

The preflight check your SVG sewing pattern should pass before fabric does.

StitchProof is a local-first command-line linter for SVG sewing patterns. It measures physical scale, calibration geometry, piece metadata, cutline closure, grainlines, paired seam lengths, notch references, and page bounds—then emits findings you can locate and repair before publishing a pattern.

简体中文 · Metadata contract · Repair playbook · Research

Why this exists

A pattern can look correct on screen and still print at the wrong scale, omit a grainline, or pair two stitched edges that differ by centimetres. Those mistakes waste paper, fabric, support time, and customer trust. StitchProof turns that release checklist into one deterministic command.

It is deliberately not a drafting program, PDF tiler, or cloud upload service:

Tool category	Primary job	StitchProof difference
Seamly2D / FreeSewing	Draft and generate patterns	Audits an already-authored SVG before release
PDFStitcher	Re-page and edit PDF patterns	Keeps SVG geometry and explicit metadata as evidence
Generic SVG validators	Check XML/SVG syntax	Checks sewing-specific scale, pieces, seams, and notches

Repository and web research found adjacent drafting and conversion tools, but no direct repository for this metadata-driven SVG release gate. See the dated research record for queries, evidence, and limitations.

Try it

Install the signed-off release directly from GitHub:

python -m pip install "git+https://github.com/KanadeK/stitchproof.git@v0.1.0"

Audit a pattern:

stitchproof audit pattern.svg

Typical finding:

StitchProof: 1 error, 0 warnings
Source: pattern.svg
Pattern: Shirt block

[ERROR] SEAM002: Paired seam 'side' differs by 40.00 mm (14.29%).
  Element: /svg[1]/g[1]/path[2]
  Measurements: difference_mm=40, first_length_mm=280,
    relative_difference_percent=14.2857, second_length_mm=240
  Fix: Make the stitched edges agree, or raise tolerances only with a reviewed
    easing allowance.

The repository includes a healthy pattern, an intentionally faulty pattern, and a standalone faulty-pattern HTML report.

Real checks, not a UI shell

StitchProof 0.1.0 parses and measures SVG geometry using only the Python standard library at runtime. It supports physical SVG units, nested transforms, common shapes, and every SVG path command (M/L/H/V/C/S/Q/T/A/Z, absolute or relative). Curves and arcs are adaptively flattened in physical millimetres before length and bounds checks.

Built-in rules cover:

• physical document size and uniform viewBox scaling;
• calibration geometry versus declared real-world dimensions;
• unique piece names, positive cut counts, one closed cutline, labels, and grainlines;
• cutline bounds, paired seam identity and measured length tolerance;
• notch-to-seam references, unknown roles, scripts, and external resources.

List the live rule catalog instead of relying on a copied table:

stitchproof rules
stitchproof rules --format json

Add the metadata contract

StitchProof reads explicit data-sp-* attributes; it does not guess sewing intent from colours, layer names, or nearby text.

<svg width="600mm" height="900mm" viewBox="0 0 600 900"
     data-sp-title="Shirt block">
  <rect data-sp-role="calibration"
        data-sp-width="100mm" data-sp-height="100mm"
        x="20" y="20" width="100" height="100" />

  <g data-sp-piece="front" data-sp-cut-count="2">
    <path data-sp-role="cutline" d="M 140 180 ... Z" />
    <line data-sp-role="grainline" x1="220" y1="260" x2="220" y2="480" />
    <text data-sp-role="label">Front — Cut 2</text>
    <path data-sp-role="seam" data-sp-seam="side" d="M 300 220 ..." />
    <line data-sp-role="notch" data-sp-seam="side" x1="295" y1="360"
          x2="305" y2="360" />
  </g>
</svg>

Read the metadata contract before annotating a production pattern. StitchProof reports evidence but never auto-edits geometry.

Reports and exit codes

stitchproof audit pattern.svg --format text
stitchproof audit pattern.svg --format json --output report.json
stitchproof audit pattern.svg --format sarif --output report.sarif
stitchproof audit pattern.svg --format html --output report.html

The HTML report is offline and has no JavaScript or external assets. Its preview is rebuilt from parsed numeric cutlines; raw untrusted SVG markup is never embedded.

Code	Meaning
0	No finding reached the configured threshold
1	At least one finding reached the threshold
2	Invalid arguments, invalid/unsafe SVG, unsupported geometry, or I/O failure

The default threshold is error. Use --fail-on warning for a strict release gate or --fail-on none when generating a report without failing a job. Seam mismatch fails only when both the absolute and relative tolerances are exceeded:

stitchproof audit pattern.svg \
  --seam-tolerance-mm 3 \
  --seam-tolerance-percent 1.5

CI use

The CLI has no network behavior, so the same command works in a private build:

- name: Install StitchProof
  run: python -m pip install "git+https://github.com/KanadeK/stitchproof.git@v0.1.0"
- name: Preflight sewing pattern
  run: stitchproof audit patterns/shirt.svg --format sarif --output stitchproof.sarif

Reproduce the release gates

Development uses uv:

$env:UV_CACHE_DIR = "$PWD/.uv-cache"
uv sync --all-extras
uv run pytest --cov=stitchproof --cov-report=term-missing --cov-fail-under=90
uv run ruff check .
uv run ruff format --check .
uv run mypy src
uv build
uv run twine check dist/*
uv run stitchproof audit examples/healthy-shirt.svg
uv run stitchproof audit examples/faulty-shirt.svg --format json --output dist/faulty.json
if ($LASTEXITCODE -ne 1) { throw "faulty example must exit 1" }

The deliberately faulty example returning 1 is a passing acceptance condition. For a clean wheel test and symptom-to-fix procedures, use the repair playbook.

Limits in 0.1.0

• SVG only; PDF ingestion, tiling, drafting, grading, and automatic fixes are out of scope.
• Rounded rectangles are rejected because their implicit arc geometry is not yet supported.
• CSS-driven intent is not inferred; metadata must be explicit on the relevant elements.
• Length agreement is a geometric preflight, not professional fit or pattern certification.
• Good positioning can improve discoverability, but no implementation can guarantee stars or views.

Contributing and security

Small reproducible SVG fixtures are welcome. Read CONTRIBUTING.md before opening a pull request. Please report parser or report-generation security issues through the process in SECURITY.md, not a public issue.

MIT licensed. See CHANGELOG.md for release history.