product-cutout-normalize：商品图抠图与标准化的 Agent Skill

Thu, 09 Apr 2026 21:43:50 +0800

product-cutout-normalize 是一个给商品图使用的 Agent Skill。

它会把原图处理成统一规格的透明底方图。默认规则是：

1024x1024 画布
透明背景
尽量完整保留主体
竖向主体自动转成横向
主体居中
主体可视宽度统一到 820px

适合电商素材、商品库和详情页图片预处理。

这个 skill 解决什么问题

很多商品图做完基础抠图后，还会有这些问题：

白边或浅灰背景残留
主体横竖方向不一致
画布大小不一致
主体大小忽大忽小
透明区域里有小噪点

这个 skill 会按固定流程处理：

用 Gemini 抠图
清理边缘浅色背景
去掉小碎片噪点
竖图转横图
按目标宽度缩放
放到统一尺寸的透明画布中央

这样导出的图片更整齐，也更适合批量使用。

适用场景

适合下面这些需求：

批量处理商品照片
统一输出透明底 PNG
统一主视觉尺寸
需要稳定、可重复的处理流程

如果你只处理少量图片，或者每张图都要单独调整布局，那它未必适合。

快速开始

最直接的运行方式：

`1`	`& ".\.venv\Scripts\python.exe" ".codex\skills\product-cutout-normalize\scripts\run_pipeline.py" "input_dir" "output_dir" --overwrite`

运行前需要：

GEMINI_API_KEY
google-genai
Pillow

安装依赖：

`1`	`.\.venv\Scripts\python.exe -m pip install google-genai pillow`

设置环境变量：

`1`	`$env:GEMINI_API_KEY="your_api_key"`

输出规则

默认输出：

透明背景 PNG
1024x1024 画布
主体宽度 820px
主体居中
小噪点会被清理

所以它不只是去背脚本，更像一个商品图整理脚本。

主要参数说明

常用参数：

--model 默认 gemini-2.5-flash-image
--canvas-size 输出方形画布尺寸，默认 1024
--target-width 主体可视宽度，默认 820
--min-component-pixels 小于这个像素数的透明碎片会被移除，默认 500
--overwrite 输出文件已存在时直接覆盖

例如：

`1`	`& ".\.venv\Scripts\python.exe" ".codex\skills\product-cutout-normalize\scripts\run_pipeline.py" ".\input" ".\output" --canvas-size 1280 --target-width 960 --overwrite`

处理流程

处理流程很简单：

用 Gemini 抠图
清理边缘浅色背景
去掉小碎片噪点
竖图转横图
按目标宽度缩放
放到统一尺寸的透明画布中央

和普通抠图脚本的区别

和普通去背脚本相比，它还会额外处理这些问题：

主体方向统一
主体尺寸统一
画布尺寸统一
小碎片噪点清理
结果更适合直接放进素材库

SKILL.md 源码

下面保留 SKILL.md 的完整源码，内容不做改动：

---
name: product-cutout-normalize
description: Run a reusable Gemini product-image pipeline that removes backgrounds, preserves the full subject, rotates tall products to a horizontal orientation, centers them on a 1024x1024 transparent canvas, and normalizes the visible subject width to 820px. Use when the user wants a repeatable cutout-and-normalize workflow for product photos or asks to batch-process product images into standardized square PNG assets.
---

# Product Cutout Normalize

Use this skill when product photos need the same deterministic finishing pipeline:

- Gemini cutout from the original photo
- border cleanup to transparent
- preserve the full subject
- rotate to horizontal when the subject is taller than it is wide
- center on a `1024x1024` transparent canvas
- normalize the visible subject width to `820px`

## Quick Start

Run the bundled script:

```powershell
& ".\.venv\Scripts\python.exe" ".codex\skills\product-cutout-normalize\scripts\run_pipeline.py" "input_dir" "output_dir" --overwrite
```

Required environment:

- `GEMINI_API_KEY`
- `google-genai`
- `Pillow`

## Workflow

1. Confirm the request matches this standard pipeline. If the user asks for a different canvas size, subject width, or layout rule, pass explicit flags instead of changing the script.
2. Run the bundled script on the input directory.
3. If a result looks misaligned, inspect the alpha bounding box and small detached artifacts first; this pipeline already removes tiny alpha components by default.
4. Report the exact input and output directories used, plus any non-default flags.

## Script

Primary entry point:

- `scripts/run_pipeline.py`

Key flags:

- `--model`: Gemini image model, default `gemini-2.5-flash-image`
- `--canvas-size`: output square size, default `1024`
- `--target-width`: visible subject width after normalization, default `820`
- `--min-component-pixels`: remove detached alpha specks smaller than this, default `500`
- `--overwrite`: replace existing outputs in the destination directory

## Repo Integration

If the current project already has [`scripts/nano_banana_cutout.py`](/c:/Work/my_shop/scripts/nano_banana_cutout.py), prefer that repo script when the user wants the same pipeline inside this repository. Use the bundled skill script when the task is cross-project reuse or when you want the workflow to stay self-contained inside the skill.

scripts/run_pipeline.py 源码

下面保留 scripts/run_pipeline.py 的完整源码，内容不做改动：

from __future__ import annotations

import argparse
import os
from collections import deque
from pathlib import Path

from PIL import Image

try:
    from google import genai
except ImportError as exc:  # pragma: no cover
    raise SystemExit(
        "Missing dependency: google-genai. Install it with "
        r"'.\.venv\Scripts\python.exe -m pip install google-genai'."
    ) from exc


PROMPT = (
    "Remove the entire background from this product photo and return only the product "
    "on a fully transparent background as a PNG. Keep the full product intact, preserve "
    "thin cable details, clean the inner loops and holes, and do not add any new objects "
    "or shadows."
)
DEFAULT_CANVAS_SIZE = 1024
DEFAULT_TARGET_WIDTH = 820
DEFAULT_MIN_COMPONENT_PIXELS = 500
SUPPORTED_EXTENSIONS = {".jpg", ".jpeg", ".png", ".webp"}


def is_light_background_pixel(r: int, g: int, b: int) -> bool:
    brightness = (r + g + b) / 3
    spread = max(r, g, b) - min(r, g, b)
    return brightness >= 170 and spread <= 35


def to_pil_image(image_obj) -> Image.Image:
    if isinstance(image_obj, Image.Image):
        return image_obj
    pil_image = getattr(image_obj, "_pil_image", None)
    if isinstance(pil_image, Image.Image):
        return pil_image
    as_pil = getattr(image_obj, "pil_image", None)
    if isinstance(as_pil, Image.Image):
        return as_pil
    raise TypeError(f"Unsupported image object type: {type(image_obj)!r}")


def make_transparent_from_borders(image: Image.Image) -> Image.Image:
    rgba = image.convert("RGBA")
    width, height = rgba.size
    pixels = rgba.load()

    visited: set[tuple[int, int]] = set()
    queue: deque[tuple[int, int]] = deque()

    def push_if_bg(x: int, y: int) -> None:
        if (x, y) in visited:
            return
        r, g, b, _ = pixels[x, y]
        if is_light_background_pixel(r, g, b):
            visited.add((x, y))
            queue.append((x, y))

    for x in range(width):
        push_if_bg(x, 0)
        push_if_bg(x, height - 1)
    for y in range(height):
        push_if_bg(0, y)
        push_if_bg(width - 1, y)

    while queue:
        x, y = queue.popleft()
        for nx, ny in ((x - 1, y), (x + 1, y), (x, y - 1), (x, y + 1)):
            if 0 <= nx < width and 0 <= ny < height:
                push_if_bg(nx, ny)

    for x, y in visited:
        pixels[x, y] = (0, 0, 0, 0)

    return rgba


def remove_small_components(image: Image.Image, min_component_pixels: int) -> Image.Image:
    if min_component_pixels <= 0:
        return image

    rgba = image.convert("RGBA")
    alpha = rgba.getchannel("A")
    width, height = rgba.size
    alpha_pixels = alpha.load()
    rgba_pixels = rgba.load()
    visited: set[tuple[int, int]] = set()

    for y in range(height):
        for x in range(width):
            if alpha_pixels[x, y] == 0 or (x, y) in visited:
                continue

            queue: deque[tuple[int, int]] = deque([(x, y)])
            visited.add((x, y))
            component: list[tuple[int, int]] = []

            while queue:
                cx, cy = queue.popleft()
                component.append((cx, cy))
                for nx, ny in ((cx - 1, cy), (cx + 1, cy), (cx, cy - 1), (cx, cy + 1)):
                    if 0 <= nx < width and 0 <= ny < height:
                        if alpha_pixels[nx, ny] == 0 or (nx, ny) in visited:
                            continue
                        visited.add((nx, ny))
                        queue.append((nx, ny))

            if len(component) < min_component_pixels:
                for px, py in component:
                    r, g, b, _ = rgba_pixels[px, py]
                    rgba_pixels[px, py] = (r, g, b, 0)

    return rgba


def normalize_product_image(
    image: Image.Image,
    canvas_size: int,
    target_width: int,
) -> Image.Image:
    rgba = image.convert("RGBA")
    bbox = rgba.getchannel("A").getbbox()
    if bbox is None:
        return Image.new("RGBA", (canvas_size, canvas_size), (0, 0, 0, 0))

    subject = rgba.crop(bbox)
    if subject.height > subject.width:
        subject = subject.rotate(-90, expand=True, resample=Image.Resampling.BICUBIC)
        rotated_bbox = subject.getchannel("A").getbbox()
        if rotated_bbox is not None:
            subject = subject.crop(rotated_bbox)

    scale = target_width / subject.width
    subject = subject.resize(
        (target_width, max(1, int(round(subject.height * scale)))),
        Image.Resampling.LANCZOS,
    )

    canvas = Image.new("RGBA", (canvas_size, canvas_size), (0, 0, 0, 0))
    offset_x = (canvas_size - subject.width) // 2
    offset_y = (canvas_size - subject.height) // 2
    canvas.alpha_composite(subject, (offset_x, offset_y))
    return canvas


def finalize_product_image(
    image: Image.Image,
    canvas_size: int,
    target_width: int,
    min_component_pixels: int,
) -> Image.Image:
    transparent = make_transparent_from_borders(image)
    cleaned = remove_small_components(transparent, min_component_pixels)
    return normalize_product_image(cleaned, canvas_size=canvas_size, target_width=target_width)


def save_first_image_part(
    response,
    dst: Path,
    canvas_size: int,
    target_width: int,
    min_component_pixels: int,
) -> None:
    parts = getattr(response, "parts", None)
    if parts is None and getattr(response, "candidates", None):
        parts = response.candidates[0].content.parts

    if not parts:
        raise RuntimeError("Model returned no content parts.")

    for part in parts:
        inline_data = getattr(part, "inline_data", None)
        if inline_data is None and isinstance(part, dict):
            inline_data = part.get("inline_data")

        if inline_data is None:
            continue

        if hasattr(part, "as_image"):
            image = to_pil_image(part.as_image())
            dst.parent.mkdir(parents=True, exist_ok=True)
            finalize_product_image(
                image,
                canvas_size=canvas_size,
                target_width=target_width,
                min_component_pixels=min_component_pixels,
            ).save(dst)
            return

        data = getattr(inline_data, "data", None)
        if data:
            dst.parent.mkdir(parents=True, exist_ok=True)
            with open(dst, "wb") as handle:
                handle.write(data)
            with Image.open(dst) as image:
                processed = finalize_product_image(
                    image,
                    canvas_size=canvas_size,
                    target_width=target_width,
                    min_component_pixels=min_component_pixels,
                )
                processed.save(dst.with_suffix(".png"))
            if dst.suffix.lower() != ".png":
                dst.unlink(missing_ok=True)
            return

    raise RuntimeError("Model returned text only and no edited image.")


def process_image(
    src: Path,
    dst: Path,
    client,
    model: str,
    canvas_size: int,
    target_width: int,
    min_component_pixels: int,
) -> None:
    with Image.open(src).convert("RGBA") as image:
        response = client.models.generate_content(
            model=model,
            contents=[PROMPT, image],
        )

    save_first_image_part(
        response,
        dst,
        canvas_size=canvas_size,
        target_width=target_width,
        min_component_pixels=min_component_pixels,
    )


def parse_args() -> argparse.Namespace:
    parser = argparse.ArgumentParser(
        description="Cut out product images with Gemini and normalize them to square transparent PNGs."
    )
    parser.add_argument("input_dir", type=Path)
    parser.add_argument("output_dir", type=Path)
    parser.add_argument("--model", default="gemini-2.5-flash-image")
    parser.add_argument("--canvas-size", type=int, default=DEFAULT_CANVAS_SIZE)
    parser.add_argument("--target-width", type=int, default=DEFAULT_TARGET_WIDTH)
    parser.add_argument("--min-component-pixels", type=int, default=DEFAULT_MIN_COMPONENT_PIXELS)
    parser.add_argument("--overwrite", action="store_true")
    return parser.parse_args()


def main() -> None:
    args = parse_args()
    api_key = os.environ.get("GEMINI_API_KEY")
    if not api_key:
        raise SystemExit("Missing GEMINI_API_KEY environment variable.")
    if not args.input_dir.is_dir():
        raise SystemExit(f"Input directory does not exist: {args.input_dir}")
    if args.canvas_size <= 0:
        raise SystemExit("--canvas-size must be positive.")
    if args.target_width <= 0 or args.target_width > args.canvas_size:
        raise SystemExit("--target-width must be positive and no larger than --canvas-size.")
    if args.min_component_pixels < 0:
        raise SystemExit("--min-component-pixels must be >= 0.")

    args.output_dir.mkdir(parents=True, exist_ok=True)
    client = genai.Client(api_key=api_key)

    for src in sorted(args.input_dir.iterdir()):
        if not src.is_file() or src.suffix.lower() not in SUPPORTED_EXTENSIONS:
            continue
        dst = args.output_dir / f"{src.stem}.png"
        if dst.exists() and not args.overwrite:
            print(f"skip {dst}")
            continue
        process_image(
            src,
            dst,
            client,
            args.model,
            canvas_size=args.canvas_size,
            target_width=args.target_width,
            min_component_pixels=args.min_component_pixels,
        )
        print(dst)


if __name__ == "__main__":
    main()

下载附件： product-cutout-normalize.7z

商品图 on KnightLi的博客