qualisr-lab 0.1.4

A toolkit for extracting IQA features, training regressors, and analyzing super-resolution image quality against human scores.

QualiSR-Lab: Reduced-Reference IQA for SR

Oleg Ryabinin^1,2 | Evgeney Bogatyrev^1,2,3 | Abud Khaled^1,2,3 | Dmitriy Vatolin^1,2,3

¹Lomonosov Moscow State University, 119991, Moscow, Russia

²AI Center, Lomonosov Moscow State University

³MSU Institute for Artificial Intelligence, Lomonosov Moscow State University

🚩 Submitted to ACM MM 2026 Open Source Software.

🔎 Overview

This project studies which features extracted from Low-Resolution (LR) and Super-Resolution (SR) images are most informative for Image Quality Assessment (IQA). Its purpose is to assist researchers in studying the best features for their upscaled image quality metrics by providing a pipeline to extract the features and build a comprehensive graphical summary on their contribution to IQA and correlation of the resulting metric with human scores.

The proposed pipeline is:

1. Prepare labels and features
   Compute image features and attach normalized quality labels.

2. Train regressors
   Fit regression models on the resulting tabular data to obtain a simple Reduced-Reference (RR) quality metric.

3. Analyze feature importance and correlation
   Evaluate feature importance and compute PLCC/SRCC to identify the most informative features for SR quality assessment.

The sections below describe the required data format and the workflow.

🐌 Quickstart With Bundled Sample Data

The fastest smoke test uses the small score/feature CSV sample bundled inside the Python package, so it works after pip installation without downloading the full dataset.

python -m pip install -e ".[regressors]"
qualisr-run-regressors

From a cloned repository, you can also run against the editable root configs/, scores/, and features/ files explicitly:

qualisr-run-regressors --config configs/default.json

Or build Docker image:

docker build -t qualisr-lab .
docker run --rm qualisr-lab

You can run any of the following commands inside the Docker container:

docker run --rm -it --mount type=bind,source="${PWD}",target=/workspace qualisr-lab bash
qualisr --help
qualisr-run-regressors --config configs/default.json

The image installs the package under /app. The optional bind mount above makes your local checkout available at /workspace without replacing the installed package inside the image.

---

🛠️ Installation Options

From PyPI after release:

python -m pip install "qualisr-lab[regressors]"

For the regression pipeline only:

python -m pip install -e ".[regressors]"

For full feature extraction on CPU:

python -m pip install -e ".[features,regressors]"

The legacy fully pinned environment is kept in requirements.txt.

See dataset/readme.md for dataset download notes.

---

🧩 Python API

The CLI remains the recommended way to run full experiments, but installed packages also expose a small stable API:

from qualisr import load_regressor_config, run_regressor_experiment

cfg = load_regressor_config()
result = run_regressor_experiment(cfg, make_plots=False)
print(result["results"])

For the unified pipeline:

from qualisr import PipelineOptions, load_pipeline_config, run_pipeline

cfg = load_pipeline_config()
run_pipeline(cfg, options=PipelineOptions(only_section=["regressors"], no_plots=True))

Implementation modules such as qualisr.regressors, qualisr.features, and qualisr.pipeline remain importable for advanced use.

---

♻️ Full Reproducibility Run

To download the dataset and run feature extraction, PCA, artifact statistics, and regressor analysis end to end:

python -m pip install -e ".[features,regressors]"
qualisr-run-pipeline --config configs/pipeline.json

You can also use BASH script:

bash reproduce_pipeline.sh

The script writes feature-group CSVs such as features/fr.csv, features/nr.csv, and features/vgg.csv, PCA outputs to features/pca/, and plots/results to plots/.

---

🚀 Workflow

You may either launch the whole pipeline in a single command with your JSON config as in previous section or do each step separately:

Step 0 (optional): Prepare reference images

Produce RLFN / SPAN / bicubic images for LR + SR pairs (used to compute FR metrics). The bundled realtime_sr/ directory is a clone-only convenience asset; pip installs do not include these scripts/checkpoints, so pass your own paths for RLFN/SPAN when running outside the repository.

qualisr-make-reference \
  --lr-dir dataset/lr \
  --sr-dirs PASD=dataset/sr/PASD SUPIR=dataset/sr/SUPIR RealESRGAN=dataset/sr/RealESRGAN \
  --out-root dataset/ref \
  --refs bicubic rlfn span \
  --scale 4 \
  --rlfn-script realtime_sr/RLFN/inference-RLFN.py \
  --rlfn-ckpt realtime_sr/RLFN/rlfn-tuned-4x.pth \
  --span-script realtime_sr/SPAN/inference-SPAN.py \
  --span-ckpt realtime_sr/SPAN/span-tuned-4x.pth

Step 1: Compute image features

Compute FR / NR / VGG / ResNet / SigLIP features for SR images and save them into a single CSV file.

SR methods are passed as METHOD=DIR.
Reference image filenames are expected in the format:

<sr_stem>@<sr_method>@<ref_name>.<ext>

qualisr-extract-features \
  --sr-dirs PASD=dataset/sr/PASD SUPIR=dataset/sr/SUPIR RealESRGAN=dataset/sr/RealESRGAN \
  --gt-dir dataset/hr \
  --lr-dir dataset/lr \
  --ref-dirs bicubic=dataset/ref/bicubic rlfn=dataset/ref/rlfn span=dataset/ref/span \
  --features fr,nr,vgg,resnet,siglip \
  --output features/image_features.csv \
  --device cuda

Add --profile to save <output_stem>_profile.csv with mean runtime per feature. Add --profile-flops to also estimate PyTorch model FLOPs for features such as VGG, ResNet, SigLIP, and PyIQA metrics; this implies profiling and reruns model calls, so it is slower.

---

Step 2: Apply PCA to high-dimensional features

Apply Principal Component Analysis (PCA) to high-dimensional feature blocks such as vgg_* and resnet_* in CSV files produced in Step 1.

qualisr-apply-pca \
  --input features/image_features.csv \
  --blocks vgg=vgg_ resnet=resnet_ \
  --n-components 5 10 25 50 75 \
  --test-size 0.2 \
  --split-seed 42 \
  --output-dir features/pca

---

Step 3: Compute artifact-mask statistics

Compute summary statistics for heatmaps stored as .npy, .npy.gz, or compatible compressed files.
Input directories can be passed as PREFIX=DIR to ensure stable sample naming.

qualisr-compute-stats \
  --heatmap-dirs PASD=dataset/heatmaps/PASD SUPIR=dataset/heatmaps/SUPIR RealESRGAN=dataset/heatmaps/RealESRGAN \
  --output features/stats.csv \
  --percentiles 5 95 \
  --area-thresholds 0 0.5 0.75

Add --profile to save <output_stem>_profile.csv with mean runtime and simple operation-count estimates for artifact statistics.

---

Step 4: Fit regressors and analyze results

Train regressors and produce summary on feature importances and correlations. The correlation plot can also include direct NR/FR metric baselines from feature CSV files.

qualisr-run-regressors --config configs/default.json

Add --profile to save regressor_profile.csv with train/predict runtime and estimated prediction FLOPs for tree regressors. If feature profile CSVs are available, pass them with --feature-profile-files or configure profiling.feature_profile_files; the pipeline also saves regressor_total_profile.csv with summed feature + regressor runtime/FLOPs.

You can also use regressors.ipynb notebook for experiments. It trains regressors, evaluates them, and visualizes:

• feature importances,
• PLCC/SRCC correlations,
• feature cross-correlation matrix,
• MOS/prediction scatter plot,
• comparisons across feature groups and model settings.

The first notebook cell describes the workflow for running experiments individually or in batches.

Example outputs:

---

🔬 Feature Types

This section summarizes the feature groups used in the pipeline. For references and guidelines to adding custom features, address features/readme.md.

No-Reference (NR) metrics

NR metrics are widely used in SR-IQA because they do not require a perfect high-resolution reference image. Their main limitation is that they ignore information available in the input LR image, which may cause them to miss or even reward artifacts introduced by SR models.

Recommended NR metrics in this project, based on results from the SR Metrics Benchmark:

• Q-Align
• MUSIQ
• ARNIQA
• UNIQUE
• PaQ2PiQ

These metrics are computed through the PyIQA interface, so the list can be changed easily.

---

Full-Reference (FR) metrics

FR metrics are not always ideal for SR-IQA because they assume access to a perfect reference image. Still, they provide useful information about fidelity.

When true GT images are unavailable, the project uses pseudo-GT references: images obtained by upscaling the LR input with methods that are faithful to the LR image and do not introduce strong hallucinated content.

Reference upscaling methods used here:

• bicubic interpolation
• SPAN
• RLFN

Recommended FR metrics in this project, based on results from the SR Metrics Benchmark:

• LPIPS-VGG
• STLPIPS-VGG
• PieAPP
• AHIQ
• PSNR
• SSIM

These metrics are also computed through PyIQA.

---

Pretrained encoder features (+ PCA)

Feature embeddings from pretrained encoders can capture semantic and perceptual information not covered by classical IQA metrics.

This project uses features extracted from:

• VGG
• ResNet
• SigLIP
• any encoders from timm

Because these embeddings are often high-dimensional, Principal Component Analysis (PCA) can be applied before training regressors.

---

Artifact-mask statistics

Artifacts are common in modern deep-learning-based SR models. The working hypothesis of this project is:

Artifact-related information provides useful signals for assessing generated image quality.

An artifact mask is a single-channel tensor with values in the range [0, 1].
Masks for SR images must be computed beforehand with a suitable method such as Prominence-Aware Artifact Detection metric.

The project extracts the following summary statistics from artifact masks:

• min
• max
• mean
• median
• std
• percentiles
• thresholded artifact area

🎫 License

This project is released under the BSD-3-Clause license.