Metadata-Version: 2.4
Name: ssimulacra2
Version: 0.2.2
Summary: Python implementation of SSIMULACRA2 image quality metric
Project-URL: Documentation, https://github.com/Pacidus/py-ssimulacra2#readme
Project-URL: Issues, https://github.com/Pacidus/py-ssimulacra2/issues
Project-URL: Source, https://github.com/Pacidus/py-ssimulacra2
Author-email: Pacidus <Pacidus@gmail.com>
License: BSD 3-Clause License
        
        Copyright (c) 2025, Pacidus
        All rights reserved.
        
        Redistribution and use in source and binary forms, with or without
        modification, are permitted provided that the following conditions are met:
        
        1. Redistributions of source code must retain the above copyright notice, this
           list of conditions and the following disclaimer.
        
        2. Redistributions in binary form must reproduce the above copyright notice,
           this list of conditions and the following disclaimer in the documentation
           and/or other materials provided with the distribution.
        
        3. Neither the name of the copyright holder nor the names of its
           contributors may be used to endorse or promote products derived from
           this software without specific prior written permission.
        
        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
        AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
        IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
        DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
        FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
        DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
        SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
        CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
        OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
        OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
License-File: LICENSE
Keywords: compression,image quality,perception,ssim,ssimulacra2
Classifier: Development Status :: 4 - Beta
Classifier: License :: OSI Approved :: BSD License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Multimedia :: Graphics
Classifier: Topic :: Scientific/Engineering :: Image Processing
Requires-Python: >=3.8
Requires-Dist: numpy>=1.19.0
Requires-Dist: pillow>=8.0.0
Requires-Dist: scipy>=1.5.0
Description-Content-Type: text/markdown

# SSIMULACRA2

[![PyPI - Version](https://img.shields.io/pypi/v/ssimulacra2.svg)](https://pypi.org/project/ssimulacra2)
[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/ssimulacra2.svg)](https://pypi.org/project/ssimulacra2)

A Python implementation of SSIMULACRA2 (Structural SIMilarity Unveiling Local And Compression Related Artifacts) - a perceptual image quality metric that helps you detect and measure compression artifacts.

## What is SSIMULACRA2?

SSIMULACRA2 is a full-reference image quality metric designed to mimic how humans perceive image quality, with a special focus on compression artifacts. This Python package offers a clean and efficient implementation that closely follows the original C++ algorithm from the JPEG XL project.

Want to know if your compressed images still look good? SSIMULACRA2 gives you a score from 100 (perfect quality) down to negative values (terrible quality) to help you decide:

- **Negative scores**: You've gone too far! Extremely low quality with very strong distortion
- **10**: Very low quality - comparable to what you'd get from cjxl -d 14 / -q 12 or libjpeg-turbo quality 14, 4:2:0
- **30**: Low quality - similar to output from cjxl -d 9 / -q 20 or libjpeg-turbo quality 20, 4:2:0
- **50**: Medium quality - like what cjxl -d 5 / -q 45 or libjpeg-turbo quality 35, 4:2:0 would produce
- **70**: High quality - you'd have trouble noticing artifacts without comparing to the original
- **80**: Very high quality - most people couldn't tell the difference from the original in a side-by-side comparison
- **85**: Excellent quality - virtually impossible to distinguish from the original in a flip test
- **90**: Visually lossless - even in a flicker test at 1:1, you can't tell the difference
- **100**: Mathematically lossless - pixel-perfect match to the original

## Getting Started

### Installation

It's easy to install via pip:

```console
pip install ssimulacra2
```

### Usage

#### Command Line

Simple and straightforward:

```console
# Basic usage - get the score with interpretation
ssymulacra2 original.png compressed.png

# Just the score, no extra info
ssymulacra2 original.png compressed.png --quiet
```

#### Python

Import directly into your Python projects:

```python
from ssimulacra2 import compute_ssimulacra2, compute_ssimulacra2_with_alpha

# Basic usage
score = compute_ssimulacra2("original.png", "compressed.png")
print(f"Quality score: {score:.2f}")

# For images with alpha channel (automatically uses both dark and light backgrounds)
score = compute_ssimulacra2_with_alpha("original.png", "compressed.png")
print(f"Quality score with alpha: {score:.2f}")
```

## Goal

This implementation aims to closely match the original C++ algorithm, providing results consistent with the reference code.

## Requirements

You'll need:
- Python 3.8+
- NumPy
- SciPy
- Pillow (PIL)

## Performance

Performance benchmarks for a 1024x768 image:

| Version | Mean [s] | Min [s] | Max [s] | Relative |
|:---|---:|---:|---:|---:|
| `v0.1.0` | 22.456 ± 0.144 | 22.245 | 22.680 | 33.29 ± 0.59 |
| `v0.2.0` | 0.674 ± 0.011 | 0.661 | 0.696 | 1.00 |
| `HEAD` | 0.689 ± 0.028 | 0.666 | 0.764 | 1.02 ± 0.05 |

The dramatic speed improvement from v0.1.0 to v0.2.0 comes from better leveraging NumPy's vectorized operations. Note that the slight differences in results between versions are due to ongoing experimentation with Gaussian blur parameters to better match the original implementation.

## License

This project is licensed under the BSD 3-Clause License - see the LICENSE file for details.

## Acknowledgements

This implementation is based on the original SSIMULACRA2 algorithm developed for the JPEG XL project.
