visual-comparison

visual-comparison is a lightweight Python library for visual regression testing. It compares two images of the same size, computes a structural similarity score, and can generate output images that highlight visual differences.

It is designed for automation and QA workflows where you want a simple API, reliable packaging, and compatibility with current NumPy releases.

Features

• Supports modern Python versions from 3.9 through 3.13.
• Compatible with current NumPy releases, including NumPy 2.x.
• Compares images from file paths or in-memory NumPy arrays.
• Produces SSIM-based similarity scores.
• Can save either a combined diff box or separate diff boxes.
• Useful for UI testing, screenshot comparison, and visual regression checks.

Installation

pip install visual-comparison

For local development:

pip install -e .

Quick Start

from visual_comparison import ImageComparisonUtil

expected = ImageComparisonUtil.read_image("expected.png")
actual = ImageComparisonUtil.read_image("actual.png")

similarity = ImageComparisonUtil.compare_images(
    expected,
    actual,
    "result.png",
)

print(f"Similarity Index: {similarity}")

API

Method	Description
read_image(path)	Load an image from disk.
save_image(path, image)	Save an image to disk.
compare_images(expected, actual, result_destination=None)	Return the SSIM score and optionally save one combined red bounding box around changed regions.
compare_images_sep(expected, actual, result_destination=None)	Return the SSIM score and optionally save separate bounding boxes for each changed region.
compare_images_bw(expected, actual, result_destination=None)	Return the SSIM score and optionally save a black-and-white diff image.
check_match(expected, actual)	Return True when images are effectively identical.
check_mismatch(expected, actual)	Return True when images differ.

Repository Structure

.
|-- src/visual_comparison/   # Library source
|-- tests/                   # Unit tests
|-- examples/                # Example scripts
|-- sample_images/           # Demo images
|-- .github/workflows/       # CI configuration
|-- README.md
|-- LICENSE
|-- pyproject.toml
|-- requirements.txt
`-- setup.py

Examples

• Similarity example: examples/get_similarity_index.py
• Match and mismatch assertions: examples/asserting_match.py

Demo Images

Basic comparison:

• Expected:
• Actual:
• Result:

Colour comparison:

• Expected:
• Actual:
• Result:

Development

Install dependencies and run the tests:

pip install -r requirements.txt
python -m unittest discover -v

Contributing

Contributions are welcome through issues and pull requests. If you are proposing an API or packaging change, please include a test update alongside it.

License

This project is licensed under the MIT License. See LICENSE for details.