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 1: Docker Compose (Recommended)

To allow full reproducibility, we compiled the main dependencies (gcc, python, ffmpeg and imagemagick) with the correct versions into a Docker Image (Dockerfile) in the root folder.

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

Warning

The authors highly suggest the usage of Docker Compose. In order to run the scripts using this option, check the CLI command in CLI.md.

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.

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.

JPEG Pleno LFC Toolkit

Limitations

Installation & Setup

Prerequisites

Option 1: Docker Compose (Recommended)

Option 2: UV

Option 3: Python venv

Running Scripts

Docker: Building Codecs

Setup

Disabling Docker for Build

Configuration File

Aliases

Available Scripts

1. Run All Scripts

2. Format Conversion: PPM → YUV/PGX

3. Codec Execution

Available Codecs

JPLM

x265

Decoded File Conversions

4. Quality Metrics

Available Metrics

5. Rate-Distortion Plots

6. Quality Heatmaps

JPEG Pleno LFC Toolkit 

Limitations 

Installation & Setup 

Running Scripts 

Docker: Building Codecs 

Configuration File 

Available Scripts 