fusebead 0.1.0__tar.gz

fusebead-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ROCKIMG
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

fusebead-0.1.0/PKG-INFO

@@ -0,0 +1,80 @@
+Metadata-Version: 2.4
+Name: fusebead
+Version: 0.1.0
+Summary: Turn a photo into a fuse-bead pattern, with palette matching, bead counts, and a printable PNG.
+Author-email: ROCKIMG <admin@rockimg.com>
+License-Expression: MIT
+Project-URL: Homepage, https://www.rockimg.com/perler-bead-pattern-maker.html
+Project-URL: Documentation, https://www.rockimg.com/perler-bead-pattern-maker.html
+Keywords: fuse-bead,bead-pattern,pixel-art,image
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Multimedia :: Graphics
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pillow>=10
+Dynamic: license-file
+
+# fusebead
+
+Turn a photo into a fuse-bead pattern: a pegboard grid, the nearest bead color, a printable PNG, and a color-count chart.
+
+Color matching follows the [ROCKIMG fuse-bead pattern maker](https://www.rockimg.com/perler-bead-pattern-maker.html): sRGB to CIE Lab, CIE76 distance, the same brightness and contrast sliders, and the same three palettes.
+
+Perler, Hama, and Artkal are trademarks of their owners. This package is not affiliated with those brands. Palette RGB values are the approximations used by the website, not official manufacturer color cards.
+
+## Install
+
+```bash
+pip install fusebead
+```
+
+From a checkout of this repository:
+
+```bash
+pip install -e packages/fusebead
+```
+
+Requires Python 3.9+ and Pillow.
+
+## Library
+
+```python
+from fusebead import Pattern
+
+pattern = Pattern.from_image(
+    "cat.png",
+    palette="perler",      # perler, hama, or artkal
+    grid_width=50,         # max pegs on the long side; aspect ratio is kept
+    grid_height=50,
+    brightness=0,          # website slider range is -80..80
+    contrast=0,
+    remove_background=True,
+)
+pattern.save_png("pattern.png")
+pattern.save_csv("beads.csv")
+
+pattern.width, pattern.height
+pattern.total
+pattern.cell(0, 0)          # BeadColor or None when the background was removed
+pattern.entries[0].color.code
+pattern.entries[0].count
+```
+
+Phone photos are rotated with EXIF orientation before sampling. The website canvas does not do that step.
+
+## Command line
+
+```bash
+fusebead cat.png -o pattern.png --csv beads.csv --palette hama --width 40 --height 40 --remove-bg
+```
+
+`--no-grid` draws beads flush. `--bead-size` sets the peg diameter in pixels. By default the PNG width follows the source image, capped at 1000 pixels, and each peg is at least 4 pixels.

fusebead-0.1.0/README.md

@@ -0,0 +1,55 @@
+# fusebead
+
+Turn a photo into a fuse-bead pattern: a pegboard grid, the nearest bead color, a printable PNG, and a color-count chart.
+
+Color matching follows the [ROCKIMG fuse-bead pattern maker](https://www.rockimg.com/perler-bead-pattern-maker.html): sRGB to CIE Lab, CIE76 distance, the same brightness and contrast sliders, and the same three palettes.
+
+Perler, Hama, and Artkal are trademarks of their owners. This package is not affiliated with those brands. Palette RGB values are the approximations used by the website, not official manufacturer color cards.
+
+## Install
+
+```bash
+pip install fusebead
+```
+
+From a checkout of this repository:
+
+```bash
+pip install -e packages/fusebead
+```
+
+Requires Python 3.9+ and Pillow.
+
+## Library
+
+```python
+from fusebead import Pattern
+
+pattern = Pattern.from_image(
+    "cat.png",
+    palette="perler",      # perler, hama, or artkal
+    grid_width=50,         # max pegs on the long side; aspect ratio is kept
+    grid_height=50,
+    brightness=0,          # website slider range is -80..80
+    contrast=0,
+    remove_background=True,
+)
+pattern.save_png("pattern.png")
+pattern.save_csv("beads.csv")
+
+pattern.width, pattern.height
+pattern.total
+pattern.cell(0, 0)          # BeadColor or None when the background was removed
+pattern.entries[0].color.code
+pattern.entries[0].count
+```
+
+Phone photos are rotated with EXIF orientation before sampling. The website canvas does not do that step.
+
+## Command line
+
+```bash
+fusebead cat.png -o pattern.png --csv beads.csv --palette hama --width 40 --height 40 --remove-bg
+```
+
+`--no-grid` draws beads flush. `--bead-size` sets the peg diameter in pixels. By default the PNG width follows the source image, capped at 1000 pixels, and each peg is at least 4 pixels.

fusebead-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "fusebead"
+version = "0.1.0"
+description = "Turn a photo into a fuse-bead pattern, with palette matching, bead counts, and a printable PNG."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "ROCKIMG", email = "admin@rockimg.com" }]
+keywords = ["fuse-bead", "bead-pattern", "pixel-art", "image"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Multimedia :: Graphics",
+]
+dependencies = ["pillow>=10"]
+
+[project.urls]
+Homepage = "https://www.rockimg.com/perler-bead-pattern-maker.html"
+Documentation = "https://www.rockimg.com/perler-bead-pattern-maker.html"
+
+[project.scripts]
+fusebead = "fusebead.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]

fusebead-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

fusebead-0.1.0/src/fusebead/__init__.py

@@ -0,0 +1,19 @@
+"""Fuse-bead patterns from images.
+
+The matching rules follow the ROCKIMG pattern maker:
+https://www.rockimg.com/perler-bead-pattern-maker.html
+"""
+
+from fusebead.palettes import PALETTES, BeadColor, Palette, get_palette
+from fusebead.pattern import ColorCount, Pattern, fit_grid
+
+__version__ = "0.1.0"
+__all__ = [
+    "BeadColor",
+    "ColorCount",
+    "PALETTES",
+    "Palette",
+    "Pattern",
+    "fit_grid",
+    "get_palette",
+]

fusebead-0.1.0/src/fusebead/__main__.py

@@ -0,0 +1,4 @@
+from fusebead.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

fusebead-0.1.0/src/fusebead/cli.py

@@ -0,0 +1,72 @@
+"""Command line for fuse-bead patterns."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from fusebead.palettes import PALETTES
+from fusebead.pattern import Pattern
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="fusebead",
+        description="Turn a photo into a fuse-bead pattern and a color-count chart.",
+    )
+    parser.add_argument("image", help="Input image path")
+    parser.add_argument("-o", "--output", required=True, help="Output PNG path")
+    parser.add_argument("--csv", help="Also write a color-count CSV")
+    parser.add_argument(
+        "--palette",
+        default="perler",
+        choices=sorted(PALETTES),
+        help="Bead palette (default: perler)",
+    )
+    parser.add_argument("--width", type=int, default=50, help="Max grid width (default: 50)")
+    parser.add_argument("--height", type=int, default=50, help="Max grid height (default: 50)")
+    parser.add_argument("--brightness", type=int, default=0, help="Brightness offset, site range -80 to 80")
+    parser.add_argument("--contrast", type=int, default=0, help="Contrast offset, site range -80 to 80")
+    parser.add_argument("--remove-bg", action="store_true", help="Drop near-white and transparent cells")
+    parser.add_argument(
+        "--bg-threshold",
+        type=int,
+        default=40,
+        help="How neutral a near-white pixel must be to count as background (default: 40)",
+    )
+    parser.add_argument("--no-grid", action="store_true", help="Draw beads without the 1px gap")
+    parser.add_argument("--bead-size", type=int, help="Bead diameter in pixels (default: fit source width)")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    try:
+        pattern = Pattern.from_image(
+            args.image,
+            palette=args.palette,
+            grid_width=args.width,
+            grid_height=args.height,
+            brightness=args.brightness,
+            contrast=args.contrast,
+            remove_background=args.remove_bg,
+            background_threshold=args.bg_threshold,
+        )
+        pattern.save_png(args.output, show_grid=not args.no_grid, bead_size=args.bead_size)
+        if args.csv:
+            pattern.save_csv(args.csv)
+    except (OSError, ValueError) as exc:
+        print(f"fusebead: {exc}", file=sys.stderr)
+        return 1
+
+    print(f"grid: {pattern.width} x {pattern.height}")
+    print(f"beads: {pattern.total}")
+    print(f"colors: {len(pattern.entries)}")
+    for entry in pattern.entries[:8]:
+        pct = entry.percent(pattern.total)
+        print(f"  {entry.color.code} {entry.color.name}: {entry.count} ({pct:.1f}%)")
+    print(f"png: {args.output}")
+    if args.csv:
+        print(f"csv: {args.csv}")
+    return 0

fusebead-0.1.0/src/fusebead/color.py

@@ -0,0 +1,93 @@
+"""Color conversion and nearest-bead matching.
+
+The formulas match the ROCKIMG fuse-bead tool: sRGB to CIE Lab, then CIE76
+distance. Ties keep the earlier palette color.
+"""
+
+from __future__ import annotations
+
+import math
+from functools import lru_cache
+from typing import Sequence
+
+from fusebead.palettes import BeadColor, Palette
+
+
+def js_round(value: float) -> int:
+    """Round half toward +infinity, matching JavaScript Math.round."""
+    return math.floor(value + 0.5)
+
+
+def clamp(value: int, low: int, high: int) -> int:
+    return low if value < low else high if value > high else value
+
+
+def srgb_to_linear(channel: float) -> float:
+    channel /= 255.0
+    if channel <= 0.04045:
+        return channel / 12.92
+    return ((channel + 0.055) / 1.055) ** 2.4
+
+
+def rgb_to_lab(r: float, g: float, b: float) -> tuple[float, float, float]:
+    rl = srgb_to_linear(r)
+    gl = srgb_to_linear(g)
+    bl = srgb_to_linear(b)
+    x = (rl * 0.4124564 + gl * 0.3575761 + bl * 0.1804375) / 0.95047
+    y = rl * 0.2126729 + gl * 0.7151522 + bl * 0.0721750
+    z = (rl * 0.0193339 + gl * 0.1191920 + bl * 0.9503041) / 1.08883
+
+    def f(t: float) -> float:
+        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 delta_e(lab1: Sequence[float], lab2: Sequence[float]) -> float:
+    d_l = lab1[0] - lab2[0]
+    d_a = lab1[1] - lab2[1]
+    d_b = lab1[2] - lab2[2]
+    return math.sqrt(d_l * d_l + d_a * d_a + d_b * d_b)
+
+
+def adjust_rgb(
+    r: int, g: int, b: int, brightness: int, contrast: int
+) -> tuple[int, int, int]:
+    """Match the site slider: contrast around 128, then brightness offset."""
+    if contrast >= 259:
+        raise ValueError("contrast must be less than 259")
+    factor = (259 * (contrast + 255)) / (255 * (259 - contrast))
+
+    def channel(value: int) -> int:
+        adjusted = js_round(factor * (value - 128) + 128 + brightness)
+        return clamp(adjusted, 0, 255)
+
+    return channel(r), channel(g), channel(b)
+
+
+def is_near_white(r: int, g: int, b: int, threshold: int) -> bool:
+    peak = r if r >= g and r >= b else g if g >= b else b
+    floor = r if r <= g and r <= b else g if g <= b else b
+    return peak > 240 and (peak - floor) < threshold
+
+
+@lru_cache(maxsize=8)
+def palette_entries(
+    palette: Palette,
+) -> tuple[tuple[BeadColor, tuple[float, float, float]], ...]:
+    return tuple((color, rgb_to_lab(color.r, color.g, color.b)) for color in palette.colors)
+
+
+def nearest_color(r: int, g: int, b: int, palette: Palette) -> BeadColor:
+    target = rgb_to_lab(r, g, b)
+    best: BeadColor | None = None
+    best_dist = math.inf
+    for color, lab in palette_entries(palette):
+        dist = delta_e(target, lab)
+        if dist < best_dist:
+            best_dist = dist
+            best = color
+    if best is None:
+        raise ValueError("palette is empty")
+    return best

fusebead-0.1.0/src/fusebead/palettes.py

@@ -0,0 +1,135 @@
+"""Approximate fuse-bead palettes used by the ROCKIMG pattern tool.
+
+Perler, Hama, and Artkal are trademarks of their owners. This package is not
+affiliated with those brands. The RGB values are the approximations shipped
+with the website tool, not official manufacturer color cards.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class BeadColor:
+    code: str
+    name: str
+    r: int
+    g: int
+    b: int
+
+    @property
+    def rgb(self) -> tuple[int, int, int]:
+        return self.r, self.g, self.b
+
+
+@dataclass(frozen=True)
+class Palette:
+    key: str
+    colors: tuple[BeadColor, ...]
+
+    def by_code(self) -> dict[str, BeadColor]:
+        return {color.code: color for color in self.colors}
+
+
+def _palette(key: str, rows: list[tuple[str, str, int, int, int]]) -> Palette:
+    colors = tuple(BeadColor(code, name, r, g, b) for code, name, r, g, b in rows)
+    return Palette(key, colors)
+
+
+PALETTES: dict[str, Palette] = {
+    "perler": _palette(
+        "perler",
+        [
+            ("80-19002", "White", 255, 255, 255),
+            ("80-19001", "Black", 28, 28, 28),
+            ("80-19005", "Red", 227, 0, 15),
+            ("80-19003", "Yellow", 255, 230, 0),
+            ("80-19004", "Orange", 255, 109, 0),
+            ("80-19017", "Blue", 0, 102, 179),
+            ("80-19010", "Green", 0, 166, 81),
+            ("80-19007", "Purple", 155, 89, 182),
+            ("80-19019", "Pink", 255, 105, 180),
+            ("80-19012", "Brown", 139, 69, 19),
+            ("80-19018", "Gray", 128, 128, 128),
+            ("80-19022", "Light Gray", 192, 192, 192),
+            ("80-19023", "Dark Blue", 0, 51, 102),
+            ("80-19024", "Light Blue", 135, 206, 235),
+            ("80-19025", "Tan", 210, 180, 140),
+            ("80-19026", "Cream", 255, 253, 208),
+            ("80-19027", "Peach", 255, 218, 185),
+            ("80-19028", "Coral", 255, 127, 80),
+            ("80-19029", "Magenta", 255, 0, 255),
+            ("80-19030", "Lime", 50, 205, 50),
+            ("80-19031", "Teal", 0, 128, 128),
+            ("80-19032", "Navy", 0, 0, 128),
+            ("80-19033", "Gold", 255, 215, 0),
+            ("80-19034", "Sand", 194, 178, 128),
+            ("80-19035", "Rust", 183, 65, 14),
+            ("80-19036", "Wine", 114, 47, 55),
+            ("80-19037", "Sky", 135, 206, 250),
+            ("80-19038", "Mint", 152, 255, 152),
+            ("80-19039", "Lavender", 230, 230, 250),
+            ("80-19040", "Beige", 245, 245, 220),
+        ],
+    ),
+    "hama": _palette(
+        "hama",
+        [
+            ("H01", "White", 255, 255, 255),
+            ("H02", "Black", 0, 0, 0),
+            ("H03", "Red", 237, 28, 36),
+            ("H04", "Blue", 0, 102, 179),
+            ("H05", "Green", 0, 166, 81),
+            ("H06", "Yellow", 255, 242, 0),
+            ("H07", "Orange", 255, 127, 39),
+            ("H08", "Brown", 139, 69, 19),
+            ("H09", "Pink", 255, 174, 201),
+            ("H10", "Purple", 128, 0, 128),
+            ("H11", "Light Blue", 135, 206, 235),
+            ("H12", "Light Green", 152, 255, 152),
+            ("H13", "Gray", 128, 128, 128),
+            ("H14", "Light Gray", 192, 192, 192),
+            ("H15", "Tan", 210, 180, 140),
+            ("H16", "Cream", 255, 253, 208),
+            ("H17", "Peach", 255, 218, 185),
+            ("H18", "Coral", 255, 127, 80),
+            ("H19", "Teal", 0, 128, 128),
+            ("H20", "Navy", 0, 0, 128),
+        ],
+    ),
+    "artkal": _palette(
+        "artkal",
+        [
+            ("A01", "White", 255, 255, 255),
+            ("A02", "Black", 30, 30, 30),
+            ("A03", "Red", 230, 0, 18),
+            ("A04", "Blue", 0, 100, 175),
+            ("A05", "Green", 0, 160, 80),
+            ("A06", "Yellow", 255, 228, 0),
+            ("A07", "Orange", 255, 110, 0),
+            ("A08", "Purple", 150, 85, 180),
+            ("A09", "Pink", 255, 100, 175),
+            ("A10", "Brown", 135, 65, 20),
+            ("A11", "Gray", 130, 130, 130),
+            ("A12", "Light Gray", 195, 195, 195),
+            ("A13", "Sky Blue", 130, 200, 240),
+            ("A14", "Mint", 150, 250, 150),
+            ("A15", "Peach", 255, 215, 180),
+            ("A16", "Tan", 205, 175, 135),
+            ("A17", "Cream", 255, 250, 205),
+            ("A18", "Teal", 0, 125, 125),
+            ("A19", "Navy", 0, 0, 120),
+            ("A20", "Gold", 255, 210, 0),
+        ],
+    ),
+}
+
+
+def get_palette(key: str) -> Palette:
+    name = key.strip().lower()
+    try:
+        return PALETTES[name]
+    except KeyError as exc:
+        choices = ", ".join(PALETTES)
+        raise ValueError(f"Unknown palette {key!r}. Choose from: {choices}.") from exc

fusebead-0.1.0/src/fusebead/pattern.py

@@ -0,0 +1,187 @@
+"""Sample an image into a fuse-bead grid."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import BinaryIO, Union
+
+from PIL import Image, ImageOps
+
+from fusebead.color import adjust_rgb, is_near_white, js_round, nearest_color
+from fusebead.palettes import BeadColor, Palette, get_palette
+
+ImageSource = Union[str, Path, BinaryIO, Image.Image]
+
+
+def fit_grid(
+    image_width: int, image_height: int, grid_width: int, grid_height: int
+) -> tuple[int, int]:
+    """Fit a grid inside the requested max width and height, keeping aspect.
+
+    This follows the website: the longer side uses the requested size, and the
+    other side shrinks. Rounding matches JavaScript Math.round.
+    """
+    if image_width < 1 or image_height < 1:
+        raise ValueError("image width and height must be at least 1")
+    if grid_width < 1 or grid_height < 1:
+        raise ValueError("grid width and height must be at least 1")
+
+    aspect = image_width / image_height
+    if aspect >= 1:
+        cells_w = grid_width
+        cells_h = max(1, js_round(grid_width / aspect))
+        if cells_h > grid_height:
+            cells_h = grid_height
+            cells_w = max(1, js_round(grid_height * aspect))
+    else:
+        cells_h = grid_height
+        cells_w = max(1, js_round(grid_height * aspect))
+        if cells_w > grid_width:
+            cells_w = grid_width
+            cells_h = max(1, js_round(grid_width / aspect))
+    return cells_w, cells_h
+
+
+@dataclass(frozen=True)
+class ColorCount:
+    color: BeadColor
+    count: int
+
+    def percent(self, total: int) -> float:
+        if total <= 0:
+            return 0.0
+        return (self.count / total) * 100
+
+
+@dataclass
+class Pattern:
+    """A bead grid. Empty cells are None when the background was removed."""
+
+    grid: list[list[BeadColor | None]]
+    palette: Palette
+    source_width: int
+    _order: tuple[str, ...]
+
+    @property
+    def width(self) -> int:
+        return len(self.grid[0]) if self.grid else 0
+
+    @property
+    def height(self) -> int:
+        return len(self.grid)
+
+    @property
+    def counts(self) -> dict[str, int]:
+        found: dict[str, int] = {}
+        for row in self.grid:
+            for cell in row:
+                if cell is None:
+                    continue
+                found[cell.code] = found.get(cell.code, 0) + 1
+        return found
+
+    @property
+    def total(self) -> int:
+        return sum(self.counts.values())
+
+    @property
+    def entries(self) -> list[ColorCount]:
+        """Counts sorted by quantity, then by the order colors first appeared."""
+        counts = self.counts
+        rank = {code: index for index, code in enumerate(self._order)}
+        by_code = self.palette.by_code()
+        items = [
+            ColorCount(by_code[code], count)
+            for code, count in counts.items()
+            if code in by_code
+        ]
+        items.sort(key=lambda item: (-item.count, rank.get(item.color.code, 0)))
+        return items
+
+    def cell(self, x: int, y: int) -> BeadColor | None:
+        return self.grid[y][x]
+
+    def render(self, show_grid: bool = True, bead_size: int | None = None) -> Image.Image:
+        from fusebead.render import render_pattern
+
+        return render_pattern(self, show_grid=show_grid, bead_size=bead_size)
+
+    def save_png(
+        self,
+        path: str | Path,
+        show_grid: bool = True,
+        bead_size: int | None = None,
+    ) -> None:
+        self.render(show_grid=show_grid, bead_size=bead_size).save(path, format="PNG")
+
+    def to_csv(self) -> str:
+        rows = [["Code", "Color", "Count", "%"]]
+        total = self.total
+        for entry in self.entries:
+            pct = f"{entry.percent(total):.1f}%"
+            rows.append([entry.color.code, entry.color.name, str(entry.count), pct])
+        rows.append([])
+        rows.append(["Total beads", str(total), "", ""])
+        lines = [",".join(_csv_cell(cell) for cell in row) for row in rows]
+        return "\ufeff" + "\r\n".join(lines)
+
+    def save_csv(self, path: str | Path) -> None:
+        Path(path).write_text(self.to_csv(), encoding="utf-8")
+
+    @classmethod
+    def from_image(
+        cls,
+        image: ImageSource,
+        palette: str | Palette = "perler",
+        grid_width: int = 50,
+        grid_height: int = 50,
+        brightness: int = 0,
+        contrast: int = 0,
+        remove_background: bool = False,
+        background_threshold: int = 40,
+    ) -> Pattern:
+        if background_threshold < 0:
+            raise ValueError("background_threshold must be 0 or greater")
+        chosen = palette if isinstance(palette, Palette) else get_palette(palette)
+        opened, close_after = _open_image(image)
+        try:
+            rgba = ImageOps.exif_transpose(opened).convert("RGBA")
+            cells_w, cells_h = fit_grid(rgba.width, rgba.height, grid_width, grid_height)
+            sampled = rgba.resize((cells_w, cells_h), Image.Resampling.BILINEAR)
+            pixels = sampled.load()
+            grid: list[list[BeadColor | None]] = []
+            order: list[str] = []
+            seen: set[str] = set()
+            for y in range(cells_h):
+                row: list[BeadColor | None] = []
+                for x in range(cells_w):
+                    r, g, b, a = pixels[x, y]
+                    r, g, b = adjust_rgb(r, g, b, brightness, contrast)
+                    if remove_background and (
+                        a < 128 or is_near_white(r, g, b, background_threshold)
+                    ):
+                        row.append(None)
+                        continue
+                    color = nearest_color(r, g, b, chosen)
+                    if color.code not in seen:
+                        seen.add(color.code)
+                        order.append(color.code)
+                    row.append(color)
+                grid.append(row)
+            return cls(grid, chosen, rgba.width, tuple(order))
+        finally:
+            if close_after:
+                opened.close()
+
+
+def _csv_cell(value: str) -> str:
+    if any(ch in value for ch in '",\n\r'):
+        return '"' + value.replace('"', '""') + '"'
+    return value
+
+
+def _open_image(image: ImageSource) -> tuple[Image.Image, bool]:
+    if isinstance(image, Image.Image):
+        return image, False
+    return Image.open(image), True

fusebead-0.1.0/src/fusebead/render.py

@@ -0,0 +1,138 @@
+"""Draw a bead pattern the same way the website canvas does."""
+
+from __future__ import annotations
+
+import math
+from functools import lru_cache
+
+from PIL import Image
+
+from fusebead.color import clamp, js_round
+from fusebead.pattern import Pattern
+
+
+def bead_pixel_size(source_width: int, cells_w: int, show_grid: bool) -> tuple[int, int]:
+    """Return (bead size, gap) so the PNG stays near the source width, max 1000px."""
+    gap = 1 if show_grid else 0
+    target_width = min(1000, max(1, source_width))
+    bead_size = js_round((target_width - gap * (cells_w + 1)) / cells_w)
+    if bead_size < 4:
+        bead_size = 4
+    return bead_size, gap
+
+
+def render_pattern(
+    pattern: Pattern, show_grid: bool = True, bead_size: int | None = None
+) -> Image.Image:
+    if pattern.width < 1 or pattern.height < 1:
+        raise ValueError("pattern grid is empty")
+    if bead_size is None:
+        bead_size, gap = bead_pixel_size(pattern.source_width, pattern.width, show_grid)
+    else:
+        if bead_size < 1:
+            raise ValueError("bead_size must be at least 1")
+        gap = 1 if show_grid else 0
+    cell = bead_size + gap
+    canvas = Image.new(
+        "RGB",
+        (pattern.width * cell + gap, pattern.height * cell + gap),
+        (255, 255, 255),
+    )
+    sprites: dict[str, Image.Image] = {}
+    for y, row in enumerate(pattern.grid):
+        for x, color in enumerate(row):
+            if color is None:
+                continue
+            sprite = sprites.get(color.code)
+            if sprite is None:
+                sprite = _bead_sprite(color.r, color.g, color.b, bead_size)
+                sprites[color.code] = sprite
+            canvas.paste(
+                sprite,
+                (gap + x * cell, gap + y * cell),
+                sprite,
+            )
+    return canvas
+
+
+@lru_cache(maxsize=128)
+def _bead_sprite(r: int, g: int, b: int, bead_size: int) -> Image.Image:
+    """Radial highlight matching canvas createRadialGradient, plus a soft edge."""
+    image = Image.new("RGBA", (bead_size, bead_size), (0, 0, 0, 0))
+    pixels = image.load()
+    radius = bead_size / 2 - 0.5
+    cx = bead_size / 2
+    cy = bead_size / 2
+    x0 = cx - radius * 0.25
+    y0 = cy - radius * 0.25
+    light = (clamp(r + 18, 0, 255), clamp(g + 18, 0, 255), clamp(b + 18, 0, 255))
+    base = (r, g, b)
+    dark = (clamp(r - 22, 0, 255), clamp(g - 22, 0, 255), clamp(b - 22, 0, 255))
+    for py in range(bead_size):
+        for px in range(bead_size):
+            sx = px + 0.5
+            sy = py + 0.5
+            dist = math.hypot(sx - cx, sy - cy)
+            coverage = radius + 0.5 - dist
+            if coverage <= 0:
+                continue
+            alpha = 255 if coverage >= 1 else int(coverage * 255)
+            t = _radial_t(sx, sy, x0, y0, cx, cy, radius)
+            if t < 0:
+                t = 0.0
+            elif t > 1:
+                t = 1.0
+            rgb = _shade(t, light, base, dark)
+            edge = abs(dist - radius)
+            if edge < 0.5:
+                ink = (1 - edge / 0.5) * 0.08
+                rgb = tuple(int(js_round(channel * (1 - ink))) for channel in rgb)
+            pixels[px, py] = (rgb[0], rgb[1], rgb[2], alpha)
+    return image
+
+
+def _shade(
+    t: float,
+    light: tuple[int, int, int],
+    base: tuple[int, int, int],
+    dark: tuple[int, int, int],
+) -> tuple[int, int, int]:
+    if t <= 0.55:
+        return _lerp(light, base, 0 if t <= 0 else t / 0.55)
+    return _lerp(base, dark, (t - 0.55) / 0.45)
+
+
+def _lerp(
+    a: tuple[int, int, int], b: tuple[int, int, int], t: float
+) -> tuple[int, int, int]:
+    return tuple(int(js_round(a[i] + (b[i] - a[i]) * t)) for i in range(3))
+
+
+def _radial_t(
+    px: float, py: float, x0: float, y0: float, x1: float, y1: float, r1: float
+) -> float:
+    """Offset of a canvas radial gradient whose start radius is 0."""
+    dx = x1 - x0
+    dy = y1 - y0
+    vx = px - x0
+    vy = py - y0
+    a = dx * dx + dy * dy - r1 * r1
+    b = -2 * (vx * dx + vy * dy)
+    c = vx * vx + vy * vy
+    if abs(a) < 1e-8:
+        if abs(b) < 1e-8:
+            return 0.0
+        return -c / b
+    disc = b * b - 4 * a * c
+    if disc < 0:
+        disc = 0.0
+    root = math.sqrt(disc)
+    t1 = (-b + root) / (2 * a)
+    t2 = (-b - root) / (2 * a)
+    inside = [t for t in (t1, t2) if 0 <= t <= 1]
+    if inside:
+        return min(inside)
+    positive = [t for t in (t1, t2) if t >= 0]
+    if positive:
+        return min(positive)
+    return min(t1, t2)

fusebead-0.1.0/src/fusebead.egg-info/PKG-INFO

@@ -0,0 +1,80 @@
+Metadata-Version: 2.4
+Name: fusebead
+Version: 0.1.0
+Summary: Turn a photo into a fuse-bead pattern, with palette matching, bead counts, and a printable PNG.
+Author-email: ROCKIMG <admin@rockimg.com>
+License-Expression: MIT
+Project-URL: Homepage, https://www.rockimg.com/perler-bead-pattern-maker.html
+Project-URL: Documentation, https://www.rockimg.com/perler-bead-pattern-maker.html
+Keywords: fuse-bead,bead-pattern,pixel-art,image
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Multimedia :: Graphics
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pillow>=10
+Dynamic: license-file
+
+# fusebead
+
+Turn a photo into a fuse-bead pattern: a pegboard grid, the nearest bead color, a printable PNG, and a color-count chart.
+
+Color matching follows the [ROCKIMG fuse-bead pattern maker](https://www.rockimg.com/perler-bead-pattern-maker.html): sRGB to CIE Lab, CIE76 distance, the same brightness and contrast sliders, and the same three palettes.
+
+Perler, Hama, and Artkal are trademarks of their owners. This package is not affiliated with those brands. Palette RGB values are the approximations used by the website, not official manufacturer color cards.
+
+## Install
+
+```bash
+pip install fusebead
+```
+
+From a checkout of this repository:
+
+```bash
+pip install -e packages/fusebead
+```
+
+Requires Python 3.9+ and Pillow.
+
+## Library
+
+```python
+from fusebead import Pattern
+
+pattern = Pattern.from_image(
+    "cat.png",
+    palette="perler",      # perler, hama, or artkal
+    grid_width=50,         # max pegs on the long side; aspect ratio is kept
+    grid_height=50,
+    brightness=0,          # website slider range is -80..80
+    contrast=0,
+    remove_background=True,
+)
+pattern.save_png("pattern.png")
+pattern.save_csv("beads.csv")
+
+pattern.width, pattern.height
+pattern.total
+pattern.cell(0, 0)          # BeadColor or None when the background was removed
+pattern.entries[0].color.code
+pattern.entries[0].count
+```
+
+Phone photos are rotated with EXIF orientation before sampling. The website canvas does not do that step.
+
+## Command line
+
+```bash
+fusebead cat.png -o pattern.png --csv beads.csv --palette hama --width 40 --height 40 --remove-bg
+```
+
+`--no-grid` draws beads flush. `--bead-size` sets the peg diameter in pixels. By default the PNG width follows the source image, capped at 1000 pixels, and each peg is at least 4 pixels.

fusebead-0.1.0/src/fusebead.egg-info/SOURCES.txt

@@ -0,0 +1,17 @@
+LICENSE
+README.md
+pyproject.toml
+src/fusebead/__init__.py
+src/fusebead/__main__.py
+src/fusebead/cli.py
+src/fusebead/color.py
+src/fusebead/palettes.py
+src/fusebead/pattern.py
+src/fusebead/render.py
+src/fusebead.egg-info/PKG-INFO
+src/fusebead.egg-info/SOURCES.txt
+src/fusebead.egg-info/dependency_links.txt
+src/fusebead.egg-info/entry_points.txt
+src/fusebead.egg-info/requires.txt
+src/fusebead.egg-info/top_level.txt
+tests/test_pattern.py

fusebead-0.1.0/src/fusebead.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

fusebead-0.1.0/src/fusebead.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+fusebead = fusebead.cli:main

fusebead-0.1.0/src/fusebead.egg-info/requires.txt

@@ -0,0 +1 @@
+pillow>=10

fusebead-0.1.0/src/fusebead.egg-info/top_level.txt

@@ -0,0 +1 @@
+fusebead

fusebead-0.1.0/tests/test_pattern.py

@@ -0,0 +1,113 @@
+"""Tests for grid fitting, palette matching, counts, and PNG output."""
+
+import tempfile
+import unittest
+from pathlib import Path
+
+from PIL import Image
+
+from fusebead import Pattern, fit_grid, get_palette
+from fusebead.cli import main
+from fusebead.color import adjust_rgb, js_round, nearest_color
+
+
+class RoundingTests(unittest.TestCase):
+    def test_js_round_matches_math_round(self):
+        self.assertEqual(js_round(12.5), 13)
+        self.assertEqual(js_round(-1.5), -1)
+        self.assertEqual(js_round(1.2), 1)
+
+
+class GridTests(unittest.TestCase):
+    def test_square_uses_both_limits(self):
+        self.assertEqual(fit_grid(100, 100, 50, 50), (50, 50))
+
+    def test_landscape_shrinks_height(self):
+        self.assertEqual(fit_grid(40, 10, 50, 50), (50, 13))
+
+    def test_portrait_shrinks_width(self):
+        self.assertEqual(fit_grid(10, 40, 50, 50), (13, 50))
+
+    def test_second_pass_when_height_exceeds_limit(self):
+        self.assertEqual(fit_grid(100, 80, 10, 5), (6, 5))
+
+
+class MatchTests(unittest.TestCase):
+    def test_exact_red_stays_red(self):
+        palette = get_palette("perler")
+        color = nearest_color(227, 0, 15, palette)
+        self.assertEqual(color.code, "80-19005")
+
+    def test_white_and_black(self):
+        palette = get_palette("perler")
+        self.assertEqual(nearest_color(255, 255, 255, palette).name, "White")
+        self.assertEqual(nearest_color(0, 0, 0, palette).name, "Black")
+
+    def test_unknown_palette(self):
+        with self.assertRaises(ValueError):
+            get_palette("nope")
+
+    def test_contrast_zero_is_identity(self):
+        self.assertEqual(adjust_rgb(40, 80, 200, 0, 0), (40, 80, 200))
+
+    def test_brightness_shifts(self):
+        self.assertEqual(adjust_rgb(40, 80, 200, 10, 0), (50, 90, 210))
+
+
+class PatternTests(unittest.TestCase):
+    def test_solid_red_fills_grid(self):
+        image = Image.new("RGB", (32, 32), (227, 0, 15))
+        pattern = Pattern.from_image(image, grid_width=8, grid_height=8)
+        self.assertEqual((pattern.width, pattern.height), (8, 8))
+        self.assertEqual(pattern.total, 64)
+        self.assertEqual(pattern.entries[0].color.code, "80-19005")
+        self.assertEqual(pattern.cell(0, 0).name, "Red")
+
+    def test_remove_white_background(self):
+        image = Image.new("RGB", (16, 16), (255, 255, 255))
+        pattern = Pattern.from_image(image, grid_width=4, grid_height=4, remove_background=True)
+        self.assertEqual(pattern.total, 0)
+        self.assertIsNone(pattern.cell(0, 0))
+
+    def test_transparent_pixel_is_removed(self):
+        image = Image.new("RGBA", (8, 8), (227, 0, 15, 0))
+        pattern = Pattern.from_image(image, grid_width=4, grid_height=4, remove_background=True)
+        self.assertEqual(pattern.total, 0)
+
+    def test_csv_and_png(self):
+        image = Image.new("RGB", (20, 10), (0, 0, 128))
+        pattern = Pattern.from_image(image, palette="hama", grid_width=10, grid_height=10)
+        csv = pattern.to_csv()
+        self.assertTrue(csv.startswith("\ufeffCode,Color,Count,%"))
+        self.assertIn("H20,Navy,", csv)
+        self.assertIn("Total beads", csv)
+        with tempfile.TemporaryDirectory() as folder:
+            png_path = Path(folder) / "pattern.png"
+            pattern.save_png(png_path, bead_size=6)
+            with Image.open(png_path) as saved:
+                self.assertEqual(saved.format, "PNG")
+                self.assertGreater(saved.size[0], pattern.width)
+
+    def test_highlight_is_lighter_than_opposite_edge(self):
+        image = Image.new("RGB", (40, 40), (227, 0, 15))
+        pattern = Pattern.from_image(image, grid_width=1, grid_height=1)
+        rendered = pattern.render(show_grid=False, bead_size=21)
+        highlight = rendered.getpixel((6, 6))
+        shade = rendered.getpixel((16, 16))
+        self.assertGreater(sum(highlight), sum(shade))
+
+    def test_cli_writes_files(self):
+        with tempfile.TemporaryDirectory() as folder:
+            root = Path(folder)
+            src = root / "in.png"
+            Image.new("RGB", (12, 12), (255, 230, 0)).save(src)
+            png = root / "out.png"
+            csv = root / "out.csv"
+            code = main([str(src), "-o", str(png), "--csv", str(csv), "--width", "6", "--height", "6"])
+            self.assertEqual(code, 0)
+            self.assertTrue(png.is_file())
+            self.assertIn("Yellow", csv.read_text(encoding="utf-8"))
+
+
+if __name__ == "__main__":
+    unittest.main()