DEV Community: Min Yi

From Pixels to Fuse Beads: Building an Image Quantization Pipeline in TypeScript

Min Yi — Fri, 11 Sep 2026 07:44:15 +0000

A fuse bead pattern looks like pixel art, but converting a photo into something you can actually build is more than shrinking an image.

Every output cell must map to a real bead color. The palette must stay manageable. Empty space should remain empty. And the result still needs to resemble the source after hundreds—or thousands—of pixels disappear.

While building Meltbead, a browser-based fuse bead pattern maker, I ended up with a compact image-processing pipeline that handles those constraints entirely on the client:

image
  → resize
  → divide into grid cells
  → sample one color per cell
  → match colors to a physical bead palette
  → remove the connected background
  → reduce the palette
  → export a buildable pattern

This post walks through the important parts in TypeScript.

1. Treat the output as a physical grid

The first design choice is the output width. If the user asks for a 50-bead-wide pattern, the height should preserve the source aspect ratio:

const targetHeight = Math.round(
  targetWidth * sourceHeight / sourceWidth
);

Each output cell owns a rectangular region of the source image. Using floor for the starting coordinate and ceil for the ending coordinate ensures that edge pixels are not silently dropped:

const startX = Math.floor(col * sourceWidth / targetWidth);
const startY = Math.floor(row * sourceHeight / targetHeight);
const endX = Math.min(
  sourceWidth,
  Math.ceil((col + 1) * sourceWidth / targetWidth)
);
const endY = Math.min(
  sourceHeight,
  Math.ceil((row + 1) * sourceHeight / targetHeight)
);

I also downscale very large uploads before calling getImageData(). The final pattern may only be 30–100 cells wide, so processing a full-resolution phone photo adds work without adding useful detail.

const longestSide = Math.max(image.naturalWidth, image.naturalHeight);
const scale = Math.min(1, 1200 / longestSide);
const sourceWidth = Math.max(1, Math.round(image.naturalWidth * scale));
const sourceHeight = Math.max(1, Math.round(image.naturalHeight * scale));

This is one of the useful properties of the problem: the physical craft gives us a natural resolution limit.

2. Average color is simple—but not always representative

The most direct way to summarize a cell is to average its visible pixels:

function averageColor(pixels: Array<[number, number, number]>) {
  let r = 0;
  let g = 0;
  let b = 0;

  for (const [pr, pg, pb] of pixels) {
    r += pr;
    g += pg;
    b += pb;
  }

  return {
    r: Math.round(r / pixels.length),
    g: Math.round(g / pixels.length),
    b: Math.round(b / pixels.length),
  };
}

This works well for gradients and photographs. But an average can invent a color that is not visually dominant. A cell split between red and blue may become purple, even if there is no purple object in the source.

For illustrations and pixel art, I offer a dominant-color mode. Each RGB channel is quantized into 16-value buckets. The largest bucket wins, and I average only the pixels inside it:

const buckets = new Map<
  string,
  { count: number; r: number; g: number; b: number }
>();

for (const [r, g, b] of pixels) {
  const key = `${r >> 4}-${g >> 4}-${b >> 4}`;
  const bucket = buckets.get(key) ?? { count: 0, r: 0, g: 0, b: 0 };

  bucket.count += 1;
  bucket.r += r;
  bucket.g += g;
  bucket.b += b;
  buckets.set(key, bucket);
}

const winner = [...buckets.values()]
  .sort((a, b) => b.count - a.count)[0];

const color = {
  r: Math.round(winner.r / winner.count),
  g: Math.round(winner.g / winner.count),
  b: Math.round(winner.b / winner.count),
};

The buckets deliberately trade precision for stability. We do not need to distinguish every camera-noise variation; we need a dependable bead choice.

Transparent pixels are skipped. If a cell contains no sufficiently opaque pixels, it becomes an empty cell instead of a white bead.

3. RGB distance needs a small perceptual correction

Once a cell has a representative color, it must be mapped to the nearest color in a real bead palette.

Plain Euclidean RGB distance is an acceptable baseline:

Math.sqrt(dr * dr + dg * dg + db * db)

But human vision does not weight all RGB differences equally. A lightweight improvement is the red-mean color-distance formula, which adjusts the red and blue weights according to the average red value:

type Rgb = { r: number; g: number; b: number };

function colorDistance(a: Rgb, b: Rgb): number {
  const redMean = (a.r + b.r) / 2;
  const dr = a.r - b.r;
  const dg = a.g - b.g;
  const db = a.b - b.b;

  return Math.sqrt(
    (2 + redMean / 256) * dr * dr +
    4 * dg * dg +
    (2 + (255 - redMean) / 256) * db * db
  );
}

Nearest-color lookup then stays pleasantly boring:

function findClosestColor(target: Rgb, palette: BeadColor[]) {
  let closest = palette[0];
  let bestDistance = Number.POSITIVE_INFINITY;

  for (const candidate of palette) {
    const distance = colorDistance(target, candidate.rgb);
    if (distance < bestDistance) {
      closest = candidate;
      bestDistance = distance;
    }
  }

  return closest;
}

For a few hundred palette entries and a modest grid, a linear scan is fast enough. If you were matching millions of pixels, a spatial index or precomputed lookup table would become more interesting.

4. Reduce colors after the first mapping pass

A palette may contain 200 colors, but a maker might only own 12. That means “closest available color” is not the whole problem; the application also needs to choose a useful subset.

The pipeline first maps every cell against the full palette and counts the result:

const frequency = new Map<string, number>();

for (const cell of patternCells) {
  const match = findClosestColor(cell.sampledColor, fullPalette);
  cell.color = match;
  frequency.set(match.key, (frequency.get(match.key) ?? 0) + 1);
}

Then it keeps the most frequently used colors up to the user's limit:

const reducedPalette = [...frequency.entries()]
  .sort((a, b) => b[1] - a[1])
  .slice(0, maxColors)
  .map(([key]) => fullPalette.find(color => color.key === key)!)
  .filter(Boolean);

Finally, every non-empty cell is remapped to that reduced palette.

This two-pass approach is intentionally pragmatic. It is not a globally optimal clustering algorithm, but it produces understandable material lists and gives users a predictable control: “make this pattern with at most N colors.”

A more advanced version could use weighted k-medoids, ensure rare accent colors survive, or optimize for the colors the user already owns.

5. Remove only the background connected to an edge

“Remove white” sounds easy until the subject contains white eyes, highlights, clothing, or text.

Deleting every light cell damages the design. Instead, I treat background removal as a flood-fill problem:

Start with light, low-saturation cells touching the outer border.
Walk to their four-directional neighbors.
Mark only that connected region as external.

function isLightNeutral(rgb: Rgb) {
  const min = Math.min(rgb.r, rgb.g, rgb.b);
  const max = Math.max(rgb.r, rgb.g, rgb.b);
  return min > 224 && max - min < 35;
}

The queue-based traversal looks like this:

const queue: Array<[number, number]> = [];
const visited = new Set<string>();

function push(row: number, col: number) {
  if (row < 0 || col < 0 || row >= height || col >= width) return;

  const id = `${row}:${col}`;
  if (visited.has(id)) return;
  if (!isLightNeutral(hexToRgb(cells[row][col].color))) return;

  visited.add(id);
  queue.push([row, col]);
}

for (let col = 0; col < width; col++) {
  push(0, col);
  push(height - 1, col);
}

for (let row = 0; row < height; row++) {
  push(row, 0);
  push(row, width - 1);
}

for (let i = 0; i < queue.length; i++) {
  const [row, col] = queue[i];
  cells[row][col].isExternal = true;

  push(row - 1, col);
  push(row + 1, col);
  push(row, col - 1);
  push(row, col + 1);
}

A white highlight enclosed by darker cells survives because it is not connected to the border. This small topology-aware rule performs much better than a global color deletion.

6. Keep the processing local

The entire pipeline can run through the Canvas API:

const canvas = document.createElement("canvas");
canvas.width = sourceWidth;
canvas.height = sourceHeight;

const context = canvas.getContext("2d", { willReadFrequently: true });
if (!context) throw new Error("Canvas is not available in this browser.");

context.drawImage(image, 0, 0, sourceWidth, sourceHeight);
const imageData = context.getImageData(0, 0, sourceWidth, sourceHeight);

That makes the interaction immediate and lets uploaded images stay on the device. It also keeps the architecture simple: no upload endpoint, no image-processing queue, and no temporary asset cleanup.

The trade-off is that browser memory and CPU are finite. Resize early, cap the output dimensions, and yield work to a Web Worker if larger patterns make the interface stutter.

7. The algorithm is only the first draft

Automatic conversion gets a pattern most of the way there, but good fuse bead art still benefits from human editing.

A useful editor should let the maker:

paint and erase individual cells;
replace one color everywhere;
inspect exact bead counts;
compare the pattern with the source image;
export a printable chart and material list;
save the project locally and return later.

This is an important product lesson: image processing creates a suggestion, not an unquestionable answer. The best tool makes its automatic decisions editable.

What I would improve next

The current approach is compact and easy to reason about, but several upgrades are tempting:

Run palette matching in CIELAB and compare colors with Delta E.
Preserve small, high-contrast details during palette reduction.
Add optional dithering for gradients.
Score pattern readability at the chosen grid size.
Let users optimize against a personal inventory of bead colors.
Move generation into a Web Worker for smoother interaction.

If you are building your own converter, start with the simple pipeline. The quality gains from correct cell boundaries, a physical palette, and connected-background removal are larger than the gains from immediately reaching for a sophisticated clustering model.

You can try the finished browser tool at Meltbead. If you build a different quantization strategy, I would love to compare notes.

Debugging API JSON in the Browser: A Practical Workflow

Min Yi — Tue, 04 Aug 2026 01:50:02 +0000

When an API response looks wrong, the problem is often not the endpoint itself. A missing field, an unexpected string, or a content-type mismatch can be hidden inside a large JSON payload. A repeatable browser-based workflow makes these issues much easier to isolate.

1. Capture the exact response

Start in your browser's Network panel. Reload the page, select the request, and inspect three things:

the request URL and query parameters
the response status and response headers
the raw response body

Do not rely only on the rendered UI. A frontend may silently ignore fields it cannot parse, while the Network panel shows the data that actually crossed the wire.

Check the Content-Type header as well. A JSON response should normally use application/json. If the server returns HTML or plain text with a 200 status, the real problem may be a proxy, authentication redirect, or server-side error page.

2. Format the payload before reading it

Minified JSON is difficult to inspect and easy to misread. Format it first so nested objects and arrays become visible. Then look for:

fields that are present in one item but absent in another
numbers returned as strings
null values where the client expects an object
duplicate keys
arrays that are empty because a filter was applied upstream

A formatter is most useful when it preserves the original value types and clearly reports invalid syntax. If formatting fails, copy the smallest failing fragment into a validator instead of guessing where the error is.

3. Compare the schema with the client

Many “API bugs” are contract mismatches. Compare the actual response with the interface your code expects.

For example, the client may expect:

{
  "total": 3,
  "items": [
    { "id": 42, "name": "Ada" }
  ]
}

But the server may return total as a string:

{
  "total": "3",
  "items": [
    { "id": 42, "name": "Ada" }
  ]
}

That difference can break sorting, arithmetic, or runtime validation even though the JSON is syntactically valid. Document the expected shape with TypeScript types or a schema validator, then validate at the boundary where data enters your application.

4. Check encoding and escaping

If a value contains a URL, Base64 string, Unicode text, or user-generated content, inspect encoding separately from structure. Common symptoms include:

plus signs or slashes changing after a round trip
spaces appearing where percent-encoding was expected
Unicode characters becoming replacement symbols
a token being decoded twice

Test the smallest representative value in both directions. This is faster than debugging the entire response and helps identify whether the issue is in the API, transport, or client code.

5. Reduce the failing case

Once you find a suspicious field, create a minimal JSON example containing only the relevant structure. A reduced case helps you answer three questions:

Is the payload invalid JSON?
Is it valid JSON with the wrong type or shape?
Is the payload correct, but the application reading it incorrectly?

Keep the original response for reference, but use the reduced case in bug reports and tests. It makes the issue reproducible without exposing unrelated data.

6. A small browser toolkit can speed up the loop

You do not need a large local setup for every inspection task. A few focused browser utilities can help with formatting JSON, converting JSON to TypeScript, encoding URLs, testing regular expressions, and checking timestamps.

For example, Yaya Tools provides free browser-based utilities for these small jobs at yayatool.com. The useful part is not the branding; it is having quick, disposable tools available while you investigate a request. No installation or account is required.

7. Record the result

Finish by writing down the request, the observed response shape, the expected shape, and the fix. If the issue is a contract mismatch, update the API documentation or type definition so the same bug does not return later.

A good debugging workflow separates transport problems, syntax problems, schema problems, and application logic. Capture the raw response, format it, compare it with the expected contract, test encoding independently, and reduce the failure to a small reproducible example. That process turns a vague “the API is broken” report into a fixable technical issue.

Abstract Syntax Tree (AST) Deep Dive: From Theory to Practical Compiler Implementation

Min Yi — Tue, 29 Apr 2025 03:44:48 +0000

Introduction

In programming, parsing and transforming source code is a fundamental process. Whether it's syntax checking, formatting, or advanced operations like code minification and transpilation, a deep understanding of code structure is essential. At the heart of this process lies the Abstract Syntax Tree (AST)—a powerful tool for representing code in a structured, tree-like format.

This article will guide you through the core concepts of AST and demonstrate its practical application by building a mini-compiler from scratch. By the end, you’ll learn:

What is an AST? How does it represent code syntax?
How to implement a compiler step-by-step, from parsing source code to generating output.
Real-world applications of AST, including code transformation and syntax validation.

1. What is an AST?

An Abstract Syntax Tree (AST) is a tree representation of source code where each node corresponds to a syntactic unit (e.g., variables, functions, operators). Its primary role is to convert raw text-based code into structured data, enabling programmatic analysis and manipulation.

2. Building a Mini-Compiler

We’ll implement a compiler that transforms LISP-style function calls into C-style syntax:

LISP: (add 2 (subtract 4 2))  
C:    add(2, subtract(4, 2))

2.1. Compiler Workflow

Parsing:
- Lexical Analysis: Convert source code into tokens.
- Syntax Analysis: Convert tokens into an AST.
Transformation: Modify the AST (e.g., for language conversion).
Code Generation: Generate new code from the transformed AST.

2.2. Lexical Analysis (Tokenizer)

Convert source code into tokens:

function tokenizer(input) {
  let current = 0;
  let tokens = [];
  while (current < input.length) {
    let char = input[current];
    if (char === '(') tokens.push({ type: 'paren', value: '(' });
    else if (char === ')') tokens.push({ type: 'paren', value: ')' });
    else if (/\s/.test(char)) current++; // Skip whitespace
    else if (/[0-9]/.test(char)) {
      let value = '';
      while (/[0-9]/.test(char)) {
        value += char;
        char = input[++current];
      }
      tokens.push({ type: 'number', value });
    }
    else if (/[a-z]/i.test(char)) {
      let value = '';
      while (/[a-z]/i.test(char)) {
        value += char;
        char = input[++current];
      }
      tokens.push({ type: 'name', value });
    }
    else throw new TypeError(`Unknown character: ${char}`);
  }
  return tokens;
}

Output:

[
  { type: 'paren', value: '(' },
  { type: 'name', value: 'add' },
  { type: 'number', value: '2' },
  { type: 'paren', value: '(' },
  { type: 'name', value: 'subtract' },
  { type: 'number', value: '4' },
  { type: 'number', value: '2' },
  { type: 'paren', value: ')' },
  { type: 'paren', value: ')' },
]

2.3. Syntax Analysis (Parser)

Convert tokens into an AST:

function parser(tokens) {
  let current = 0;
  function walk() {
    let token = tokens[current];
    if (token.type === 'number') {
      current++;
      return { type: 'NumberLiteral', value: token.value };
    }
    if (token.type === 'paren' && token.value === '(') {
      token = tokens[++current];
      let node = { type: 'CallExpression', name: token.value, params: [] };
      token = tokens[++current];
      while (token.type !== 'paren' || token.value !== ')') {
        node.params.push(walk());
        token = tokens[current];
      }
      current++;
      return node;
    }
    throw new TypeError(`Unknown token: ${token.type}`);
  }
  let ast = { type: 'Program', body: [] };
  while (current < tokens.length) ast.body.push(walk());
  return ast;
}

AST Output:

{
  type: 'Program',
  body: [{
    type: 'CallExpression',
    name: 'add',
    params: [
      { type: 'NumberLiteral', value: '2' },
      {
        type: 'CallExpression',
        name: 'subtract',
        params: [
          { type: 'NumberLiteral', value: '4' },
          { type: 'NumberLiteral', value: '2' },
        ],
      },
    ],
  }],
}

2.4. Transformation

Modify the AST to match the target output structure:

function transformer(ast) {
  let newAst = { type: 'Program', body: [] };
  ast._context = newAst.body;
  traverser(ast, {
    NumberLiteral: {
      enter(node, parent) {
        parent._context.push({ type: 'NumberLiteral', value: node.value });
      },
    },
    CallExpression: {
      enter(node, parent) {
        let expression = {
          type: 'CallExpression',
          callee: { type: 'Identifier', name: node.name },
          arguments: [],
        };
        node._context = expression.arguments;
        if (parent.type !== 'CallExpression') {
          expression = {
            type: 'ExpressionStatement',
            expression: expression,
          };
        }
        parent._context.push(expression);
      },
    },
  });
  return newAst;
}

Transformed AST:

{
  type: 'Program',
  body: [{
    type: 'ExpressionStatement',
    expression: {
      type: 'CallExpression',
      callee: { type: 'Identifier', name: 'add' },
      arguments: [
        { type: 'NumberLiteral', value: '2' },
        {
          type: 'CallExpression',
          callee: { type: 'Identifier', name: 'subtract' },
          arguments: [
            { type: 'NumberLiteral', value: '4' },
            { type: 'NumberLiteral', value: '2' },
          ],
        },
      ],
    },
  }],
}

2.5. Code Generation

Convert the transformed AST into C-style code:

function codeGenerator(node) {
  switch (node.type) {
    case 'Program': return node.body.map(codeGenerator).join('\n');
    case 'ExpressionStatement': return `${codeGenerator(node.expression)};`;
    case 'CallExpression':
      return `${codeGenerator(node.callee)}(${node.arguments.map(codeGenerator).join(', ')})`;
    case 'Identifier': return node.name;
    case 'NumberLiteral': return node.value;
    default: throw new TypeError(`Unknown node type: ${node.type}`);
  }
}

Final Output:

add(2, subtract(4, 2));

3. Real-World Applications with Babel

Babel, a popular JavaScript compiler, uses AST for:

Transpiling modern JS (e.g., ES6+ → ES5).
Code optimization (e.g., dead code elimination).
Custom transformations (e.g., JSX → JS).

Example: Renaming a Function with Babel

const parser = require("@babel/parser");
const traverse = require("@babel/traverse");
const generator = require("@babel/generator");

const code = `const hello = () => {};`;
const ast = parser.parse(code);

traverse.default(ast, {
  Identifier(path) {
    if (path.node.name === "hello") path.node.name = "world";
  },
});

const result = generator.default(ast, {}, code);
console.log(result.code); // Output: const world = () => {};

Conclusion

ASTs are foundational to modern programming tools. By understanding them, you gain the ability to:

Build custom compilers/transpilers.
Analyze and refactor code programmatically.
Create domain-specific languages (DSLs).

For further reading, explore:

Original article: https://webfem.com/post/ast. Translated to English.