# photoid

**Repository Path**: ChenGp/photoid

## Basic Information

- **Project Name**: photoid
- **Description**: # 智能证件照处理工具（PhotoID Studio）

一个功能强大的证件照处理工具，支持多种背景去除方法，可自动处理证件照，包括去除背景、更换背景颜色、调整尺寸等功能。

- **Primary Language**: Python
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-01-21
- **Last Updated**: 2025-01-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 智能证件照处理工具（PhotoID Studio）

一个功能强大的证件照处理工具，支持多种背景去除方法，可自动处理证件照，包括去除背景、更换背景颜色、调整尺寸等功能。

## 项目地址

```bash
git clone https://gitee.com/ChenGp/photoid.git
```

## 功能特点

- 支持多种背景去除方法：
  - rembg: 效果好，适合复杂背景
  - MediaPipe: 速度快，适合人像处理
  - DeepLab: 通用性强，支持GPU加速

- 背景颜色选项：
  - 标准红色背景
  - 标准蓝色背景
  - 纯白色背景
  - 渐变背景

- 支持多种证件照尺寸：
  - 一寸 (25×35mm, 295×413px)
  - 二寸 (35×49mm, 413×579px)
  - 小一寸 (22×32mm, 260×378px)
  - 小二寸 (35×45mm, 413×531px)

- 其他特性：
  - 智能边缘处理
  - 头发细节保留
  - 肩部优化处理
  - 详细的处理时间统计

## 安装

1. 创建虚拟环境（推荐）：
```bash
python -m venv .venv
source .venv/bin/activate  # Linux/Mac
# 或
.venv\Scripts\activate  # Windows
```

2. 安装依赖：
```bash
pip install opencv-python
pip install numpy
pip install pillow
pip install rembg
pip install mediapipe
```

3. 可选依赖（使用 DeepLab 方法时需要）：
```bash
pip install torch torchvision
```

## 使用方法

基本用法：
```bash
python example.py input.jpg
```

指定背景颜色：
```bash
python example.py input.jpg --color blue
python example.py input.jpg -c white
```

指定照片尺寸：
```bash
python example.py input.jpg --size 2inch
python example.py input.jpg -s small1inch
```

选择背景去除方法：
```bash
python example.py input.jpg --method rembg     # 默认方法
python example.py input.jpg -m mediapipe       # 速度优先
python example.py input.jpg -m deeplab         # 需要安装 PyTorch
```

自定义尺寸：
```bash
python example.py input.jpg --width 413 --height 579
```

## 参数说明

- `input_path`: 输入图片路径
- `--color, -c`: 背景颜色 (red/blue/white/gradient)
- `--size, -s`: 照片尺寸规格
- `--method, -m`: 背景去除方法
- `--width, -w`: 自定义宽度（像素）
- `--height, -ht`: 自定义高度（像素）

## 输出说明

程序会在当前目录生成处理后的图片，文件名格式为：
```
output_[原文件名]_[方法]_[背景色]_[尺寸]_[时间戳].jpeg
```

例如：
```
output_photo1_rembg_red_1inch_20240321123456.jpeg
```

## 注意事项

1. 输入图片建议：
   - 使用正面免冠照片
   - 背景尽量简单
   - 光线充足均匀
   - 人像居中

2. 性能考虑：
   - rembg: 效果好但速度较慢
   - MediaPipe: 速度快但可能需要调整参数
   - DeepLab: 需要额外安装 PyTorch

3. M1 Mac 用户优化：
```bash
export PYTORCH_ENABLE_MPS_FALLBACK=1  # 使用 DeepLab 时
```

## 常见问题

1. 如果遇到 ModuleNotFoundError，请检查依赖安装：
```bash
pip install -r requirements.txt
```

2. DeepLab 方法报错，需要安装 PyTorch：
```bash
pip install torch torchvision
```

3. 处理效果不理想，可以尝试：
   - 更换背景去除方法
   - 调整光线条件
   - 使用纯色背景拍摄

## License

MIT License

## 调优指南

### rembg 方法调优

rembg 方法主要通过 alpha matting 参数进行调优：

```python
# 参数说明
alpha_matting=True,                        # 启用透明度细节处理
alpha_matting_foreground_threshold=250,    # 前景阈值 (0-255)
alpha_matting_background_threshold=3,      # 背景阈值 (0-255)
alpha_matting_erode_size=20               # 腐蚀大小（像素）
```

调优建议：
1. 头发细节处理：
   - 降低 foreground_threshold (如 240)
   - 提高 background_threshold (如 5)
   - 减小 erode_size (如 15)

2. 背景残留处理：
   - 提高 foreground_threshold (如 252)
   - 降低 background_threshold (如 2)
   - 增大 erode_size (如 25)

### MediaPipe 方法调优

MediaPipe 方法主要通过多层 mask 和形态学操作调优：

```python
# 主要调优参数
mask_main_threshold = 0.35      # 主体阈值
mask_shoulder_threshold = 0.2   # 肩部阈值
mask_detail_threshold = 0.1     # 细节阈值
kernel_size = (5,5)            # 形态学核大小
blur_radius = 3                # 模糊半径
```

调优建议：
1. 肩部锯齿处理：
   - 增大 kernel_size (如 (7,7))
   - 使用椭圆形核 cv2.MORPH_ELLIPSE
   - 增加高斯模糊半径

2. 边缘细节处理：
   - 调整阈值（main: 0.3-0.4, shoulder: 0.15-0.25）
   - 使用小核心处理细节
   - 减小模糊半径

### DeepLab 方法调优

DeepLab 方法主要通过后处理参数调优：

```python
# 关键参数
main_threshold = 0.8           # 主体阈值
hair_threshold = 0.3           # 头发阈值
detail_threshold = 0.1         # 细节阈值
edge_threshold = 0.1           # 边缘检测阈值
```

调优建议：
1. 提高精度：
   - 增大输入图片尺寸
   - 调整阈值（main: 0.7-0.9）
   - 使用更大的处理核心

2. 提高速度：
   - 减小输入图片尺寸
   - 使用 GPU 加速
   - 简化后处理步骤

### 通用调优技巧

1. 图片预处理：
   - 调整亮度和对比度
   - 确保背景和前景对比明显
   - 适当裁剪无用背景

2. 边缘处理：
   ```python
   # 羽化处理
   blur_radius = 2  # 较小的值保持边缘锐利
   kernel = np.ones((3,3), np.uint8)  # 较小的核心保留细节
   ```

3. 性能优化：
   - rembg: 减小输入图片尺寸
   - MediaPipe: 使用较小的处理核心
   - DeepLab: 启用 GPU 加速

### 常见问题解决

1. 头发细节丢失：
   - rembg: 降低 foreground_threshold
   - MediaPipe: 降低细节阈值
   - DeepLab: 调整 hair_threshold

2. 肩部边缘不平滑：
   - 使用椭圆形核心
   - 增加高斯模糊
   - 调整边缘检测阈值

3. 背景残留：
   - 增大主体阈值
   - 增加形态学处理次数
   - 调整边缘检测参数

## Ubuntu 部署指南

### 1. 安装

1. 下载项目：
```bash
git clone https://gitee.com/ChenGp/photoid.git
cd photoid
```

2. 运行安装脚本：
```bash
chmod +x install.sh
sudo ./install.sh
```

安装脚本会：
- 安装系统依赖
- 创建 Python 虚拟环境
- 安装所需 Python 包
- 创建全局命令 `photoid`

### 2. 使用方法

基本用法：
```bash
photoid input.jpg
```

指定背景颜色：
```bash
photoid input.jpg -c blue      # 蓝色背景
photoid input.jpg --color red  # 红色背景
```

指定照片尺寸：
```bash
photoid input.jpg -s 2inch        # 二寸照片
photoid input.jpg --size small1inch  # 小一寸照片
```

选择背景去除方法：
```bash
photoid input.jpg -m rembg     # 默认方法，效果好
photoid input.jpg -m mediapipe # 速度优先
photoid input.jpg -m deeplab   # 需要 GPU 加速
```

自定义尺寸：
```bash
photoid input.jpg -w 413 -h 579  # 指定像素大小
```

批量处理：
```bash
# 处理当前目录下所有 jpg 文件
for img in *.jpg; do
    photoid "$img" -c blue -s 1inch
done

# 处理指定目录下的图片
for img in /path/to/photos/*.jpg; do
    photoid "$img" -c gradient -s 2inch -m mediapipe
done
```

### 3. 输出说明

处理后的图片会在当前目录生成，文件名格式为：
```
output_[原文件名]_[方法]_[背景色]_[尺寸]_[时间戳].jpeg
```

例如：
```
output_photo1_rembg_red_1inch_20240321123456.jpeg
```

### 4. 卸载

运行卸载脚本：
```bash
chmod +x uninstall.sh
sudo ./uninstall.sh
```

卸载脚本会：
- 删除全局命令 `photoid`
- 删除应用目录及所有文件

### 5. 系统要求

- Ubuntu 18.04 或更高版本
- Python 3.9
- 2GB 以上可用内存
- 如使用 DeepLab 方法，建议有 NVIDIA GPU

### 6. 故障排除

1. 如果遇到权限问题：
```bash
sudo chown -R $USER:$USER /opt/photoid_studio
```

2. 如果遇到 OpenCV 相关错误：
```bash
sudo apt-get install -y \
    libgl1-mesa-glx \
    libsm6 \
    libxext6 \
    libxrender1
```

3. 如果内存不足（使用 DeepLab 时）：
```bash
# 减小处理图片的大小
photoid input.jpg -m deeplab --max-size 1000
```

4. 确保 Python 虚拟环境正确激活：
```bash
source /opt/photoid_studio/.venv/bin/activate
```

### 7. 注意事项

1. 输入图片建议：
   - 使用正面免冠照片
   - 背景尽量简单
   - 光线充足均匀
   - 人像居中

2. 性能考虑：
   - rembg: 效果好但速度较慢
   - MediaPipe: 速度快但可能需要调整参数
   - DeepLab: 需要额外安装 PyTorch

3. 存储空间：
   - 程序安装需要约 500MB 空间
   - 建议保留足够的空间存储输出图片

# 人脸搜索服务

基于 FastAPI 和 Milvus 的高性能人脸搜索服务。

## 功能特点

- 人脸特征提取和向量化
- 高性能相似人脸搜索
- 支持批量处理
- 异步处理和超时控制
- 优雅的资源管理
- 详细的性能统计

## 系统要求

- Python 3.9+
- Milvus 2.3.0+
- 足够的内存和存储空间

## 快速开始

1. 克隆项目：
```bash
git clone <repository_url>
cd face-search-service
```

2. 启动服务：
```bash
chmod +x start.sh stop.sh
./start.sh
```

3. 停止服务：
```bash
./stop.sh
```

## API 接口

### 1. 添加人脸
```
POST /faces/add
```
参数：
- file: 人脸图片文件
- person_id: 人物ID
- name: 人物姓名（可选）
- age: 年龄（可选）
- gender: 性别（可选）
- id_card: 身份证号（可选）
- save_image: 是否保存原始图片（可选）

### 2. 搜索人脸
```
POST /faces/search
```
参数：
- file: 查询用的人脸图片
- threshold: 相似度阈值 (0-1)
- top_k: 返回的最相似人脸数量

### 3. 批量添加人脸
```
POST /faces/batch-add
```
参数：
- files: 人脸图片文件列表
- person_id: 人物ID
- name: 人物姓名（可选）
- age: 年龄（可选）
- gender: 性别（可选）
- id_card: 身份证号（可选）

### 4. 删除人脸
```
DELETE /faces/{person_id}
```
参数：
- person_id: 要删除的人物ID

### 5. 健康检查
```
GET /health
```

## 配置说明

环境变量：
- APP_ENV: 运行环境 (development/production)
- MILVUS_HOST: Milvus 服务器地址
- MILVUS_PORT: Milvus 服务器端口

## 目录结构

```
.
├── face_search_service.py  # 主服务文件
├── face_searcher_milvus.py # Milvus 搜索实现
├── requirements.txt        # 依赖列表
├── start.sh               # 启动脚本
├── stop.sh               # 停止脚本
├── logs/                 # 日志目录
├── temp_uploads/         # 临时文件目录
└── uploads/             # 永久存储目录
```

## 性能优化

1. 使用连接池管理 Milvus 连接
2. 异步处理请求
3. 超时控制
4. 资源自动清理
5. 文件名随机化

## 日志管理

日志文件位置：`logs/app.log`

查看实时日志：
```bash
tail -f logs/app.log
```

## 故障排除

1. 服务无法启动
   - 检查 Milvus 服务是否可用
   - 检查端口是否被占用
   - 查看日志文件

2. 搜索超时
   - 调整超时参数
   - 检查网络连接
   - 优化索引参数

## 维护说明

1. 日志轮转
2. 临时文件清理
3. 性能监控
4. 资源使用监控

## 安全建议

1. 生产环境禁用 Swagger
2. 配置适当的 CORS 策略
3. 实施访问控制
4. 定期备份数据

## License

[License 信息]