gecko-dev/third_party/jpeg-xl/README.md

JPEG XL reference implementation

This repository contains a reference implementation of JPEG XL (encoder and decoder), called libjxl.

JPEG XL is in the final stages of standardization and its codestream format is frozen.

The libraries API, command line options and tools in this repository are subject to change, however files encoded with cjxl conform to the JPEG XL format specification and can be decoded with current and future djxl decoders or libjxl decoding library.

Quick start guide

For more details and other workflows see the "Advanced guide" below.

Checking out the code

git clone https://gitlab.com/wg1/jpeg-xl.git --recursive

This repository uses git submodules to handle some third party dependencies under third_party/, that's why is important to pass --recursive. If you didn't check out with --recursive, or any submodule has changed, run: git submodule update --init --recursive.

Important: If you downloaded a zip file or tarball from the web interface you won't get the needed submodules and the code will not compile. You can download these external dependencies from source running ./deps.sh. The git workflow described above is recommended instead.

Installing dependencies

Required dependencies for compiling the code, in a Debian/Ubuntu based distribution run:

sudo apt install cmake pkg-config libbrotli-dev

Optional dependencies for supporting other formats in the cjxl/djxl tools, in a Debian/Ubuntu based distribution run:

sudo apt install libgif-dev libjpeg-dev libopenexr-dev libpng-dev libwebp-dev

We recommend using a recent Clang compiler (version 7 or newer), for that install clang and set CC and CXX variables. For example, with clang-7:

sudo apt install clang-7
export CC=clang-7 CXX=clang++-7

Building

cd jpeg-xl
mkdir build
cd build
cmake -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTING=OFF ..
cmake --build . -- -j$(nproc)

The encoder/decoder tools will be available in the build/tools directory.

Installing

sudo cmake --install .

Basic encoder/decoder

To encode a source image to JPEG XL with default settings:

build/tools/cjxl input.png output.jxl

For more settings run build/tools/cjxl --help or for a full list of options run build/tools/cjxl -v -v --help.

To decode a JPEG XL file run:

build/tools/djxl input.jxl output.png

When possible cjxl/djxl are able to read/write the following image formats: .exr, .gif, .jpeg/.jpg, .pfm, .pgm/.ppm, .pgx, .png.

Benchmarking

For speed benchmarks on single images in single or multi-threaded decoding djxl can print decoding speed information. See djxl --help for details on the decoding options and note that the output image is optional for benchmarking purposes.

For a more comprehensive comparison of compression density between multiple options see "Benchmarking with benchmark_xl" section below.

Advanced guide

Building with Docker

We build a common environment based on Debian/Ubuntu using Docker. Other systems may have different combinations of versions and dependencies that have not been tested and may not work. For those cases we recommend using the Docker environment as explained in the step by step guide.

Building JPEG XL for developers

For experienced developers, we also provide build instructions for an up to date Debian-based Linux and 64-bit Windows. If you encounter any difficulties, please use Docker instead.

Benchmarking with benchmark_xl

We recommend build/tools/benchmark_xl as a convenient method for reading images or image sequences, encoding them using various codecs (jpeg jxl png webp), decoding the result, and computing objective quality metrics. An example invocation is:

build/tools/benchmark_xl --input "/path/*.png" --codec jxl:wombat:d1,jxl:cheetah:d2

Multiple comma-separated codecs are allowed. The characters after : are parameters for the codec, separated by colons, in this case specifying maximum target psychovisual distances of 1 and 2 (higher implies lower quality) and the encoder effort (see below). Other common parameters are r0.5 (target bitrate 0.5 bits per pixel) and q92 (quality 92, on a scale of 0-100, where higher is better). The jxl codec supports the following additional parameters:

Speed: falcon, cheetah, hare, wombat, squirrel, kitten, tortoise control the encoder effort in ascending order. This also affects memory usage: using lower effort will typically reduce memory consumption during encoding.

• falcon disables all of the following tools.
• cheetah enables coefficient reordering, context clustering, and heuristics for selecting DCT sizes and quantization steps.
• hare enables Gaborish filtering, chroma from luma, and an initial estimate of quantization steps.
• wombat enables error diffusion quantization and full DCT size selection heuristics.
• squirrel (default) enables dots, patches, and spline detection, and full context clustering.
• kitten optimizes the adaptive quantization for a psychovisual metric.
• tortoise enables a more thorough adaptive quantization search.

Mode: JPEG XL has two modes. The default is Var-DCT mode, which is suitable for lossy compression. The other mode is Modular mode, which is suitable for lossless compression. Modular mode can also do lossy compression (e.g. jxl:m:q50).

• m activates modular mode.

Other arguments to benchmark_xl include:

• --save_compressed: save codestreams to output_dir.
• --save_decompressed: save decompressed outputs to output_dir.
• --output_extension: selects the format used to output decoded images.
• --num_threads: number of codec instances that will independently encode/decode images, or 0.
• --inner_threads: how many threads each instance should use for parallel encoding/decoding, or 0.
• --encode_reps/--decode_reps: how many times to repeat encoding/decoding each image, for more consistent measurements (we recommend 10).

The benchmark output begins with a header:

Compr              Input    Compr            Compr       Compr  Decomp  Butteraugli
Method            Pixels     Size              BPP   #    MP/s    MP/s     Distance    Error p norm           BPP*pnorm   Errors

ComprMethod lists each each comma-separated codec. InputPixels is the number of pixels in the input image. ComprSize is the codestream size in bytes and ComprBPP the bitrate. Compr MP/s and Decomp MP/s are the compress/decompress throughput, in units of Megapixels/second. Butteraugli Distance indicates the maximum psychovisual error in the decoded image (larger is worse). Error p norm is a similar summary of the psychovisual error, but closer to an average, giving less weight to small low-quality regions. BPP*pnorm is the product of ComprBPP and Error p norm, which is a figure of merit for the codec (lower is better). Errors is nonzero if errors occurred while loading or encoding/decoding the image.

License

This software is available under a 3-clause BSD license which can be found in the LICENSE file, with an "Additional IP Rights Grant" as outlined in the PATENTS file.

Please note that the PATENTS file only mentions Google since Google is the legal entity receiving the Contributor License Agreements (CLA) from all contributors to the JPEG XL Project, including the initial main contributors to the JPEG XL format: Cloudinary and Google.

Additional documentation

Codec description

• Introductory paper (open-access)
• XL Overview - a brief introduction to the source code modules
• JPEG XL white paper
• JPEG XL website
• Jon's JXL info page

Development process

• Docker setup - start here
• Building on Debian - for experts only
• Building on Windows - for experts only
• More information on testing/build options
• Git guide for JPEG XL - for developers only
• Building Web Assembly artifacts

Contact

If you encounter a bug or other issue with the software, please open an Issue here.

There is a subreddit about JPEG XL, and informal chatting with developers and early adopters of libjxl can be done on the JPEG XL Discord server.