Panorama Stitcher

What it is

Many photos, one seamless image

Stitching looks like image editing but is really geometry. Two photos of the same scene from a slightly turned camera are related by a single mathematical transform — a homography. Find that transform and you can warp one image into the other's frame so they line up exactly. Do it across a sequence and the whole panorama snaps together.

The catch is that the matches you find between images are noisy — plenty of them are wrong. The art of the pipeline is fitting the right transform despite the bad matches, and then blending the overlap so the join disappears. It's a tour of the fundamentals every vision course is built on.

The demo

Two crops in, one panorama out

The bundled demo splits a 1200×500 textured skyline into two overlapping 744×500 crops, then stitches them back together. ORB finds matches, RANSAC fits the homography that the most matches agree on, and the overlap is feather-blended away.

pip install -r requirements.txt
python stitch.py                       # bundled demo → output.png
python stitch.py a.jpg b.jpg c.jpg -o pano.png   # your own photos
python -m pytest -q                    # 11 passing tests

Numbers above are from a real run on the OpenCV ORB backend. The reconstructed panorama lands within 2 px of the original scene the crops were cut from.

The stack

From loose photos to one panorama

Each stage is a classic vision building block, implemented to actually understand it.

Architecture

How a panorama is built

The code lives in a small panorama/ package plus stitch.py. Each new photo is folded in by the same sequence:

1. Detect & match · features.py

   ORB keypoints + Hamming brute-force + Lowe ratio test (OpenCV), or Harris corners + NCC patch matching (NumPy fallback).

2. Estimate H · homography.py

   Normalized Direct Linear Transform: build the 2n×9 system, solve by SVD, Hartley-normalize for conditioning. From scratch in NumPy.

3. Robust fit · ransac.py

   RANSAC over minimal 4-point samples, inliers counted by reprojection error, adaptive iteration count, refit on all inliers. From scratch.

4. Warp · blend.py

   Compute the canvas bounding box and reproject each image into a shared frame (OpenCV warpPerspective or NumPy bilinear inverse-map).

5. Blend · blend.py

   Distance-transform feather weights merge the overlap so the seam disappears, then on to the next photo.

Reflection

What rebuilding it taught me

• Stitching is geometry, not editing. The whole effect rests on one realisation: overlapping views are related by a homography you can solve for.
• RANSAC is the unsung hero. Feature matches are full of garbage; fitting a model that ignores the outliers is what makes it robust.
• Good keypoints decide everything. If the detector picks distinctive, repeatable points, the rest of the pipeline almost works itself out.
• The seam is where it's won or lost. A perfect alignment with a hard exposure edge still looks fake; blending is the finishing craft.
• Small errors compound. Across many images, tiny per-pair misalignments accumulate into drift — order and reference choice matter.