README.md (6544B)
1 # JPEG XL reference implementation 2 3 []( 4 https://github.com/libjxl/libjxl/actions/workflows/build_test.yml) 5 []( 6 https://github.com/libjxl/libjxl/actions/workflows/build_test_cross.yml) 7 []( 8 https://github.com/libjxl/libjxl/actions/workflows/conformance.yml) 9 []( 10 https://github.com/libjxl/libjxl/actions/workflows/fuzz.yml) 11 []( 12 https://github.com/libjxl/libjxl/actions/workflows/release.yaml) 13 []( 14 https://libjxl.readthedocs.io/en/latest/?badge=latest) 15 []( 16 https://www.bestpractices.dev/projects/7845) 17 []( 18 https://securityscorecards.dev/viewer/?uri=github.com/libjxl/libjxl) 19 []( 20 https://codecov.io/gh/libjxl/libjxl) 21 22 <img src="doc/jxl.svg" width="100" align="right" alt="JXL logo"> 23 24 This repository contains a reference implementation of JPEG XL (encoder and 25 decoder), called `libjxl`. This software library is 26 [used by many applications that support JPEG XL](doc/software_support.md). 27 28 JPEG XL was standardized in 2022 as [ISO/IEC 18181](https://jpeg.org/jpegxl/workplan.html). 29 The [core codestream](doc/format_overview.md#codestream-features) is specified in 18181-1, 30 the [file format](doc/format_overview.md#file-format-features) in 18181-2. 31 [Decoder conformance](https://github.com/libjxl/conformance) is defined in 18181-3, 32 and 18181-4 is the [reference software](https://github.com/libjxl/libjxl). 33 34 The library API, command line options, and tools in this repository are subject 35 to change, however files encoded with `cjxl` conform to the JPEG XL specification 36 and can be decoded with current and future `djxl` decoders or the `libjxl` decoding library. 37 38 ## Installation 39 40 In most Linux distributions, installing `libjxl` is just a matter of using the package management system. 41 For example in Debian-based distributions: `apt install libjxl-tools` will install `cjxl` and `djxl` 42 and other tools like `benchmark_xl` are available in the package `libjxl-devtools`. 43 On MacOS, you can use [Homebrew](https://brew.sh/): `brew install jpeg-xl`. 44 45 [](https://repology.org/project/libjxl/versions) 46 47 From the [releases page](https://github.com/libjxl/libjxl/releases/) the following can be downloaded: 48 - Windows binaries 49 - Debian and Ubuntu .deb packages 50 51 Of course you can also [build libjxl from sources](BUILDING.md). 52 53 54 ## Usage 55 56 To encode a source image to JPEG XL with default settings: 57 58 ```bash 59 cjxl input.png output.jxl 60 ``` 61 62 The desired visual fidelity can be selected using the `--distance` parameter 63 (in units of just-noticeable difference, where 0 is lossless and the most useful lossy range is 0.5 .. 3.0), 64 or using `--quality` (on a scale from 0 to 100, roughly matching libjpeg). 65 The [encode effort](doc/encode_effort.md) can be selected using the `--effort` parameter. 66 67 For more settings run `cjxl --help` or for a full list of options 68 run `cjxl -v -v --help`. 69 70 To decode a JPEG XL file run: 71 72 ```bash 73 djxl input.jxl output.png 74 ``` 75 76 When possible `cjxl`/`djxl` are able to read/write the following 77 image formats: .exr, .gif, .jpeg/.jpg, .pfm, .pgm/.ppm, .pgx, .png. 78 Specifically for JPEG files, the default `cjxl` behavior is to apply lossless 79 recompression and the default `djxl` behavior is to reconstruct the original 80 JPEG file (when the extension of the output file is .jpg). 81 82 ### Benchmarking 83 84 For speed benchmarks on single images in single or multi-threaded decoding 85 `djxl` can print decoding speed information. See `djxl --help` for details 86 on the decoding options and note that the output image is optional for 87 benchmarking purposes. 88 89 For more comprehensive benchmarking options, see the 90 [benchmarking guide](doc/benchmarking.md). 91 92 ### Library API 93 94 Besides the `libjxl` library [API documentation](https://libjxl.readthedocs.io/en/latest/), 95 there are [example applications](examples/) and [plugins](plugins/) that can be used as a reference or 96 starting point for developers who wish to integrate `libjxl` in their project. 97 98 99 ## License 100 101 This software is available under a 3-clause BSD license which can be found in 102 the [LICENSE](LICENSE) file, with an "Additional IP Rights Grant" as outlined in 103 the [PATENTS](PATENTS) file. 104 105 Please note that the PATENTS file only mentions Google since Google is the legal 106 entity receiving the Contributor License Agreements (CLA) from all contributors 107 to the JPEG XL Project, including the initial main contributors to the JPEG XL 108 format: Cloudinary and Google. 109 110 ## Additional documentation 111 112 ### Codec description 113 114 * [JPEG XL Format Overview](doc/format_overview.md) 115 * [Introductory paper](https://www.spiedigitallibrary.org/proceedings/Download?fullDOI=10.1117%2F12.2529237) (open-access) 116 * [XL Overview](doc/xl_overview.md) - a brief introduction to the source code modules 117 * [JPEG XL white paper](https://ds.jpeg.org/whitepapers/jpeg-xl-whitepaper.pdf) 118 * [JPEG XL official website](https://jpeg.org/jpegxl) 119 * [JPEG XL community website](https://jpegxl.info) 120 121 ### Development process 122 123 * [More information on testing/build options](doc/building_and_testing.md) 124 * [Git guide for JPEG XL](doc/developing_in_github.md) - for developers 125 * [Fuzzing](doc/fuzzing.md) - for developers 126 * [Building Web Assembly artifacts](doc/building_wasm.md) 127 * [Test coverage on Codecov.io](https://app.codecov.io/gh/libjxl/libjxl) - for 128 developers 129 * [libjxl documentation on readthedocs.io](https://libjxl.readthedocs.io/) 130 131 ### Contact 132 133 If you encounter a bug or other issue with the software, please open an Issue here. 134 135 There is a [subreddit about JPEG XL](https://www.reddit.com/r/jpegxl/), and 136 informal chatting with developers and early adopters of `libjxl` can be done on the 137 [JPEG XL Discord server](https://discord.gg/DqkQgDRTFu).