# BiRefNet Matting 图像抠图服务

基于 FastAPI 的图像背景移除服务，使用 BiRefNet 模型进行高质量图像抠图。

## 环境要求

- Python 3.8 或更高版本
- Windows 系统（已配置 .bat 启动脚本）
- 建议使用 GPU（CPU 也可运行，但速度较慢）

## 项目结构

### 实际项目文件

```
birefnet-matting/
├── server.py              # FastAPI 服务器主程序
├── birefnet-matting.py    # BiRefNet 图像处理脚本
├── start-server.bat       # 启动服务器脚本
├── requirements_python.txt # Python 依赖
├── rec/                   # 服务器接收图片的文件夹
├── send/                  # 服务器处理结果的文件夹
└── BiRefNet/              # BiRefNet 模型目录
```

### 测试相关文件

```
birefnet-matting/
└── test-client/           # 测试客户端目录
    ├── test-client.py     # 测试客户端程序
    ├── start-test-client.bat  # 启动测试客户端脚本
    ├── test-send/         # 测试：要发送的图片文件夹
    └── test-rec/          # 测试：接收处理结果的文件夹
```

## 快速开始

### 1. 安装依赖

**方式一：自动安装（推荐）**

直接运行启动脚本，会自动创建虚拟环境并安装依赖：
- 运行 `start-server.bat` 会自动安装服务器依赖
- 运行 `test-client/start-test-client.bat` 会自动安装客户端依赖

**方式二：手动安装**

```bash
# 创建虚拟环境
python -m venv .venv

# 激活虚拟环境（Windows）
.venv\Scripts\activate

# 安装依赖
pip install -r requirements_python.txt
pip install -r BiRefNet\requirements.txt
```

### 2. 准备测试图片

将要处理的图片放入 `test-client/test-send` 文件夹。

支持的格式：`.jpg`, `.jpeg`, `.png`, `.bmp`, `.webp`, `.tiff`, `.tif`

### 3. 启动服务器

双击根目录下的 `start-server.bat` 启动 FastAPI 服务器。

- 服务器地址：`http://localhost:8000`
- API 文档：`http://localhost:8000/docs`
- 健康检查：`http://localhost:8000/health`

### 4. 运行测试

1. 进入 `test-client` 文件夹
2. 双击 `start-test-client.bat` 启动测试客户端
3. 按回车键开始处理
4. 处理结果会保存到 `test-client/test-rec` 文件夹

## 工作流程

```
1. 测试客户端 (test-client/test-client.py)
   ├─ 从 test-client/test-send 文件夹打包图片
   ├─ 生成 test-client/test-send/test_images.zip
   └─ 发送 POST 请求到服务器

2. 服务器 (server.py)
   ├─ 接收 zip 文件，保存到 rec 文件夹
   ├─ 解压到 rec 文件夹
   ├─ 调用 birefnet-matting.py 处理图片
   ├─ 处理结果保存到 send 文件夹
   ├─ 打包成 send/processed_images.zip
   └─ 返回 zip 文件

3. 测试客户端接收
   ├─ 接收处理后的 zip 文件
   └─ 解压到 test-client/test-rec 文件夹
```

## API 接口

### POST /api/process

接收 zip 图包，处理后返回处理后的 zip 文件。

**请求：**
- Content-Type: `multipart/form-data`
- 参数：`file` (zip 文件)

**响应：**
- Content-Type: `application/zip`
- 返回处理后的图片 zip 文件

### GET /health

健康检查接口。

### GET /docs

Swagger API 文档（自动生成）。

## 支持的图片格式

- `.jpg`, `.jpeg`
- `.png`
- `.bmp`
- `.webp`
- `.tiff`, `.tif`

## 使用说明

### 服务器端

- **启动**：双击 `start-server.bat`
- **停止**：在服务器窗口按 `Ctrl+C`
- **接收文件夹**：`rec/` - 服务器接收上传的图片
- **输出文件夹**：`send/` - 服务器处理后的图片和 zip 文件

### 测试客户端

- **启动**：进入 `test-client` 文件夹，双击 `start-test-client.bat`
- **输入文件夹**：`test-client/test-send/` - 放入要处理的图片
- **输出文件夹**：`test-client/test-rec/` - 接收处理结果

## 注意事项

1. **启动顺序**：必须先启动服务器，再运行测试客户端
2. **处理时间**：处理大量图片时可能需要较长时间，请耐心等待
3. **输出格式**：处理后的图片会保存为 PNG 格式（带透明背景）
4. **数量验证**：服务器会自动验证接收和处理图片数量是否一致
5. **连接重试**：测试客户端连接失败时会自动重试 3 次（每次间隔 1 秒）
6. **文件清理**：每次处理前会自动清空相关文件夹，确保结果准确