Residual Error Analyzer

Residual Error Analyzer is a small PyQt6 + OpenCV desktop tool for measuring residual geometric error in already-undistorted chessboard images.

It is designed for camera-calibration quality checks where the original distorted image is not available. In that situation, the tool does not claim to measure the original lens distortion. Instead, it reports how much residual non-projective geometry remains after undistortion.

What It Measures

• Homography residual: how well the detected chessboard corners fit a single planar homography.
• Straightness residual: how far each detected chessboard row/column deviates from a fitted line.
• Residual ratio: residual error normalized by average grid spacing, reported as % of grid spacing.

The main quality number is:

Homography RMS(%)

Suggested interpretation:

< 0.5%    Excellent
0.5%-1%   Good
1%-2%     Usable, inspect edge regions
> 2%      Check undistortion parameters, image quality, or pattern settings

These thresholds are engineering heuristics, not OpenCV standards.

Features

• Friendly desktop UI built with PyQt6.
• Single-image and folder-based batch analysis.
• Live result updates: each completed image is added to the result table immediately.
• Live preview: the newest successfully detected chessboard annotation is shown while analysis continues.
• CSV export: residual_report.csv.
• Annotated output images with highlighted chessboard rows, columns, and corner points.
• Unicode-safe image reading/writing through OpenCV encode/decode helpers.
• uv-based local environment setup.

Installation

Requirements:

• Python 3.10+
• uv
• Linux desktop environment capable of running Qt applications

Clone and run:

git clone https://github.com/Rosatus/ResidualErrorAnalyzer.git
cd ResidualErrorAnalyzer
./run_app.sh

The launcher creates venv/ with uv when needed and installs the project in editable mode.

Manual setup:

uv venv venv
uv pip install --python venv/bin/python -e .
source venv/bin/activate
python -m residual_error_analyzer

Usage

1. Open the application.
2. Choose one undistorted chessboard image, or a directory of images.
3. Set the number of inner chessboard corners.
   • Example: a board with 12 squares by 9 squares has 11 columns and 8 rows of inner corners.
4. Choose whether to save annotated images.
5. Click Start Analysis.

Outputs are written to the selected export directory:

residual_report.csv
annotated/*_residual.png

Metric Notes

If you only have the undistorted image, there is no observed position for each corner before undistortion. Therefore, the original lens distortion rate cannot be measured directly.

This project reports residual geometry after undistortion:

Homography RMS residual = RMS distance between detected corners and their best homography projection
Residual ratio = RMS residual / mean detected grid spacing * 100%

The straightness residual is a complementary metric:

Straightness residual = point-to-line distance for every detected row and column

Development

Install development dependencies:

uv venv venv
uv pip install --python venv/bin/python -e ".[dev]"
source venv/bin/activate
pytest

Run the app from source:

python -m residual_error_analyzer

Project layout:

src/residual_error_analyzer/
  analyzer.py      OpenCV detection and residual metric code
  app.py           PyQt6 desktop UI
  __main__.py      python -m entry point
tests/             synthetic-board regression tests
docs/              additional project notes

License

This project is licensed under the GNU Affero General Public License v3.0 or later. See LICENSE.