agentbrush 0.1.0__py3-none-any.whl

agentbrush/__init__.py

@@ -0,0 +1,38 @@
+"""AgentBrush — Image editing toolkit for AI agents."""
+
+__version__ = "0.1.0"
+
+from agentbrush.core.result import Result
+from agentbrush.background.ops import remove_background
+from agentbrush.greenscreen.ops import remove_greenscreen
+from agentbrush.border.ops import cleanup_border
+from agentbrush.text.ops import add_text, render_text
+from agentbrush.composite.ops import composite, paste_centered
+from agentbrush.resize.ops import resize_image
+from agentbrush.validate.ops import validate_design, compare_images
+from agentbrush.convert.ops import convert_image
+
+# generate is optional (requires openai package)
+try:
+    from agentbrush.generate.ops import generate_image
+    _has_generate = True
+except ImportError:
+    _has_generate = False
+
+__all__ = [
+    "Result",
+    "remove_background",
+    "remove_greenscreen",
+    "cleanup_border",
+    "add_text",
+    "render_text",
+    "composite",
+    "paste_centered",
+    "resize_image",
+    "validate_design",
+    "compare_images",
+    "convert_image",
+]
+
+if _has_generate:
+    __all__.append("generate_image")

agentbrush/__main__.py

@@ -0,0 +1,4 @@
+"""Allow running agentbrush as `python -m agentbrush`."""
+from agentbrush.cli import main
+
+main()

agentbrush/background/__init__.py

@@ -0,0 +1,3 @@
+from agentbrush.background.ops import remove_background
+
+__all__ = ["remove_background"]

agentbrush/background/cli.py

@@ -0,0 +1,51 @@
+"""CLI for background removal."""
+from __future__ import annotations
+
+import argparse
+import sys
+
+from agentbrush.background.ops import remove_background
+
+
+def add_parser(subparsers):
+    """Register the remove-bg subcommand."""
+    p = subparsers.add_parser(
+        "remove-bg",
+        help="Remove solid-color background via edge-based flood fill",
+    )
+    p.add_argument("input", help="Input image path")
+    p.add_argument("output", help="Output image path")
+    p.add_argument(
+        "--color", default="black",
+        help="Background color: black, white, or R,G,B (default: black)",
+    )
+    p.add_argument(
+        "--threshold", type=int, default=25,
+        help="Color match threshold 0-255 (default: 25)",
+    )
+    p.add_argument(
+        "--smooth", action="store_true",
+        help="Apply 1px edge feathering",
+    )
+    p.add_argument(
+        "--resize",
+        help="Resize output: WxH (e.g. 1664x1664)",
+    )
+    p.set_defaults(func=run)
+
+
+def run(args):
+    resize = None
+    if args.resize:
+        w, h = args.resize.lower().split("x")
+        resize = (int(w), int(h))
+
+    result = remove_background(
+        args.input, args.output,
+        color=args.color,
+        threshold=args.threshold,
+        smooth=args.smooth,
+        resize=resize,
+    )
+    print(result.summary())
+    return 0 if result.success else 1

agentbrush/background/ops.py

@@ -0,0 +1,77 @@
+"""Background removal via edge-based flood fill.
+
+NEVER use threshold-based removal — it destroys internal outlines/details.
+This module starts flood fill from image edges only, preserving artwork.
+"""
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Optional, Tuple, Union
+
+from PIL import Image
+
+from agentbrush.core.alpha import smooth_edges
+from agentbrush.core.color import ColorTuple, parse_color
+from agentbrush.core.flood_fill import flood_fill_from_edges
+from agentbrush.core.result import Result
+
+
+def remove_background(
+    input_path: Union[str, Path],
+    output_path: Union[str, Path],
+    color: str = "black",
+    threshold: int = 25,
+    smooth: bool = False,
+    resize: Optional[Tuple[int, int]] = None,
+) -> Result:
+    """Remove solid-color background using edge-based flood fill.
+
+    Args:
+        input_path: Source image path.
+        output_path: Destination path for processed image.
+        color: Background color name or 'R,G,B' string.
+        threshold: Color match threshold 0-255.
+        smooth: Apply 1px edge feathering for cleaner cutlines.
+        resize: Optional (width, height) to resize output.
+
+    Returns:
+        Result with stats about the operation.
+    """
+    input_path = Path(input_path)
+    output_path = Path(output_path)
+
+    if not input_path.exists():
+        return Result(errors=[f"File not found: {input_path}"])
+
+    target_color = parse_color(color)
+    img = Image.open(input_path).convert("RGBA")
+
+    # Check if already transparent (no-op)
+    data = list(img.get_flattened_data())
+    initial_transparent = sum(1 for p in data if p[3] == 0)
+    if initial_transparent == len(data):
+        result = Result.from_image(img, output_path)
+        result.warnings.append("Image is already fully transparent")
+        os.makedirs(output_path.parent, exist_ok=True)
+        img.save(output_path, "PNG")
+        return result
+
+    img, removed = flood_fill_from_edges(
+        img, target_color=target_color, threshold=threshold
+    )
+
+    if smooth:
+        img = smooth_edges(img, radius=1)
+
+    if resize:
+        img = img.resize(resize, Image.LANCZOS)
+
+    os.makedirs(output_path.parent, exist_ok=True)
+    img.save(output_path, "PNG")
+
+    result = Result.from_image(img, output_path)
+    result.metadata["pixels_removed"] = removed
+    result.metadata["color"] = color
+    result.metadata["threshold"] = threshold
+    return result

agentbrush/border/__init__.py

@@ -0,0 +1,3 @@
+from agentbrush.border.ops import cleanup_border
+
+__all__ = ["cleanup_border"]

agentbrush/border/cli.py

@@ -0,0 +1,50 @@
+"""CLI for border cleanup."""
+from __future__ import annotations
+
+import argparse
+
+from agentbrush.border.ops import cleanup_border
+
+
+def add_parser(subparsers):
+    """Register the border-cleanup subcommand."""
+    p = subparsers.add_parser(
+        "border-cleanup",
+        help="Remove white sticker border + optional green halo",
+    )
+    p.add_argument("input", help="Input image path")
+    p.add_argument("output", help="Output image path")
+    p.add_argument(
+        "--passes", type=int, default=15,
+        help="White border erosion passes (default: 15)",
+    )
+    p.add_argument(
+        "--threshold", type=int, default=185,
+        help="White pixel threshold (default: 185)",
+    )
+    p.add_argument(
+        "--green-halo-passes", type=int, default=0,
+        help="Green halo erosion passes (default: 0, disabled)",
+    )
+    p.add_argument(
+        "--alpha-smooth", action="store_true",
+        help="Apply Gaussian alpha edge smoothing",
+    )
+    p.add_argument(
+        "--alpha-blur-radius", type=float, default=1.5,
+        help="Alpha blur radius (default: 1.5)",
+    )
+    p.set_defaults(func=run)
+
+
+def run(args):
+    result = cleanup_border(
+        args.input, args.output,
+        passes=args.passes,
+        threshold=args.threshold,
+        green_halo_passes=args.green_halo_passes,
+        alpha_smooth=args.alpha_smooth,
+        alpha_blur_radius=args.alpha_blur_radius,
+    )
+    print(result.summary())
+    return 0 if result.success else 1

agentbrush/border/ops.py

@@ -0,0 +1,150 @@
+"""Border erosion and halo removal for sticker cleanup.
+
+Handles:
+- White sticker border erosion (AI generators add a white outline)
+- Green halo erosion (anti-aliased fringe after green screen removal)
+- Alpha edge smoothing (Gaussian blur on edges, interior preserved)
+"""
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Optional, Union
+
+from PIL import Image
+
+from agentbrush.core.alpha import smooth_alpha_edges
+from agentbrush.core.result import Result
+
+
+def _erode_white_border(
+    img: Image.Image,
+    passes: int = 15,
+    threshold: int = 185,
+) -> tuple:
+    """Iteratively remove light pixels adjacent to transparent (white sticker border).
+
+    Threshold < 170 eats into colored artwork. 185 is the safe default.
+    """
+    w, h = img.size
+    pixels = img.load()
+    total = 0
+
+    for _ in range(passes):
+        to_remove = []
+        for y in range(h):
+            for x in range(w):
+                r, g, b, a = pixels[x, y]
+                if a == 0:
+                    continue
+                if r > threshold and g > threshold and b > threshold:
+                    adj_transparent = False
+                    for dx, dy in [(-1, 0), (1, 0), (0, -1), (0, 1)]:
+                        nx, ny = x + dx, y + dy
+                        if 0 <= nx < w and 0 <= ny < h:
+                            if pixels[nx, ny][3] == 0:
+                                adj_transparent = True
+                                break
+                        else:
+                            adj_transparent = True
+                            break
+                    if adj_transparent:
+                        to_remove.append((x, y))
+        for x, y in to_remove:
+            pixels[x, y] = (0, 0, 0, 0)
+        total += len(to_remove)
+        if len(to_remove) == 0:
+            break
+
+    return img, total
+
+
+def _erode_green_halo(
+    img: Image.Image,
+    passes: int = 20,
+) -> tuple:
+    """Remove green-tinted pixels adjacent to transparent (anti-alias fringe)."""
+    w, h = img.size
+    pixels = img.load()
+    total = 0
+
+    for _ in range(passes):
+        to_remove = []
+        for y in range(h):
+            for x in range(w):
+                r, g, b, a = pixels[x, y]
+                if a == 0:
+                    continue
+                is_greenish = g > 80 and g > r * 1.2 and g > b * 1.2
+                if not is_greenish:
+                    continue
+                adj_transparent = False
+                for dx, dy in [(-1, 0), (1, 0), (0, -1), (0, 1)]:
+                    nx, ny = x + dx, y + dy
+                    if 0 <= nx < w and 0 <= ny < h:
+                        if pixels[nx, ny][3] == 0:
+                            adj_transparent = True
+                            break
+                    else:
+                        adj_transparent = True
+                        break
+                if adj_transparent:
+                    to_remove.append((x, y))
+        for x, y in to_remove:
+            pixels[x, y] = (0, 0, 0, 0)
+        total += len(to_remove)
+        if len(to_remove) == 0:
+            break
+
+    return img, total
+
+
+def cleanup_border(
+    input_path: Union[str, Path],
+    output_path: Union[str, Path],
+    passes: int = 15,
+    threshold: int = 185,
+    green_halo_passes: int = 0,
+    alpha_smooth: bool = False,
+    alpha_blur_radius: float = 1.5,
+) -> Result:
+    """Clean up sticker borders: white border erosion + optional green halo removal.
+
+    Args:
+        input_path: Source image path.
+        output_path: Destination path.
+        passes: Number of white border erosion passes.
+        threshold: White pixel threshold (R,G,B all above this = white).
+        green_halo_passes: Number of green halo erosion passes (0 to skip).
+        alpha_smooth: Apply Gaussian alpha smoothing for die-cut outline.
+        alpha_blur_radius: Blur radius for alpha smoothing.
+
+    Returns:
+        Result with operation stats.
+    """
+    input_path = Path(input_path)
+    output_path = Path(output_path)
+
+    if not input_path.exists():
+        return Result(errors=[f"File not found: {input_path}"])
+
+    img = Image.open(input_path).convert("RGBA")
+    metadata = {}
+
+    img, white_removed = _erode_white_border(img, passes=passes, threshold=threshold)
+    metadata["white_border_removed"] = white_removed
+
+    if green_halo_passes > 0:
+        img, green_removed = _erode_green_halo(img, passes=green_halo_passes)
+        metadata["green_halo_removed"] = green_removed
+
+    if alpha_smooth:
+        img = smooth_alpha_edges(img, blur_radius=alpha_blur_radius)
+        metadata["alpha_smoothed"] = True
+
+    os.makedirs(output_path.parent, exist_ok=True)
+    img.save(output_path, "PNG")
+
+    result = Result.from_image(img, output_path)
+    result.metadata = metadata
+    return result

agentbrush/cli.py

@@ -0,0 +1,65 @@
+"""Top-level CLI dispatcher for agentbrush.
+
+Usage:
+    agentbrush <command> [options]
+
+Commands:
+    remove-bg        Remove solid-color background via edge-based flood fill
+    greenscreen      Remove green screen background (multi-pass pipeline)
+    border-cleanup   Remove white sticker border + optional green halo
+    text             Render text onto an image or new canvas
+    composite        Alpha-composite overlay onto base image
+    resize           Resize image (exact, fit, pad, or scale)
+    validate         Validate design against product specs
+    convert          Convert image format (PNG, JPEG, WEBP, etc.)
+    generate         Generate image from text prompt (OpenAI/Pollinations)
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+
+from agentbrush import __version__
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(
+        prog="agentbrush",
+        description="Image editing toolkit for AI agents",
+    )
+    parser.add_argument(
+        "--version", action="version",
+        version=f"agentbrush {__version__}",
+    )
+
+    subparsers = parser.add_subparsers(dest="command", help="Available commands")
+
+    # Register subcommands
+    from agentbrush.background.cli import add_parser as add_bg
+    from agentbrush.greenscreen.cli import add_parser as add_gs
+    from agentbrush.border.cli import add_parser as add_border
+    from agentbrush.text.cli import add_parser as add_text
+    from agentbrush.composite.cli import add_parser as add_composite
+    from agentbrush.resize.cli import add_parser as add_resize
+    from agentbrush.validate.cli import add_parser as add_validate
+    from agentbrush.convert.cli import add_parser as add_convert
+    from agentbrush.generate.cli import add_parser as add_generate
+
+    add_bg(subparsers)
+    add_gs(subparsers)
+    add_border(subparsers)
+    add_text(subparsers)
+    add_composite(subparsers)
+    add_resize(subparsers)
+    add_validate(subparsers)
+    add_convert(subparsers)
+    add_generate(subparsers)
+
+    args = parser.parse_args(argv)
+
+    if args.command is None:
+        parser.print_help()
+        sys.exit(0)
+
+    exit_code = args.func(args)
+    sys.exit(exit_code or 0)

agentbrush/composite/__init__.py

@@ -0,0 +1,3 @@
+from agentbrush.composite.ops import composite, paste_centered
+
+__all__ = ["composite", "paste_centered"]

agentbrush/composite/cli.py

@@ -0,0 +1,169 @@
+"""CLI for image compositing.
+
+Supports two modes:
+    agentbrush composite <base> <overlay> <output> [--position X,Y] [--opacity N]
+    agentbrush composite paste-centered <output> --overlay <img> --canvas WxH [--fit] [--bg-color R,G,B,A]
+"""
+from __future__ import annotations
+
+import argparse
+
+from agentbrush.composite.ops import composite, paste_centered
+
+
+def add_parser(subparsers):
+    """Register the composite subcommand."""
+    p = subparsers.add_parser(
+        "composite",
+        help="Composite images: overlay onto base, or center on new canvas",
+        usage=(
+            "agentbrush composite <base> <overlay> <output> [options]\n"
+            "       agentbrush composite paste-centered <output> "
+            "--overlay <img> --canvas WxH [--fit]"
+        ),
+    )
+    p.add_argument("rest", nargs=argparse.REMAINDER)
+    p.set_defaults(func=run)
+
+
+def _overlay_parser():
+    """Parser for overlay mode (default)."""
+    p = argparse.ArgumentParser(
+        prog="agentbrush composite",
+        description="Alpha-composite overlay onto base image",
+    )
+    p.add_argument("base", help="Base (background) image path")
+    p.add_argument("overlay", help="Overlay (foreground) image path")
+    p.add_argument("output", help="Output image path")
+    p.add_argument(
+        "--position", default="0,0",
+        help="Position as X,Y (default: 0,0). Use 'center' to auto-center.",
+    )
+    p.add_argument(
+        "--resize-overlay",
+        help="Resize overlay: WxH (e.g. 400x400)",
+    )
+    p.add_argument(
+        "--opacity", type=float, default=1.0,
+        help="Overlay opacity 0.0-1.0 (default: 1.0)",
+    )
+    return p
+
+
+def _paste_centered_parser():
+    """Parser for paste-centered mode."""
+    p = argparse.ArgumentParser(
+        prog="agentbrush composite paste-centered",
+        description="Center image on a new canvas",
+    )
+    p.add_argument("output", help="Output image path")
+    p.add_argument(
+        "--overlay", required=True,
+        help="Image to center on canvas",
+    )
+    p.add_argument(
+        "--canvas", required=True,
+        help="Canvas size as WxH (e.g. 4500x5400)",
+    )
+    p.add_argument(
+        "--bg-color", default="0,0,0,0",
+        help="Background color as R,G,B,A (default: transparent)",
+    )
+    p.add_argument(
+        "--resize-overlay",
+        help="Resize overlay before centering: WxH",
+    )
+    p.add_argument(
+        "--fit", action="store_true",
+        help="Scale overlay to fit canvas while preserving aspect ratio",
+    )
+    return p
+
+
+def _parse_color(s):
+    parts = [int(x) for x in s.split(",")]
+    if len(parts) == 3:
+        parts.append(255)
+    return tuple(parts)
+
+
+def run(args):
+    """Dispatch composite command based on mode."""
+    remaining = args.rest
+
+    # Strip leading '--' if argparse inserted it
+    if remaining and remaining[0] == "--":
+        remaining = remaining[1:]
+
+    if not remaining or remaining[0] in ("-h", "--help"):
+        print(
+            "Usage:\n"
+            "  agentbrush composite <base> <overlay> <output> [--position X,Y]\n"
+            "  agentbrush composite paste-centered <output> "
+            "--overlay <img> --canvas WxH [--fit]\n"
+            "\n"
+            "Modes:\n"
+            "  (default)        Alpha-composite overlay onto base image\n"
+            "  paste-centered   Center image on a new canvas\n"
+            "\n"
+            "Run 'agentbrush composite paste-centered --help' for mode-specific help."
+        )
+        return 0
+
+    if remaining[0] == "paste-centered":
+        return _run_paste_centered(remaining[1:])
+    else:
+        return _run_overlay(remaining)
+
+
+def _run_overlay(argv):
+    """Run overlay composite mode."""
+    parser = _overlay_parser()
+    ov_args = parser.parse_args(argv)
+
+    resize = None
+    if ov_args.resize_overlay:
+        w, h = ov_args.resize_overlay.lower().split("x")
+        resize = (int(w), int(h))
+
+    if ov_args.position == "center":
+        from PIL import Image
+        base = Image.open(ov_args.base)
+        result = paste_centered(
+            base.width, base.height,
+            ov_args.overlay, ov_args.output,
+            resize_overlay=resize,
+        )
+    else:
+        pos = tuple(int(x) for x in ov_args.position.split(","))
+        result = composite(
+            ov_args.base, ov_args.overlay, ov_args.output,
+            position=pos, resize_overlay=resize,
+            opacity=ov_args.opacity,
+        )
+
+    print(result.summary())
+    return 0 if result.success else 1
+
+
+def _run_paste_centered(argv):
+    """Run paste-centered composite mode."""
+    parser = _paste_centered_parser()
+    pc_args = parser.parse_args(argv)
+
+    cw, ch = [int(v) for v in pc_args.canvas.lower().split("x")]
+
+    resize = None
+    if pc_args.resize_overlay:
+        w, h = pc_args.resize_overlay.lower().split("x")
+        resize = (int(w), int(h))
+
+    result = paste_centered(
+        cw, ch, pc_args.overlay, pc_args.output,
+        bg_color=_parse_color(pc_args.bg_color),
+        resize_overlay=resize,
+        fit=pc_args.fit,
+    )
+
+    print(result.summary())
+    return 0 if result.success else 1