CommunityImagegithub.com

make-perler-beads

Convert user-provided images or text concepts into fuse bead (Perler / Hama / Artkal) patterns, outputting accurate bead previews, numbered layout grids, color legends, bead usage lists, and optionally generate social-media-style showcase images.

What is make-perler-beads?

This skill, `make-perler-beads`, transforms any image (photos, pets, characters, logos, icons, screenshots, illustrations) into precise, buildable fuse bead patterns—compatible with Perler, Hama, Artkal, and other bead brands. It first generates a clear color-block preview without holes to verify composition, then produces an exact bead-effect rendering and a numbered construction grid with color codes and quantities determined by deterministic Python scripts. The skill supports four modes: Pattern Mode (default for images), Showcase Mode (adds a lifestyle display photo after the pattern), Text Design Mode (creates a source image from text concepts first), and Prompt-Only Mode (returns generation parameters only upon explicit request). It emphasizes accuracy: all outputs—preview, grid, CSV, legend, and bill of materials—are derived from the same bead matrix via `scripts/render_bead_pattern.py`, and generative images are never used as construction guides. The user must follow design guidelines from `references/design-guide.md` and quality checks from `references/quality-gate.md`. Color palettes can be extracted from the source or custom user/brand palettes in JSON format. The skill is designed for use with Codex Desktop (Python + Pillow required) and can be called with commands like `$make-perler-beads` to generate practical, shareable bead patterns.

Works with~Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/billxfan/agent-skills/tree/HEAD/skills/make-perler-beads

Installed? Explore more Image skills: steipete/songsee, affaan-m/frontend-design, mattpocock/improve-codebase-architecture · View all 6 →

Ask in your favorite AI

Open a new chat with this agent skill pre-loaded.

Preview

From the skill README

Clear Color Preview
Fuse Bead Effect

Documentation

Fuse Bead Pattern Generator

Transform images into fuse bead patterns that both resemble the original and are buildable. First ensure the subject is clear in the hole-free color preview, then render the actual bead surface. Exact bead positions, color codes, and quantities must be computed by deterministic scripts; image generation is used only for optional showcase images.

Determine Request Mode

Choose the smallest mode that satisfies the request:

  • Pattern Mode – default when an image is provided: Original image → precise bead effect preview + numbered construction grid + color and usage file.
  • Showcase Mode: Complete Pattern Mode first, then generate a social-media-style flat lay or product showcase image based on the effect preview. Do NOT use a generative image as a construction guide.
  • Text Design Mode: When the user has no image, only a text concept, first generate a clean, focused source image, then proceed to Pattern Mode.
  • Prompt-Only Mode: Use only when the user explicitly asks; return prompts and recommended parameters, do NOT claim a pattern has been generated.

When the user uploads an image and says "make it into fuse beads," use Pattern Mode directly. Do not ask the user for parameters that can be safely decided automatically.

Read Related Guides

  • Before selecting grid size, background processing, palette, or bead style, read references/design-guide.md.
  • Before returning output, read references/quality-gate.md and complete the checks.

Input Conventions

  1. Before conversion, examine the real original image: record its dimensions, aspect ratio, subject, background complexity, transparent areas, and any important text or identity features.
  2. Unless the user indicates the image is for style reference only, treat it as the editing target that must preserve the subject.
  3. Within the grid's capability, preserve visible identity features, outlines, orientation, object count, major color blocks, and any necessary short text.
  4. If the grid is too small to accommodate faces, fine text, complex scenes, or small marks, briefly explain the limitation and increase the grid size; do not invent details.
  5. Do not remove meaningful backgrounds arbitrarily. Only use automatic background removal if the background is nearly solid or if the user explicitly requests subject isolation.
  6. For multi-person or complex scenes, first do a "clarity budget": estimate how many bead cells each core subject will receive. If a core face, pet head, or logo is narrower than about 16 cells, prioritize cropping tighter or increasing the grid rather than generating directly.

Pattern Mode Workflow

  1. Use the local image viewing capability to inspect the original image and read its file dimensions.
  2. According to references/design-guide.md, choose grid size, palette, fitting method, background handling, and bead style.
  3. Find a Python environment with Pillow. On Codex desktop, first load workspace dependencies, then use the returned built-in Python path. If Pillow is missing, explain the dependency; do not install it without permission.
  4. Run:
<python-with-pillow> scripts/render_bead_pattern.py input_image output_dir \
  --width-beads 48 \
  --max-colors 18 \
  --fit contain \
  --background keep \
  --render beads

Resolve script and resource paths relative to this Skill's directory. Use --help to see all parameters. For complex illustrations, increase --sharpen 1.2; to focus on the subject, use --crop "left,top,right,bottom"; to lock small critical color areas, use quoted --anchor-colors "#F2C76E,#8A315F". To extract an adaptive palette from the source image, use --palette source; to use a user's inventory or brand palette, pass a JSON file with the same structure as assets/generic-palette.json.

  1. First inspect the hole-free color preview to judge if composition and subject are clear; then examine the bead effect preview and construction grid. Do not rely solely on command output.
  2. Compare the original image at both full size and thumbnail size. If identity or outlines are lost, prioritize cropping tighter or increasing the grid; if thin lines are lost, increase sharpening; if critical colors disappear, lock them. Retry once.
  3. Verify that the total usage count equals the number of all non-empty grid cells.

The script outputs:

  • *-color-preview.png: hole-free, unlabeled clear color preview for judging subject recognizability;
  • *-bead-preview.png: fuse bead effect preview rendered from the exact grid;
  • *-pattern.png: numbered construction grid;
  • *-legend.png: color legend with count per color;
  • *-pattern.csv: per-cell color code table;
  • *-bom.csv: material usage list;
  • *-metadata.json: conversion parameters, colors, and totals.

Showcase Mode Workflow

Pattern Mode must be completed first, then pass the generated bead effect preview as the editing target into the built-in image generation capability.

Keep the design, grid proportions, outlines, orientation, and major color positions unchanged. Only allow changes to camera angle, bead board material, tabletop, lighting, props, and background. Prefer a clean top-down craft tabletop, soft natural light, and a few related tools; do not let hands or props obscure the work.

If the showcase image noticeably alters the design or bead positions, retry once with stricter preservation requirements. Return the exact effect preview and construction files first, then the showcase image, to avoid confusion.

Text Design Mode Workflow

  1. Reduce the user's request to a centered, recognizable outline or compact composition.
  2. Generate a source image with a clean or transparent background, broad color blocks, no texture or lighting gradients, and no small text.
  3. Pass the actually generated image into Pattern Mode.
  4. Clearly state that this is a design created from the user's text concept, not a conversion of the user's original image.

Output Format

Prioritize returning the most practical outputs:

**Clear Pattern Preview**

![Clear Color Preview](absolute/path/to/color-preview)

**Fuse Bead Effect Preview**

![Fuse Bead Effect](absolute/path/to/bead-preview)

**Construction Grid & Usage**

- Grid: [width] × [height]
- Colors: [number of colors]
- Total beads: [number of non-empty cells]
- Construction grid: [clickable absolute path]
- Color code legend: [clickable absolute path]
- Usage list: [clickable absolute path]

**Conversion Settings**

- [Grid / Palette / Fit / Background / Bead Style]
- [One sentence explaining preserved effects or necessary trade-offs]

Add Showcase Image only if Showcase Mode was run. Do not output internal logs or full metadata JSON unless the user requests it.

Mandatory Rules

  • The effect preview, construction grid, CSV, legend, and usage must all come from the same bead matrix.
  • The hole-free color preview and the bead effect preview must also come from the same bead matrix; do not use a different "better-looking" image as the clear preview.
  • Never use a generative image as an exact bead-count construction guide.
  • Never refer to generic palette color codes as official Perler, Hama, Artkal, or other brand color numbers.
  • When the user provides a brand color table, use it as data and accurately cite the source.
  • Do not place long text on small patterns; use initials, short words, or a larger grid.
  • Upscaling a low-resolution PNG does not improve fidelity; you must increase bead cells and recalculate.
  • If two core subjects are still unrecognizable in the thumbnail of the color preview, do not describe the result as "clear" or "fully restored."

Calling Examples

  • "Use $make-perler-beads to turn this cat photo into a 48-bead-wide fuse bead pattern."
  • "Keep only the person, remove the background, and limit to 16 colors."
  • "Make this logo into a 29×29 fuse bead pattern and give me the construction grid and usage list."
  • "After the pattern is done, generate a social-media-style tabletop showcase image."

Related Skills