How the Cross Stitch Pattern Maker Works

Everything runs in your browser

Photos are read and converted on your device. The page decodes the image with the browser’s own image decoder, then a Web Worker (a background thread) does the heavy calculation so the page stays responsive. Images are never uploaded to a server. Projects are saved in your browser’s IndexedDB storage. The site’s own server only delivers the pages and code.

Accepting an image

• Only JPG, PNG and WebP are accepted, identified by their file signature, not their name. SVG, HTML and other active formats are refused.
• Files over 25 MB, or images larger than 12000 px on a side or 60 megapixels, are refused before decoding where the header allows.
• Orientation stored by cameras (EXIF) is applied once by the browser’s decoder. The tool never rotates the image again.
• A working copy is limited to 1600 px on its longest side to keep memory use predictable. Your original file is not modified or kept.

Converting to a stitch grid

1. Framing: rotation, crop and mirror are applied to the working copy.
2. Adjustments: optional brightness and contrast (applied to a copy).
3. Resampling: in Photo mode each stitch is the area-weighted average of the pixels it covers, with transparency respected. In Pixel Art mode each stitch copies the pixel at its centre (nearest neighbour), so edges and colours are preserved.
4. Transparency: pixels below 50% opacity become no-stitch squares, never a new white colour. You can instead flatten onto a background colour you choose.
5. Colour reduction: if the image has more colours than your limit (2–48), colours are grouped with a weighted median cut in the OKLab perceptual colour space and refined with up to 12 rounds of k-means. Large photos are pre-binned to 32 levels per channel to bound the work. Images with no more colours than the limit keep their exact colours.
6. Optional dithering (Floyd–Steinberg error diffusion) is off by default.
7. Optional simplify replaces a stitch whose colour appears in none of its 8 neighbours with the most common neighbouring colour (if at least 3 neighbours share it).
8. Counts are always recomputed from the final grid, including every later edit.

The process is deterministic: the same image and settings always give the same chart. Grids can be up to 300 × 300 stitches.

Colours and thread

Every chart colour is a custom RGB value with a descriptive name (for example “Light Peach”). We do not label colours with thread brand codes. A brand match would need a properly licensed, verified colour table, which this release does not ship, and any match between a screen and a thread is approximate anyway. Screens emit light; thread reflects it, and both vary with lighting. Choose floss by eye in daylight. See why screen colours and floss differ.

The materials list gives the number of stitches per colour. It does not estimate skeins, because thread use depends on fabric, strands, tension and waste.

Symbols

There are 51 chart symbols, each a different shape (filled, open and dotted circles, squares, triangles, diamonds, hexagons and stars; bars, crosses, chevrons, half-filled shapes and dots). Every active colour gets its own symbol, so charts work in black and white. Symbols are drawn as vector paths, not taken from a font.

Stitchability Check

A region is a set of same-colour stitches connected edge to edge (up, down, left, right). An isolated group is a region of at most N stitches (default 2, adjustable 1–4). The check reports stitches, colours used, regions per colour and isolated groups, with a short explanation. It is not a quality score and does not estimate stitching time. Cleanup proposes merging each unprotected isolated group into the neighbouring colour it shares the most edges with; groups touching a protected area, or with no stitched neighbour, are left alone. You preview changes before applying, and every cleanup can be undone.

Editing and undo

The Studio keeps the last 100 steps of undo history (or about 48 MB of history data, whichever limit is reached first; the oldest steps are dropped). Drawing is rendered on a canvas, not as one page element per stitch, so large charts stay responsive.

Printing

PDFs are generated in your browser with the open-source pdf-lib library. Grid lines, colour squares and symbols are vector graphics, so they stay sharp at any zoom. Large charts are split into pages that repeat a few shaded rows or columns as overlap; the tiling guarantees every stitch appears on at least one page, and the key counts come from the chart, not the pages. Text uses a standard PDF font that covers Western European characters; others in titles are replaced with “?”.

Saving and progress

Projects and progress are stored in IndexedDB on this device, with a schema version so future updates can migrate them safely. Writes happen in transactions, and the “Saved” label only appears after the browser confirms a write. Progress is stored separately from the colours and tied to a pattern revision; if the stitched squares change, old progress is never laid over the new chart. Project files (JSON) are validated on import; invalid files are rejected without touching existing projects. The format is documented in the repository (docs/project-file-format.md).

Known limitations

• No cloud sync or accounts; projects live in one browser.
• No automatic background removal; background is removed by choosing colours.
• No fractional stitches, backstitch or beads in this release.
• Stitch alphabets cover A–Z, a–z, digits and common punctuation; other scripts are not supported yet.
• Colour names are descriptions, and colours on screen will not exactly match thread.
• Very large charts (around 300 × 300) can feel slower on older phones.