Console/terminal utility that stitches two overlapping photos into a panorama with OpenCV, supporting Windows 11 and Ubuntu Linux 24.04. The pipeline is the classic one: detect keypoints in both images, match them, estimate a homography with RANSAC so that outlier matches do not skew the result, warp the right image onto the left one, and finally auto-crop the black borders the warp leaves behind. Three example pairs ship under data/ (hill, house and tv) and the results are saved to model/stitching/. No GPU is involved.

 

[Folder Structure]

  • CLAUDE.md / AGENT.md: program specification (identical content).
  • CHANGELOG.md: change log.
  • copyright.txt: copyright notice.
  • iccv2003.pdf: the reference paper (Brown & Lowe, panorama recognition).
  • data/: the example pairs hill_left/right, house_left/right and tv_left/right.
  • model/stitching/: the panoramas; it ships with the hill example and its match visualization.
  • tool/tools.py: shared helpers.
  • src/: the utility, the launcher scripts and this document.
  • venv/: Python virtual environment, created by step 1.

[Prerequisites]

  • Operating system: Windows 11 or Ubuntu Linux 24.04.
  • Python 3 and pip.
  • Dependencies are listed in src/requirements.txt and installed by step 1.
  • No GPU required.

[Instructions]

Step 1: create the virtual environment

Delete the old venv/, create a fresh one and install src/requirements.txt. Aborts loudly if pip fails.

 

Windows 11: src\01_venv_create.bat

Ubuntu 24.04: bash src/01_venv_create.sh

 

Step 2: activate the virtual environment

Activate the venv you just created. On Linux, source it so the environment variables apply to the current shell.

 

Windows 11: src\02_venv_activate.bat

Ubuntu 24.04: source src/02_venv_activate.sh

 

Step 3: stitch a pair of photos

Stitch the default hill pair into a panorama. Extra arguments are forwarded to the Python script, for example --left and --right.

 

Windows 11: src\03_stitching.bat

Ubuntu 24.04: bash src/03_stitching.sh

The other example pairs:

bash src/03_stitching.sh --left data/house_left.jpg --right data/house_right.jpg --output model/stitching/house.jpg

bash src/03_stitching.sh --left data/tv_left.jpg --right data/tv_right.jpg --output model/stitching/tv.jpg

 

Step 4: clear the virtual environment (optional)

Delete the venv/ folder to free disk space when you no longer need it.

 

Windows 11: src\99_venv_clear.bat

Ubuntu 24.04: bash src/99_venv_clear.sh

 

[Python Entry Point]

  • src/stitching.py: [--left IMG] [--right IMG] [--output IMG] [--feature-extractor brisk|orb] [--matcher knn|bf] [--ratio 0.75] [--save-matches] [--show].
  • --left / --right: the two input photos, the hill pair by default. They must overlap for the stitch to succeed.
  • --output: the output file, default model/stitching/image_stitching.jpg.
  • --feature-extractor: brisk (default) or orb. On OpenCV 5 the program falls back to ORB automatically.
  • --matcher: knn (default) or bf.
  • --ratio: the ratio test threshold for KNN matching, default 0.75. Lower it to keep only the more reliable matches.
  • --save-matches: also save a picture showing the matched keypoints, which is handy when a stitch goes wrong.
  • --show: also open the result in a window.

[References]

 

Image-Stitching-Python-1.png

 

This SDK is built in AppForAI - AI Dev Tools.

 

Purchase license separately: USD 600, permanent authorization, single APP authorization, single machine authorization, one-year activation, one-year download, one-year update, one-year email technical support.