The StitchingLab Pattern Notation

Why a notation

Every pattern in the StitchingLab catalog has a single canonical text form — the SLPN string. Anyone with the SLPN can reconstruct the pattern exactly: the grid, the palette, the optional yarn assignments. Anyone with the pattern can serialize back to the same string. Round-trip identity is enforced by property-based tests.

That property is what makes SLPN useful beyond StitchingLab. The format is small enough to fit in a tweet, an SMS, an email signature, a QR code, a yarn label. Third-party tools — offline knitting apps, AR pattern viewers, e-readers, smart hooks — can integrate by parsing it. Patterns become portable.

Syntax (v1)

SLPN/<version>/<stitch_type>/<dimensions>/<palette>/<grid>/<yarn_map>?/<meta>?

A concrete 4×4 tapestry pattern with three colors:

SLPN/1/T/4x4/3:F5E6D3,A8755C,3D3935/AAABABCBABCBCABA/LB-VC-CR:0,LB-VC-BR:1,LB-VC-CL:2/t=Wildflower-Square

Fields

• SLPN/1/ — magic prefix and format version. Always literally SLPN.
• stitch_type — one of T (tapestry), F (filet), X (cross-stitch), K (knit colorwork).
• dimensions — WxH integers. 80x80, 4x4, etc.
• palette — n:hex,hex,.... Count, then comma-separated 6-char hex (uppercase, no #).
• grid — encoded cells. See encoding modes below.
• yarn_map (optional) — code:idx,code:idx,... mapping yarn merchant codes to palette indices.
• meta (optional) — k=v;k=v;... with restricted charsets.

Grid encoding modes

The grid is emitted in one of three modes, chosen by size:

• ASCII (no marker, or A:) — for grids with ≤256 cells and ≤26 colors. Each character A..Z is a palette index. Easy to read, easy to parse.
• Packed base64 (B:) — each cell is N bits big-endian, packed sequentially. Bit width: 1 (≤2 colors), 2 (≤4), 4 (≤16), 5 (≤32), 6 (≤64), 7 (≤128), 8 (≤256). Per spec, palettes ≤8 colors use 4 bits for byte alignment. URL-safe base64.
• Gzip + base64 (Z:) — for very large grids (over 200×200 cells or over 32 colors). Bits packed → gzipped → URL-safe base64 encoded.

Yarn map

Each entry is <merchant>-<line>-<color>:<palette_index>. Example: LB-VC-CR:0 = Lion Brand, Vanna’s Choice, Cream → palette index 0. The merchant codes are stable identifiers maintained in our yarn database’s code column.

Meta

Optional key/value pairs. Keys match [a-z][a-z0-9]*; values match [A-Za-z0-9_.\-]+. Spaces are not allowed in values (use _). Reserved keys:

• t — pattern title
• a — attribution

Versioning and compatibility

Breaking changes increment the version number. Parsers must support all previous versions for indefinite backward compatibility. Chess FEN is 30+ years old; SLPN should aspire to similar longevity.

v2 of the format will likely add:

• Stitch-instruction layer — written patterns (rows of sc, dc, ch, sl st with shaping).
• Repeat markers — for parametric patterns.
• Construction graph — for non-grid 3D patterns (amigurumi).

v1 doesn’t preclude any of these. We will preserve forward and backward parsing in all subsequent versions.

Reference implementation

The reference TypeScript implementation lives at github.com/stitchinglab/stitchinglab in src/lib/slpn/. Property-based tests verify lossless round-trip on 1,000+ random patterns.

Plaintext API

Any public pattern can be fetched as plaintext SLPN at GET /api/p/<content_hash> with Content-Type: text/plain. This is the integration entry point for third-party tools.