JPEG XL reference implementation
This repository contains a reference implementation of JPEG XL (encoder and decoder), called
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.
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
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
CXX variables. For example, with clang-7:
sudo apt install clang-7 export CC=clang-7 CXX=clang++-7
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
sudo cmake --install .
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
djxl are able to read/write the following image formats: .exr, .gif, .jpeg/.jpg, .pfm, .pgm/.ppm, .pgx, .png.
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.
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
Benchmarking with benchmark_xl
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:
tortoise control the encoder effort in ascending order. This also affects memory usage: using lower effort will typically reduce memory consumption during encoding.
falcondisables all of the following tools.
cheetahenables coefficient reordering, context clustering, and heuristics for selecting DCT sizes and quantization steps.
hareenables Gaborish filtering, chroma from luma, and an initial estimate of quantization steps.
wombatenables error diffusion quantization and full DCT size selection heuristics.
squirrel(default) enables dots, patches, and spline detection, and full context clustering.
kittenoptimizes the adaptive quantization for a psychovisual metric.
tortoiseenables 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.
mactivates modular mode.
Other arguments to benchmark_xl include:
--save_compressed: save codestreams to
--save_decompressed: save decompressed outputs to
--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.
--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
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.
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.
- 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
- 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
If you encounter a bug or other issue with the software, please open an Issue here.