图片粘合器 / Collager

简介 / Introduction

一个基于 SIFT 特征匹配、稳健几何估计和羽化融合 的命令行图片拼接工具。脚本会自动寻找图片之间的重叠关系，选择参考图，计算全局变换，并输出拼接后的全景图。

A command-line image stitching tool based on SIFT feature matching, robust geometric estimation, and feather blending. The program automatically detects overlapping regions between images, selects a reference image, computes global transformations, and generates a stitched panorama.

功能 / Functions

• 使用 scikit-image 的 SIFT 提取和匹配局部特征
• Extracts and matches local features using SIFT from scikit-image
• 支持平移、相似和投影三种变换模型
• Supports translation, similarity, and projective transformation models
• 自动筛选最大连通图片组
• Automatically identifies the largest connected group of overlapping images
• 根据匹配质量选择参考图并累计全局变换
• Selects an optimal reference image and computes accumulated global transformations
• 使用距离权重进行羽化融合，减轻接缝
• Uses distance-based feather blending to reduce visible seams
• 自动裁剪外围空白区域
• Automatically crops surrounding empty borders
• 对异常大画布进行保护，降低错误匹配导致的内存风险
• Protects against excessively large panorama canvases to reduce the risk of memory exhaustion caused by incorrect feature matches

环境要求 / Environment

• Python >= 3.10
• imageio>=2.31
• matplotlib>=3.7
• numpy>=1.24
• scipy>=1.10
• scikit-image>=0.21
• pillow>=9.5

安装 / Installation

克隆仓库后安装依赖 / Clone the repository:

git clone https://github.com/wkzhang81/stitch-sift.git
cd stitch-sift
python -m venv .venv

激活虚拟环境 / Activating environment:

# macOS / Linux
source .venv/bin/activate

# Windows PowerShell
.venv\Scripts\Activate.ps1

安装 / Installation:

pip install -r requirements.txt

也可以把项目安装为命令行工具 / Install as cli:

pip install -e .

使用方法 / Usage

将待拼接图片放进同一目录，并保证相邻图片之间存在足够重叠区域。 / Place all images to be stitched in the same directory, and make sure that adjacent images have sufficient overlap.

直接运行脚本 / Run as following：

python stitch_sift.py "images/*.jpg" -o output/panorama.png
# cli installation:
stitch-sift "images/*.jpg" -o output/panorama.png

显示结果窗口 / show result windows：

python stitch_sift.py "images/*.jpg" -o panorama.png --show

使用允许旋转和统一缩放的相似变换 / Use a similarity transformation that allows rotation and uniform scaling：

python stitch_sift.py "images/*.jpg" \
  -o panorama.png \
  --transform-model similarity

使用完整投影变换 / Use a full projective transformation：

python stitch_sift.py "images/*.jpg" \
  -o panorama.png \
  --transform-model projective

常用参数 / Parameters

参数	默认值	说明
input	必填	输入图片 glob，例如 "images/*.jpg"
-o, --output	panorama.png	输出图片路径
--max-ratio	0.75	描述子最近邻比率阈值
--min-matches	12	接受一对图片所需的最少匹配数
--min-inliers	10	所需的最少内点数
--min-inlier-ratio	0.25	所需的最小内点比例
--residual-threshold	3.0	几何估计的像素残差阈值
--transform-model	translation	translation、similarity 或 projective
--show	关闭	完成后显示拼接结果

查看完整帮助 / helps：

python stitch_sift.py --help

变换模型选择 / model selection

• translation：仅允许平移，最稳定，适合同一平面扫描、显微图或相机姿态基本不变的图片。/ Allows translation only, providing the most stable alignment. Best suited for images captured on the same plane, microscopy images, or image sequences with little to no camera motion.
• similarity：允许平移、旋转和统一缩放，适合轻微旋转或距离变化。/ Allows translation, rotation, and uniform scaling. Suitable for images with slight camera rotation or small changes in shooting distance.
• projective：允许透视变化，灵活性最高，但错误匹配可能导致画布倾斜或过大。/ Allows full perspective transformations, providing the greatest flexibility. However, incorrect feature matches may result in a skewed panorama or an excessively large canvas.

拍摄建议 / Image suggestions

• 相邻图片建议保留约 30%–50% 的重叠区域。
• Keep approximately 30%–50% overlap between adjacent images.
• 避免大面积纯色、重复纹理和严重运动模糊。
• Avoid large textureless regions, repetitive patterns, and severe motion blur.
• 尽量保持曝光、焦距和拍摄距离一致。
• Keep the exposure, focal length, and shooting distance as consistent as possible.
• 使用 projective 时，应特别检查输出画布是否异常扩大。
• When using the projective transformation model, carefully check whether the output canvas has become abnormally large.

测试 / Testing

pip install -r requirements-dev.txt
pytest -q

项目结构 / Structure

.
├── .github/workflows/ci.yml
├── examples/input/.gitkeep
├── tests/test_stitch_sift.py
├── .gitignore
├── CONTRIBUTING.md
├── LICENSE
├── README.md
├── pyproject.toml
├── requirements-dev.txt
├── requirements.txt
└── stitch_sift.py

已知限制 / Limits

• 当前会对所有图片两两匹配，图片数量很大时计算成本较高。
• The current implementation performs pairwise matching between all images, which can be computationally expensive for large image sets.
• 主要依赖局部特征，低纹理或重复纹理场景可能失败。
• It relies primarily on local features, so it may fail in low-texture scenes or scenes with repetitive patterns.
• 当前融合方式是加权平均，不包含曝光补偿、多频段融合或接缝优化。
• The current blending method uses weighted averaging and does not include exposure compensation, multiband blending, or seam optimization.
• 不可靠图片会被排除在最大连通组之外。
• Unreliable images are excluded from the largest connected component.

License

MIT License，详见 LICENSE。