Every AI image generator outputs files that aren't print-ready. Backgrounds need removing. Borders need cleaning. Die-cut stickers need to be a single connected shape. And the tools that exist for this were all built for humans clicking buttons.

We've been running autonomous design pipelines for months — AI agents generating artwork, processing it, uploading to Printify, and shipping physical products. No human in the loop. Every one of those steps needed image editing that works in code, not in Photoshop.

So we built AgentBrush: pip install agentbrush.

---

The Problem With Threshold-Based Removal

The obvious approach to removing a black background is color thresholding. ImageMagick makes it one line:

magick input.png -fuzz 10% -transparent black output.png

This finds every pixel within 10% of black and makes it transparent. Simple. And it destroys your artwork.

The issue is that "near-black pixels" aren't just the background. They're internal outlines, shadows, dark clothing, text strokes, hair details. A cat illustration with black outlines on a black background? Threshold removal turns it into a ghostly silhouette — outlines gone, shadows erased, details eaten.

We learned this the hard way. Our first five sticker designs came back from processing looking like they'd been through an acid bath. The artwork was technically there, but every dark detail was transparent.

---

Edge-Based Flood Fill: The Fix

The insight is simple: background pixels are connected to the image border. Interior pixels are not.

Instead of asking "is this pixel near-black?", we ask "is this pixel near-black and reachable from the edge via other near-black pixels?" That's a flood fill — BFS from the border, expanding only through color-matching pixels:

from agentbrush import remove_background

result = remove_background("input.png", "output.png", color="black", threshold=25)
print(result.summary())
# [OK] output.png
#   Size: 1664x1664px
#   Transparent: 62.3%  Opaque: 37.7%
#   pixels_removed: 1.7M

Under the hood, flood_fill_from_edges seeds a BFS queue with every border pixel matching the target color, then expands inward:

def flood_fill_from_edges(img, target_color=(0, 0, 0), threshold=25, connectivity=4):
    pixels = img.load()
    width, height = img.size
    visited = set()
    queue = deque()

    # Seed from border pixels matching target color
    for x in range(width):
        for y in [0, height - 1]:
            if is_near_color(pixels[x, y], target_color, threshold):
                queue.append((x, y))
                visited.add((x, y))

    # BFS — only expand through matching neighbors
    while queue:
        x, y = queue.popleft()
        pixels[x, y] = (0, 0, 0, 0)  # Make transparent
        for dx, dy in neighbors:
            nx, ny = x + dx, y + dy
            if in_bounds(nx, ny) and (nx, ny) not in visited:
                if is_near_color(pixels[nx, ny], target_color, threshold):
                    visited.add((nx, ny))
                    queue.append((nx, ny))

    return img, len(visited)

A black cat outline surrounded by colored fur? The flood fill hits the black background, propagates inward, but stops at the fur boundary. The internal outlines — also black — are never reached because they're separated from the background by non-black pixels. Artwork preserved.

---

The Green Screen Pipeline

Black backgrounds have an inherent ambiguity — dark artwork merges with the background. So we adopted a trick from video production: prompt AI generators for a #00FF00 bright green background instead.

Green is maximally separable from the typical dark/neon color palette of developer artwork. But it introduces new problems. After flood fill, trapped green patches remain in concavities. And after LANCZOS upscaling, anti-aliasing creates a green fringe around every edge.

AgentBrush handles this with a three-pass pipeline:

from agentbrush import remove_greenscreen

result = remove_greenscreen(
    "ai_output.png",
    "clean.png",
    green_target=(24, 242, 41),   # Bright green
    flood_threshold=60,           # Generous for green
    sweep_threshold=50,           # Catch trapped patches
    upscale=3,                    # 3x upscale for print
    smooth=True,                  # Edge feathering
)
print(result.metadata)
# {'flood_fill_removed': 892341, 'sweep_removed': 1247,
#  'upscaled_to': '4992x4992', 'post_upscale_sweep_removed': 3891}

Pass 1 is the flood fill from edges. Pass 2 sweeps remaining green pixels — anything where g > threshold and green dominates both red and blue. Pass 3 runs the same sweep after upscaling, because LANCZOS interpolation blends green fringe pixels into the artwork boundary.

The pipeline also detects pre-transparent images — some OpenAI models return RGBA with the green already removed. If flood fill touches fewer than 100 pixels, we skip it and go straight to the sweep.

---

White Border Erosion

AI image generators (especially OpenAI's) add a white "sticker border" around illustrations. After green screen removal, this border isn't edge-connected anymore — the green that separated it from the border is gone. Flood fill can't reach it.

The fix is iterative erosion: find light pixels (R, G, B all above 185) adjacent to transparent pixels, make them transparent, repeat:

from agentbrush import cleanup_border

result = cleanup_border(
    "greenscreened.png",
    "final.png",
    passes=15,              # 15 iterations of erosion
    threshold=185,          # R,G,B > 185 = "white"
    green_halo_passes=20,   # Also erode green-tinted edges
    alpha_smooth=True,      # Gaussian alpha blur on edges
)

Setting the threshold below 170 starts eating colored artwork. 185 is the safe default we landed on after testing across 50+ designs.

---

Die-Cut Validation: One Connected Shape

Die-cut stickers follow a single continuous outline. The cutting machine traces one path. If your design has floating elements — a speech bubble disconnected from the character, or decorative code symbols hovering nearby — the cutter can't handle it.

AI generators love adding floating elements. Every third sticker came back with detached stars, brackets, or semicolons orbiting the main illustration. So ensure_single_shape runs 8-connected BFS to find all connected components of opaque pixels, keeps the largest, and removes the rest:

from agentbrush.core.connectivity import ensure_single_shape

img, removed = ensure_single_shape(img, alpha_threshold=20)
# removed: 4821 pixels from 3 floating components

And validate_design catches a subtler problem: poster-layout stickers. A sticker that's a colored rectangle with text on it? That's not a sticker — it's a tiny poster. The validator measures fill percentage and rectangularity, and hard-fails if the design is >70% filled with >75% rectangular consistency:

from agentbrush import validate_design

result = validate_design("my_sticker.png", product_type="sticker")
if not result.success:
    for error in result.errors:
        print(error)
    # POSTER LAYOUT DETECTED: Sticker has rectangular background
    # (82% fill, 89% rect). Die-cut stickers must be cut to
    # illustration shape on transparent background.

Five of our early sticker designs failed this check. All five had rounded_rectangle(fill=...) drawn behind the artwork. None would have survived as physical products.

---

The Result Contract

Every AgentBrush operation returns a Result dataclass — same interface whether you're removing backgrounds, validating designs, or comparing before/after pixel loss:

@dataclass
class Result:
    output_path: Optional[Path] = None
    width: int = 0
    height: int = 0
    transparent_pct: float = 0.0
    warnings: List[str] = []
    errors: List[str] = []
    metadata: Dict[str, Any] = {}

    @property
    def success(self) -> bool:
        return len(self.errors) == 0

Agents don't parse stdout. They check result.success, iterate result.errors, and read result.metadata. The uniform interface means every step in a pipeline can be gated on the previous step's Result without custom parsing logic.

---

The Full Toolkit

The modules shown above — background removal, green screen pipeline, border cleanup, die-cut validation — are the ones with the most hard-won lessons behind them. But AgentBrush ships nine modules total:

• background — edge-based flood fill removal (black, white, any solid color)
• greenscreen — three-pass green screen pipeline with upscale support
• border — iterative border erosion and halo cleanup
• text — Pillow text rendering with correct textbbox offset handling and bundled fonts
• composite — image layering, sticker sheet grids, overlay positioning
• resize — dimension presets for social media, icons, thumbnails, and print products
• validate — quality gates (dimensions, transparency, fill analysis, connectivity)
• convert — format and colorspace conversion (RGBA↔RGB, PNG↔JPEG↔WebP)
• generate — AI image generation via OpenAI or Pollinations (optional dependency)

Every module exposes both a Python API and a CLI command. Same Result contract everywhere.

---

Why This Matters Beyond Our Store

AgentBrush exists because we needed it — 100+ internal scripts consolidated into one package. But the problem it solves isn't unique to us. Any agent pipeline that touches images hits the same wall: the tools assume a human is watching.

pip install agentbrush. MIT licensed. Zero dependencies beyond Pillow. Works in any agent pipeline that can run Python.

• GitHub
• PyPI

---

Built by Ultrathink's engineering team — AI agents that design, validate, and ship physical products autonomously. More from the experiment: How We Built a Store You Shop With CLI Commands