Perler Pattern

Perler Bead Pattern Generator · 拼豆图纸生成器

把任意图片自动去背景，生成精美拼豆图纸。 内置 GrabCut 离线去背景，无需任何外部 API，零费用。

Palette reference → references/palettes.md Style guide → references/styles.md

Trigger / 触发时机

• "Turn this photo into a perler bead pattern"
• "帮我把这张图片做成拼豆图纸"
• "Make a hama bead pattern from my pet photo"
• "把我家宠物的照片转成拼豆图纸"
• "Generate a 40×40 Artkal bead pattern"
• "用欧小色板生成拼豆图纸，深色背景"

---

Step 0: Dependency Check / 环境检查

# Check and install required packages
python3 -c "import cv2" 2>/dev/null || pip3 install opencv-python-headless --quiet
python3 -c "from PIL import Image" 2>/dev/null || pip3 install Pillow --quiet
python3 -c "import numpy" 2>/dev/null || pip3 install numpy --quiet
echo "✅ Ready"

---

Step 1: Extract Parameters / 提取参数

Image / 图片来源:
  Local path 本地路径  or  URL 网络链接

Grid size / 网格尺寸 (default 40×40):
  "small"  → 29×29   (one board / 一块板)
  "medium" → 40×40   (default / 默认)
  "large"  → 48×48
  "xlarge" → 64×64

Palette / 色板 (default: hama):
  hama / artkal / perler / universal

Background color / 背景色 (default: dark_navy):
  dark_navy  → (15, 15, 40)   深海军蓝，最常见
  black      → (5, 5, 5)      纯黑
  white      → (255,255,255)  白色（适合浅色主体）
  custom     → 用户指定 RGB

Max colors / 颜色数 (default: 25):
  "simple"   → 15
  "standard" → 25
  "detailed" → 32

---

Step 2: Run / 执行脚本

Replace all __PARAM__ placeholders before running.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""Perler Bead Pattern Generator v1.2 — Auto background removal via GrabCut"""

import os, sys, json, math
import cv2
import numpy as np
from pathlib import Path
from PIL import Image, ImageEnhance, ImageFilter, ImageDraw

# ── Parameters (filled by OpenClaw) ──────────────────────
IMAGE_PATH   = "__IMAGE_PATH__"
GRID_W       = 40
GRID_H       = 40
MAX_COLORS   = 25
PALETTE_NAME = "hama"           # hama / artkal / perler / universal
BG_COLOR     = (15, 15, 40)     # deep navy blue
OUTPUT_DIR   = "__OUTPUT_DIR__"

# ── Guard ────────────────────────────────────────────────
if "__IMAGE_PATH__" in IMAGE_PATH or not IMAGE_PATH:
    print("❌ IMAGE_PATH not set."); sys.exit(1)
os.makedirs(OUTPUT_DIR, exist_ok=True)

# ── Palettes ─────────────────────────────────────────────
PALETTES = {
    "hama": {
        "H01":("White/白",        (255,255,255)), "H02":("Cream/奶油",     (255,253,208)),
        "H03":("Lt Yellow/淡黄",  (255,239, 96)), "H04":("Yellow/黄",      (255,216,  0)),
        "H05":("Orange/橙",       (255,140,  0)), "H06":("Red-Orange/橙红",(230, 75,  0)),
        "H07":("Red/红",          (210, 20, 20)), "H08":("Dark Red/暗红",  (155,  0,  0)),
        "H09":("Lt Pink/浅粉",    (255,190,210)), "H10":("Pink/粉",        (255,130,170)),
        "H11":("Rose/玫红",       (220, 45,120)), "H12":("Purple/紫",      (128, 28,156)),
        "H13":("Violet/紫罗兰",   ( 88, 18,196)), "H14":("Lavender/薰衣草",(200,168,255)),
        "H15":("Lt Blue/天蓝",    (130,198,255)), "H16":("Blue/蓝",        (  0, 96,200)),
        "H17":("Dark Blue/深蓝",  (  0, 28,138)), "H18":("Turquoise/青",   (  0,178,178)),
        "H19":("Dark Green/深绿", (  0, 88,  0)), "H20":("Green/绿",       ( 28,158, 28)),
        "H21":("Lime/黄绿",       (146,218,  0)), "H22":("Mint/薄荷",      (168,255,210)),
        "H23":("Dark Brown/深棕", ( 78, 38,  0)), "H24":("Brown/棕",       (138, 68, 18)),
        "H25":("Tan/浅棕",        (198,152, 88)), "H26":("Skin/肤色",      (255,208,168)),
        "H27":("Peach/桃",        (255,178,140)), "H28":("Coral/珊瑚",     (255,108,100)),
        "H29":("Lt Grey/浅灰",    (210,210,210)), "H30":("Grey/灰",        (148,148,148)),
        "H31":("Dark Grey/深灰",  ( 78, 78, 78)), "H32":("Black/黑",       ( 10, 10, 10)),
        "H33":("Gold/金",         (218,178,  0)), "H34":("Silver/银",      (188,188,188)),
        "H35":("Neon Yellow/荧光黄",(226,255,0)),"H36":("Neon Pink/荧光粉",(255,18,144)),
        "H37":("Neon Green/荧光绿",(  0,252, 78)),"H38":("Neon Orange/荧光橙",(255,100,0)),
    },
    "artkal": {
        "C01":("White/白",(255,255,255)),"C02":("Cream/奶油",(255,248,208)),
        "C03":("Lt Yellow/淡黄",(255,232,88)),"C04":("Yellow/黄",(255,212,0)),
        "C05":("Orange/橙",(255,138,0)),"C06":("Red-Orange/橙红",(228,68,0)),
        "C07":("Red/红",(208,14,14)),"C08":("Dark Red/深红",(138,0,0)),
        "C09":("Lt Pink/浅粉",(255,172,192)),"C10":("Rose/玫红",(222,38,118)),
        "C11":("Purple/紫",(118,24,152)),"C12":("Dark Purple/深紫",(78,0,118)),
        "C13":("Sky Blue/天蓝",(128,192,255)),"C14":("Blue/蓝",(0,88,192)),
        "C15":("Navy/深蓝",(0,18,128)),"C16":("Cyan/青",(0,172,172)),
        "C17":("Green/绿",(24,152,24)),"C18":("Dark Green/深绿",(0,78,0)),
        "C19":("Yellow-Green/黄绿",(138,212,0)),"C20":("Brown/棕",(132,62,14)),
        "C21":("Dark Brown/深棕",(72,32,0)),"C22":("Tan/浅棕",(192,148,82)),
        "C23":("Skin/肤色",(248,202,162)),"C24":("Coral/珊瑚",(248,122,102)),
        "C25":("Lt Grey/浅灰",(208,208,208)),"C26":("Grey/灰",(142,142,142)),
        "C27":("Dark Grey/深灰",(72,72,72)),"C28":("Black/黑",(4,4,4)),
        "C29":("Gold/金",(212,172,0)),"C30":("Lavender/薰衣草",(202,172,248)),
    },
    "perler": {
        "P01":("White/白",(255,255,255)),"P02":("Cream/奶油",(255,246,218)),
        "P03":("Yellow/黄",(255,222,0)),"P04":("Orange/橙",(255,118,0)),
        "P05":("Red/红",(212,0,14)),"P06":("Lt Pink/浅粉",(255,168,188)),
        "P07":("Pink/粉",(255,108,158)),"P08":("Rose/玫红",(218,42,118)),
        "P09":("Purple/紫",(122,28,152)),"P10":("Lt Blue/天蓝",(122,188,255)),
        "P11":("Blue/蓝",(0,82,188)),"P12":("Dark Blue/深蓝",(0,22,128)),
        "P13":("Teal/青",(0,162,162)),"P14":("Green/绿",(18,148,18)),
        "P15":("Dark Green/深绿",(0,72,0)),"P16":("Kiwi/黄绿",(142,208,0)),
        "P17":("Brown/棕",(128,58,8)),"P18":("Peach/桃",(255,198,158)),
        "P19":("Lt Grey/浅灰",(208,208,208)),"P20":("Grey/灰",(138,138,138)),
        "P21":("Black/黑",(0,0,0)),"P22":("Gold/金",(208,168,0)),
        "P23":("Silver/银",(182,182,182)),"P24":("Clear/透明",(238,238,238)),
    },
    "universal": {
        "U01":("White/白",(255,255,255)),"U02":("Ivory/米白",(255,248,210)),
        "U03":("Lt Yellow/浅黄",(255,238,82)),"U04":("Yellow/黄",(255,212,0)),
        "U05":("Amber/琥珀",(222,178,0)),"U06":("Lt Orange/浅橙",(255,168,58)),
        "U07":("Orange/橙",(255,110,0)),"U08":("Dk Orange/深橙",(218,68,0)),
        "U09":("Salmon/鲑鱼",(255,120,100)),"U10":("Red/红",(210,0,0)),
        "U11":("Dark Red/深红",(138,0,0)),"U12":("Lt Pink/浅粉",(255,198,212)),
        "U13":("Pink/粉",(255,148,178)),"U14":("Hot Pink/玫红",(218,38,118)),
        "U15":("Magenta/品红",(198,0,148)),"U16":("Lavender/薰衣草",(208,178,255)),
        "U17":("Purple/紫",(128,28,158)),"U18":("Dk Purple/深紫",(78,0,118)),
        "U19":("Baby Blue/婴儿蓝",(178,222,255)),"U20":("Sky Blue/天蓝",(98,178,255)),
        "U21":("Blue/蓝",(0,88,198)),"U22":("Dark Blue/深蓝",(0,22,138)),
        "U23":("Cyan/青",(0,178,178)),"U24":("Dark Cyan/深青",(0,118,118)),
        "U25":("Lt Green/浅绿",(148,228,148)),"U26":("Green/绿",(28,158,28)),
        "U27":("Dark Green/深绿",(0,88,0)),"U28":("Yellow Green/黄绿",(152,222,0)),
        "U29":("Lt Brown/浅棕",(208,168,108)),"U30":("Brown/棕",(148,78,22)),
        "U31":("Dark Brown/深棕",(88,42,0)),"U32":("Skin/肤色",(255,208,168)),
        "U33":("Peach/桃",(255,178,138)),"U34":("Lt Grey/浅灰",(208,208,208)),
        "U35":("Grey/灰",(148,148,148)),"U36":("Dark Grey/深灰",(78,78,78)),
        "U37":("Black/黑",(4,4,4)),"U38":("Gold/金",(218,178,0)),
        "U39":("Silver/银",(190,190,190)),"U40":("Neon Yellow/荧光黄",(228,255,0)),
        "U41":("Neon Pink/荧光粉",(255,18,144)),"U42":("Neon Green/荧光绿",(0,252,78)),
    }
}

# ── Color math: Lab color space ───────────────────────────
def rgb_to_lab(rgb):
    r,g,b = [c/255.0 for c in rgb]
    def lin(c): return c/12.92 if c<=0.04045 else ((c+0.055)/1.055)**2.4
    r,g,b = lin(r),lin(g),lin(b)
    X=r*0.4124564+g*0.3575761+b*0.1804375
    Y=r*0.2126729+g*0.7151522+b*0.0721750
    Z=r*0.0193339+g*0.1191920+b*0.9503041
    X/=0.95047; Z/=1.08883
    def f(t): return t**(1/3) if t>0.008856 else 7.787*t+16/116
    fx,fy,fz=f(X),f(Y),f(Z)
    return 116*fy-16, 500*(fx-fy), 200*(fy-fz)

def lab_dist(a,b): return sum((x-y)**2 for x,y in zip(a,b))**0.5

def build_lab_pal(palette):
    return {code:(info[0],info[1],rgb_to_lab(info[1])) for code,info in palette.items()}

def nearest_color(rgb, lab_pal):
    lab=rgb_to_lab(rgb)
    best,dist=None,float('inf')
    for code,(_,pal_rgb,pal_lab) in lab_pal.items():
        d=lab_dist(lab,pal_lab)
        if d0.04045
        rgb=np.where(m,((rgb+0.055)/1.055)**2.4,rgb/12.92)
        M=np.array([[0.4124564,0.3575761,0.1804375],[0.2126729,0.7151522,0.0721750],[0.0193339,0.1191920,0.9503041]])
        xyz=rgb@M.T/[0.95047,1,1.08883]
        m2=xyz>0.008856
        xyz=np.where(m2,xyz**(1/3),7.787*xyz+16/116)
        return np.stack([116*xyz[:,:,1]-16,500*(xyz[:,:,0]-xyz[:,:,1]),200*(xyz[:,:,1]-xyz[:,:,2])],2)
    def l2r(lab):
        L,a,b=lab[:,:,0],lab[:,:,1],lab[:,:,2]
        fy=(L+16)/116;fx=a/500+fy;fz=fy-b/200
        xyz=np.stack([fx,fy,fz],2)
        m=xyz>0.2068966
        xyz=np.where(m,xyz**3,(xyz-16/116)/7.787)*[0.95047,1,1.08883]
        Mi=np.array([[3.2404542,-1.5371385,-0.4985314],[-0.9692660,1.8760108,0.0415560],[0.0556434,-0.2040259,1.0572252]])
        rgb=np.clip(xyz@Mi.T,0,1)
        m2=rgb>0.0031308
        return np.clip(np.where(m2,1.055*rgb**(1/2.4)-0.055,12.92*rgb)*255,0,255).astype(np.uint8)
    lab=r2l(arr)
    L=lab[:,:,0]
    p2,p98=np.percentile(L,2),np.percentile(L,98)
    if p98-p2>5:
        lab[:,:,0]=np.clip((L-p2)/(p98-p2)*100,0,100)
    return l2r(lab)

# ── Map pixels to palette ─────────────────────────────────
def map_to_palette(arr,lab_pal,max_colors):
    h,w=arr.shape[:2]
    cache={}
    grid=[[None]*w for _ in range(h)]
    usage={}
    for y in range(h):
        for x in range(w):
            rgb=tuple(arr[y,x])
            if rgb not in cache:
                code,pal_rgb=nearest_color(rgb,lab_pal)
                name=lab_pal[code][0]
                cache[rgb]=(code,name,pal_rgb)
            code,name,pal_rgb=cache[rgb]
            grid[y][x]=code
            if code not in usage:
                usage[code]={"name":name,"rgb":pal_rgb,"count":0}
            usage[code]["count"]+=1
    # Enforce max_colors: merge least-used into nearest
    while len(usage)>max_colors:
        least=min(usage,key=lambda c:usage[c]["count"])
        ll=rgb_to_lab(usage[least]["rgb"])
        best_alt,bd=None,float('inf')
        for c in usage:
            if c==least: continue
            d=lab_dist(ll,rgb_to_lab(usage[c]["rgb"]))
            if d',
       f'',
       f'']
    for y,row in enumerate(grid):
        for x,code in enumerate(row):
            r,g,b=usage[code]["rgb"]
            fill=f"#{r:02x}{g:02x}{b:02x}"
            lum=0.299*r+0.587*g+0.114*b
            tc="#fff" if lum<128 else "#000"
            px,py=x*cell,y*cell
            L.append(f'')
            if cell>=10:
                num=''.join(c for c in code if c.isdigit())
                L.append(f'{num}')
    for i in range(0,cols+1,10): L.append(f'')
    for i in range(0,rows+1,10): L.append(f'')
    L.append(f'')
    L.append('')
    return '\n'.join(L)

# ── 3D Bead preview PNG ───────────────────────────────────
def gen_bead_preview(arr_q,bg_color,cell=20):
    rows,cols=arr_q.shape[:2]
    canvas=Image.new("RGB",(cols*cell,rows*cell),bg_color)
    draw=ImageDraw.Draw(canvas)
    for y in range(rows):
        for x in range(cols):
            r,g,b=int(arr_q[y,x,0]),int(arr_q[y,x,1]),int(arr_q[y,x,2])
            cx,cy=x*cell+cell//2,y*cell+cell//2
            pad=1
            # Main bead body
            draw.ellipse([cx-cell//2+pad,cy-cell//2+pad,cx+cell//2-pad,cy+cell//2-pad],fill=(r,g,b))
            # Bottom-right shadow (same hue, darker)
            dark=(max(0,r-55),max(0,g-55),max(0,b-55))
            draw.arc([cx-cell//2+pad+1,cy-cell//2+pad+1,cx+cell//2-pad-1,cy+cell//2-pad-1],
                     start=30,end=210,fill=dark,width=2)
            # Top-left highlight (lighter)
            hs=cell//5
            hi=(min(255,r+90),min(255,g+90),min(255,b+90))
            draw.ellipse([cx-hs,cy-hs,cx,cy],fill=hi)
    return canvas

# ── Interactive HTML viewer ───────────────────────────────
def gen_html(grid,usage,palette_name,bg_color):
    rows,cols=len(grid),len(grid[0])
    total=sum(v["count"] for v in usage.values())
    bg_hex="#{:02x}{:02x}{:02x}".format(*bg_color)
    cells_js=json.dumps([[grid[y][x] for x in range(cols)] for y in range(rows)])
    colors_js=json.dumps([
        {"code":c,"name":v["name"],"hex":"#{:02x}{:02x}{:02x}".format(*v["rgb"]),"count":v["count"]}
        for c,v in sorted(usage.items(),key=lambda x:-x[1]["count"])
    ])
    return f"""<!DOCTYPE html>


Perler Pattern · 拼豆图纸 {cols}×{rows}


  🧩 Perler Bead Pattern · 拼豆图纸
  {cols}×{rows} · {palette_name.upper()} · {len(usage)} colors · {total:,} beads


  Cell 格子 14px
   Numbers 编号
   Grid 网格
  ⬇ SVG
  ⬇ PNG
  🖨 Print
  ✖ Clear


  
    📊 Stats · 统计
    
      {cols}×{rows}Grid 网格
      {total:,}Beads 豆数
      {len(usage)}Colors 颜色
      {palette_name.upper()}Palette 色板
    
  
  
    🎨 Bead List · 用豆清单
    
  


"""

# ── Bead list text ────────────────────────────────────────
def gen_bead_list(usage,palette_name,gw,gh):
    total=sum(v["count"] for v in usage.values())
    lines=[f"Perler Bead List · 用豆清单",f"Palette: {palette_name.upper()}  Grid: {gw}×{gh}  Colors: {len(usage)}",
           "="*62,f"{'Code':<8}{'Name':<28}{'Count':>6}   {'Hex'}","-"*62]
    for code,v in sorted(usage.items(),key=lambda x:-x[1]["count"]):
        r,g,b=v["rgb"]
        lines.append(f"{code:<8}{v['name']:<28}{v['count']:>4} pcs  #{r:02x}{g:02x}{b:02x}")
    lines+=["="*62,f"{'Total / 合计':<36}{total:>4} pcs"]
    return '\n'.join(lines)

# ── MAIN ──────────────────────────────────────────────────
print("🧩 Perler Pattern Generator v1.2 starting...")

if not Path(IMAGE_PATH).exists() and not IMAGE_PATH.startswith("http"):
    print(f"❌ Not found: {IMAGE_PATH}"); sys.exit(1)

print("📷 Loading image...")
img_rgb = load_image(IMAGE_PATH)
print(f"   Size: {img_rgb.shape[1]}×{img_rgb.shape[0]}")

print("✂️  Removing background (GrabCut, fully offline)...")
img_nobg = remove_background(img_rgb, BG_COLOR)
print("   Done")

print(f"📐 Resizing to {GRID_W}×{GRID_H}...")
img_small = resize_crop(img_nobg, GRID_W, GRID_H)

print("🌈 Equalizing brightness (Lab color space)...")
img_eq = lab_equalize(img_small)

print("🔪 Sharpening edges...")
img_pil = Image.fromarray(img_eq)
img_pil = img_pil.filter(ImageFilter.UnsharpMask(radius=1.2, percent=120, threshold=2))
img_pil = ImageEnhance.Contrast(img_pil).enhance(1.25)
img_arr = np.array(img_pil)

print(f"🎨 Quantizing → {PALETTE_NAME} palette ({MAX_COLORS} colors)...")
img_q = img_pil.quantize(colors=MAX_COLORS, method=Image.Quantize.MEDIANCUT, dither=0).convert("RGB")
palette = PALETTES.get(PALETTE_NAME, PALETTES["hama"])
lab_pal = build_lab_pal(palette)
grid, grid_rgb, usage = map_to_palette(np.array(img_q), lab_pal, MAX_COLORS)
print(f"   Actual colors used: {len(usage)}")

print("💾 Generating output files...")

svg = gen_svg(grid, usage, cell=16)
p = os.path.join(OUTPUT_DIR, "pattern.svg")
open(p,"w",encoding="utf-8").write(svg); print(f"   ✅ SVG: {p}")

html = gen_html(grid, usage, PALETTE_NAME, BG_COLOR)
p = os.path.join(OUTPUT_DIR, "pattern.html")
open(p,"w",encoding="utf-8").write(html); print(f"   ✅ HTML: {p}")

bead_canvas = gen_bead_preview(grid_rgb, BG_COLOR, cell=20)
p = os.path.join(OUTPUT_DIR, "preview_beads.png")
bead_canvas.save(p); print(f"   ✅ Bead preview: {p}")

flat = Image.fromarray(grid_rgb).resize((GRID_W*16, GRID_H*16), Image.NEAREST)
p = os.path.join(OUTPUT_DIR, "preview_flat.png")
flat.save(p); print(f"   ✅ Flat preview: {p}")

blist = gen_bead_list(usage, PALETTE_NAME, GRID_W, GRID_H)
p = os.path.join(OUTPUT_DIR, "bead_list.txt")
open(p,"w",encoding="utf-8").write(blist); print(f"   ✅ Bead list: {p}")

total=sum(v["count"] for v in usage.values())
print(f"""
╔════════════════════════════════════════╗
║  🧩 Pattern Ready! · 拼豆图纸生成完成  ║
╠════════════════════════════════════════╣
║  Grid  : {GRID_W}×{GRID_H}  Colors: {len(usage)}  Beads: {total:,}
║  Palette: {PALETTE_NAME.upper()}
╠════════════════════════════════════════╣
║  pattern.html      ← 浏览器查看/打印
║  pattern.svg       ← 可打印矢量图纸
║  preview_beads.png ← 3D豆子效果预览
║  preview_flat.png  ← 平铺效果预览
║  bead_list.txt     ← 购买清单
╚════════════════════════════════════════╝
Output: {OUTPUT_DIR}
""")
print(blist)

---

Step 3: Conversation / 多轮对话

"background messy / 背景去除不干净" → ask user to pre-crop or use phone app to remove bg first
"more colors / 颜色太少"             → increase MAX_COLORS (+5), re-run
"fewer colors / 颜色太多"            → decrease MAX_COLORS (-5), re-run
"change to black bg / 换黑色背景"    → BG_COLOR=(5,5,5), re-run
"white background / 白色背景"        → BG_COLOR=(255,255,255), re-run
"switch palette / 换色板"            → change PALETTE_NAME, re-run
"how many beads / 需要多少豆"        → show bead_list.txt

---

Tips / 使用建议

Best images 最佳图片类型:

• ✅ Pets / animals on simple background · 简单背景的宠物
• ✅ Cartoon / anime characters · 卡通角色
• ✅ Logos, icons · Logo图标
• ✅ Pre-removed background (PNG with transparency) · 已去背景的PNG

If GrabCut result is poor / 如果去背景效果不好:

• Use phone app first: iOS "Remove Background" / Android "Background Eraser"
• 先用手机App去背景，效果会更好
• Or crop image to focus on subject only · 先裁剪让主体占满画面

Color count guide / 颜色数建议:

• 15: Simple, easy to assemble · 简单，容易拼
• 25: Standard, good detail · 标准，细节好（默认）
• 32: Detailed, complex · 精细，适合大尺寸