A Python re-implementation of APAP (local-homography warping).
This program takes a list of images and performs stitching recursively.
Official Matlab Code: https://cs.adelaide.edu.au/~tjchin/apap/
Research Paper: LINK
Zaragoza, Julio, et al. "As-projective-as-possible image stitching with moving DLT." Proceedings of the IEEE Conference on Computer Vision and Pattern Recognition (CVPR). 2013.
conda create -n apap -c conda-forge python=3.13 numpy=2.5.4 opencv=5.0.0 pillow=12.3.0 tqdm=4.70.1
conda activate apap
bash scripts/demo1.sh
- Windows:
scripts\demo1.bat - Run at the project root. Results are saved in
./results/demo1. - Extra options are passed to main.py. (e.g.
bash scripts/demo5.sh --multiband True)
Three ways to give input images:
python main.py --img1 a.jpg --img2 b.jpg --saveroot ./results/mine
python main.py --imgs a.jpg b.jpg c.jpg --saveroot ./results/mine
python main.py --imgroot ./images/demo1 --imglist ./splits/demo1.txt --saveroot ./results/mine
With --imglist, each line of the txt file is one stitching set.
| Option | Default | Description |
|---|---|---|
--resize W H |
400 300 | each input image is resized to this size |
--mesh_size |
100 | # of cells per side for local homographies |
--gamma |
0.01 | weight offset in the paper (see 6.) |
--sigma |
8.5 | weight bandwidth in the paper (see 6.) |
--ransac_thres |
30 | RANSAC inlier distance (px) |
--ransac_sample |
12 | # of samples per RANSAC trial |
--multiband |
False | multi-band blending instead of uniform blending |
--auto_param |
False | choose sigma and gamma automatically (see 6.) |
--saveroot |
None | save directory (not saved if None) |
--image_show |
0 | # of result images to show, -1 shows all |
See option.py for all options.
Too small input images give few feature points, which may lead to a wrong homography.
- Image Loading
- Grayscaling & SIFT (OpenCV)
- Brute-Force KNN Matching & Ratio Test
- RANSAC
- Global-Homography Estimating & Final Size Extracting
- Local-Homography Estimating (Moving DLT)
- Mesh-based Local Warping
- Uniform Blending (50:50), or Multi-band Blending with
--multiband True
The paper and the official code blend images by simple averaging so that misalignments remain visible. Multi-band blending (Burt & Adelson, 1983) hides the exposure difference along the overlap border.
| Uniform (50:50) | Multi-band |
|---|---|
![]() |
![]() |
(demo5 with sigma 8.5 and gamma 0.01, the same warped images)
Moving DLT weights each feature point by max(exp(-d / sigma^2), gamma), where d is the distance from a mesh cell.
The paper writes exp(-d^2 / sigma^2), but d is measured in pixels, so with sigma 8.5 the weights vanish within about 18 px and most cells end up with the global homography.
The official code uses d instead of d^2, which spreads the weights over about sigma^2 (= 72) px, and this implementation follows it.
sigma: how far a feature point affects the local homography.gamma: the lower bound of the weights. Cells far from feature points fall back to the global homography as gamma grows.
The defaults, sigma 8.5 and gamma 0.01, are chosen empirically, and all demo scripts use them.
- Recommended: 0.005 ~ 0.01 (with sigma 8.5)
Each colored line is one image pair, and the dashed black line is their mean.
Below 1.0, APAP aligns the images better than a single global homography.
The larger the value, the more the regions without feature points are bent.
The best values differ by scene, so sigma and gamma can also be chosen automatically.
python main.py --imgs a.jpg b.jpg c.jpg --auto_param True # chooses them for each stitching stage
python tune.py --imgs a.jpg b.jpg c.jpg # recommends one pair for the whole input
tune.pytakes the same options asmain.py, and prints the values to put in--sigmaand--gamma.- The candidates (sigma 4 ~ 24, gamma 0.0015 ~ 0.1) are evaluated by spatial cross-validation on the matched feature points. Among the candidates within 1% of the lowest error, the largest gamma and sigma are chosen to bend the image less.
- Recommendations of
tune.pyfor the demo images:
| Case | sigma | gamma |
|---|---|---|
| bridge, newspaper, pier | 24 | 0.1 |
| hill | 6 | 0.05 |
| ledge, uttower | 6 | 0.01 |
| snow | 6 | 0.0015 |
| demo2 | 8.5 | 0.0015 |
| demo3 | 12 | 0.1 |
| demo4 | 6 | 0.1 |
| demo5 | 6 | 0.0015 |
- The error is measured only near feature points, so the chosen values do not always look better than the defaults.
- If images are stitched sequentially from the left, the first image becomes the reference and the far side is stretched excessively.
- Recursive stitching splits the list in half and warps each half toward the middle, so the center image becomes the reference.
- Recursive Stitching (
a -> b: a is warped onto b):
- Sequential Stitching:
(demo2 with sigma 8.5 and gamma 0.01)
- https://github.com/lxlscut/APAP_S
- https://github.com/fredzzhang/Normalized-Eight-Point-Algorithm
- https://cs.adelaide.edu.au/~tjchin/apap/#Source
- https://github.com/daeyun/Image-Stitching
- https://github.com/opencv/opencv_extra
- https://www.pyimagesearch.com/2018/12/17/image-stitching-with-opencv-and-python/
- 2020.12.28. ~ 2021.01.03. Initial implementation
- 2026.10.15. ~ 2026.10.16. 1st major update
- Local homographies are estimated in the canvas frame, as in the official code.
- Mesh vertices are placed at the cell centers.
- Faster RANSAC and local warping (vectorized).
- Multi-band blending option (
--multiband). - Automatic sigma & gamma selection (
--auto_param,tune.py). - Supports recent libraries (NumPy 2, OpenCV 5).
- Bug fixes: RANSAC trial number, error handling, mask list,
--imglistorder. - Demo scripts are moved to
scripts/, and results are saved in./results.




