JLD Perceptual Distance

JLD Perceptual Distance

Scores how different a distorted image looks from its reference, with a lens overlay showing where. For image quality researchers who want to try the JLD metric in a browser.

Made by shreshthsaini on Hugging Face. These notes are Mindket's, written from its Space page and README; the app's own files and license are on Hugging Face.

About

What it is: This demo scores how far a distorted image sits from its reference. You upload an aligned pair, pick JLD or JLD-fast, and get one distance number plus an overlay of the local lens response. A lower number means the two images look more alike.

Who it suits: It suits researchers and engineers who compare image quality and want to try the JLD metric before using its Python package.

Industry | Who uses it | How they use it | Example
Image research | Quality-metric researchers | Try a perceptual distance on image pairs | Score a reference and a distorted copy
Video and imaging | Codec and pipeline engineers | Check how a processing step changes an image | Compare a source frame with its processed version
Machine learning | Model developers | Judge output of a restoration or generation model | Score a result image against its target
Teaching | Instructors | Show how a metric reacts to distortion | Upload a pair and read the overlay together

You can skip it if your images are not aligned or not the same size, since the metric needs aligned pairs.

Where to use it:

• A web browser, on the Space's page at Hugging Face
• Your own computer, running Python 3.12 on Windows, macOS or Linux
• Your own Python code, through the jld package

Use case | Who | What they get back
Score an image pair | Researchers | A single distance, lower for more similar images
See where they differ | Engineers | An overlay of the local lens response
Score at full size | Developers | Native-resolution scores through the local package

How to set it up:

• Nothing to install if you use the Space online
• Python 3.12, if you run a copy of the Space
• The packages in requirements.txt
• Optionally uv, for the local commands the README shows

1. Open the Space's page on Hugging Face to use it online.
2. To run a copy, install huggingface_hub and download the Space into a folder.
3. Move into that folder and install Gradio at the pinned version, then the listed packages.
4. Start the app with Python.

pip install -U huggingface_hub
hf download shreshthsaini/JLD-demo --repo-type space --local-dir JLD-demo
cd JLD-demo
pip install gradio==6.29.1
pip install -r requirements.txt
python app.py

The README also shows how to run the Space checkout with uv.

uv run --python 3.12 --with-requirements requirements.txt app.py

How to use it: Upload the reference image and the distorted image, choose JLD or JLD-fast, and run it. Both images must be aligned and the same size. Each image may hold at most 24 megapixels, measure at most 8192 pixels along its long edge, and weigh at most 10 MB. For native-resolution scoring of larger images, use the local package from Python.

from jld import JLD

metric = JLD.pretrained("full")
distance = metric("reference.png", "distorted.png")

Example: Upload a reference photo and a copy that has been compressed. Pick JLD and run it. You get one distance value and an overlay of the lens response, and the result also lists the original, resized and scored sizes.

For newcomers and experts: If you are new, upload two copies of the same picture first, one of them slightly changed, and read the number. A lower number means they look more alike.

If you know the field, the demo is the author's interactive version of a perceptual distance built on a Jacobian lens. By default a large pair is scaled down as one unit, through a single Lanczos filter, so it fits the hosted limits. The reported score then covers the scaled pair. A checkbox turns this off and asks for native resolution. The overlay leaves out the global CLS term and is scaled separately for each pair.

You upload an aligned image pair
Large pairs are shrunk together by default
The app scores the pair with JLD or JLD-fast
You get a distance and a lens overlay

Good to know:

• License: mit for the code. Bundled example images have their own provenance notes, and the encoder weights keep their upstream license.
• Cost to run: none named. Hosted use runs on free, shared ZeroGPU time, where waiting and daily caps can apply.
• Data it reaches: the image pairs you upload. The README says uploads and scores are not stored on purpose, but the platforms can hold temporary copies.
• Not for: unaligned or differently sized images, or native-resolution scoring of large pairs on the hosted Space. Use the local package for those.

On Hugging Face, 13 November 2026

• Likes: 2
• Built with: gradio
• License: mit

Links

• Space: https://huggingface.co/spaces/shreshthsaini/JLD-demo
• Files: https://huggingface.co/spaces/shreshthsaini/JLD-demo/tree/main

Try it

Open the Space in your browser, or copy it to your own Hugging Face account from its page. Nothing in this kit runs by itself.