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.mdand complete the checks.
Input Conventions
- Before conversion, examine the real original image: record its dimensions, aspect ratio, subject, background complexity, transparent areas, and any important text or identity features.
- Unless the user indicates the image is for style reference only, treat it as the editing target that must preserve the subject.
- Within the grid's capability, preserve visible identity features, outlines, orientation, object count, major color blocks, and any necessary short text.
- 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.
- 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.
- 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
- Use the local image viewing capability to inspect the original image and read its file dimensions.
- According to
references/design-guide.md, choose grid size, palette, fitting method, background handling, and bead style. - 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.
- 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.
- 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.
- 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.
- 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
- Reduce the user's request to a centered, recognizable outline or compact composition.
- Generate a source image with a clean or transparent background, broad color blocks, no texture or lighting gradients, and no small text.
- Pass the actually generated image into Pattern Mode.
- 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**

**Fuse Bead Effect 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-beadsto 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."