| --- |
| 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. |
|
|
