Skip to content

About

As-Projective-As-Possible (APAP) Image Stitching with Moving DLT (CVPR 2013) - Python Implementation

Topics

Resources

Stars

198 stars

Watchers

5 watching

Forks

Latest commit

 

History

33 Commits

Folders and files

Repository files navigation

As-Projective-As-Possible Image Stitching with Moving DLT

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/

1. Target Research Paper

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.

Figure1

2. Quick Start

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)

3. Usage

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.

4. Pipeline

  1. Image Loading
  2. Grayscaling & SIFT (OpenCV)
  3. Brute-Force KNN Matching & Ratio Test
  4. RANSAC
  5. Global-Homography Estimating & Final Size Extracting
  6. Local-Homography Estimating (Moving DLT)
  7. Mesh-based Local Warping
  8. Uniform Blending (50:50), or Multi-band Blending with --multiband True

5. Blending

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.

Blending

Uniform (50:50) Multi-band
Uniform Multi-band

(demo5 with sigma 8.5 and gamma 0.01, the same warped images)

6. Parameter Study

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.

Gamma

  • Recommended: 0.005 ~ 0.01 (with sigma 8.5)

Each colored line is one image pair, and the dashed black line is their mean.

Gamma error

Below 1.0, APAP aligns the images better than a single global homography.

Gamma bending

The larger the value, the more the regions without feature points are bent.

Automatic Selection

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.py takes the same options as main.py, and prints the values to put in --sigma and --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.py for 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.

7. Why do stitching recursively?

  • 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):

Recursive

  • Sequential Stitching:

Sequential

(demo2 with sigma 8.5 and gamma 0.01)

8. References

code

  1. https://github.com/lxlscut/APAP_S
  2. https://github.com/fredzzhang/Normalized-Eight-Point-Algorithm
  3. https://cs.adelaide.edu.au/~tjchin/apap/#Source

demo images

  1. https://github.com/daeyun/Image-Stitching
  2. https://github.com/opencv/opencv_extra
  3. https://www.pyimagesearch.com/2018/12/17/image-stitching-with-opencv-and-python/

9. History

  • 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, --imglist order.
    • Demo scripts are moved to scripts/, and results are saved in ./results.

About

As-Projective-As-Possible (APAP) Image Stitching with Moving DLT (CVPR 2013) - Python Implementation

Topics

Resources

Stars

198 stars

Watchers

5 watching

Forks

Releases

Packages

Contributors

Languages