How Kandiverse turns a photo into a bead pattern

When you upload a photo, it is decoded directly in your browser or phone. No copy is ever sent to a server. The raw pixel data (a grid of red, green, and blue values for every pixel) is handed straight to the processing engine running locally on your device. This is not a legal promise; it is simply how the code works. There is no upload step.

The cropping tool lets you frame the part of the image you care about. Once confirmed, the engine reads the cropped image into an array of RGBA values: four numbers per pixel. Red (0 to 255), green (0 to 255), blue (0 to 255), and alpha (transparency, 0 to 255). A 500x500 crop becomes exactly 1,000,000 numbers. Everything from here is pure math on that array.

Most photos have a background that you do not want in your bead pattern. The engine detects it automatically without any machine learning. Just geometry and color math. First, it samples the four corner regions of the image (roughly the outermost 5% of each corner). Corners are almost always pure background in subject photos. If at least 60% of corner pixels agree on a dominant color, that color becomes the estimated background. Then a flood-fill starts from every pixel on the image border, spreading inward to any pixel that is close enough to the background color. "Close enough" is measured using CIEDE2000, the international standard for how humans perceive color differences. A pixel must score below ΔE 22 (roughly meaning "these look like the same color to a human") to be flagged as background. A luminance guard prevents over-erosion: if the background is dark, only dark pixels are removed; if the background is bright, only bright pixels are removed. This protects fuzzy edges like hair or fur.

Pixel art and regular photos need different treatment, so the engine checks using two tests: ① Color count test: it samples up to 8,000 pixels and buckets each color to 5-bit precision (32 levels per channel instead of 256). Pixel art typically uses fewer than 48 distinct colors at this precision. Regular photos use thousands. ② Block variance test: the image is divided into small NxN blocks. Inside each block, the engine measures how much the colors vary. Pixel art has near-zero variance, meaning each block is a solid-color pixel. Photos have smooth gradients with high variance. The threshold is set at an average variance of 300. Both tests must agree for the image to be treated as pixel art.

The board you selected (say, 29x29 pegs) defines how many beads wide and tall your pattern will be. The engine divides the image dimensions by the board dimensions to get a cell size. For example, a 580x580 pixel image mapped to a 29x29 board gives 20x20 pixels per cell. Each cell maps to exactly one bead slot. Non-slot positions (like the center hole on a hexagonal board, or off-grid cells) are marked empty automatically.

This step works differently for pixel art versus regular photos. For pixel art: the engine reads the single center pixel of each cell. There is no blending, because pixel art is designed so that one pixel equals one color. Averaging would destroy the crisp edges. For regular photos: the engine collects all foreground (non-background) pixels inside the cell. Instead of averaging them (which would produce muddy blended colors at edges), it finds the modal color, which is the most frequently occurring color bucket. Colors are bucketed to 6-bit precision (64 levels per channel) so nearly identical shades group together. The winning bucket's average becomes the cell's representative color. In both paths, cells that are mostly background (more than 40% background pixels) are marked empty.

Dark outlines are one of the hardest things to get right. Anti-aliasing (the slight blurring along edges in photos) can average a black outline with the background, producing a dark grey that might get mapped to a brown or navy bead rather than black. To fix this, the engine runs an outline snap check: if 30% or more of the foreground pixels in a cell are near-black neutral (all RGB channels below 48, and the spread between the highest and lowest channel below 32), the whole cell is forced to the black bead. This threshold catches anti-aliased edges without falsely converting dark-brown fur or dark-blue denim.

RGB values (red, green, blue) are convenient for screens, but the distances between RGB numbers do not match how humans perceive color differences. A 10-unit shift in blue looks smaller than the same shift in green. To fix this, each cell's color is converted to CIE Lab: a color space specifically designed so that equal numerical distances correspond to equal perceived differences. ① The RGB values are linearized (undoing the gamma correction that screens apply). ② The linear RGB values are multiplied through a 3x3 matrix to get CIE XYZ coordinates, which are a device-independent description of light. ③ XYZ coordinates are rescaled relative to a D65 white point (standard daylight) and passed through a cube-root function to produce Lab. L is lightness (0 is black, 100 is white), a is the green-to-red axis, and b is the blue-to-yellow axis. This is the same math used by professional color management systems.

Every bead color in the Perler, Artkal, and Hama palettes has been pre-converted to Lab values and stored in the app. The engine compares each cell's Lab color to every bead in your selected palette using the CIEDE2000 formula, which is the international standard for measuring human-perceived color difference, published by the International Commission on Illumination. CIEDE2000 improves on plain Lab distance by adding corrections for: • Hue rotation near blue (where Lab distances are non-uniform). • Chroma-dependent weighting (saturated colors need bigger corrections). • Lightness, chroma, and hue weighted independently. The bead with the lowest ΔE (delta-E, the color difference score) wins. A ΔE below 1 is imperceptible to most people; below 3 is acceptable for print; above 10 is clearly different. Real bead-to-bead mapping typically produces ΔE values between 2 and 15 depending on how unusual the input color is.

Each cell now has a bead color ID. These IDs are assembled into a 2D grid: an array of rows, each row containing an array of cells, each cell storing the bead's ID. The grid is rendered on-screen using a Canvas element (web) or SVG (native), at whatever zoom level your device supports. You can edit individual beads by tapping or clicking, zoom and pan with pinch and scroll, print a chart with a color key, or save the design to your account to continue later.