Multi-camera image stitching with cylindrical projection, seam-aware blending
and grid-based illumination compensation.
The pipeline is modular and video-ready: all components can be reused
for real-time multi-camera video stitching.
简介：多路摄像机全景图像拼接工程，包含柱面投影、接缝线优化、 简单羽化融合以及网格光照补偿模块，代码结构为后续升级到实时视频拼接预留了接口。
- Multi-camera image stitching
- 支持多路图像输入与统一“世界画布（panorama canvas）”计算
- Cylindrical projection (optional)
- 可选柱面投影（CP-SIFT 风格），适合较大视场角场景
- Blending
- 简单羽化融合（feather blending）
- 接缝线优化融合（seam-aware blending）
- Illumination compensation
- 全局比例光照补偿
- 基于网格 surface 的局部光照补偿
- Modular design
- 几何、特征、光照、融合模块解耦，便于扩展到视频拼接管线
.
├── main.py # 主示例：多路图像 + 柱面投影 + 接缝融合 + 网格光照
├── test.py # 调试脚本：几何 + 光照补偿对比
├── features/ # SIFT 特征、匹配、配置类型等
│ ├── detector.py
│ ├── matcher.py
│ └── types.py
├── geometry/ # 柱面投影、单应估计、世界画布、warp 等几何模块
│ ├── canvas.py
│ ├── cylindrical.py
│ ├── homography.py
│ └── warp.py
├── rendering/ # 简单融合、接缝融合、后处理
│ ├── illumination.py
│ ├── postprocess.py
│ └── seam_blending.py
├── views/ # 视图封装 / 相机视角相关类型
│ ├── init_views.py
│ └── types.py
├── image/ # 示例图片（city/weir 等测试数据）
└── requirements.txt # 依赖列表
Tested with Python 3.11 (conda environment "stitch").
Python 3.10+ should work as well.
# 创建独立环境（示例）
conda create -n test python=3.11
conda activate test
# 安装依赖
pip install -r requirements.txtpython main.py ./image/city输入：./image/city 目录下的多张图片
输出：results/ 目录：
pano_feather.jpg — 羽化融合结果
pano_seam.jpg — 接缝线优化融合结果
python main.py ./image/city --cyl使用同一组 city 场景，对比平面投影与柱面投影下的接缝优化拼接结果：
| 平面投影（planar） | 柱面投影（cylindrical） |
|---|---|
|
|
在常见工程里，光照补偿通常只使用一个 全局比例系数，对所有像素统一缩放。这种方法实现简单、开销很小，但在存在暗角、局部阴影或自动曝光的多相机场景下，亮度差异往往是空间变化的，全局比例难以同时兼顾整幅图像。
本工程在此基础上，基于性能与效果的综合权衡，设计并实现了一种网格光照补偿方案：
- 将重叠区域划分为规则网格，在每个网格内估计局部增益；
- 对网格增益做平滑约束，保证不同网格之间的过渡连续；
- 复杂度仍然接近全局比例法，但能明显减弱多相机间的“亮度板块感”，为接缝优化创造更平坦的亮度环境。
主流程 main.py 默认启用该网格补偿，test.py 中可对比 global ratio 与 grid-based 两种策略的效果差异。
在主流程中，脚本会同时导出两张结果图：
results/pano_feather.jpg —— 简单融合（feather blending）
results/pano_seam.jpg —— 接缝优化融合（seam-aware blending）
| 简单融合（planar） | 接缝优化融合（cylindrical） |
|---|---|
|
|
在上面的对比图中，可以看到两种融合方式的差异：
-
简单融合（feather blending）
- 只根据到重叠区两侧边界的距离做线性权重，越靠近哪一侧就越偏向哪张图。
- 优点：实现简单、速度快。
- 缺点：视差 / 几何误差明显时容易出现双影、模糊，明暗不一致时会出现明显的亮度过渡带。
-
接缝线优化融合（seam-aware blending）
- 先在重叠区域计算能量（像素差、梯度等），再用动态规划寻找一条代价最小的接缝线，尽量让接缝经过背景和低纹理区域，避开建筑边缘、直线等高对比区域。
- 最终只在接缝附近做窄带融合，能明显减少结构断裂、双影和亮度跳变，接缝位置更不显眼。
简单理解：简单融合是“平均糊掉”，接缝优化融合是“先选对接缝在哪里再融”，在复杂场景下画质提升更明显。
本工程的 seam 模块预留了 接缝掩膜（seam mask）输入接口，用于在拼接时显式避开关键目标。下面以一组 road 场景为例：
| 前景目标掩膜（来自 SAM） | 未避开目标的接缝融合 | 避开目标后的接缝融合 |
|---|---|---|
|
|
|
- 左：使用 SAM (Segment Anything Model) 对路牌、路灯、车道线等前景目标生成的二值掩膜；
- 中：普通接缝优化，仅考虑像素差 / 梯度等能量，接缝可能穿过路牌附近，出现轻微结构割裂；
- 右：在能量图中对掩膜区域施加高惩罚，强制接缝绕开路牌和路灯，前景结构保持完整连贯。
在实现上，seam_blending 支持额外传入 seam_mask 通道，用于约束接缝的搜索空间。
静态图像中，mask 由离线算法（如 SAM）生成即可；在视频场景下，可以在首帧生成并固化 mask 和接缝线，后续帧复用，同步兼顾画质和实时性。这里仅说明接口能力，不对具体分割模型做展开。
This repository provides a modular multi-camera image stitching pipeline with:
- 世界画布（panorama canvas）计算与多路配准；
- 可选柱面投影（cylindrical projection），适合大视场角场景；
- 接缝线优化融合（seam-aware blending），支持接缝掩膜通道；
- 网格 surface 光照补偿，提升多路摄像机之间亮度一致性。
工程已经在静态图片上完成验证，并通过接口设计预留了向实时视频拼接扩展的空间。
后续可以考虑的方向包括：
- 将几何 / 光照 / 融合模块接入视频流，完成 multi-camera video stitching demo；
- 在 GPU 上重写特征提取和 warp 等瓶颈模块，提升实时性能；
- 引入更鲁棒的特征与匹配（如 SuperPoint / R2D2 等），增强在弱纹理场景下的稳定性；
- 结合在线分割模型，自动生成前景掩膜，提升 seam mask 的自动化程度。
如果你在此基础上做了改进或扩展，欢迎提 issue 或发 PR 一起讨论。
-
Lu Yang, Zhenglun Kong, Ting Li, Xinyi Bai, Zhiye Lin, Hong Cheng.
GPU Accelerated Color Correction and Frame Warping for Real-time Video Stitching. -
Shuo-Han Yeh, Shang-Hong Lai.
Real-time Video Stitching. -
Yuan Jia, Zhongyao Li, Lei Zhang, Bin Song, Rui Song.
Semantic Aware Stitching for Panorama. -
闵海波.
《多路视频实时拼接技术研究》.