pindou-pattern

Perler Bead Pattern Generation (pindou-pattern)

Turn an image or pixel data into a perler bead pattern PNG you can directly follow: dark title bar + gradient brand logo + row and column coordinates around the edges + 30px color block grid (brand color code inside each cell, emphasized lines every 10 cells) + color code usage statistics area.

AI optimization effect (handling process when the user is dissatisfied)

When the user expresses dissatisfaction with an already generated pattern—such as "the effect is not good", "it doesn't look good", "the colors are too messy/too varied", "the details are blurry", "help me optimize it", "AI optimization", "redo it to look better"—do not just adjust the quantization parameters; follow the AI redraw → regenerate two steps.

Step 1: AI image editing (choose a provider by priority)

Preferred: the agent's built-in imagegen tool. First check whether you yourself have image generation/editing tools (such as the built-in image_genin Codex/WorkBuddy sessions, imagegen exposed as an MCP tool, etc.). If so, use it directly to perform the default PROMPT edit on the original image (the original image must be passed in as a reference image, a text-only prompt will redraw irrelevant content out of thin air), save the result as a local file (such as 原名_optimized.png), and skip optimize.js:

图片修改为：chibi画风，背景白底。pixel art style, 16-bit, retro game aesthetic, sharp focus, high contrast, clean lines, detailed pixel art, masterpiece, best quality

When there is no built-in tool: run optimize.js, the script automatically selects a provider (--provider auto）：

node .agents/skills/pindou-pattern/scripts/optimize.js 原图.png
# 提供方优先级: codex（WorkBuddy 版）CLI 内置 imagegen（免积分，需已装并开启 image_generation）
#              → apiz CLI 图像编辑（约 60~65 积分/次，默认 openai/gpt-image-2/edit，兜底）

Step 2: Regenerate the pattern using the optimized image

node .agents/skills/pindou-pattern/scripts/generate.js 原图_optimized.png --size 48 --system 盼盼 --blank-white --max-colors 16

Key points:

• The optimized image path is based on the actual output printed to stdout in Step 1: the codex path defaults to _optimized.png, the apiz path defaults to _optimized.jpg, do not copy the extension from the example.
• --max-colors 16 is the recommended combination after AI optimization: AI output is usually 1024px JPEG, and compression noise will cause direct quantization to scatter into 100+ colors; only after converging to 1224 colors is the bill of materials practical. Measured 104 colors → 16 colors, the main outline is unaffected.
• Give the optimization result to the user for comparison and judgment: report all three paths—the original image, the optimized image, and the final pattern—to the user, and let the user view and confirm. Do not perform visual model review. If the user reports that the optimized image is unrelated to the original image content (a sign that the reference image did not take effect), check --params image_urls after passing the parameter and retry.
• --blank-white is only used for subject images on a white background (cartoon characters, etc.); landscapes/full-frame patternsdo notuse it (the sky and clouds are beads you need to buy). AI's "white background" often has a ±10 color cast (measured 245,251,251), and the default threshold 240 can already catch it.
• --prompt can be replaced with a custom instruction; the apiz path --model can be replaced with an editing model (default openai/gpt-image-2/edit).
• When all providers are unavailable, fall back to only adjusting the --max-colors / --size / --match parameters, and explain this to the user.

Environment

• Node.js（≥16）+ sharp(the only npm dependency; the skill root directory already includes package.json).First userun once in the skill root directory npm install is sufficient; if the script reports that sharp is missing, prompt the user to run that command. Dependencies are looked up in node_modules by searching upward from the script's location, regardless of the current working directory; it can run without installation only when an upstream directory (such as this repository's root node_modules) already has sharp installed.
• AI optimization is an optional capability, with additional dependencies (depending on the provider): the agent's built-in imagegen tool / codex CLI / apiz CLI, any one of the three is sufficient; if all are missing, only AI optimization is affected (image generation is unaffected).

Quick Start

# 图片 → 32×32 MARD 图纸（默认输出 <输入名>_pattern.png）
node .agents/skills/pindou-pattern/scripts/generate.js 素材/卡通猫.png

# 指定品牌、尺寸、标题、输出路径，并把近白背景当空格
node .agents/skills/pindou-pattern/scripts/generate.js 素材/卡通猫.png \
  --size 48 --system 盼盼 --title 卡通猫 --blank-white --out 图纸/猫.png

# JSON 像素数据 → 图纸 + CSV 物料清单
node .agents/skills/pindou-pattern/scripts/generate.js 作品.json --csv 物料.csv

Input Format

Image (png/jpg/webp/bmp/gif/tiff) or JSON. JSON format:

{
  "gridSize": 16,
  "pixelData": ["#FFFFFF", "#FBED56", "..."]
}

• Image input: transparent areas are first composited onto a white background before quantization; non-square images are scaled proportionally (contain) and the empty areas are filled with white; without adding --blank-white , the white fill will be counted as light-colored beads
• pixelData row-major one-dimensional array, length = gridSize²,#FFFFFF represents an empty cell (no bead purchased)
• Non-palette colors in JSON are by default automatically snapped to the nearest color code among the 205 colors (ensuring the beads can be purchased);--no-snap disables this

Common Options

Option	Description	Default
--size <n>	Grid N×N (4~150), only effective for image input	32
--system <name>	Color code system: MARD / COCO / 漫漫 / 盼盼 / 咪小窝	MARD
--match <mode>	Color matching: rgb (Euclidean distance) / lab (perceptual color difference, usually more accurate)	rgb
--blank-white	Treat near-white in the image as empty cells	Off
--white-threshold <n>	Near-white threshold (used with --blank-white, default 240; AI white backgrounds often have a ±10 color cast, and if necessary it can be lowered to 230 for more aggressive blanking)	240
--max-colors <n>	Color count convergence: keep the top n colors by usage, and merge low-frequency colors into the nearest retained color (12~24 recommended for photos/AI-optimized images)	Unlimited
--title <text> / --watermark <text>	Title / watermark (empty string removes it)	拼豆图纸 / pindou.348349.xyz
--interval <n> / --grid-color <hex>	Bold line interval / color	10 / #555555
--no-grid --no-coordinates --no-cellnumbers --no-stats	Disable the corresponding layer	All on
--csv <path>	Export a CSV of color code usage (Excel-friendly with BOM)	None
--out <path>	Output PNG path	<输入名>_pattern.png

For the full list of options, see node .../generate.js --help。

Regression test (run once after skill changes to confirm functionality is normal):

node .agents/skills/pindou-pattern/scripts/generate.js .agents/skills/pindou-pattern/assets/sample-heart.json --out heart_test.png
# 预期: 16x16 | 用色 2 种 | 总豆数 128 颗 | F02 ×125 | E03 ×3（验证后删除 heart_test.png）

Workflow

1. Confirm what the user wants: grid size (16/24/32/48/100 are common tiers), brand color code system, and whether the background should be left blank. If the user is expressing dissatisfaction with an existing pattern, switch to the "AI Optimization Effect" workflow above.
2. Run generate.js; the command will print to stdout: output path, canvas size, number of colors used, total bead count, and the usage of each color code.
3. Report to the user: pattern path + color code usage list (directly cite the stdout statistics) + total bead count; if there is a CSV, provide its path as well.

Do not perform visual inspection. The generation process is deterministic; objective metrics are based on the script's stdout statistics and (when necessary) pixel-level checks; the quality of the pattern is for the user to view and judge. Do not use a visual model to "review" the image content—measured hallucination rates are high and will create misjudgments.

Color Code Data Maintenance

• Color code mapping table scripts/colorData.js(205 colors × 5 brands) is already inlined in this skill, and running it does not depend on any external files. If the data needs to be updated, pass in the colorData.ts source file path to re-extract (do not manually edit colorData.js):

  node .agents/skills/pindou-pattern/scripts/_extract.js <colorData.ts 的路径>
  

• Rendering pipeline: SVG → sharp → PNG.