Light Field Coding Toolkit

JPEG Pleno LFC Toolkit

The JPEG Pleno Light Field Coding Common Test Conditions Toolkit (JPEG Pleno LFC Toolkit) contains scripts to help running the JPEG Pleno Light Field Coding Common Test Conditions v4.0.

Limitations

  • Currently we support only PGX, PNG, PPM and YUV file formats.

  • For PGX, PPM, and YUV, only 10 bits per sample is supported.

  • For PNG, only 8 bits per sample is supported.

    • Conversion to 10 bit is done to keep the files coherent with the other formats (PGX, PPM, and YUV).

  • The colour space for the PGX and YUV files is set to BT.709-6 Full range (FR).

  • Only supports 4:4:4 sampling.

  • Only Linux is supported.

Installation & Setup

Clone this repository:

git clone https://gitlab.com/eclufsc/light-field-coding/jpeg-pleno-ctc-tools.git
cd jpeg-pleno-ctc-tools

Prerequisites

The following software must be installed before proceeding:

  • docker

  • docker compose (available in most docker installations)

  • ffmpeg

  • imagemagick

  • gcc

  • git

  • pip

  • python3 (3.12)

  • UV or venv

Note

If the user executes the scripts with Option 1, the only dependency that needs to be pre-installed is docker and docker compose.

Option 2: UV

UV is a fast, modern package and dependency manager written in Rust. It automatically manages virtual environments and installs dependencies — no manual activation needed.

Install UV via the official guide, or install version 0.10.7 directly:

curl -LsSf https://astral.sh/uv/0.10.7/install.sh | sh
uv --version  # verify installation

Option 3: Python venv

If you prefer a standard Python virtual environment:

python3 -m venv ctc
source ctc/bin/activate
pip install -r requirements.txt
pip install -e .

To deactivate when done:

deactivate

Note

If the requirements installation fails, check your Python version (3.12 required).

Running Scripts

For the full CLI reference — flags, commands, and usage examples — see CLI.md.

Docker: Building Codecs

x265, the anchor codec used in CTC v4.0, produces encoded files with different MD5 checksums depending on the compiler version. To ensure reproducibility during cross-checks, we strongly recommend building codecs inside the provided Docker container.

Warning

This step only needs to be done if you have not opted for Option 1. If you will proceed to execute the script with the toolkit Docker Compose, you do not need to reproduce this. Another important warning is that this approach will only work with Options 2 or 3 if the GLIBC version on your machine meets the minimum required version used to build the codec binaries (GLIBC >= 2.41).

Setup

If Docker is not installed, follow the installation guide and the post-installation steps.

From the lfc_toolkit folder, build the image:

cd lfc_toolkit
docker build -t codecs-compilation .

Warning

Run docker without sudo. If you can’t, follow the post-installation steps to fix permissions — otherwise the build step will fail.

Disabling Docker for Build

If needed, you can build codecs without Docker by setting the following in your configuration file:

"codecs": {
    "use-docker-for-build": false
}

Warning

This makes results dependent on your local GCC version. We recommend GCC 14.3.0 (same as the container). You must report this deviation with your results.

Configuration File

All scripts are driven by a JSON configuration file. A basic example is provided at lfc_toolkit/examples/configuration-base-example.json. A more complete example, with all functionalities, is provided at lfc_toolkit/examples/configuration-complete-example.json. The full documentation is available at the repository’s Gitlab Page.

Note

For first executions, we suggest you to use the configuration-base-example.json, updating only the paths of raw-path and ce-path to match your machine.

Aliases

Aliases let you define reusable path variables to avoid repetition:

{
    "aliases": {
        "raw-path": "/home/my-user-name/RAW/lightfields",
        "ce-path":  "/home/my-user-name/JPEG/Pleno/ce16"
    }
}

These can then be referenced anywhere in the config using ${alias-name}:

{
    "raw_paths": {
        "ppm":      "${raw-path}/PPM",
        "ppm11x11": "${raw-path}/PPM_lenslets_11x11",
        "yuv":      "${raw-path}/YUV/serpentine",
        "pgx":      "${raw-path}/PGX"
    }
}

There is also a built-in ${base-path} alias that resolves to the scripts source folder.

Available Scripts

1. Run All Scripts

Runs all processing steps in the correct order (conversion → codecs → metrics → plots → heatmaps):

export LFC_DATA_DIR="../lfc-test" && \
docker compose run --rm lfc-toolkit \
--configuration "path/to/cfg" \
--raw-path /data/raw --ce-path /data/ce

Warning

Running the toolkit on all light fields in the CTC requires approximately 273 GB of storage space.

2. Format Conversion: PPM → YUV/PGX

export LFC_DATA_DIR="../lfc-test" && \
docker compose run --rm lfc-toolkit \
--configuration "path/to/cfg" \
--raw-path /data/raw --ce-path /data/ce \
-convert

Note

Requires PPM files or an internet connection to download them from the JPEG Pleno Light Field Dataset.

3. Codec Execution

Encodes and decodes using all codecs listed under "codecs" → "run" in your configuration:

export LFC_DATA_DIR="../lfc-test" && \
docker compose run --rm lfc-toolkit \
--configuration "path/to/cfg" \
--raw-path /data/raw --ce-path /data/ce \
-codecs

Note

JPLM requires PGX files; x265 requires YUV files.

Available Codecs
JPLM

The JPEG PLeno Model (jplm) is cloned by default to ${base-path}/../temporary/jpeg-pleno-refsw. Overriding the path configuration is recommended. The JPLM version used by default is 3.0.0-rc1.

For the CTC, JPLM must be used with default parameters. To test custom parameters, create an inheriting codec entry:

"jplm-pnt": {
    "inherit": "jplm",
    "results": "${ce-path}/results/jplm_pnt_results",
    "kwargs": {
        "extra_params": "-pnt"
    },
    "rd_preferences": {
        "title": "JPLM - PNT",
        "color": "orange",
        "marker": "X"
    }
}
x265

The scripts use by default the version 4.0 of the codec x265.

Decoded File Conversions

After decoding, the toolkit can automatically convert outputs to additional formats. Configure this under the codec’s decoded_conversions key:

"codecs": {
    "jplm": {
        "decoded_conversions": ["yuv", "ppm"]
    }
}

By default no conversions are performed. If a quality metric requires a specific format, the conversion is handled automatically.

4. Quality Metrics

export LFC_DATA_DIR="../lfc-test" && \
docker compose run --rm lfc-toolkit \
--configuration "path/to/cfg" \
--raw-path /data/raw --ce-path /data/ce \
-metrics

Note

Requires the original raw files and the decoded codec output.

Available Metrics

From YUV files (BT.709-FR) — computed via VMAF:

Metric

Description

psnr_y

Peak Signal-to-Noise Ratio (PSNR) of the Y channel

psnr_cb

PSNR of the Cb (U) channel

psnr_cr

PSNR of the Cr (V) channel

psnr_yuv_average

Average PSNR across Y, U, V (equal weights)

psnr_yuv_weighted

Weighted PSNR: $\frac{6 \times PSNR_Y + PSNR_{Cb} + PSNR_{Cr}}{8}$

float_ssim

Structural Similarity Index (SSIM)

float_ssim_db

SSIM with log adjustment

vmaf

Video Multimethod Assessment Fusion (VMAF)

vmaf_db

VMAF with log adjustment

The CTC requires: PSNR Y, PSNR YUV (weighted), SSIM, and VMAF.

Note

Custom metrics can be added by creating a metric wrapper and declaring it in the configuration file, for cases they are not computed by the VMAF tool.

5. Rate-Distortion Plots

export LFC_DATA_DIR="../lfc-test" && \
docker compose run --rm lfc-toolkit \
--configuration "path/to/cfg" \
--raw-path /data/raw --ce-path /data/ce \
-rd-plots

Note

Requires quality metrics reports and encoded files (for rate data).

Customization options are available for markers, curve color, figure size, figure format (e.g., pdf, png) and interpolation method.

6. Quality Heatmaps

export LFC_DATA_DIR="../lfc-test" && \
docker compose run --rm lfc-toolkit \
--configuration "path/to/cfg" \
--raw-path /data/raw --ce-path /data/ce \
-heatmaps

Note

Requires quality metrics reports.

Contents