A project of the sub-pixel Least-Square Matching Refining Algorithm for Epipolar-Rectified Stereo Image Pairs in window-size areas. The classic algorithm is proposed by Ackermann in DIGITAL IMAGE CORRELATION: PERFORMANCE AND POTENTIAL APPLICATION IN PHOTOGRAMMETRY (1984), where the correspondence search reduces to a one-dimensional problem along epipolar lines, enabling both fast convergence and high accuracy.
We provide the source code in C++ and a Python API library built upon it. A PyQt Demo Application and the CUDA-based GPU-accelerated version is also provided.
Up to now we have successfully tested the C++ and Python built from source code on Windows 10 and Windows 11.
Project Page
Contributors: Haojun Tang, Jiahao Zhou
Acknowledgements: Thanks to the guidance of Yunsheng Zhang from Central South University.
| Left Image | Right Image |
|---|---|
 |  |
| Setups | CPU | GPU |
|---|---|---|
| Time (sec) | 332.27 | 0.621 |
Improved by 500+ times in our GPU implementation!
Prerequisites
MSVC (Visual Studio 2022, with C++ CMake tools), CMake ≥ 3.20, and the source code:
git clone https://github.com/DonaldTrump-coder/G-LSMEI --recursive
Build for the Code
In the project directory, run the following commands:
mkdir build
cd build
cmake .. -G "Visual Studio 17 2022"
cmake --build . --config Release
.\Release\leastsquares_matching.exe
The output is from the main function in core\src\test.cpp
Use the C++ source code for testing the algorithm.
Prerequisites
You also need MSVC and CMake, conda (or any Python environment), as well as nvcc for CUDA (Already successfully tested on CUDA 12.4). Install them and start to build!
1. Install the Requirement Packages for Python
In the project directory, run
conda create -n matching python=3.11
conda activate matching
pip install -r requirements.txt
2. Build the C++ and CUDA Source for Python Application
cd python
python setup.py bdist_wheel
python -m pip install (Get-ChildItem dist\glsmei-*.whl).FullName --force-reinstall
cd ..
Then the installation of glsmei is done.
3. Use the Application in Python
run
python main.py
Installation from pip (If your Python and CUDA environment is supported): pip install glsmei
Verify installation: python -c "import lsmatching; print(lsmatching.__version__)"
Matching(left_image_path: str, right_image_path: str)| APIs | Params | Returns | Description |
|---|---|---|---|
set_params(windowsize, d_corr_threshold) | int=15, float=0.04 | — | Set template window size and correlation change threshold |
set_matching_params(windowsize, corr_threshold) | int=3, float=0.7 | — | Set initial matching parameters |
set_centers(x1, y1, x2, y2) | int × 4 | — | Set initial conjugate points on left/right images |
calculate() | — | — | Run single-point least-squares matching |
get_left_window() | — | np.ndarray | Get the left image matching window |
get_right_window() | — | np.ndarray | Get the right image matching window |
get_matched_points(savepath) | str | — | Export matching results |
get_matched_x() | — | float | Matched point x-coordinate |
get_matched_y() | — | float | Matched point y-coordinate |
get_delta0() | — | float | Standard error of unit weight |
get_deltag() | — | float | Standard error of window |
get_deltax() | — | float | Standard error of parameters |
get_SNR() | — | float | SNR |
get_h0() / get_h1() | — | float | Radiometric distortion parameters |
get_a0() / get_a1() / get_a2() | — | float | Affine parameters (left → right, x-direction) |
get_b0() / get_b1() / get_b2() | — | float | Affine parameters (left → right, y-direction) |
gpu_device_count() | — | int | Number of available GPUs |
batch_adjust_gpu(window_size=15, d_corr=0.04, max_iter=20, matching_wsize=3, corr_threshold=0.7, savepath=None)GPU batch pipeline: Feature Extraction → Correlation Matching → Least-Squares Refinement
| Parameter | Type | Default | Description |
|---|---|---|---|
window_size | int | 15 | Least-squares refinement template window size |
d_corr | float | 0.04 | Correlation change threshold (convergence criterion) |
max_iter | int | 20 | Maximum iteration count |
matching_wsize | int | 3 | Initial correlation matching template window size |
corr_threshold | float | 0.7 | Initial matching correlation threshold |
savepath | str | None | Output save path |
This project is licensed under the Apache License 2.0. See LICENSE details.
If you use our work or our data in your research, please cite:
@misc{Tang2026GLSMEI,
title = {G-LSMEI: GPU-Accelerated Least-Square Matching Refiner for Epipolar Image Pairs},
author = {Tang, Haojun and Zhou, Jiahao},
year = {2026},
howpublished = {\url{https://github.com/DonaldTrump-coder/G-LSMEI}},
note = {Version 1.0.2. Apache License 2.0}
}