CLI Reference

Options

Configuration

Flag	Short	Description
--configuration	-c	Path to the configuration file (required)
--raw-path	-raw	Absolute path where the RAW light fields are or will be stored. Overrides the value set in the configuration file.
--ce-path	-ce	Absolute path where experiment results, codecs, and other outputs will be stored. Overrides the value set in the configuration file.
--lightfields	-lfs	List of Light Fields separated by space to execute with the scripts. Overrides the list set in the configuration file.

Scripts

Flag	Short	Description
--all	-a	Run all scripts in order. This is the default when no script flag is provided.
--yuv-and-pgx-from-ppm	-convert	Convert light fields from PPM to YUV and PGX formats.
--run-codecs	-codecs	Encode and decode light fields using the codecs defined in the configuration.
--equivalence-check	-equivalence	Run equivalence checks on the encoded/decoded outputs.
--quality-metrics	-metrics	Compute quality metrics (PSNR, SSIM, VMAF…) on the decoded outputs.
--generate-rd-plots	-rd-plots	Generate rate-distortion plots from the quality metrics reports.
--generate-heatmaps	-heatmaps	Generate quality heatmaps from the quality metrics reports.

Note

When --all is used (or no script flag is given), scripts run in the following fixed order: convert → codecs → equivalence → metrics → rd-plots → heatmaps.

---

Running with Docker Compose

To run the toolkit with Docker Compose, execute the following command:

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

The environment variable must be named LFC_DATA_DIR and point to your local data folder. The path/to/cfg is a path inside the container. We recommend the user to include the configuration into the LFC_DATA_DIR. Inside the container, the LFC_DATA_DIR is mapped to /data. Therefore, raw-path and ce-path paths must begin with /data/, in order to access the mounted volume correctly.

Codecs in private repositories

If, for any reason, the user wants to run the Docker Compose to evaluate codecs that are in private repositories, make sure an SSH agent is running:

ssh-add -l

If you receive an error such as: Could not open a connection to your authentication agent, start a new SSH agent with:

eval "$(ssh-agent -s)"

Then add your private key:

ssh-add ~/.ssh/{YOUR_PRIVATE_KEY}

Note

The user can use the CLI flags shown in the next section, as in the example:

export LFC_DATA_DIR="../lfc-test" && \
docker compose run --rm lfc-toolkit \
--configuration lfc_toolkit/examples/configuration-base-example.json \
--raw-path /data/raw --ce-path /data/ce \
-convert --run-codecs --quality-metrics \
--lightfields Bikes

Running with UV

Run all scripts (both lines are equivalent)

uv run lfc-toolkit --configuration "path/to/cfg"
uv run lfc-toolkit --configuration "path/to/cfg" --all

Run a specific script (e.g., run codecs)

uv run lfc-toolkit --configuration "path/to/cfg" --run-codecs

Override paths from the configuration file

uv run lfc-toolkit --configuration "path/to/cfg" --raw-path "/absolute/path/to/raw" --ce-path "/absolute/path/to/ce"

Override the Light Fields list from the configuration file

uv run lfc-toolkit --configuration "path/to/cfg" --lightfields Bikes Danger_de_Mort

Standalone commands

uv run lfc-convert     --configuration "path/to/cfg"
uv run lfc-codecs      --configuration "path/to/cfg"
uv run lfc-metrics     --configuration "path/to/cfg"
uv run lfc-rd-plots    --configuration "path/to/cfg"
uv run lfc-heatmaps    --configuration "path/to/cfg"

Help command

uv run lfc-toolkit --help

To run a script directly:

uv run lfc_toolkit/src/run_codecs.py --configuration "path/to/cfg"

Running with venv

With the venv activated, the same commands are available:

Main Pipeline

python3 lfc_toolkit/src/cli.py --configuration "path/to/cfg"

Individual scripts

python3 lfc_toolkit/src/run_codecs.py              --configuration "path/to/cfg"
python3 lfc_toolkit/src/yuv_and_pgx_from_ppm.py    --configuration "path/to/cfg"
python3 lfc_toolkit/src/compute_quality_metrics.py --configuration "path/to/cfg"
python3 lfc_toolkit/src/generate_rd_plots.py       --configuration "path/to/cfg"
python3 lfc_toolkit/src/generate_heatmaps.py       --configuration "path/to/cfg"