证件扶正工具

基于 U2Net + Flask 的本地证件图像处理工具，支持 AI 智能抠图、自动扶正、调色，以及手机扫码上传。所有处理在本地完成，不上传任何数据。

功能特性

• AI 智能抠图 — 使用 U2Net 深度学习模型自动去除证件背景
• 自动扶正 — 基于主轴协方差分析，将倾斜证件旋转至水平
• 自动调色 — 自动色阶 + 轻微提亮 + 对比度增强，改善扫描质量
• 批量流水线 — 一次请求完成「抠图 → 扶正 → 调色」全流程，支持多图批处理
• 手机扫码上传 — PC 端生成二维码，手机扫码直接将照片推送到 PC（SSE 实时推流）
• EXIF 方向修正 — 自动处理手机拍摄照片的 EXIF 旋转信息

项目结构

.
├── app.py              # Flask 后端主程序（API + 静态页面路由）
├── u2net_model.py      # U2Net 模型加载与推理（抠图核心）
├── u2net_official.py   # U2Net 官方网络结构定义
├── image_processor.py  # 图像基础工具（base64 互转、EXIF 修正）
├── index.html          # PC 端主页（证件处理界面）
├── mobile.html         # 手机端上传页（扫码上传）
├── requirements.txt    # Python 依赖
├── start.bat           # Windows 一键启动脚本
├── build_exe.py        # 打包为可执行文件的脚本
├── DESIGN.md           # 设计规范
├── PRODUCT.md          # 产品定义
└── uploads/            # 上传文件临时目录

环境要求

• Python 3.8+
• U2Net 模型权重文件 u2net.pth（约 176MB）

快速开始

1. 安装依赖

pip install -r requirements.txt

CPU-only 环境（无 GPU）推荐安装轻量版 PyTorch：

pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu

2. 准备模型文件

下载 u2net.pth 并放到本机任意位置，然后修改 app.py 中的路径：

MODEL_PATH = r'C:\path\to\u2net.pth'

模型下载地址：google drive | 百度网盘（提取码：u2net）

3. 启动服务

python app.py

或直接双击 start.bat（Windows）。

服务启动后访问：

• PC 端：http://localhost:5001
• 手机端：http://<局域网IP>:5001/mobile

API 接口

方法	路径	说明
GET	/api/health	健康检查，返回模型加载状态
POST	/api/segment	单独抠图（返回透明背景 PNG）
POST	/api/fix_orientation	仅修正 EXIF 方向
POST	/api/batch_pipeline	批量流水线（抠图→扶正→调色）
GET	/api/mobile/info	返回本机 IP，供 PC 端生成二维码
POST	/api/mobile/upload	手机端上传图片（multipart/form-data）
GET	/api/mobile/stream	SSE 流，PC 端订阅手机推送的图片

批量流水线请求示例

POST /api/batch_pipeline
{
  "images": ["data:image/jpeg;base64,...", "..."],
  "steps": {
    "segment": true,
    "straighten": true,
    "color": true
  }
}

响应：

{
  "success": true,
  "results": [
    { "success": true, "image": "data:image/png;base64,..." },
    { "success": false, "error": "..." }
  ]
}

常见问题

模型文件找不到
修改 app.py 顶部的 MODEL_PATH 为实际路径。即使模型不存在，服务仍会正常启动，抠图功能不可用，其他功能不受影响。

CUDA 报错
模型默认使用 CPU（device='cpu'），无需 GPU。若要启用 GPU，将 app.py 中的 device='cpu' 改为 device='cuda'，并确保安装了对应 CUDA 版本的 PyTorch。

端口冲突
修改 app.py 末尾 app.run(port=5001) 中的端口号。

手机无法扫码上传
确保手机与 PC 在同一局域网，且防火墙未屏蔽 5001 端口。

技术栈

层	技术
后端框架	Flask 3.0
AI 模型	U2Net（PyTorch）
图像处理	Pillow、NumPy
前端	原生 HTML/CSS/JS + OpenCV.js
实时推流	Server-Sent Events (SSE)

License

MIT