---
license: mit
library_name: xjpeg
datasets:
  - detection-datasets/coco
tags:
  - image-compression
  - jpeg
  - mozjpeg
  - computer-vision
  - quantization
---

# X-JPEG 0.1

Extending JPEG with neural networks (X-JPEG): Image-adaptive quantization with neural networks for JPEG

X-JPEG predicts image-adaptive JPEG quantization tables. The encoder produces
three 8×8 tables for Y, Cb, and Cr; those tables are passed to MozJPEG or
libjpeg to produce an ordinary, standards-compliant `.jpg`. No neural network
or custom software is required to decode the output.

Developed by **Migel Tissera / Trinity Cloud**.

## Artifact

| File | Purpose | SHA-256 |
|---|---|---|
| `model.safetensors` | Encoder-only weights | `823a305b9cdf6d16e2296644d88a343dfc68621fa8e3d4b3c0125772c50b92e8` |
| `config.json` | Architecture and preprocessing contract | `f4766ca0045dc256645054da19dda60401e9f05d1438f1ef986e77bfd0cf5e87` |
| `benchmark.json` | Sanitized low-rate aggregate results | `41ffb4739cb58e5687a8a200b27b1c5cfd016aae5d823f79a6cae5d22cc791a6` |

The source PyTorch checkpoint was converted with `weights_only=True` and
prediction parity was verified exactly on a deterministic non-square RGB
input. This repository contains no pickle checkpoint or training optimizer
state.

## Use

The PyPI package already contains these weights:

```bash
pip install xjpeg
xjpeg photo.png --target-bpp 0.5
```

To load this Hub snapshot explicitly:

```python
from pathlib import Path
from huggingface_hub import snapshot_download
from xjpeg import XJPEG

snapshot = Path(snapshot_download(
    "migtissera/x-jpeg",
    allow_patterns=["model.safetensors", "config.json"],
))
codec = XJPEG(snapshot / "model.safetensors")
result = codec.compress("photo.png", output="photo.jpg", target_bpp=0.5)
print(result.bpp, result.msssim, result.backend)
```

Source, training code, and methodology:
<https://github.com/trinity-cloud/x-jpeg>

## Model architecture

- 256×256 RGB thumbnail input.
- Four 5×5 stride-2 convolution + reparameterized GDN blocks.
- Final stride-2 head producing a `3×8×8` table bottleneck.
- Frequency-aligned `3×8×8` conditioning from full-resolution DCT-band
  energy.
- Integer tables mapped to `[1, 255]` and stored in JPEG DQT segments.
- Three predicted tables; the package defaults to averaging Cb/Cr only at
  emission time to reduce low-rate header overhead.

The model has 19 tensors in its encoder artifact. The training-only mirror
decoder, table entropy model, coefficient rate model, and optimizer state are
not included.

## Training

The model was trained on COCO train2017. Its differentiable 4:2:0 JPEG
objective combines RGB MS-SSIM, a 0.25-weight luma MS-SSIM guard, and a
learned DCT-symbol rate proxy with rate weight 0.05. Release measurements use
actual encoded files rather than the rate proxy.

## Low-rate evaluation

100 deterministic held-out native-resolution COCO val2017 images, seed
`20260721`, complete-file conventional bpp, pinned MozJPEG pipeline:

| Method | bpp | RGB MS-SSIM ↑ | Y MS-SSIM ↑ | PSNR ↑ |
|---|---:|---:|---:|---:|
| X-JPEG default | 0.49975 | **0.957182** | 0.967685 | 27.045 dB |
| Annex-K + same MozJPEG | 0.50097 | 0.953630 | 0.972323 | 26.958 dB |
| WebP method 6 | 0.50015 | 0.956685 | **0.972758** | **29.164 dB** |
| X-JPEG default | 0.25111 | 0.917638 | 0.932246 | 24.899 dB |
| Annex-K + same MozJPEG | 0.25000 | 0.912369 | 0.938567 | 25.009 dB |
| WebP method 6 | 0.24996 | **0.922521** | **0.942144** | **26.609 dB** |

These results support an RGB MS-SSIM improvement over the declared
standard-table JPEG control. They do not establish general superiority over
WebP; WebP is clearly ahead at 0.25 bpp and in luma/PSNR.

## Intended use and limitations

Intended for lossy compression of natural photographs and research on
adaptive JPEG quantization. It is not an archival or forensic-preservation
codec.

- Other image domains, including medical and scientific imagery, are not
  established.
- Version 0.1.0 does not preserve EXIF or ICC metadata.
- `--target-bpp` performs multiple real encodes per image.
- Encoding is slower than libjpeg; decoding remains ordinary JPEG decoding.
- The 100-image low-rate evaluation should be expanded before making strong
  frontier claims.

## License

The X-JPEG code and model weights are released under the MIT License.
MozJPEG is not included in this model repository; platform wheels may bundle
it under its upstream license notices.