# 图片去背景工具

用于书画、篆刻作品的去背景与去主体补背景脚本。

默认模式优先走书画专用前景提取逻辑：
- 对墨色笔画做局部背景校正与明暗差分
- 对印章做更严格的红色检测
- 在粗掩码内进一步细化 alpha，尽量减少字边残留底色
- 仅在需要时才回退到 `rembg`

## 功能概览

- 单张图片去背景，输出透明 PNG
- 批量处理单层目录中的图片
- 支持 `artwork`、`auto`、`rembg` 三种前景提取模式
- 支持 `calligraphy`、`seal`、`auto` 三种书画类型
- 支持 AOT-GAN 去主体补背景
- 支持常见格式：`jpg`、`jpeg`、`png`、`bmp`、`webp`
- 安装 `pillow-heif` 后可读取 `heic` / `heif`

## 依赖

项目当前依赖见 [requirements.txt](/Users/gavin/removeback/requirements.txt)：

```txt
rembg[gpu]
pillow
pillow-heif
opencv-python
```

如果要使用 AOT-GAN 补背景，还需要额外安装 `torch` / `torchvision`，并准备 AOT-GAN 代码目录与权重文件。

## 环境准备

推荐使用现有虚拟环境：

```bash
source ~/venv/bin/activate
```

安装依赖：

```bash
pip install -r requirements.txt
```

如果你需要启用去主体补背景：

```bash
pip install torch torchvision
```

## 快速开始

处理默认 `images/` 目录中的图片，结果输出到 `output/`：

```bash
python remove_background.py
```

处理单张图片：

```bash
python remove_background.py input.jpg output.png
```

处理指定目录：

```bash
python remove_background.py my_images/ my_output/
```

指定为印章场景：

```bash
python remove_background.py input.jpg output.png --artwork-type seal
```

强制使用 `rembg`：

```bash
python remove_background.py input.jpg output.png --foreground-mode rembg -m isnet-general-use
```

查看完整参数：

```bash
python remove_background.py -h
```

## 输出规则

- 单张图片默认输出为 `*_nobg.png`
- 处理目录时，输出文件写入你指定的输出目录
- 脚本内置的目录批处理只扫描输入目录的第一层文件，不递归子目录
- 如果启用 `--remove-subject`，输出文件名改为 `*_bgfill.<原扩展>` 或 `*_bgfill.jpg`

## 前景提取模式

### `artwork`

默认模式。优先适用于书法、国画、篆刻等纸本图像。

### `auto`

先尝试书画专用掩码；如果结果明显不可信，再回退到 `rembg`。

### `rembg`

强制使用通用抠图模型。适合非书画类图片，或书画专用规则不适合的特殊样本。

## 书画类型

### `auto`

自动兼容书法与印章。

### `calligraphy`

更偏重墨色笔画、灰黑色文字。

### `seal`

更偏重红章、篆刻印记。

## 常用参数

### 书画专用参数

- `--foreground-mode`
- `--artwork-type`
- `--artwork-max-size`

建议：
- 大图先尝试 `--artwork-max-size 1600`
- 超大图如果速度较慢，可降低到 `1200` 或 `1000`
- 红章较多的图片优先试 `--artwork-type seal`
- 纯墨迹优先试 `--artwork-type calligraphy`

### rembg 相关参数

这些参数只在 `--foreground-mode rembg` 或 `auto` 回退到 `rembg` 时生效：

- `-m, --model`
- `-a, --alpha-matting`
- `-ft, --foreground-threshold`
- `-bt, --background-threshold`
- `-es, --erode-size`
- `-p, --post-process`

当前支持的 `rembg` 模型包括：

- `u2net`
- `u2netp`
- `u2net_human_seg`
- `silueta`
- `isnet-general-use`
- `isnet-anime`
- `birefnet-general`
- `birefnet-general-lite`
- `birefnet-portrait`
- `birefnet-dis`
- `birefnet-hrsod`
- `birefnet-cod`
- `birefnet-massive`

### 去主体补背景参数

启用：

```bash
python remove_background.py input.jpg output.jpg --remove-subject --aot-pretrain experiments/your_model.pt
```

常用参数：

- `--aot-root`
- `--aot-pretrain`
- `--aot-device`
- `--aot-block-num`
- `--aot-rates`
- `--aot-crop`
- `--aot-crop-pad`
- `--aot-max-size`
- `--aot-noise-prefill`
- `--aot-noise-strength`
- `--mask-dilate`
- `--mask-blur`
- `--mask-threshold`
- `--edge-grow`
- `--save-mask`
- `--black-subject`
- `--black-threshold`
- `--gray-subject`
- `--gray-saturation-threshold`
- `--gray-value-threshold`
- `--feather`
- `--feather-radius`

一个偏保守的示例：

```bash
python remove_background.py "images/inpaint/IMG_9259 2.JPG" output.jpg \
  --remove-subject \
  --foreground-mode artwork \
  --artwork-type auto \
  --aot-pretrain experiments/G0000000.pt \
  --aot-crop \
  --aot-crop-pad 64 \
  --aot-max-size 900 \
  --aot-noise-prefill \
  --aot-noise-strength 1.0
```

## 典型用法

书法图去背景：

```bash
python remove_background.py input.jpg output.png \
  --foreground-mode artwork \
  --artwork-type calligraphy
```

印章图去背景：

```bash
python remove_background.py input.jpg output.png \
  --foreground-mode artwork \
  --artwork-type seal
```

通用图片走 `rembg`：

```bash
python remove_background.py input.jpg output.png \
  --foreground-mode rembg \
  --model birefnet-general
```

## 调参建议

如果背景没有去掉：

- 先尝试 `--artwork-type calligraphy`
- 再尝试 `--foreground-mode auto`
- 非书画图直接改用 `--foreground-mode rembg`

如果字边仍有底色：

- 先确认原图是否有严重纸纹、阴影或压缩噪声
- 降低 `--artwork-max-size` 可能更快，但通常不利于细节
- 对超大图可以保留 `1600`，必要时单独抽样检查结果

如果去主体补背景不自然：

- 开启 `--aot-crop`
- 增加 `--aot-crop-pad`
- 尝试 `--aot-noise-prefill`
- 减小 `--mask-dilate`、`--mask-blur`

## 校验命令

项目当前可用的检查命令：

```bash
~/venv/bin/python -m pytest -q
~/venv/bin/python -m mypy remove_background.py tests/test_remove_background.py
~/venv/bin/python -m ruff check remove_background.py tests/test_remove_background.py
~/venv/bin/python -m ruff format remove_background.py tests/test_remove_background.py
```

说明：
- `mypy` 与 `ruff` 的项目配置见 [pyproject.toml](/Users/gavin/removeback/pyproject.toml)
- `images/` 与 `output/` 已在静态检查配置里排除

## 已知限制

- CLI 自带的目录批处理不递归子目录
- 书画专用规则仍然可能受极端纸色、重阴影、扫描边框影响
- 某些透明 PNG 在图片预览器里会显示白底或棋盘底，这是预览器合成效果，不代表 alpha 一定有问题

## 仓库结构

```txt
remove_background.py        主脚本
tests/test_remove_background.py
requirements.txt
pyproject.toml
images/                     输入样例
output/                     输出目录
experiments/                AOT-GAN 权重示例
```