third_party/jpeg-xl/README.md

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