---
name: playcraft-image-processing
description: 可玩广告流程步骤 6。对生成的图片进行后处理：缩放、裁剪、旋转、翻转、填充、格式转换、滤镜、合成等。所有操作通过 `playcraft image` CLI 命令在沙箱本地执行，无需 backend，速度快。
compatibility: agent,opencode
---

## Skill Definition
tools:
  - bash
  - read
prompt_extension: |
  你是图像处理工程师。不得向 /project/ 写入；所有输出路径必须在 ta-workspace（技术美术角色）。
  通过 bash 工具运行 `playcraft image <command>` CLI 命令进行图片处理，所有操作在沙箱本地执行，无需往返 backend。

## 我做什么

- 对生成的图片进行后处理，使其符合游戏引擎和可玩广告的规格
- 支持：缩放、裁剪、旋转、翻转、填充边距、格式转换、灰度化、模糊、色调叠加、反色、图片合成、像素化、自动裁边

## 何时用我

当 `playcraft tools generate-image` 生成的图片需要进一步处理时：
- 尺寸不符合纹理要求（如需 2 的幂次、特定分辨率）
- 需要像素风效果
- 需要旋转/镜像翻转（如左右角色复用同一张图）
- 需要统一多帧尺寸后合并精灵图
- 需要格式转换（png → webp 优化体积）
- 需要裁掉透明边界、叠加合成等

## 命令速查

所有命令格式：`playcraft image <command> --input <路径> --output <路径> [选项]`

### 几何变换

```bash
# 缩放（支持比例或指定宽高）
playcraft image resize --input src.png --output out.png --scale 0.5
playcraft image resize --input src.png --output out.png --width 512 --height 512 --fit contain

# 裁剪（指定区域）
playcraft image crop --input src.png --output out.png --x 0 --y 0 --width 256 --height 256

# 旋转（任意角度，默认背景透明）
playcraft image rotate --input src.png --output out.png --angle 90
playcraft image rotate --input src.png --output out.png --angle 45 --background "#ffffff"

# 镜像翻转
playcraft image flip --input src.png --output out.png --direction horizontal
playcraft image flip --input src.png --output out.png --direction vertical

# 扩展画布/加边距（统一精灵尺寸常用）
playcraft image pad --input src.png --output out.png --all 16
playcraft image pad --input src.png --output out.png --top 8 --bottom 8 --left 0 --right 0

# 自动裁掉透明/纯色边界
playcraft image trim --input src.png --output out.png --threshold 10
```

### 格式与质量

```bash
# 格式转换 + 压缩质量（png/jpg/webp/avif）
playcraft image convert --input src.png --output out.webp --quality 85
playcraft image convert --input src.jpg --output out.png
```

### 滤镜与色彩

```bash
# 灰度化
playcraft image grayscale --input src.png --output out.png

# 高斯模糊（背景虚化等）
playcraft image blur --input src.png --output out.png --sigma 5

# 色调叠加（做角色不同颜色变体）
playcraft image tint --input src.png --output out.png --color "#ff4400"

# 反色
playcraft image negate --input src.png --output out.png

# 像素化（像素风格）
playcraft image pixelate --input src.png --output out.png --pixel-size 8
```

### 合成

```bash
# 将一张图叠在另一张图上（居中对齐）
playcraft image overlay --base bg.png --overlay icon.png --output out.png

# 指定坐标叠加
playcraft image overlay --base bg.png --overlay icon.png --output out.png --x 100 --y 200
```

### 语义分割（SAM3）

通过 SAM3（Segment Anything Model 3）对图片进行**开放词汇语义分割**：用文字或框 prompt 精确抠出任意对象，返回 mask 和 RGBA 透明图。
需要经由 backend 代理，首次冷启动约 15s，热启动约 5-10s。

```bash
# ── 单 prompt — 文本 ──
# 找到图中所有"logo"区域，输出 mask + RGBA
playcraft image segment \
  --input ta-workspace/banner.png \
  --text "logo" \
  --output-dir ta-workspace/segment-out

# ── 单 prompt — 框选区域 ──
# 用 [x1,y1,x2,y2] 绝对像素坐标指定目标区域
playcraft image segment \
  --input ta-workspace/banner.png \
  --boxes "[[50,100,300,400]]" \
  --output-dir ta-workspace/segment-out

# ── 多 prompt 批量（一次调用，多个目标）──
playcraft image segment \
  --input ta-workspace/banner.png \
  --prompts '[{"text":"icon"},{"text":"button"},{"text":"logo"}]' \
  --output-dir ta-workspace/segment-out

# ── 调节得分阈值（默认 0.3，越低召回越多）──
playcraft image segment \
  --input ta-workspace/hero.png \
  --text "character" \
  --threshold 0.2 \
  --output-dir ta-workspace/segment-out

# ── 不需要 RGBA 抠图，只要 mask ──
playcraft image segment \
  --input ta-workspace/hero.png \
  --text "character" \
  --no-rgba \
  --output-dir ta-workspace/segment-out
```

**输出目录结构**：

```
segment-out/
  prompt_0_logo/
    00_mask.png       ← 二值 mask（白色为前景）
    00_rgba.png       ← RGBA 透明抠图
    01_mask.png       ← 同一 prompt 的第二个实例（若有多个）
    01_rgba.png
  prompt_1_button/
    00_mask.png
    00_rgba.png
  segment-meta.json   ← 汇总：image_size、prompts、instances count、scores、bbox
```

**使用要点**：

- **冷启动**：SAM3 缩容后首次调用约 15s，命令会自动等待，无需手动 ping
- **热启动**：模型就绪后约 5-10s 完成分割
- **抠图直接可用**：`rgba.png` 已是透明背景，可直接用于游戏资产，无需再跑 `remove-background`
- **多实例**：同一 prompt 可能检测到多个对象（如图中有 3 个 logo），每个实例单独输出 `00_`、`01_`…
- **bbox 信息**：`segment-meta.json` 包含每个实例的 bbox 坐标，可用于后续裁切定位

**与 remove-background 的对比**：

| 场景 | 推荐方案 |
|------|---------|
| 去除纯色/渐变/棋盘格背景（AI 生成图） | `remove-background --method floodfill` |
| 去除复杂真实照片背景 | `remove-background --method ai` |
| **精确分割特定对象**（如从 UI 截图中提取某个按钮） | `segment --text "button"` |
| **批量提取多个不同对象** | `segment --prompts '[...]'` |
| **需要 mask 做遮罩特效** | `segment`（直接输出 mask.png） |

### 背景移除

支持两种方法，根据图片类型选择：

```bash
# ── floodfill（默认）— 本地执行，AI 生成素材首选 ──
# 从边缘 flood-fill 移除纯色/渐变/棋盘格背景，前景纹理零损失
playcraft image remove-background --input ta-workspace/hero_raw.png --output ta-workspace/hero.png

# 调节容差（背景与前景颜色接近时增大）
playcraft image remove-background --input ta-workspace/tile.png --output ta-workspace/tile.png --tolerance 40

# 关闭边缘平滑（需要硬边像素风时）
playcraft image remove-background --input ta-workspace/pixel_art.png --output ta-workspace/pixel_art.png --edge-smooth 0

# ── ai — 调用 backend AI 模型，复杂背景照片用 ──
playcraft image remove-background --input ta-workspace/photo.jpg --output ta-workspace/photo.png --method ai
```

**方法选择指南**：
| 方法 | 适用场景 | 速度 | 纹理保真度 |
|------|---------|------|-----------|
| `floodfill`（默认） | AI 生成的素材（纯色/灰色/棋盘格背景） | <0.5s | 零损失 |
| `ai` | 真实照片、复杂背景 | ~1-3s | 可能褪色 |

> **注意**：`--method ai` 会调用 backend API（需要沙箱 token）；`floodfill` 完全本地执行。

## 可玩广告常见规格

- 纹理尺寸：建议 2 的幂次（256×256、512×512、1024×1024）
- 像素风：`--pixel-size 8` 到 `16` 常见
- WebP 转换：通常比 PNG 小 30–50%，可玩广告体积敏感时优先用 webp
- 统一精灵帧尺寸：先 `resize` → 再 `sprite-sheet` 合并

## 典型流程

```bash
# 生成图片 → 缩放到规格 → 转 webp 压缩
playcraft tools generate-image --prompt "cute hero character, transparent background" --output ta-workspace/hero_raw.png
playcraft image resize --input ta-workspace/hero_raw.png --output ta-workspace/hero_512.png --width 512 --height 512 --fit contain
playcraft image convert --input ta-workspace/hero_512.png --output ta-workspace/hero_512.webp --quality 85

# 制作角色颜色变体
playcraft image tint --input ta-workspace/hero_512.png --output ta-workspace/hero_blue.png --color "#0055ff"
playcraft image tint --input ta-workspace/hero_512.png --output ta-workspace/hero_red.png --color "#ff2200"
```