TensorForger/RQI-safetensors

RQI: Relative Quality Index

Safetensors re-host of the RQI model from Bridging the Perception Gap in Image Super-Resolution Evaluation (CVC-Color/rqi, original weights at shaolin999/rqi, Apache-2.0). This is not an official release.

This Safetensors file is not compatiple with original repo's code. Use this fork instead.

What is different from the original

	Original	This repo
Weight format	.pt pickle	.safetensors
Self-contained	downloads a ViT backbone from timm at construction time	no extra downloads
Model code	several files, depends on timm and einops	one file, rqi_model.py, depends only on torch
Size	581 MB	485 MB, unused weights removed
Training	inference only	RqiMetric is differentiable, usable as a loss
torch.compile	not checked	works with fullgraph=True

Outputs match the original implementation to about 1e-7 for the same crops.

Model description

RQI compares an image with a reference image. A ViT-B/8 extracts features of both, followed by channel attention, Swin transformers and a patch-weighted score head. The network scores a pair of 224x224 crops. The metric samples random crops at up to three scales (20, 10 and 5 crops, the image is halved between scales) and averages the crop scores.

Class	Input	Output
RqiNetwork	two [B, 3, 224, 224] RGB tensors in [-1, 1]	[B] scores
RqiMetric	two [B, 3, H, W] RGB tensors in [0, 1], H, W >= 224	[B] scores

A higher score means the first image is closer to the reference. RQI is asymmetric: the first argument is the evaluated image, the second is the reference. The score is not normalized: an image compared with itself does not return 1. Both images must have the same size and both sides must be at least 224 pixels, smaller images raise a ValueError.

Installation

git clone https://huggingface.co/tensorforger/RQI-safetensors
cd RQI-safetensors
pip install -r requirements.txt

Usage

import torch
from safetensors.torch import load_file
from rqi_model import RqiMetric, RqiNetwork

network = RqiNetwork()
network.load_state_dict(load_file("model.safetensors"))
metric = RqiMetric(network, seed=20).to("cuda")

# image, reference: [B, 3, H, W], RGB, float32 in [0, 1], H and W >= 224
with torch.no_grad():
    scores = metric(image, reference)  # [B]

seed=20 makes the crops reproducible, seed=None (default) samples new crops on every call.

Use as a training loss

metric = RqiMetric(network, crops_per_scale=(4, 2, 1), gradient_checkpointing=True).to(
    "cuda"
)
loss = (1 - metric(restored, target)).mean()
loss.backward()

Gradients flow only to the first argument, the network is frozen and stays in eval mode. Fewer crops and gradient_checkpointing=True reduce memory a lot. On an RTX 5090, one 1024x1024 image, forward and backward in fp32: the default 35 crops need 27.0 GB (7.4 GB with checkpointing), 7 crops need 5.9 GB (1.9 GB), a single crop needs 1.3 GB (0.7 GB). For inference, max_crops_per_forward=8 lowers the peak memory from 4.0 GB to 1.4 GB without slowing down.

torch.compile

metric.network.compile(fullgraph=True)

Works for inference and for backward passes. On fp32 it gives no speedup, because matrix multiplications dominate, and every new batch size recompiles the network.

Run the bundled demo

The demo builds a synthetic image, distorts it with noise and with a drawn rectangle, prints the RQI scores and plots the images with matplotlib.

python demo.py

Files

File	Content
model.safetensors	weights, fp32
rqi_model.py	RqiNetwork and RqiMetric
config.json	architecture hyperparameters
demo.py	minimal example

License

Weights follow the license of the original Hugging Face repository (Apache-2.0). The upstream code repository does not specify a license.

Citation

@inproceedings{su2026rqi,
  title     = {Bridging the Perception Gap in Image Super-Resolution Evaluation},
  author    = {Su, Shaolin and Rocafort, Josep M. and Xue, Danna and
               Serrano-Lozano, David and Sun, Lei and Vazquez-Corral, Javier},
  booktitle = {Proceedings of the IEEE/CVF Conference on Computer Vision
               and Pattern Recognition (CVPR)},
  year      = {2026}
}