一款面向法务合规与文档核验场景的本地印章对比工具，支持将单据印章与合同印章进行可视化对比和文字识别。
开发者：李劲松 (BI4IWN)
- 🤖 AI 文字提取（可配置项）：识别方式默认为本地 PaddleOCR；页面左上角「识别」可选 AI——点击「🤖 AI」配置 OpenAI 兼容模型（默认提供 DeepSeek、智谱预设，支持自定义地址/模型/密钥），两种模式：视觉识别（无需 PaddleOCR）与文本解析（本地粗识别 + AI 清洗）；AI 模式下每枚印章有独立识别按钮，加载后自动识别
- 智能印章提取：自动检测印章区域并归一化为标准圆形，支持异形章与圆环缺口/断笔的残缺圆章识别，提取输出 1200×1200 高分辨率保持墨迹清晰 ：自动检测印章区域并归一化为标准圆形，支持异形章与圆环缺口/断笔的残缺圆章识别，提取输出 1200×1200 高分辨率保持墨迹清晰
- 墨色多选：默认红章，可叠加选择红 / 蓝 / 紫多种墨色同时提取（混合盖章场景一网打尽），切换后自动重新提取
- 💧 手工取色与剔除（每枚印章独立，含颜色排除）：参考章与待验章各有独立的墨色面板（位于各自提取区上方），预设红/蓝/紫多选 + 在原图预览上点选任意墨色（支持多种、芯片色点展示），× 剔除不需要的颜色，按该印章的选择实时重新提取，互不影响
- 颜色排除：每个自选色可标记为「提取」（保留）或「排除」（去除），排除色优先——印章提取时把所选排除色的像素剔除（如去除背景色、误捕捉的杂色），点选颜色后在芯片上即可切换
- 单章即显示：加载第一枚印章后对比区域立即显示提取结果，可先行人工查验，无需等两枚齐全
- 多印章候选：一张图检出多个印章时提供候选切换芯片，单据上的公章 / 财务章可分别提取对比
- 一键自动对齐：质心对齐 + RMS 半径归一 + 角度直方图圆相关 + IoU 精调，自动计算旋转 / 缩放 / 偏移（快捷键
A），对齐后即时给出相似度与差异提示 - 三种对比模式：叠加模式（双色叠印）、滑块模式（左右分割对比）、并排模式（等大并列展示）
- 差异高亮：像素级对比两枚印章，绿色表示吻合、红色表示偏差，实时计算相似度百分比（带结果缓存，交互流畅）
- 交互微调：旋转、缩放（等比/水平/垂直独立调节）、偏移、拖拽，精确对齐两枚印章
- 放大镜：4 倍局部放大，配合高分辨率提取可检查笔画级细节
- OCR 文字识别：集成 PaddleOCR 后端，自动识别印章公司名称、编码和类型，兼容 PaddleOCR 2.x / 3.x，支持多墨色识别
- 对比报告导出：一键生成自包含 HTML 报告（内嵌图片、相似度结论、OCR 对照表、时间戳），适合核验留痕归档
- PNG 导出：将当前对比画面导出为 PNG 图片
- 纯本地运行：所有数据处理均在本地完成，不上传任何信息
AI 识别与本地 OCR 拆分
- 识别方式切换移至页面左上角（标题旁「识别：本地 / AI」），不再位于工具栏
- 默认使用原有本地 PaddleOCR 功能；AI 为可配置项——点击「🤖 AI」配置好模型后，左上角选择 AI 才启用
- 选择 AI 后每枚印章提取区下出现独立的「🤖 AI 识别」按钮，可单独对某枚印章触发 AI 识别
- AI 模式下印章加载后自动调用 AI 识别（视觉模式配置就绪即自动识别，无需手动触发）
- 移除原「启用 AI」自动切换开关（配置面板只负责保存模型配置）
- 选择 AI 但未配置/配置不完整时明确提示，不静默回退
新增
- 🤖 AI 文字提取：点击工具栏「🤖 AI」配置，默认提供 DeepSeek（文本解析模式）与智谱 AI（视觉识别模式）预设，也支持自定义任意 OpenAI 兼容接口（地址/模型/密钥）
- 视觉识别：印章图片直接发送给多模态模型（glm-4v、gpt-4o 等）识别，无需安装 PaddleOCR
- 文本解析：本地 PaddleOCR 粗识别 + AI 清洗结构化（deepseek-chat 等纯文本模型）
- 配置保存在本机浏览器（localStorage），密钥不上传服务器；面板内「测试连接」即时验证
- 启用 AI 后「全部识别」自动走 AI；PaddleOCR 缺失时视觉模式仍可用
新增 / 改进
- 可在已提取印章图上取色：进入取色模式后，除原图预览外，还可在提取结果缩略图上直接点选颜色（透明区域自动忽略），便于在去除背景后的纯净印章上精确取色
- 提取/排除以最后操作为准：同一颜色先提取后排除（或反之），按最后一次操作切换其"提取/排除"状态，不再产生重复项
- 修复连续取色/排除时卡顿、无法选中颜色：① 重提取改为防抖合并（连续点选只触发一次）；② 形态学膨胀由 O(N·r²) 暴力循环优化为 O(N·r) 可分膨胀，重提取提速数十倍，主线程不再长时间阻塞
- 自选色芯片重新显示颜色色点（背景色=选定颜色），并保留十六进制编码
新增 / 改进
- 手工取色覆盖默认墨色：首次点选手工颜色（提取或排除）时，自动取消默认红章，仅按手工选择的颜色提取（不再叠加默认色）；移除所有手工颜色后自动恢复默认红章
- 提取结果支持缩放：点击提取缩略图可在 1× ↔ 2× 之间切换；对比区缩放范围由 30%-200% 扩大到 20%-400%
- 修复排除黑色无法提取印章：排除色改为"色相+饱和度+亮度"综合匹配，正确区分黑色（无彩色，hue 0）与红色（彩色，hue 0），排除黑色不再误伤红章；排除色允许选取黑色/深色（此前被"饱和度过低"校验拒绝）
新增 / 改进
- 颜色排除功能：自选色新增「提取 / 排除」两种模式（面板新增「⊘ 排除」取色按钮，芯片可一键切换）。排除色优先——印章提取时命中所选排除色的像素被剔除，用于去除背景色或误捕捉的杂色
- 修复排除后无法提取印章：排除色改用收紧的独立容差（前端 ±6°、后端 ±8°），只剔除贴近所选颜色的像素，不再因容差过宽误伤整枚印章
- 修复无法选择多个颜色：相近颜色点选改为「重新启用」而非静默跳过；提取 / 排除两种模式均可连续点选多种颜色
- 修复点选后颜色未选中的问题：取色改为在点击瞬间实时采样原图像素，并修正边缘采样越界（此前依赖悬停缓存 + 边缘越界会取到错误颜色）
- 排除色同时贯通前端检测/提取与后端 OCR（
/ocr新增excludes参数）
新增 / 改进
- 墨色选择改为每枚印章独立：参考章与待验章各有独立的墨色面板（位于各自提取区上方），预设红 / 蓝 / 紫多选、手工取色、颜色剔除均按印章分别生效，互不影响
- 自定义颜色支持多种并直观展示：每枚印章可点选多种自定义墨色，芯片以色点展示所选颜色，点击启停、× 剔除
- 按所选印章实时重新提取：改动任一印章的墨色，仅重新提取该印章（不再同时重提两枚），OCR 识别同样使用各自的选择
新增 / 改进
- 💧 手工取色：点击「💧 取色」后在原图预览上点选印章墨水颜色，任意色相（绿 / 橙 / 黑等预设之外的颜色）均可提取；可连续添加多种
- 自选色剔除：每个自选色芯片带 × 按钮，可剔除不需要的颜色；点击芯片可临时启用 / 停用；停用最后一个生效墨色时自动恢复默认红章
- 按选择实时重新提取：预设多选或手工取色任一改动后，已加载印章自动按新墨色重新检测并提取（前端提取 + 后端 OCR 均生效）
- 修复：预设色可全部清空、仅按自选色提取（此前会强制回退红章）；修复主脚本一处语法错误导致的页面无法运行问题
- 启动器支持
--port <端口>、--no-install、--no-browser参数；后端新增--no-ocr快速启动模式 - PEP 668 兼容：Homebrew / Ubuntu / uv 等"外部管理" Python 不再报错——启动器会优先使用已装好依赖的 Python（免安装直用），否则自动创建项目内
.venv虚拟环境安装依赖（标准 venv → uv venv → 无 pip 模式逐级兜底）；并优先挑选 PaddlePaddle 兼容的 Python 3.8-3.13 - macOS 双击运行：新增「启动印章对比工具.command」双击启动器（.sh 双击默认打开文本编辑器的问题不再存在）
v2.1.0 更新日志
新增 / 改进
- 墨色改为多选并默认红章：红 / 蓝 / 紫可任意组合同时提取（前后端均为并集检测），替代原「自动」模式
- 单枚印章加载后立即显示对比区域并按原色呈现提取结果——此前需两枚齐全才显示对比界面
- 提取分辨率 800→1200、源图上限 1600→2048、画布启用高质量插值，参考章墨迹更清晰
- 残缺圆章识别：圆环有缺口/断笔的印章（如磨损公章）不再误判为异形章，改用墨迹距离分布判定圆度
- 自动对齐缩放范围收紧至 55%-180%，两章差异过大时状态栏明确提示"对齐结果仅供参考"
- 移除印章后操作目标自动切换到剩余印章，继续可交互
v2.0.0 更新日志
新增
- ⚡ 一键自动对齐：四阶段算法自动完成两枚印章的旋转/缩放/偏移对齐，完成后即时给出相似度
- 🔵 蓝色印章支持：前端提取与后端 OCR 均支持红/蓝/自动三种墨色模式
- 多印章候选检测与切换：一张图最多检出 3 个印章，芯片一键切换
- HTML 对比报告导出：图片 + 相似度 + OCR 结果 + 参数 + 免责声明，自包含可归档
- 快捷键
A触发自动对齐
优化
- 后端改用多线程 HTTP 服务：OCR 识别期间页面与健康检查不再阻塞
- OCR 依赖容错：未安装 PaddleOCR 时服务仍可启动（对比功能不依赖后端），并给出明确安装指引
- OCR 错误以 JSON 结构化返回，前端显示具体失败原因而非静默失败
- 差异高亮计算结果缓存 + 分辨率上限：参数不变时零重算，交互更流畅
- file:// 直开页面时自动回退到默认端口 8765 连接 OCR 服务（此前该场景 OCR 永远失败）
- 后端每次请求重读前端页面文件，前端更新后刷新即生效
stamp-toolkit/
├── README.md # 本文件
├── LICENSE
├── docs/
│ ├── operation-manual.md # 操作手册（用户使用指南）
│ └── technical-doc.md # 技术文档（架构与实现细节）
└── src/
├── stamp-compare.html # 前端页面（~2700 行单文件应用）
├── stamp_app.py # Python 后端（HTTP 服务 + PaddleOCR API）
├── launcher.sh # macOS / Linux 一键启动器
├── launcher.bat # Windows 一键启动器
└── 启动印章对比工具.command # macOS 双击启动器（.command 双击即运行）
macOS（推荐）：
直接双击 启动印章对比工具.command 即可运行（.command 扩展名会被 macOS 自动用「终端」打开，无需任何设置）。
说明：双击
launcher.sh在部分 macOS 上会打开文本编辑器（系统将 .sh 关联到文本编辑），属正常现象；请改用 .command 文件，或右键launcher.sh→ 打开方式 → 终端.app。
Linux：
chmod +x launcher.sh
./launcher.shWindows：
双击 launcher.bat
启动器会自动完成以下工作：
- 检测 Python 3 环境，缺失则提示安装
- 检测并安装 PaddlePaddle、PaddleOCR、OpenCV 依赖
- 启动本地 HTTP 服务（端口 8765）
- 自动打开浏览器访问工具页面
常用参数：
./launcher.sh --port 9000更换端口；./launcher.sh --no-install跳过依赖安装（依赖已就绪时启动更快）；./launcher.sh --no-browser不自动打开浏览器；python3 stamp_app.py --no-ocr跳过 OCR 模型加载（仅使用对比功能）。依赖安装说明：首次运行时，若系统 Python 缺少 OCR 依赖，启动器会创建
.venv虚拟环境并把 PaddlePaddle / PaddleOCR / OpenCV 安装到其中（约 700MB，需几分钟）。虚拟环境位于src/.venv，已在.gitignore中排除。
如果只需要印章对比功能（不需要 OCR），可以直接用浏览器打开 stamp-compare.html：
# macOS
open stamp-compare.html
# Linux
xdg-open stamp-compare.html
# Windows
start stamp-compare.html# 安装依赖
pip install paddlepaddle paddleocr opencv-python
# 启动服务
python3 stamp_app.py # 默认端口 8765
python3 stamp_app.py --port 9000 # 自定义端口
python3 stamp_app.py --no-ocr # 跳过 OCR 模型加载，启动更快（仅对比/导出）- 操作系统：macOS、Windows、Linux
- 浏览器：Chrome、Safari、Firefox、Edge 等现代浏览器
- Python：3.8+（仅 OCR 功能需要）
- Python 依赖（仅 OCR 功能需要）：
- PaddlePaddle（~700MB）
- PaddleOCR
- opencv-python
注意：即使不安装 Python 和 OCR 依赖，印章对比、差异高亮、导出等核心功能仍可正常使用。
- 加载图片：通过粘贴（Ctrl+V）、拖拽或点击上传，分别加载参考章和待验章图片
- 自动提取：工具自动检测印章区域（按墨色模式）并提取归一化；一图多章时通过候选芯片切换
- 一键对齐：点击「⚡ 自动对齐」（或按
A）自动完成旋转/缩放/偏移对齐 - 选择对比模式：叠加 / 滑块 / 并排，快捷键 1/2/3 切换
- 微调（可选）：如需更精细的对齐，使用工具栏滑块或鼠标交互调整
- 差异分析：开启差异高亮查看像素级对比结果和相似度
- 识别（可选）：点击「全部识别」提取印章文字信息——默认本地 PaddleOCR；页面左上角「识别」可切到 AI（需先点「🤖 AI」配置模型，AI 模式下印章加载后自动识别、每枚印章有独立识别按钮，视觉模式无需 PaddleOCR）
- 导出结果：点击"导出"保存对比画面 PNG，或点击"报告"生成归档用对比报告 ：点击"导出"保存对比画面 PNG，或点击"报告"生成归档用对比报告
详细操作说明请参阅 操作手册。
本项目仅供学习和内部使用。
BI4IWN · 李劲松