Unified Interface For Learned Image Compression (UI-LIC)

This repository provides a unified framework for managing, training, and testing multiple state-of-the-art Learned Image Compression (LIC) models through a single, consistent interface. It simplifies the complex setup and execution requirements of various research models into a streamlined workflow.

Core Workflow

1. Environment Setup

Note: This repository targets Linux-based systems with an NVIDIA GPU. We tested primarily on Ubuntu 24.04 and WSL2 across RTX 30-series, 40-series, and 50-series GPUs. If you run into issues on your operating system (especially with the automatic setup and GUI commands), please file an issue on our GitHub page. Automatic environment setup handles C++ compiler toolchains (gxx_linux-64), CUDA shared libraries, and hardware compatibility flags out of the box.

System Prerequisites

Before setting up your virtual environments, ensure your system has the necessary external libraries and tools installed.

Docker (Required for VMAF)

The evaluation pipeline uses Docker to calculate the VMAF (Video Multi-Method Assessment Fusion) metric. This ensures that a correctly compiled version of FFmpeg with libvmaf is available regardless of your host OS configuration.

Requirement: Docker Desktop (Mac/Windows) or Docker Engine (Linux) must be installed and running.
Implementation: The system uses the mwader/static-ffmpeg image. Local images are dynamically mounted into the container as read-only volumes for comparison, avoiding the need for a complex local FFmpeg installation.

OS-Level Dependencies

For standard frame manipulation and other video-based tasks, the ffmpeg binary is still recommended on your host system:

# For Ubuntu/Debian based systems
sudo apt-get update
sudo apt-get install ffmpeg

Install and activate Anaconda

Environment setup

Each LIC model often requires a specific environment with distinct dependencies.

Batch Setup (quick-start.py, recommended!) : Use this to automatically create environments and download weights for ALL integrated models at once.
```
python quick-start.py
```
Features:
- Interactive Selection: Choose specifically which models to set up and which pretrained weights to download.
- Quality/Lambda Selection: For models like StableCodec or HPCM, you can select specific quality levels to save bandwidth and disk space.
- Confirmation Summary: Review a full plan (including checks for previously installed environments or weights) before any changes are made.
- Automatic Dependency Mapping: Uses the recommended Python versions and requirements files defined for each model automatically.
Individual Setup (create-env.py): Use this to create an environment for a single model with custom settings.
```
python create-env.py
```

Qualities & Weights Explanation

Different models use different scales for their pretrained weights. Generally:

Lambda (λ): A higher λ value means the model is optimized for higher quality (and higher bitrate), while a lower λ means higher compression (and lower quality).
Metric: Models are typically optimized for either MSE (standard PSNR-focused) or MS-SSIM (perceptual-focused).

Model-Specific Scales:

StableCodec: Uses ft (finetuned) numbers. Higher numbers (e.g., ft32) target extreme compression (~0.005 bpp), while lower numbers (e.g., ft2) provide higher quality (~0.035 bpp).
RwkvCompress (LALIC): Uses quality levels q1 to q6. q1 is the highest compression (lowest bitrate), and q6 is the highest quality.
HPCM: Provides Base and Large versions. Each has 6 quality levels for both MSE and MS-SSIM metrics.
LIC-TCM: Provides N=128 (Large) and N=64 (Small) variants. The quality ranges from λ=0.0025 (highest compression) to λ=0.05 (highest quality).

2. GUI Evaluation (inference and analysis)

Launch the GUI app with python ./GUI-Visualizer/desktop_app.py.

From the start page, you can select the inference dataset directory, enable/disable codecs for inference and analyis, tune codec-specific settings, and launch the evaluation pipeline.

After inference has been performed, on the "Visual Comparison" tab you can compare two image reconstructions side by side. The vertical blue line is a slider to adjust the viewport of the two images. The quality metrics may be toggled, and a number of error overlay maps be visualized. For example, this image shows the LPIPS feature maps, conveying the areas of greatest perceptual error.

On the "Metrics Report" tab, you can view all the quantitative metrics for each codec and input image individually, or you can view the mean results of each codec.

3. CLI Configuration Generation (`configure-jobs.py`)

Instead of manually editing JSON files, use configure-jobs.py to interactively build your queue for CLI-based training and inference jobs.

What it does:

Scans Interfaces/ to find all registered models (e.g., StableCodec, ELIC).
Prompts for Global Arguments (shared across all tasks like cuda, batch_size).
Prompts for Task-Specific Arguments for each model you want to run.
Automatically handles argument aliases and provides default values.
Generates a valid arguments.json file ready for the dispatcher.

How to use:

# Start interactive configuration
python configure-jobs.py

# Options:
# --train       : Configure training jobs
# --test        : Configure testing/evaluation jobs
# --output      : Specify custom output filename (default: arguments.json)

4. Running the Dispatcher (`dispatcher.py`)

The dispatcher.py script is the execution engine that processes the arguments.json queue.

What it does:

Environment Switching: Automatically runs each task within its dedicated Conda environment.
Path Validation: Interactively verifies that all input datasets and checkpoints exist before starting.
Safety Checks: Verifies that dataset images meet the minimum patch_size requirements to prevent PyTorch dataloader crashes.
Automated Evaluation: After testing tasks finish, it automatically triggers evaluation.py to calculate final metrics and aggregate results.

How to use:

# Execute the training and/or testing queue
python dispatcher.py --train --test

# Optional: Specify a custom configuration file
python dispatcher.py --train --args_json my_config.json

Technical Architecture

Unified Interfaces (`Interfaces/`)

The Interfaces/ directory contains the "bridge" logic for each model. Each interface file defines:

TASK_NAME: The identifier used in the JSON config.
CLI_MAPPING: Maps unified argument names to the model's specific CLI flags.
REQUIRED_ARGS: Ensures the dispatcher doesn't start a job with missing parameters.
ALIASES: Allows flexible naming (e.g., data, dataset, and test_dataset all map to the same parameter).

Evaluation Pipeline (`evaluation.py`)

The dispatcher automatically hands off results to evaluation.py. This script handles:

Calculating PSNR, SSIM, LPIPS, and BPP.
VMAF Evaluation: Optional high-quality perceptual metric calculated via Dockerized FFmpeg.
Aggregating results into structured reports in the save-dir.

Enabling VMAF: To enable VMAF, add "use_vmaf": true to the evaluation block in your arguments.json, or pass the --use_vmaf flag when running evaluation.py manually.

Integration Guidelines

This guide outlines everything a researcher needs to know to integrate a new Learned Image Compression (LIC) model into the UI-LIC framework. Integrating a model enables it to work with the interactive CLI generator (configure-jobs.py), execution dispatcher (dispatcher.py), metric evaluation pipeline (evaluation.py), and visual comparison desktop application (GUI-Visualizer).

Step 1: Model Codebase Setup (`LIC-Models/<ModelName>/`)

Place your model repository source code under LIC-Models/<ModelName>/. A typical structure includes:

LIC-Models/<ModelName>/
├── weights/                  # Pretrained model checkpoints (.pth, .pkl, etc.)
├── custom-evaluation.py      # Dedicated evaluation/inference script for UI-LIC
├── requirements.txt          # Python dependencies specific to this model
└── src/                      # Model architectures, layers, and entropy coders

Step 2: Model Evaluation Script & Generalization (Suggested Best Practices)

When evaluating models within UI-LIC, the primary goal of your inference/testing script is to generate reconstructed images and bitstreams that UI-LIC's evaluation.py and GUI visualizer can process automatically.

Tip — Dedicated Custom Evaluation Script:
If modifying the upstream repository's original inference script is invasive or complex, we strongly suggest creating a lightweight custom evaluation script (e.g. custom-evaluation.py or test_image_encoding.py) inside LIC-Models/<ModelName>/.

Suggested Generalization Best Practices:

Note: The following are recommended guidelines to improve portability across hardware and datasets. Certain LIC models may have inherent hardware or architectural constraints.

Input & Resolution Agnosticism: Ensure your evaluation script accepts arbitrary image formats (.png, .jpg, .jpeg, .webp) and handles variable input image dimensions dynamically without assuming fixed patch sizes (e.g., $256 \times 256$).
Filename Standardization: Strip model-specific filename prefixes/suffixes (such as rec_, bits_, or bitrate values) from your output files. Save reconstructed images as <base_name>.<ext> (e.g., kodim01.png) and bitstreams as <base_name>.pt or <base_name>.bin (e.g., kodim01.pt). This ensures 1-to-1 matching with original dataset filenames.
Architecture Parameter Exposure: Avoid hardcoding model architecture hyperparameters (e.g., channel counts -N 128, heads, or quality scaling factors) inside Python files. Expose them via CLI arguments so UI-LIC can evaluate different model variants.
Hardware & Device Abstraction: Avoid hardcoding specific CUDA device indices (cuda:0) or GPU series assumptions. Use dynamic PyTorch device selection:
```
device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
```

Step 3: Environment & Pretrained Weight Registration (`quick-start.py`)

To allow users to automatically build Conda environments and download pre-trained weights for your model using quick-start.py, register your model's weight checkpoints in the WEIGHTS_DATA dictionary in quick-start.py using Google Drive file IDs:

"YourModelName": {
    "base_path": "LIC-Models/YourModelName/weights/",
    "description": "Short description of model quality variants.",
    "options": [
        {"name": "your_model_q1.pth", "id": "GOOGLE_DRIVE_FILE_ID", "desc": "Quality level 1 / Lambda X"},
        ...
    ]
}

Each checkpoint entry under "options" requires a "name" (target file name), "id" (the Google Drive file ID used for automated downloading), and an optional "desc" (description of the quality level or lambda value).

Also ensure your model has a requirements.txt file inside its directory so create-env.py can construct its Conda environment.

Step 4: Implementing the Unified Interface (`Interfaces/`)

The core bridge between UI-LIC and your model is an Interface class inheriting from BaseInterface (base_interface.py).

Important:
The primary objective of the testing interface is to bridge CLI/GUI parameters to your model's evaluation script so it produces outputs compatible with UI-LIC's metric pipeline.

Create a testing interface script in Interfaces/Testing-Interfaces/<ModelName>-Testing-Interface.py (and optionally a training interface in Interfaces/Training-Interfaces/<ModelName>-Training-Interface.py).

This interface script serves as the translation layer between UI-LIC and your model:

Parameter Mapping: It receives standardized UI-LIC arguments (e.g., dataset, checkpoint, save_dir) and uses CLI_MAPPING to translate them directly into the specific command-line flags expected by your model's evaluation script (e.g., --data, --checkpoint, --save_dir).
Command Construction & Execution: It sets EXECUTION_PATH to point to your model's evaluation script (e.g., LIC-Models/<ModelName>/custom-evaluation.py), constructs the full shell command, and executes it within the model's environment.

Note — GUI Discovery & Scope:
Placing your testing interface in Interfaces/Testing-Interfaces/ allows the GUI application (GUI-Visualizer/desktop_app.py) to automatically discover your model's TASK_NAME and auto-generate parameter input fields. Note that the GUI is designed exclusively for inference, visual side-by-side comparison, and metric reporting. Model training is executed via CLI (configure-jobs.py and dispatcher.py).

Interface Template:

import os
from base_interface import BaseInterface

class YourModelTestInterface(BaseInterface):

    # 1. TASK_NAME must be unique and match your model identifier
    TASK_NAME = "YourModelName"
    
    USE_MODULE_EXECUTION = False
    EXECUTION_PATH = "LIC-Models/YourModelName/custom-evaluation.py"
    WORKING_DIR = "LIC-Models/YourModelName"  # Optional: execution working dir

    # 2. Parameters required for job execution
    REQUIRED_ARGS = ["checkpoint", "dataset", "save_dir"]
    
    # 3. Boolean switch flags (passed without trailing values)
    ACTION_FLAGS = ["cuda", "half"]

    # 4. Default parameter values
    DEFAULT_VARS = {
        "checkpoint": None,
        "dataset": None,
        "save_dir": None,
        "cuda": True,
        "half": False,
    }

    # 5. Parameter aliases (e.g. mapping global UI-LIC parameter names to standard keys)
    ALIASES = {
        "test_dataset": "dataset",
        "data": "dataset",
        "output": "save_dir",
        "out": "save_dir"
    }

    # 6. Map unified internal keys to your CLI flags
    CLI_MAPPING = {
        "checkpoint": "--checkpoint",
        "dataset": "--data",
        "save_dir": "--save_dir",
        "cuda": "--cuda",
        "half": "--half"
    }

    def __init__(self, job_args=None, global_args=None):
        super().__init__(job_args, global_args)
        
        # Fallback to global test_dataset if not provided locally
        if not self.params.get("dataset") and global_args and "test_dataset" in global_args:
            self.params["dataset"] = global_args["test_dataset"]

        # Ensure target directory and input paths are resolved to absolute paths
        for key in ["checkpoint", "dataset", "save_dir"]:
            if self.params.get(key):
                self.params[key] = os.path.abspath(os.path.expanduser(self.params[key]))

Step 5: Output Directory Contract & File Naming Conventions

When your model's evaluation script receives the --save_dir parameter, it must structure its output files into the following directory layout so evaluation.py and the GUI app can compute metrics automatically:

<save_dir>/
├── reconstruction/          (or reconstructions/)
│   ├── kodim01.png
│   ├── kodim02.png
│   └── ...
└── bitstreams/              (or bitstream/)
    ├── kodim01.pt           (or kodim01.bin)
    ├── kodim02.pt
    └── ...

Key Output Rules:

Reconstructed Images (<save_dir>/reconstruction/): Save decoded image files with filenames matching the exact base name of the input image (<image_base_name>.<ext>). Valid formats include .png, .jpg, .jpeg, and .webp.
Bitstream Files (<save_dir>/bitstreams/): Save bitstream files or string payloads using <image_base_name>.pt or <image_base_name>.bin. UI-LIC calculates Bit-Per-Pixel (BPP) automatically based on the size of the bitstream file in bits divided by original image dimensions ($W \times H$).
Automated Evaluation: Once inference completes, dispatcher.py automatically invokes evaluation.py on <save_dir>, calculating PSNR (RGB & YUV), SSIM, LPIPS, BPP, and optional Docker-based VMAF scores.

Step 6: Verification Checklist

After adding your model code, custom evaluation script, and interface class, verify your integration using the following steps:

CLI Job Configuration: Run python configure-jobs.py --test and verify your model's TASK_NAME appears in the list of available models and prompts for all required arguments.
Execution Dispatcher: Run python dispatcher.py --test with your generated arguments.json to verify environment switching, job execution, and automatic triggering of evaluation.py.
GUI Visualizer (Inference & Evaluation): Launch python ./GUI-Visualizer/desktop_app.py. Verify that your testing interface (located in Interfaces/Testing-Interfaces/) is dynamically discovered in the codec list, inference executes cleanly, and image reconstructions and metric reports display properly in the visualizer tabs.

Integrated Models

The following models are integrated into the platform, each with a specialized interface to bridge their unique CLI requirements:

StableCodec

Taming One-Step Diffusion for Extreme Image Compression (ICCV 2025)

Recommended Python Version: 3.10
Core Concept: Uses a one-step diffusion process (SD-Turbo) combined with a dual-branch coding structure.
Strength: Exceptional visual realism at ultra-low bitrates (as low as 0.005 bpp).

50-Series Compatibility Changes

StableCodec.py: Added _encode_latent helper that casts inputs to the model's native dtype before VAE encoding; denoised latents are also cast back before decoding to prevent dtype mismatches on 50-series cards.
latent_codec.py: get_mask_four_parts now accepts and propagates an explicit dtype argument for all four checkerboard masks; compress_group_with_mask and decompress_group_with_mask cast their return tensors back to the input dtype.

ELIC

Efficient Learned Image Compression with Context-Adaptive Masked Modeling

Recommended Python Version: 3.10
Strength: State-of-the-art Rate-Distortion performance, balancing complexity and compression.

50-Series Compatibility Changes

Network.py: Imports of trunc_normal_, GaussianConditional, and ste_round now use try/except fallback chains to support both old and new timm/compressai API locations.
Network.py: load_state_dict now calls self.update(force=True) after loading weights to rebuild entropy coding tables required by newer compressai versions.
requirements.txt: Loosened from pinned CUDA 11 packages to >=-bounded versions targeting PyTorch 2.4+; added numpy<2.0.0 upper bound to avoid ABI breakage.

DCVC-RT

Deep Contextual Video Compression - Real Time

Recommended Python Version: 3.12
Strength: Optimized for low-latency and real-time performance. Foundation for video tasks.

50-Series Compatibility Changes

rans.cpp: Output buffer allocation increased to 4× symbol count + 10000 with a pointer bounds assertion, fixing a buffer-overrun crash on sm_120 (RTX 50-series) hardware.
setup.py: Removed the -arch=native nvcc flag; compute capability is now detected at runtime instead of being baked in at build time.
requirements.txt: Added ninja and nvidia-cuda-nvcc to ensure the JIT/AOT build toolchain is always available.
Testing interface: Extracted a compile_extensions method so create-env.py can trigger C++ and CUDA extension compilation automatically after pip install.

LIC-TCM

Learned Image Compression with Mixed Transformer-CNN Architectures

Recommended Python Version: 3.10
Strength: Superior context modeling for complex textures using Transformers.

50-Series Compatibility Changes

requirements.txt: CUDA index URL updated from cu121 to cu128; PyTorch/torchvision/torchaudio minimums bumped to >=2.4.0/>=0.19.0/>=2.4.0 for sm_120 (Blackwell) wheel support.
Testing interface: Added explicit ENV_PATH and WORKING_DIR class attributes so the dispatcher and create-env.py can locate the environment without relying on inferred paths.

LIC-HPCM

Learned Image Compression with Hierarchical Progressive Context Modeling

Recommended Python Version: 3.10
Strength: Optimized for hardware acceleration and fast parallel decoding.

50-Series Compatibility Changes

HPCM_Base, HPCM_Base_PhiContext, HPCM_Large: adaptive_params_list parameters no longer hard-code device='cuda' at construction, removing the import-time CUDA dependency.
entropy_models/__init__.py and entropy_models.py: Added try/except relative/absolute import fallbacks for the compiled _CXX extension.
requirements.txt: PyTorch/torchvision/torchaudio minimums bumped to >=2.4.0/>=0.19.0/>=2.4.0.
Testing interface: Added compile_extensions and _check_and_install_dependencies to automatically build the unbounded_rans C++ extension if it is missing from the active environment.

RwkvCompress

Efficient Learned Image Compression via RWKV architecture

Recommended Python Version: 3.10
Strength: Global dependency modeling with linear-attention computational efficiency.

50-Series Compatibility Changes

biwkv4_cuda_new.cu: Replaced deprecated k.type() with k.scalar_type() in both AT_DISPATCH_FLOATING_TYPES calls to fix a compile error with modern PyTorch.
lalic.py: JIT load logic now detects the GPU's compute capability at startup and generates matching -gencode arch=compute_XY,code=sm_XY flags dynamically instead of hardcoding sm_86; the loaded module is also cached to avoid redundant recompilation.
eval.py: Removed erroneous .item() call on IQA metric tensors.
requirements.txt: Added ninja and nvidia-cuda-nvcc as explicit dependencies.

Kodak Benchmark Results & Publication Vector Figures

The UI-LIC Kodak Benchmark Suite evaluates 285 compression tasks across all integrated learned image codecs and standard video codecs on the Kodak dataset (24 images).

Below are the Rate-Distortion (RD) curves, family breakdowns, and BD-rate savings bar charts rendered as lightweight, crisp SVG vector figures.

1. Unified Rate-Distortion (RD) Curves & Variance

Metric	Vector Figure (SVG)
PSNR (dB)
SSIM
LPIPS (Lower is Better)
Per-Image Variance ($\pm 1\sigma$)

2. Model Family Breakdown Figures

StableCodec Checkpoint Finetuning Progression (Scaled to Ultra-Low BPP Points)

Metric	Vector Figure (SVG)
PSNR (dB)
SSIM
LPIPS (Lower is Better)

Learned Neural Codecs Comparison

Metric	Vector Figure (SVG)
PSNR (dB)
SSIM
LPIPS (Lower is Better)

HPCM Model Family (Base vs Large, MSE vs SSIM)

Metric	Vector Figure (SVG)
PSNR (dB)
SSIM
LPIPS (Lower is Better)

Standard Video Codecs (AV1, HEVC, AVC)

Metric	Vector Figure (SVG)
PSNR (dB)
SSIM
LPIPS (Lower is Better)

3. BD-Rate Bitrate Savings Bar Charts

Reference Anchor	Vector Figure (SVG)
AV1 Anchor
HEVC Anchor
AVC Anchor
ELIC Anchor

4. BD-Rate Benchmark Results Tables

Note: Generative codecs (e.g. StableCodec) are excluded from BD-rate comparison. BD-rate requires both codecs to perform faithful signal reconstruction on the same quality axis. Diffusion-based codecs synthesise plausible images rather than reconstructing pixels, making cross-paradigm BD comparisons conceptually invalid.

BD-Rate Comparison (Anchor: `AV1`)

Model	Type	BD-Rate (PSNR)	BD-Rate (SSIM)	BD-Rate (LPIPS)	BD-PSNR (dB)
HEVC	Predictive	+6.69%	+0.78%	-9.23%	-0.27 dB
RwkvCompress	Predictive	-10.98%	+5.44%	+11.50%	+0.52 dB
HPCM_Base_SSIM	Predictive	+114.99%	-3.46%	+2.15%	-2.93 dB
HPCM_Base	Predictive	-13.79%	+2.92%	+12.71%	+0.67 dB
DCVC-RT	Predictive	-44.52%	-34.45%	-28.83%	+2.54 dB
AVC	Predictive	+20.96%	+9.33%	-8.24%	-0.79 dB
ELIC	Predictive	-38.29%	-29.66%	-24.17%	+2.10 dB
StableCodec	Generative	—	—	—	—
LIC-TCM	Predictive	-4.20%	+10.14%	+18.29%	+0.26 dB
HPCM_Large_SSIM	Predictive	+105.15%	-5.19%	+0.50%	-2.78 dB
HPCM_Large	Predictive	-17.40%	+1.24%	+11.97%	+0.85 dB

BD-Rate Comparison (Anchor: `HEVC`)

Model	Type	BD-Rate (PSNR)	BD-Rate (SSIM)	BD-Rate (LPIPS)	BD-PSNR (dB)
AV1	Predictive	-6.27%	-0.77%	+10.17%	+0.27 dB
RwkvCompress	Predictive	-16.99%	+3.35%	+21.17%	+0.88 dB
HPCM_Base_SSIM	Predictive	+79.39%	-5.95%	+10.56%	-2.48 dB
HPCM_Base	Predictive	-19.52%	+1.24%	+22.70%	+1.03 dB
DCVC-RT	Predictive	-52.83%	-45.41%	-37.03%	+3.15 dB
AVC	Predictive	+7.57%	+0.49%	-7.65%	-0.35 dB
ELIC	Predictive	-46.44%	-39.34%	-29.30%	+2.70 dB
StableCodec	Generative	—	—	—	—
LIC-TCM	Predictive	-10.07%	+9.73%	+29.48%	+0.59 dB
HPCM_Large_SSIM	Predictive	+72.87%	-7.73%	+8.59%	-2.32 dB
HPCM_Large	Predictive	-23.20%	-1.65%	+20.08%	+1.24 dB

BD-Rate Comparison (Anchor: `AVC`)

Model	Type	BD-Rate (PSNR)	BD-Rate (SSIM)	BD-Rate (LPIPS)	BD-PSNR (dB)
HEVC	Predictive	-7.04%	-0.48%	+8.28%	+0.35 dB
AV1	Predictive	-17.32%	-8.53%	+8.98%	+0.79 dB
RwkvCompress	Predictive	-26.79%	-4.67%	+19.93%	+1.42 dB
HPCM_Base_SSIM	Predictive	+65.79%	-13.17%	+9.33%	-2.00 dB
HPCM_Base	Predictive	-29.04%	-6.71%	+21.39%	+1.57 dB
DCVC-RT	Predictive	-57.51%	-47.66%	-35.28%	+3.49 dB
ELIC	Predictive	-51.85%	-42.36%	-28.10%	+3.00 dB
StableCodec	Generative	—	—	—	—
LIC-TCM	Predictive	-20.91%	+0.80%	+28.09%	+1.16 dB
HPCM_Large_SSIM	Predictive	+59.71%	-14.79%	+7.41%	-1.85 dB
HPCM_Large	Predictive	-32.18%	-9.04%	+19.02%	+1.74 dB

BD-Rate Comparison (Anchor: `ELIC`)

Model	Type	BD-Rate (PSNR)	BD-Rate (SSIM)	BD-Rate (LPIPS)	BD-PSNR (dB)
HEVC	Predictive	+86.71%	+64.86%	+41.44%	-2.70 dB
AV1	Predictive	+62.05%	+42.17%	+31.88%	-2.10 dB
RwkvCompress	Predictive	+43.56%	+50.04%	+46.99%	-1.63 dB
HPCM_Base_SSIM	Predictive	+278.18%	+38.02%	+35.95%	-4.97 dB
HPCM_Base	Predictive	+38.69%	+46.05%	+48.18%	-1.47 dB
DCVC-RT	Predictive	-11.30%	-6.95%	-7.35%	+0.45 dB
AVC	Predictive	+107.70%	+73.50%	+39.07%	-3.00 dB
StableCodec	Generative	—	—	—	—
LIC-TCM	Predictive	+53.85%	+55.22%	+53.08%	-1.98 dB
HPCM_Large_SSIM	Predictive	+263.45%	+35.62%	+34.14%	-4.83 dB
HPCM_Large	Predictive	+33.46%	+44.76%	+48.45%	-1.26 dB

Name		Name	Last commit message	Last commit date
GUI-Visualizer		GUI-Visualizer
Interfaces		Interfaces
LIC-Models		LIC-Models
assets/benchmark_figures		assets/benchmark_figures
scripts		scripts
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
base_interface.py		base_interface.py
configure-jobs.py		configure-jobs.py
create-env.py		create-env.py
dispatcher.py		dispatcher.py
evaluation-requirements.txt		evaluation-requirements.txt
evaluation.py		evaluation.py
example-arguments.json		example-arguments.json
quick-start.py		quick-start.py
vmaf_docker.py		vmaf_docker.py

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

Unified Interface For Learned Image Compression (UI-LIC)

Core Workflow

1. Environment Setup

System Prerequisites

Docker (Required for VMAF)

OS-Level Dependencies

Environment setup

Qualities & Weights Explanation

Model-Specific Scales:

2. GUI Evaluation (inference and analysis)

3. CLI Configuration Generation (configure-jobs.py)

4. Running the Dispatcher (dispatcher.py)

Technical Architecture

Unified Interfaces (Interfaces/)

Evaluation Pipeline (evaluation.py)

Integration Guidelines

Step 1: Model Codebase Setup (LIC-Models/<ModelName>/)

Step 2: Model Evaluation Script & Generalization (Suggested Best Practices)

Suggested Generalization Best Practices:

Step 3: Environment & Pretrained Weight Registration (quick-start.py)

Step 4: Implementing the Unified Interface (Interfaces/)

Interface Template:

Step 5: Output Directory Contract & File Naming Conventions

Key Output Rules:

Step 6: Verification Checklist

Integrated Models

StableCodec

50-Series Compatibility Changes

ELIC

50-Series Compatibility Changes

DCVC-RT

50-Series Compatibility Changes

LIC-TCM

50-Series Compatibility Changes

LIC-HPCM

50-Series Compatibility Changes

RwkvCompress

50-Series Compatibility Changes

Kodak Benchmark Results & Publication Vector Figures

1. Unified Rate-Distortion (RD) Curves & Variance

2. Model Family Breakdown Figures

StableCodec Checkpoint Finetuning Progression (Scaled to Ultra-Low BPP Points)

Learned Neural Codecs Comparison

HPCM Model Family (Base vs Large, MSE vs SSIM)

Standard Video Codecs (AV1, HEVC, AVC)

3. BD-Rate Bitrate Savings Bar Charts

4. BD-Rate Benchmark Results Tables

BD-Rate Comparison (Anchor: AV1)

BD-Rate Comparison (Anchor: HEVC)

BD-Rate Comparison (Anchor: AVC)

BD-Rate Comparison (Anchor: ELIC)

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

3. CLI Configuration Generation (`configure-jobs.py`)

4. Running the Dispatcher (`dispatcher.py`)

Unified Interfaces (`Interfaces/`)

Evaluation Pipeline (`evaluation.py`)

Step 1: Model Codebase Setup (`LIC-Models/<ModelName>/`)

Step 3: Environment & Pretrained Weight Registration (`quick-start.py`)

Step 4: Implementing the Unified Interface (`Interfaces/`)

BD-Rate Comparison (Anchor: `AV1`)

BD-Rate Comparison (Anchor: `HEVC`)

BD-Rate Comparison (Anchor: `AVC`)

BD-Rate Comparison (Anchor: `ELIC`)