这份开发指南旨在指导你如何使用 Python 和 OpenCV 库，将一张电子凭证“无缝”地嵌入到一张实景桌面图中。

---

项目开发指南：实景文档自动化替换系统

1. 开发目的

在金融、政务或自动化测试场景中，常需要合成具有真实感的实拍图。本项目通过算法手段，将干净的电子文档替换到复杂的实拍背景中，要求达到：

• 透视一致性：文档的倾斜角度、透视缩放与原背景完美契合。
• 光照融合：新文档需继承背景环境的光照强度和色调。
• 边缘无痕：替换后的文档边缘无锯齿，与桌面背景过渡自然。

---

2. 技术方案

为了实现“优雅”的合成效果，我们采用以下技术链路：

A. 空间几何映射 (Perspective Transformation)

利用 单应性矩阵 (Homography) 将源图（Source）的四个顶点映射到目标图（Destination）的特定区域。这能解决拍摄角度产生的拉伸和变形。

新增：自适应比例锁定 (Smart Aspect Ratio)
针对实景中由于大角度透视导致的“视觉压扁”现象，系统引入了**智能补白（Padding）**策略。在变换前，算法会计算目标区域的物理宽高比，动态对电子凭证进行 Padding（上下或左右填充白边），强制保持凭证内容的原始纵横比，确保文字和表格不会变形。

B. 智能区域识别 (Intelligent ROI Detection)

针对“同色系物体分割”（如白纸放在白桌面上）的复杂场景，引入 CLAHE（自适应直方图均衡化） 与 双边滤波 技术，增强局部对比度并去除纹理噪声。结合 Canny 边缘检测 和 几何形态筛选，自动精确定位实景图中的凭证坐标。

系统具备 Coordinates Persistence（坐标持久化） 能力：

1. 缓存优先：系统优先读取 coordinates.json，若已有历史标注数据则直接使用，实现“一次标注，永久复用”。
2. 人机回环：若自动识别失败，自动降级为交互式手动点击模式。
3. 自动记忆：用户手动标注的坐标会被自动保存至 JSON 文件，后续运行同一张图片时无需重复操作。

C. 色彩空间校准 (Color Space Matching)

在 LAB 色彩空间（L 代表亮度，A/B 代表色度）中进行处理。通过计算原背景纸张区域的均值和标准差，将电子文档的 L 通道进行线性拉伸，使其“亮度”和“对比度”与环境光匹配。

D. 梯度域合成 (Poisson Blending)

使用 泊松融合（Poisson Blending） 算法。为了防止背景文字透过新凭证显示（透底问题），采用 NORMAL_CLONE 模式。该模式保留前景（新文档）的纹理结构，仅在边缘自适应背景的光照颜色，实现完美的覆盖效果。

---

3. 环境准备

确保你的 Python 环境中安装了以下库：

pip install opencv-python numpy

---

4. 代码实现 (Main Logic)

核心实现逻辑包含自动识别与图像合成两部分。完整代码请参考 main.py。

主要流程：

1. 缓存检查：加载 coordinates.json，若存在对应图片的缓存数据，直接跳过识别步骤。
2. 预处理：降采样、CLAHE 增强、双边滤波（仅在无缓存时执行）。
3. 边缘检测与轮廓分析：应用 Canny 算子与形态学膨胀，筛选最大闭合轮廓。
4. 人工介入与持久化：若自动识别失败，启动交互式窗口，用户手动选点后自动写入 JSON 文件。
5. 比例校正：对比源图与目标区域的物理宽高比，自动对源图进行智能补白（Padding），防止内容挤压。
6. 透视变换：计算单应性矩阵，矫正电子凭证形状。
7. 光照匹配：基于 LAB 空间的统计学直方图匹配。
8. 最终融合：使用 seamlessClone 将校准后的凭证嵌入背景。

---

5. 注意事项与优化

• 鲁棒性设计：自动识别算法已针对低对比度场景优化，但极度模糊或过曝图片仍推荐使用手动模式。
• 中文支持：代码已通过 cv2.imdecode 封装，完美支持 Windows 下的中文路径与文件名。
• 性能考量：泊松融合在处理 4K 大图时可能较慢（需数秒）。代码中包含了自动降采样（resize）逻辑以加速检测过程。