autoclaw-pixelbead-cli

pixelbead 🎨

Convert images into perler bead (拼豆) patterns with accurate color matching.

Built with AutoClaw — an AI-powered agent.

Features

• Multi-Brand Palettes — Built-in color databases for Artkal, Hama, Perler, MARD, COCO
• Perceptual Color Matching — CIEDE2000 color distance in Lab color space (not naive RGB)
• Noise Cleaning — BFS connected-component detection removes stray pixels
• Background Removal — Flood-fill from edges to detect and remove solid backgrounds
• Outline Enhancement — Darker shade outlines for better contrast
• Floyd-Steinberg Dithering — Smoother gradients when palette is limited
• Max Color Limit — Restrict the number of distinct bead colors used
• Multiple Output Formats — Terminal preview, PNG grid image, PDF printable template
• Material List — Bill of materials with color codes, names, bead counts

Install

npm install
npm run build

Usage

# Basic — terminal preview (Artkal, 29x29)
node dist/index.js convert input.png

# Specify brand and board size
node dist/index.js convert input.png -b hama --board 39x39

# Output PNG grid with color codes
node dist/index.js convert input.png -b artkal --board 100x100 -o pattern.png

# Output PDF printable template
node dist/index.js convert input.png -b perler --board 39x39 -o pattern.pdf

# Control color count and noise
node dist/index.js convert input.png --max-colors 25 --merge-threshold 15 --remove-bg

# Enable dithering and outline
node dist/index.js convert input.png --dither --outline -o pattern.png

# Use only specific colors you own
node dist/index.js convert input.png -b artkal --colors C-1,C-2,C-15,C-48,C-77

# List available brands
node dist/index.js brands

# Show all colors for a brand
node dist/index.js palette -b artkal

# Generate demo patterns
node dist/index.js demo -o ./demo/

Board Sizes

Size	Beads	Boards (29×29)	Best For
29×29	841	1	Simple icons
39×39	1,521	2	Small patterns
58×58	3,364	4	Detailed icons
80×80	6,400	8	Photos (good)
100×100	10,000	12	Photos (great) ⭐
120×120	14,400	17	Photos (finest)
200×200	40,000	48	Maximum detail

Sweet spot: 100×100 for photo-quality patterns with manageable bead count.

Supported Brands

Brand	Colors	Type
Artkal (C series)	81	2.6mm mini
Hama (midi)	65	5mm standard
Perler	66	5mm standard
MARD (咪小窝)	69	2.6mm mini
COCO (可可)	69	2.6mm mini

Output Examples

Terminal Preview

Rich ANSI 24-bit color output showing the bead pattern at a glance.

PNG Grid

Clean grid image with:

• Color code labels in each cell
• Grid lines separating bead positions
• Color legend with swatches
• Material list with bead counts
• Board boundary markers

PDF Template

Printable A4 PDF with:

• Grid pattern with color codes
• Multi-page support for large patterns
• Color legend and material list
• Board coordinates

How It Works

• Load & Resize — Image is loaded with sharp and resized to the target board dimensions using Lanczos3 interpolation
• Color Sampling — Each grid cell samples the dominant color (most frequent pixel), avoiding gray halos at color boundaries
• Color Matching — CIEDE2000 perceptual color distance finds the nearest bead color in Lab color space
• Post-Processing — Noise cleaning (BFS), background removal (flood-fill), outline enhancement, optional dithering
• Color Limiting — Merges least-used colors into their nearest popular neighbors
• Rendering — Outputs terminal preview, PNG grid, or PDF template

Tech Stack

• TypeScript — Full type safety
• sharp — Image loading and Lanczos3 resizing
• @napi-rs/canvas — PNG grid rendering with text labels
• pdfkit — PDF template generation
• chalk — Terminal color output
• commander — CLI argument parsing

License

MIT

Built with 🤖 AutoClaw