image-similarity-measures: Eight Image Comparison Metrics Behind One CLI

What the package actually computes, and for whom

The repository implements eight evaluation metrics for comparing two images: RMSE, PSNR, SSIM, ISSM, FSIM, SRE, SAM and UIQ. The README links each one to a source paper or reference, which matters because several of these are not the metrics a general-purpose image library ships by default. ISSM and SRE come from remote sensing literature, and the citation the README asks users to use is a 2020 ISPRS Annals paper on super-resolution of multispectral satellite images. That citation is the clearest statement of intended audience: researchers reconstructing satellite imagery and needing to report how close a predicted image sits to a reference. The same eight metrics apply to any paired-image evaluation task, but the defaults and the TIFF handling point at geospatial and scientific rasters rather than photographs. If you are scoring a generative model on natural images, you will recognize PSNR and SSIM and probably not the other six.

The mechanism: one evaluation entry point over eight metric functions

The package exposes two layers. The lower layer is image_similarity_measures.quality_metrics, where each metric is a standalone function. The README shows rmse being imported directly and called with two NumPy arrays, org_img and pred_img, each shaped (3,2,1) in the example. That shape is the important detail: the convention is channel last. The upper layer is image_similarity_measures.evaluate.evaluation, which takes file paths rather than arrays, accepts a metrics list, and returns results keyed by metric name. The command line tool wraps that same function, and the README states the output is machine-readable JSON specifically so it can be redirected into a file. So the data flow is: paths in, images read from disk, metric functions applied to array pairs, JSON out. There is no caching layer, no batching, and no aggregation of the eight numbers into a single score. Each metric is reported on its own terms, which is honest but pushes the interpretation problem onto you.

Getting it running: pip, the CLI, and the two optional extras

Installation is a single command, pip install image-similarity-measures, and the README states the package supports Python 3.10 and above. The command line invocation is image-similarity-measures --org_img_path=a.tif --pred_img_path=b.tif. Two parameters control the run: --org_img_path and --pred_img_path take file paths, and --metric selects one of fsim, issm, psnr, rmse, sam, sre, ssim, uiq, or all. The README notes --metric can be repeated, so you can request a subset rather than the full eight. In Python, the same call is evaluation(org_img_path=..., pred_img_path=..., metrics=["rmse", "psnr"]). Two extras exist. pip install image-similarity-measures[speedups] pulls in pyfftw, which the README says speeds up FSIM evaluation. pip install image-similarity-measures[rasterio] adds rasterio for reading TIFF images instead of OpenCV. Both are described as optional, which means the default install reads TIFF through OpenCV and you only change that by asking for the extra.

Channel-last arrays and the TIFF reader are the two places runs break

The README puts a bold note on the evaluation inputs: images should be channel last. Nothing in the documented API reshapes for you. A channel-first array passed to the CLI or to evaluation will either raise or, worse, produce numbers that look plausible and mean nothing, because metrics like SAM and SSIM operate on the channel structure. This is the failure mode to guard against, and it is a silent one. The second constraint is the reader. OpenCV is the default path for TIFF, and rasterio is an opt-in extra. Multispectral satellite rasters frequently carry more bands than OpenCV expects, and geospatial TIFFs can carry georeferencing and band metadata that a plain image reader discards. The README does not document what happens when a raster has, say, six bands rather than three. Given that the project's own citation is about multispectral imagery, the gap between the default reader and the target data is a real design tension, not a hypothetical one.

What it does not do: no batching, no ground truth, no interpretation

The tool compares exactly two images per invocation. The README documents no directory mode, no manifest input, and no parallelism across pairs. If you are evaluating a test set of a few thousand image pairs, you write the loop yourself, and you pay process startup and model-free image reading costs on every call unless you stay in Python and reuse the imported functions. There is also no notion of a reference or baseline. The package will tell you that SSIM is 0.91 between two images; it will not tell you whether 0.91 is good for your dataset, and it keeps no history to compare against. Ranking a set of reconstruction methods therefore requires you to store the JSON output and do the comparison elsewhere. That is a reasonable division of labor for a metrics library, but it means the package is a component, not a benchmark harness.

Alternatives: scikit-image and OpenCV cover less ground, more carefully

The obvious alternative for the overlapping metrics is scikit-image, which provides structural_similarity and peak_signal_noise_ratio in skimage.metrics, plus a broader image processing toolkit around them. The difference in approach is scope and convention. scikit-image is a general library where each function has its own documented array expectations and its own keyword arguments, and it has no CLI that emits JSON for a paired comparison. image-similarity-measures trades that generality for a uniform interface: one function, one set of parameter names, eight metrics, consistent output. OpenCV offers quality modules too, but the same trade applies in reverse: you get a large computer vision library and you assemble the metric calls yourself. The honest framing is that image-similarity-measures is a convenience wrapper with a specific metric set. If you only need SSIM and PSNR, scikit-image removes a dependency and gives you a more actively maintained codebase to reason about. If you need ISSM, SRE or UIQ, this package is one of the few straightforward ways to get them without reading the papers and implementing them.

Maintenance, licensing, and what the release history shows

The license is MIT, which permits commercial use and modification provided the copyright notice and permission notice are retained. Nothing in the supplied material suggests any additional restriction, and this is not legal advice; check the LICENSE file in the repository for the binding text. On maintenance, the release history is uneven. v0.3.5 landed in February 2021, v0.3.6 in May 2023, and the last push to the default branch is dated September 2026, which is later than the most recent tagged release. A gap between the newest tag and ongoing commits is normal for a small metrics package, but it means the released artifact and the repository head are not the same thing. If you depend on a specific metric's behavior, pin the version in your requirements file rather than tracking master. The Python 3.10 floor stated in the README also means older interpreter environments need either an upgrade or an older release, and the README does not document which releases map to which Python versions.

Editorial conclusion

Adopt image-similarity-measures if you are evaluating super-resolution or restoration output and want several metrics in one JSON-emitting call, especially if you work with multispectral or TIFF rasters. Do not adopt it if you need per-region scoring, dataset-scale batch runs, or a single interpretable quality number; the package returns raw metric values and stops there. Verify first that your arrays are channel last and that your TIFF path is covered by rasterio, since OpenCV is the default reader and the two backends are optional installs rather than automatic fallbacks.

Official sources

1. Issues
2. License: MIT
3. nekhtiari/image-similarity-measures on GitHub
4. README
5. Releases