DEV Community: Edinamar Luce

Turning a photo into a cross stitch pattern in the browser: Wu quantization, CIEDE2000 and no dithering

Edinamar Luce — Sun, 15 Nov 2026 21:09:14 +0000

Cross stitch patterns are just tiny images: one square of fabric, one stitch, one color of thread. So "photo to pattern" sounds like a resize and a palette swap. It mostly is, and the parts that make it hard taught me a few useful things about color and images. Here's how the converter I built works. It runs entirely in the browser, so the photo never leaves the user's machine.

1. One pixel per stitch

The first step is the boring one: scale the photo so that one pixel is one stitch. A pattern 140 stitches wide gets a 140-pixel-wide image. Everything after this works on that small grid, which is why the whole pipeline runs in milliseconds even on a phone.

2. Reduce the colors first, then match to thread

Embroidery floss comes in fixed colors. The DMC range has around 500, and nobody wants to buy 500 skeins, so a pattern needs to use maybe 15 to 40 of them.

The naive approach is to snap every pixel straight to its nearest DMC color. That gives you far too many colors and no control over how many. Instead:

Reduce the photo's own colors to N using Wu's color quantizer (via the MIT-licensed image-q library). Wu's method is fast and keeps the colors that cover lots of pixels, which is what you want for stitching.
Match each of those N colors to the nearest DMC floss. Two palette colors sometimes land on the same floss, and when that happens they merge.
Assign every stitch to the nearest color in that small floss palette.

3. "Nearest" means perceptual distance, not RGB distance

Measuring color distance in RGB is a classic trap. Two colors can be close in RGB numbers and look clearly different to a person, or the other way round. So colors are converted from sRGB to CIE Lab (D65 white point), a space designed so that distances roughly match what people see.

There are two formulas in use:

CIEDE2000 for choosing which floss represents each palette color. It's the most accurate standard color-difference formula, and it's also expensive. That's fine here, because it runs only N × ~500 times.
Plain Lab distance (CIE76) for assigning each of the tens of thousands of stitches to one of the N chosen floss. That step is fast, and with only a few dozen well-separated candidates the cheaper formula picks the same answer almost every time.

If you implement CIEDE2000 yourself, test it against the published test pairs in Sharma, Wu & Dalal (2005). The formula has several places where a sign or a hue-angle wrap goes wrong silently.

4. No dithering

In normal image work, dithering is how you hide a small palette: scatter pixels of two colors so the eye blends them. For stitching it's the worst possible choice. Every isolated pixel becomes a single stitch that needs its own start and stop of thread. So the converter deliberately does no dithering, and you accept some banding in exchange for a pattern that's pleasant to stitch.

5. Count and clean up the "confetti"

Even without dithering, photos (fur especially) produce lots of confetti: single stitches whose eight neighbors are all other colors. This is the biggest complaint stitchers have about computer-generated patterns, so the tool measures it and shows it up front:

Easy to stitch · 19 colors · <1% confetti

The count is simple: for every stitched cell, check its 8 neighbors; if none share its color, it's confetti. The percentage is confetti over stitched cells. From our own side-by-side tests, under about 5% feels calm to stitch and over about 12% means constant thread changes. These are working numbers, not science, so the raw percentage is always shown too.

The basic clean-up is one pass of a majority rule. Each confetti stitch takes the color that most of its stitched neighbors share, but only if at least 3 of them share it, and the pass reads from the old grid and writes to a new one so the result doesn't depend on scan order. Stronger levels go further: they flood-fill small same-color patches (up to 2, 3 or 5 stitches touching edge to edge) and merge each patch into the color that borders it most. Afterwards, any floss that no longer has stitches is dropped, and the remaining ones are sorted by stitch count and given chart symbols in that order.

6. Skein counts from geometry

A pattern also needs a shopping list. On fabric with count holes per inch, a stitch has side s = 2.54 / count cm. A full cross uses two diagonals on the front (2√2·s) and roughly two sides on the back (2·s). Add 50% for tails and travel between stitches. A DMC skein is 8 m of six strands, so stitched two strands at a time it gives 24 m of working thread.

That works out to about 1,830 stitches per skein on 14-count with 2 strands, within 3% of the old needlework rule of thumb "stitches per skein = 255 × count ÷ strands" (1,785). It's reassuring when first principles agree with decades of stitchers' experience.

Try it

The tool is The Cross Stitch Pattern Maker. Disclosure: I built it. You upload a photo, see the stitchability check before anything else, and get a symbol chart, a DMC floss list with skein counts and a printable PDF. The first PDF is free and there's no sign-up. If you only want the size and floss math, there's also a standalone cross stitch calculator.

I'd love to hear from anyone who has worked on palette reduction for physical media (beads, LEGO mosaics, knitting), because the "no dithering, fewer isolated pixels" trade-off shows up everywhere.

Fitting a whole game build into a URL fragment, stamped with the patch it was made for

Edinamar Luce — Sun, 15 Nov 2026 20:42:16 +0000

I run a small fan-made build planner for Azeroth Survivors, a browser survivor game. The planner has no accounts and no database of builds. A build lives entirely in the URL, so "save" and "share" are the same action: copy the link.

That constraint shaped two pieces of code I want to walk through: how a full build fits into a short URL fragment, and how a link made months ago tells you which parts of it a later game patch may have broken.

What has to fit in the link

A build in this game is a class (nine of them), up to six skills, a set of skills you "banish" from the level-up pool, and talent points spread across three trees. Every class has 39 or 40 talents, each with a maximum rank of 5, and a full build spends exactly 51 points with 5 points needed per tier before the next tier opens.

The naive version is JSON in a query string. It works, but a talent map alone is several hundred characters once it is URL-encoded, and the link breaks in chat apps that wrap long lines.

Bit-packing the first format

The first share format is a fixed byte layout:

byte 0      version (4 bits) | class id (4 bits)
bytes 1-6   one byte per skill slot: 0 = empty, else 1 + ability index
bytes 7-8   banished skills as a bit mask, in class ability order
byte 9...   talent ranks in class-data order, 3 bits each

Three bits cover ranks 0 to 7, which leaves headroom over the current maximum of 5. The talent block is written with a small writeBits helper that walks a bit offset across the byte array, most significant bit first:

export function writeBits(bytes: Uint8Array, bitOffset: number, value: number, width: number) {
  for (let i = 0; i < width; i += 1) {
    const bit = (value >> (width - 1 - i)) & 1;
    const position = bitOffset + i;
    bytes[position >> 3] |= bit << (7 - (position & 7));
  }
}

For a 40-talent class that is 9 fixed bytes plus 15 bytes of talents: 24 bytes, which base64url turns into 32 characters. The whole thing goes after #p= in the fragment, so it never reaches a server log and the page stays fully static.

Two details mattered more than I expected:

Indices, not names. Skills are stored as offsets into the class's generated ability list. That keeps each slot to one byte, but it means the order of that list is part of the format. If a patch inserts a skill in the middle, old links point at the wrong skill. The rule in the code comment is blunt: bump the version whenever an offset or slot width changes.
The version nibble comes first. The decoder reads byte 0, checks the version and class id, and returns null on a mismatch instead of guessing. The page can also read just the class id from that first byte and fetch only that class's data module before decoding the rest.

The current format carries the game version

The planner later grew per-stage plans (early, mid, late, endless), gear, run items, an optional race and a build name. That became format 8, which keeps the same bit-packing approach but adds a short metadata header: a length-prefixed name (up to 80 bytes) and a length-prefixed game version string (up to 32 bytes), followed by the four stage blocks.

Putting the game version inside the link was the useful part. A build shared during one patch is stamped with that patch, for example v0.143.3, and the planner knows which version its own data was last checked against (at the time of writing, data checked on 2026-11-13).

Telling the reader what a patch may have broken

When a link opens, a function compares the stamped version with the current one and walks every stage of the build:

each talent id must still exist in the class data,
each skill key must still exist, and a chosen upgrade path must still be one of that skill's options,
each equipment and run-item key must still resolve.

Anything that does not resolve becomes an issue tagged with its stage and category, and the page shows a short report instead of silently dropping the choice. If the versions match, the report just confirms that every saved choice still resolves.

What it deliberately does not do is pretend to know old numbers. The message for an older link says it can verify which choices still exist, but it cannot reconstruct values from a game build that is no longer available. That honesty is cheaper than shipping historical data for every patch, and it tells the player exactly where to look.

Where the tier list fits

The same "show your date" rule applies to the tier list page. There is no official tier list or public win-rate data for this game, so the page grades all nine classes three ways (overall, first-clear safety, endgame clear speed), explains why each grade differs, and prints the game version and last-checked date at the top. It is an editorial call, labelled as one.

Takeaways

If your app's state is small and structured, a versioned bit layout in the URL fragment is a full persistence layer with zero backend.
Store the data version inside the payload, not next to it.
When old data cannot be trusted, list what changed instead of guessing.

The planner is here if you want to see the links in action. It is free, has no sign-up, and is an unofficial fan project not affiliated with Blizzard Entertainment or the game's creator. Disclosure: this is my site, and this post was written by an AI agent working from the site's actual source code.

Knitting charts aren't square: stitch-accurate grids and photo-to-colorwork in the browser

Edinamar Luce — Sun, 15 Nov 2026 11:03:57 +0000

Knitters have a geometry problem that most charting software ignores: a knitted stitch is not square. I build a browser-based knitting chart tool, and three small pieces of code did most of the work of getting charts right: a gauge-based cell aspect ratio, a photo-to-chart pipeline that thinks in stitches instead of pixels, and a row walker that turns the grid into written instructions. Here is how each one works.

1. Stitches are wider than they are tall

Knitters measure gauge: how many stitches and how many rows fit in 10 cm (4 in). A typical worsted-weight gauge is 18 stitches × 24 rows. That means one stitch is 10/18 ≈ 0.56 cm wide but only 10/24 ≈ 0.42 cm tall.

If you draw a motif on square graph paper, every row is drawn taller than it will knit. A circle charted on squares knits up as a squashed oval, and lettering looks short and wide. The fix is to draw each cell at the stitch's real proportions:

/** Height of one stitch relative to its width, from the gauge. */
export const stitchAspect = (gauge: { stitches: number; rows: number }) =>
  gauge.stitches / gauge.rows;

// layout
const cellH = proportional ? cellW * stitchAspect(chart.gauge) : cellW;

With 18 × 24, stitchAspect is 0.75, so a 20 px wide cell is drawn 15 px tall. Everything else (hit testing, row numbers, outlines) has to use cellW and cellH separately instead of a single cellSize:

const x = Math.floor((px - layout.left) / layout.cellW);
const y = Math.floor((py - layout.top) / layout.cellH);

It sounds trivial, but once cells are not square you find every place in the code that quietly assumed they were. There is still a toggle for square cells for people who prefer them, but the default is proportional.

2. Photo to chart: resample in stitches, not pixels

The naive way to turn a photo into a colorwork chart is to shrink it to N × M pixels and posterize. That gets the proportions wrong for the same reason as above: if the chart is 60 stitches wide, the number of rows has to come from the photo's aspect ratio and the gauge:

export const rowsForStitches = (img: HTMLImageElement, stitches: number, gauge: Gauge) =>
  Math.max(1, Math.round(
    stitches * (img.naturalHeight / img.naturalWidth) * (gauge.rows / gauge.stitches)
  ));

A square photo at 60 stitches and 18 × 24 gauge becomes 60 × 80: more rows than stitches, because rows are shorter. Knit it and the result is square again.

The rest of the pipeline runs on a canvas in the browser, so the photo never leaves the device:

Draw the image into a canvas sized stitches × rows with imageSmoothingQuality = 'high'. Each pixel is now one stitch.
Build a palette with image-q using Wu quantization and BT.709-weighted Euclidean distance. Wu is fast and deterministic, which matters when someone drags a "colors" slider and expects the same result each time.
Map every pixel to its nearest palette color, with no dithering.

That last point is knitting-specific. Dithering makes photos look better on screen, but in stranded colorwork every isolated stitch of a different color is a strand you have to carry and catch. A dithered chart is technically accurate and miserable to knit.

Cleaning up single stitches

Even without dithering, quantized photos are full of lone stitches. A small cleanup pass looks at each stitch's four neighbours: if none of them share its color, and one color holds the majority (at least three of the four, or all of them at an edge), the stitch takes that color:

if (same || neighbours < 2) continue;      // keep stitches that touch their own color
if (bestCount >= Math.min(3, neighbours)) out[i] = best;

Running it twice catches the pairs the first pass exposes. Finally the palette is sorted by how many stitches use each color, so the most-used color becomes color A, the main color, and unused colors are dropped. Knitters expect A to be the background.

3. Turning the grid into written instructions

Many knitters prefer written rows to a chart. Generating them is a run-length encoding problem with one twist: direction.

When knitting flat, right-side rows are worked from right to left across the chart, and wrong-side rows from left to right, with every stitch turned into its wrong-side equivalent (a knit seen from the back is a purl). In the round, every round reads right to left.

const ws = isWrongSide(chart, y);
const xs = ws ? [...Array(width).keys()] : [...Array(width).keys()].reverse();

Then walk xs, merge consecutive cells with the same stitch and color into a run, and format each run in standard abbreviations: k5 A, k2 B, p3 A. Cells marked "no stitch" (used when stitch counts change across a chart) are skipped and not counted, so each row ends with its true stitch total, which is the first thing a knitter checks when something goes wrong.

What I'd tell anyone building tools for crafters

Model the physical object, not the picture. Gauge, direction of work and "no stitch" cells are the domain; pixels are an implementation detail.
Optimise for the person holding the needles. No dithering, a cleanup pass, and the main color as A are all choices that make the output worse as an image and better as a pattern.
Keep it local. Everything above runs in the browser. People upload family photos to make sweaters; not sending those to a server is a feature.

You can try all of this in Knitting Chart, the free tool I built: draw a chart in true stitch proportions, or use the photo to knitting chart converter and download a PDF with the key and written rows. Disclosure: I made it, and it has an optional one-time paid upgrade for cloud sync; everything described in this post is in the free version.