# 图片去背景工具

使用rembg库实现的Python去背景工具

## 快速开始

```bash
# 激活虚拟环境
source ~/venv/bin/activate

# 使用默认参数处理images文件夹
python remove_background.py

# 处理单个文件
python remove_background.py input.jpg output.png

# 查看所有参数
python remove_background.py -h
```

不同模型适用于不同场景：

| 模型名称 | 大小 | 适用场景 | 推荐度 |
|---------|------|---------|--------|
| **isnet-general-use** | 179MB | 通用场景 | ⭐⭐⭐⭐⭐ 默认推荐 |
| birefnet-general | 250MB | 通用场景，质量更高 | ⭐⭐⭐⭐⭐ |
| birefnet-portrait | 250MB | 人像专用 | ⭐⭐⭐⭐⭐ |
| u2net | 176MB | 经典通用模型 | ⭐⭐⭐⭐ |
| u2netp | 4.7MB | 快速处理 | ⭐⭐⭐ |
| u2net_human_seg | 176MB | 人物分割 | ⭐⭐⭐⭐ |
| isnet-anime | 179MB | 动漫角色 | ⭐⭐⭐⭐ |
| silueta | 43MB | 精简快速 | ⭐⭐⭐ |

**使用示例**:
```bash
# 使用默认模型
python remove_background.py input.jpg

# 使用人像专用模型
python remove_background.py input.jpg output.png -m birefnet-portrait

# 使用快速模型
python remove_background.py input.jpg output.png -m u2netp

# 书画类文字偏浅的温和参数示例
python remove_background.py images output \
  --remove-subject --black_subject --gray_subject --save_mask \
  --black-threshold 30\
  --gray-saturation-threshold 30 --gray-value-threshold 30 \
  --edge-grow 2 \
  --feather --feather-radius 4 \
  --aot-pretrain experiments/G0000000.pt \
  --aot-max-size 1000
```

查看已下载模型：
```bash
ls -lh ~/.u2net/
```

### 模型大小参考

| 模型名称 | 文件大小 | 特点 |
|---------|---------|------|
| u2net | 176MB | 通用模型 |
| u2netp | 4.7MB | 轻量级，速度快 |
| isnet-general-use | 179MB | 新一代通用，推荐 |
| birefnet-general | ~250MB | 最新通用模型 |
| birefnet-portrait | ~250MB | 人像专用 |

### 手动下载模型（网络问题时）

```bash
# 创建目录
mkdir -p ~/.u2net/

# 下载指定模型（以isnet-general-use为例）
curl -L "https://github.com/danielgatis/rembg/releases/download/v0.0.0/isnet-general-use.onnx" \
  -o ~/.u2net/isnet-general-use.onnx
```

### 清理模型缓存

```bash
# 删除所有已下载的模型
rm -rf ~/.u2net/

# 删除特定模型
rm ~/.u2net/u2net.onnx
```

## AOT-GAN 修补后端

`--remove-subject` 默认使用 AOT-GAN 修补。
AOT-GAN 依赖 PyTorch（官方仓库测试 Python 3.8 / torch 1.8.1）。建议使用独立虚拟环境或确保兼容版本。

```bash
# 安装依赖（示例）
pip install torch torchvision
```

下载预训练权重后，运行示例：
```bash
python remove_background.py "images/IMG_9259 2.JPG" \
  --remove-subject --black-subject --gray-subject --save-mask \
  --aot-pretrain experiments/places2.pth
```

CPU 无 GPU 时的加速建议（只裁剪主体区域并限制最大边）：
```bash
python remove_background.py "images/IMG_9259 2.JPG" \
  --remove-subject --black-subject --gray-subject --save-mask \
  --aot-pretrain experiments/places2.pth \
  --aot-crop --aot-crop-pad 24 --aot-max-size 1400
```

减少“补脸”倾向：启用随机噪声预填充
```bash
python remove_background.py "images/IMG_9259 2.JPG" \
  --remove-subject --black-subject --gray-subject --save-mask \
  --aot-pretrain experiments/places2.pth \
  --aot-crop --aot-crop-pad 64 --aot-max-size 900 \
  --aot-noise-prefill --aot-noise-strength 1.0
```

## 可调整参数说明

### 1. 模型选择 (model_name)

不同模型适用于不同场景：

- **u2net** (默认): 通用模型，适合大多数场景
- **u2netp**: 轻量版，速度更快但精度稍低
- **u2net_human_seg**: 专门用于人物分割
- **silueta**: 精简版u2net (43MB)，速度快
- **isnet-general-use**: 新一代通用模型，效果可能更好
- **isnet-anime**: 专门用于动漫角色
- **birefnet-general**: 最新的通用模型，推荐尝试
- **birefnet-portrait**: 专门用于人像
- **birefnet-general-lite**: 轻量版birefnet

**建议**: 如果u2net效果不好，试试 `isnet-general-use` 或 `birefnet-general`

### 2. Alpha Matting 参数

Alpha Matting 是后处理步骤，可以显著改善边缘质量，特别是头发、毛发等细节。

#### alpha_matting（开关）
- **作用**: 是否启用 alpha matting，提升边缘质量
- **默认**: 关闭（不传 `-a/--alpha-matting`）
- **启用方式**: 传入 `-a` 或 `--alpha-matting`
- **效果**: 有利于细节边缘（毛发/细线），但速度稍慢

#### alpha_matting_foreground_threshold (0-255)
- **作用**: 前景阈值，控制哪些区域被认为是前景
- **默认**: 240
- **调整建议**:
  - 值越大(如270): 保留更多细节，但可能保留一些背景
  - 值越小(如210): 去除更彻底，但可能丢失细节
  - 如果前景被过度去除，增加此值
  - 如果背景残留太多，减小此值

#### alpha_matting_background_threshold (0-255)
- **作用**: 背景阈值，控制哪些区域被认为是背景
- **默认**: 10
- **调整建议**:
  - 值越大(如20-30): 去除背景更彻底
  - 值越小(如5): 保留更多过渡区域
  - 如果背景残留，增加此值

#### alpha_matting_erode_size (像素)
- **作用**: 侵蚀大小，用于平滑边缘
- **默认**: 10
- **调整建议**:
  - 值越大(如15-20): 边缘更平滑，但可能损失细节
  - 值越小(如5-8): 保留更多细节，但边缘可能不够平滑

### 3. Mask后处理 (post_process_mask)

- **作用**: 对 mask 进行额外后处理
- **默认**: 关闭（不传 `-p/--post-process`）
- **启用方式**: 传入 `-p` 或 `--post-process`
- **效果**: 有助于减少毛边，但可能略损失细节

### 4. 去主体补背景 (remove_subject)

用于“去掉主体并补全背景”。当前仅使用 AOT-GAN 修补。

- **remove_subject（开关）**: 启用去主体补背景（默认关闭，传 `--remove-subject` 开启）
- **aot_root**: AOT-GAN 目录（默认: `AOT-GAN-for-Inpainting`）
- **aot_pretrain**: AOT-GAN 权重文件路径（必填）
- **aot_device**: AOT-GAN 设备（默认: `cpu`）
- **aot_block_num**: AOTBlock 数量（默认: 8）
- **aot_rates**: AOTBlock 膨胀率（默认: `1+2+4+8`）
- **aot_crop（开关）**: 仅对 mask 覆盖区域裁剪修补（默认关闭，传 `--aot-crop` 开启）
- **aot_crop_pad (像素)**: 裁剪边缘留白像素（默认: 0）
- **aot_max_size (像素)**: AOT 输入最大边限制（默认: 0 表示不限制）
- **aot_noise_prefill（开关）**: AOT使用随机噪声预填充（默认关闭）
- **aot_noise_strength (系数)**: 噪声强度（默认: 1.0）
- **mask_dilate (像素)**: mask 膨胀大小（默认: 3）。越大去除范围越大，风险更高
- **mask_blur (像素)**: mask 模糊大小（默认: 3）。越大边缘越柔和但易过度
- **mask_threshold (0-255)**: alpha 阈值（默认: 10）。越大保留越多主体
- **edge_grow (像素)**: 主体边缘额外扩张（默认: 0）。用于清理残留边缘
- **save_mask（开关）**: 保存 mask 方便检查（默认关闭，传 `--save-mask` 开启）
- **black_subject（开关）**: 将黑色内容也视为主体（默认关闭，传 `--black-subject` 开启）
- **black_threshold (0-255)**: 黑色阈值（默认: 50）。越大越容易把浅灰当黑
- **gray_subject（开关）**: 将灰阶内容也视为主体（默认关闭，传 `--gray-subject` 开启）
- **gray_saturation_threshold (0-255)**: 灰阶饱和度阈值（默认: 30）。越大越容易把彩色当灰
- **gray_value_threshold (0-255)**: 灰阶亮度阈值（默认: 200）。越大越容易把浅灰当灰
- **feather（开关）**: 启用边缘过渡（默认关闭，传 `--feather` 开启）
- **feather_radius (像素)**: 过渡半径（默认: 5）。越大过渡越柔和但可能变糊
- **说明**: 过渡仅在 mask 外侧进行，避免把主体边缘带回

### 5. 参数调优建议（针对书画/字迹）
- 先开启 `--remove-subject`，仅看主体遮罩是否覆盖到字迹
- 文字残留：提高 `--black-threshold` 或 `--gray-*` 阈值
- 过度修补：降低 `--black-threshold`、`--gray-value-threshold`，并减小 `--mask-dilate/--mask-blur`
- 边缘不自然：尝试开启 `--feather` 并使用较小的 `--feather-radius`

## 常见问题解决

### 问题1: 前景被过度去除
**解决方案**:
```python
alpha_matting = True
alpha_matting_foreground_threshold = 270  # 增加此值
alpha_matting_background_threshold = 10   # 保持较小
```

### 问题2: 背景残留太多
**解决方案**:
```python
alpha_matting = True
alpha_matting_foreground_threshold = 240  # 保持默认或减小
alpha_matting_background_threshold = 20   # 增加此值
post_process_mask = True                  # 启用后处理
```

### 问题3: 边缘不自然、有锯齿
**解决方案**:
```python
alpha_matting = True
alpha_matting_erode_size = 15  # 增加平滑程度
```

### 问题4: 毛发、头发细节丢失
**解决方案**:
```python
model_name = "birefnet-portrait"  # 使用人像专用模型
alpha_matting = True
alpha_matting_foreground_threshold = 270  # 增加以保留细节
alpha_matting_erode_size = 5             # 减小以保留细节
```

## 推荐配置

### 配置1: 高质量人像
```python
model_name = "birefnet-portrait"
alpha_matting = True
alpha_matting_foreground_threshold = 260
alpha_matting_background_threshold = 15
alpha_matting_erode_size = 10
post_process_mask = True
```

### 配置2: 通用高质量
```python
model_name = "birefnet-general"
alpha_matting = True
alpha_matting_foreground_threshold = 250
alpha_matting_background_threshold = 12
alpha_matting_erode_size = 10
post_process_mask = True
```

### 配置3: 快速处理
```python
model_name = "u2netp"
alpha_matting = False
post_process_mask = False
```

## 测试不同参数

建议按以下顺序调整:

1. 先尝试不同的模型
2. 启用alpha_matting
3. 调整foreground_threshold和background_threshold
4. 最后调整erode_size

每次修改后运行脚本，对比结果。