本项目使用 OpenCV 图像处理实现透视矫正和扫描增强，并可选使用 Teklia Doc-UFCN 文档分割模型提升复杂场景主体检测。默认运行在 CPU 上，不需要 GPU。
cd document-scanner
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt如果系统命令是 python3，将上面的 python 替换为 python3。
默认使用 SmartDoc 2015 Challenge 1 Dataset 的样例数据集进行开发验证。
下载小样例数据：
cd document-scanner
source .venv/bin/activate
python scripts/download_smartdoc.py --variant sample --extract下载完整帧数据：
python scripts/download_smartdoc.py --variant full --extract完整帧数据压缩包约 972 MiB，解压后会更大。低配置机器建议先使用 sample，批处理时配合 --limit 和 --sample-step 抽样。
SmartDoc 小样例包内主要是 .avi 视频。可先抽帧再做图片扫描：
python scripts/extract_video_frames.py data/raw/sample --output-dir data/samples/smartdoc_frames --every 30 --max-frames-per-video 8
python -m src.document_scanner batch data/samples/smartdoc_frames --output-dir outputs/smartdoc_sample --limit 24干净仓库不包含图片数据。没有下载数据集时，先生成一张本地测试图：
cd document-scanner
source .venv/bin/activate
python scripts/create_demo_image.pycd document-scanner
source .venv/bin/activate
python -m src.document_scanner single data/samples/demo_document.jpg --output-dir outputs/single也可以使用脚本入口：
python scripts/process_image.py data/samples/demo_document.jpg --output-dir outputs/single输出文件包括：
*_00_original.jpg：原图*_01_edges.jpg：边缘图*_02_detected.jpg：边界检测可视化*_03_warped.jpg：透视矫正结果*_04_scanned.jpg：扫描增强结果*_metadata.json：检测状态、四角点和参数
cd document-scanner
source .venv/bin/activate
python -m src.document_scanner batch data/raw/sample --output-dir outputs/batch --limit 50脚本入口：
python scripts/batch_process.py data/raw/sample --output-dir outputs/batch --limit 50批处理会递归查找图片文件，并生成 batch_summary.json。
cd document-scanner
source .venv/bin/activate
uvicorn src.web_app:app --host 0.0.0.0 --port 8000浏览器访问：
http://localhost:8000
Web 页面支持上传 JPG/PNG/WebP/BMP 图片，调节 Canny 阈值和检测宽度，显示原图、边界检测、透视矫正、扫描增强四个结果。
默认检测器为 OpenCV。传统高对比文档照片通常由 OpenCV 轮廓检测更稳定处理；需要尝试复杂多平面照片时，可在 Web 页面或 CLI 中选择 自适应候选评分 或 仅 Doc-UFCN。
Doc-UFCN 以常驻 worker 子进程运行。首次请求会启动 Python 3.10 worker 并加载模型，后续请求复用同一模型进程，避免每张图重复加载权重。
Doc-UFCN 的输出只作为候选生成和粗定位。程序会保留多个 Doc-UFCN 候选，对每个候选执行二阶段边缘精修，并对候选四边执行保守的边缘吸附与角点精修，再用边缘支撑、面积比例、边界接触、透视形状和聚焦点距离等通用规则选择最终主体。
在多平面照片中，可以先在原图上点击一个聚焦点，再处理图片。后端会围绕该点生成 focus_seed_candidate 强约束候选，并与 OpenCV、Doc-UFCN 候选一起评分；结果 metadata 会记录 focus_point、candidate_count、selection_reason 和最终 detector。
Web 页面有两种图片来源：
服务器图片：从data/server_images递归读取图片并下拉选择。本地上传：从浏览器上传图片到后端，由服务器端 OpenCV 处理。
仓库默认不包含服务器端演示图片。需要使用 服务器图片 下拉选择时，创建 data/server_images 并放入 JPG/PNG/WebP/BMP 图片，然后刷新网页即可；不放图片也不影响本地上传功能。
Doc-UFCN 需要 Python 3.10 隔离环境。系统已有 python3.10 时执行：
cd document-scanner
bash scripts/setup_docufcn_env.sh如果系统没有 python3.10，可先在主虚拟环境中安装 uv，再运行同一脚本：
source .venv/bin/activate
pip install uv
bash scripts/setup_docufcn_env.sh安装完成后，可以显式选择 Doc-UFCN 候选评分路径：
python scripts/create_demo_image.py
python -m src.document_scanner single data/samples/demo_document.jpg --detector docufcn --output-dir outputs/docufcn_single命令行也支持传入原图坐标系中的聚焦点：
python -m src.document_scanner single data/samples/demo_document.jpg --detector docufcn --focus-x 600 --focus-y 450 --output-dir outputs/docufcn_focus如果只想使用传统 OpenCV：
python -m src.document_scanner single data/samples/demo_document.jpg --detector opencv --output-dir outputs/single验证自有上传图片：
python scripts/evaluate_uploaded_images.py --input-dir data/samples --detector opencv该脚本会递归读取输入目录中的常见图片文件，默认使用 OpenCV，基础依赖安装后即可运行。最小仓库不包含评估图片，可先运行 python scripts/create_demo_image.py 生成 data/samples/demo_document.jpg，或把自有图片放入 data/server_images 后通过 --input-dir 指定目录。结果默认写入 outputs/image_eval/，包含每张图的边界检测、透视矫正、扫描增强、contact sheet 和 summary.json。可用 --detector auto|docufcn|opencv、--output-dir 指定目录；使用 --detector auto 或 --detector docufcn 前需先完成 Doc-UFCN 环境安装。命令行可用 --focus-points-json 传入图片文件名到 [x, y] 的聚焦点映射。
注意：该批处理脚本在 --detector auto 或 --detector docufcn 模式下会启动自己的 Doc-UFCN worker。低内存环境下不要与 Web 服务的 Doc-UFCN 请求同时运行。
请在仓库根目录执行 compose 命令：
cd document-scanner
mkdir -p data/server_images outputs
docker compose up --build -d访问：
http://服务器IP:8000
查看日志：
docker compose logs -f web停止服务：
docker compose down说明：
- Compose 项目名固定为
document-scanner。 - 服务容器名为
document-scanner-web。 - 端口映射为
8000:8000。 - 镜像构建时会安装
uv、创建/app/.venv-docufcn、下载 Doc-UFCNgeneric-page权重，并通过常驻 worker 进行文档主体检测。构建过程不会执行uv cache clean，避免删除 venv 解释器指向的 uv-managed Python runtime。 ./data/server_images以只读方式挂载到容器。该目录可为空；新增服务器端演示图片后刷新网页即可。./outputs挂载到容器用于保留后续输出。.dockerignore会排除.venv、outputs、data/raw、data/samples、data/server_images等大目录，避免把虚拟环境、运行输出和数据文件打进镜像。
没有下载数据集时，可以先生成一张测试图验证流程：
cd document-scanner
source .venv/bin/activate
python scripts/create_demo_image.py
python -m src.document_scanner single data/samples/demo_document.jpg --output-dir outputs/single输入图片
→ 等比例缩放
→ 灰度化与 CLAHE 光照增强
→ 高斯滤波
→ Canny 边缘检测
→ 形态学闭运算和膨胀
→ 轮廓查找
→ 多边形拟合与四边形筛选
→ 四角点排序
→ 透视变换
→ 阴影削弱、自适应阈值扫描增强
→ 输出结果
document-scanner/
├── src/
│ ├── document_scanner.py
│ ├── docufcn_detector.py
│ └── web_app.py
├── scripts/
│ ├── batch_process.py
│ ├── create_demo_image.py
│ ├── download_smartdoc.py
│ ├── extract_video_frames.py
│ ├── docufcn_worker.py
│ ├── setup_docufcn_env.sh
│ └── process_image.py
├── web_static/
│ └── index.html
├── data/ # 运行时数据、样例图和服务器图片，按需生成或放入
├── outputs/ # 运行输出，按需生成
├── requirements.txt
└── README.md