V9 Change log and read me (#559)

Co-authored-by: Alejandro González <me@alegon.dev>

CHANGELOG.md

@@ -1,3 +1,27 @@
+## Version 9.0.0
+
+- [Breaking] Remove `--backup` option. Use `--out` or `--dir` to preserve existing files.
+- [Breaking] Remove `--check` option. Use `--nx --nz` to perform a non-optimizing run.
+- [Breaking] API: Replace `pretend` option with `OutFile::None`.
+- [Breaking] API: Move `preserve_attrs` into `OutFile::Path`.
+- [Breaking] Default to removing interlacing. Use `-i keep` to retain existing interlacing.
+- [Feature] Add Raw API for creating optimised PNGs from raw image data.
+- [Feature] Add basic support for APNG files.
+- [Feature] Add `--scale16` option to forcibly reduce 16-bit images to 8-bit.
+- [Improvement] Process multiple files in parallel.
+- [Improvement] Improve reductions, particularly for indexed or very small images.
+- [Improvement] Improve compression with latest version of libdeflate.
+- [Improvement] Recompress iCCP chunks.
+- [Improvement] Change recursive mode to only process .png/.apng files.
+- [Improvement] Add support for glob patterns in quotes on Windows.
+- [Improvement] Quieter default output logging, with multiple levels of verbosity.
+- [Bugfix] Fix deadlock when using oxipng within an existing Rayon thread pool.
+- [Bugfix] Fix early abort in recursive mode when a read error occurred.
+- [Bugfix] Fix losing aux chunks when there's more than one of the same type.
+- [Bugfix] Fix sometimes writing output even when it was larger.
+- [Misc] Revamp CI workflow to upload artifacts and generate binaries for additional architectures.
+- [Misc] Bump minimum Rust version to 1.66.0.
+
 ## Version 8.0.0
 
 - [Breaking] Revamp alpha optimization

Cargo.toml

@@ -9,7 +9,7 @@ homepage = "https://github.com/shssoichiro/oxipng"
 license = "MIT"
 name = "oxipng"
 repository = "https://github.com/shssoichiro/oxipng"
-version = "8.0.0"
+version = "9.0.0"
 rust-version = "1.66.0"
 
 [badges]

README.md

@@ -7,7 +7,7 @@
 
 ## Overview
 
-Oxipng is a multithreaded lossless PNG compression optimizer. It can be used via a command-line
+Oxipng is a multithreaded lossless PNG/APNG compression optimizer. It can be used via a command-line
 interface or as a library in other Rust programs.
 
 ## Installing
@@ -38,31 +38,32 @@ Oxipng follows Semantic Versioning.
 
 ## Usage
 
-Oxipng is a command-line utility. Basic usage looks similar to the following:
+Oxipng is a command-line utility. An example usage, suitable for web, may be the following:
 
 ```
-oxipng -o 4 -i 1 --strip safe *.png
+oxipng -o 4 --strip safe --alpha *.png
 ```
 
 The most commonly used options are as follows:
 
-- Optimization: `-o 1` through `-o 6`, lower is faster, higher is better compression.
-  The default (`-o 2`) is sufficiently fast on a modern CPU and provides 30-50% compression
-  gains over an unoptimized PNG. `-o 4` is 6 times slower than `-o 2` but can provide 5-10%
-  extra compression over `-o 2`. Using any setting higher than `-o 4` is unlikely
-  to give any extra compression gains and is not recommended.
-- Interlacing: `-i 1` will enable [Adam7](https://en.wikipedia.org/wiki/Adam7_algorithm)
-  PNG interlacing on any images that are processed. `-i 0` will remove interlacing from all
-  processed images. Not specifying either will keep the same interlacing state as the
-  input image. Note: Interlacing can add 25-50% to the size of an optimized image. Only use
-  it if you believe the benefits outweigh the costs for your use case.
+- Optimization: `-o 0` through `-o 6` (or `-o max`), lower is faster, higher is better compression.
+  The default (`-o 2`) is quite fast and provides good compression. Higher levels can be notably
+  better but generally have increasingly diminishing returns.
 - Strip: Used to remove metadata info from processed images. Used via `--strip [safe,all]`.
   Can save a few kilobytes if you don't need the metadata. "Safe" removes only metadata that
   will never affect rendering of the image. "All" removes all metadata that is not critical
   to the image. You can also pass a comma-separated list of specific metadata chunks to remove.
   `-s` can be used as a shorthand for `--strip safe`.
+- Alpha: `--alpha` can improve compression of images with transparency, by altering the color
+  values of fully transparent pixels. This is generally recommended, but take care as this is
+  technically a lossy transformation and may be unsuitable for some specific applications.
 
-More advanced options can be found by running `oxipng -h`.
+More advanced options can be found by running `oxipng --help`, or viewed [here](MANUAL.txt).
+
+Some options have both short (`-a`) and long (`--alpha`) forms. Which form you use is just a
+matter of preference. Multiple short options can be combined together, e.g.:
+`-savvo6` is equivalent to to `--strip safe --alpha --verbose --verbose --opt 6`.
+Note that all options are case-sensitive.
 
 ## Git integration via [Trunk]
 
@@ -75,15 +76,15 @@ To enable oxipng via [trunk]:
 trunk check enable oxipng
 
 # to get a specific version:
-trunk check enable oxipng@8.0.0
+trunk check enable oxipng@9.0.0
 ```
 
 or modify `.trunk/trunk.yaml` in your repo to contain:
 
 ```
 lint:
   enabled:
-    - oxipng@8.0.0
+    - oxipng@9.0.0
 ```
 
 Then just run:
@@ -111,14 +112,14 @@ other Rust projects. To do so, simply add oxipng as a dependency in your Cargo.t
 then `extern crate oxipng` in your project. You should then have access to all of the library
 functions [documented here](https://docs.rs/oxipng). The simplest
 method of usage involves creating an
-[Options struct](https://docs.rs/oxipng/3.0.1/oxipng/struct.Options.html) and
+[Options struct](https://docs.rs/oxipng/latest/oxipng/struct.Options.html) and
 passing it, along with an input filename, into the
-[optimize function](https://docs.rs/oxipng/3.0.1/oxipng/fn.optimize.html).
+[optimize function](https://docs.rs/oxipng/latest/oxipng/fn.optimize.html).
 
 It is recommended to disable the "binary" feature when including oxipng as a library. Currently, there is
 no simple way to just disable one feature in Cargo, it has to be done by disabling default features
 and specifying the desired ones, for example:
-`oxipng = { version = "8.0", features = ["parallel", "zopfli", "filetime"], default-features = false }`
+`oxipng = { version = "9.0", features = ["parallel", "zopfli", "filetime"], default-features = false }`
 
 ## History
 
@@ -131,6 +132,9 @@ The core goal of rewriting OptiPNG was to implement multithreading,
 which would be very difficult to do within the existing C codebase of OptiPNG.
 This also served as an opportunity to choose a more modern, safer language (Rust).
 
+Note that, while similar, Oxipng is not a drop-in replacement for OptiPNG.
+If you are migrating from OptiPNG, please check the [help](MANUAL.txt) before using.
+
 ## Contributing
 
 Any contributions are welcome and will be accepted via pull request on GitHub. Bug reports can be
@@ -145,6 +149,43 @@ Oxipng is open-source software, distributed under the MIT license.
 
 ## Benchmarks
 
+Tested OxiPNG 9.0.0 (commit `c16519b38b0519988db625913be919d4f0e42f5d`, compiled
+on `rustc 1.74.0-nightly (7b4d9e155 2023-09-28)`) against OptiPNG version 0.7.7,
+as packaged by Debian unstable, on a Linux 6.5.0-2-amd64 kernel, Intel Core
+i7-12700 CPU (8 performance cores, 4 efficiency cores, 20 threads), DDR5-5200
+RAM in dual channel configuration.
+
+```
+
+Benchmark 1: ./target/release/oxipng -P ./tests/files/rgb_16_should_be_grayscale_8.png
+  Time (mean ± σ):      59.6 ms ±   7.7 ms    [User: 77.4 ms, System: 3.6 ms]
+  Range (min … max):    53.3 ms …  89.9 ms    32 runs
+
+Benchmark 2: optipng -simulate ./tests/files/rgb_16_should_be_grayscale_8.png
+  Time (mean ± σ):     132.4 ms ±   0.8 ms    [User: 132.5 ms, System: 0.6 ms]
+  Range (min … max):   131.8 ms … 134.4 ms    22 runs
+
+Summary
+  ./target/release/oxipng -P ./tests/files/rgb_16_should_be_grayscale_8.png ran
+    2.22 ± 0.29 times faster than optipng -simulate ./tests/files/rgb_16_should_be_grayscale_8.png
+
+Benchmark 1: ./target/release/oxipng -o4 -P ./tests/files/rgb_16_should_be_grayscale_8.png
+  Time (mean ± σ):      88.7 ms ±   4.3 ms    [User: 270.3 ms, System: 11.0 ms]
+  Range (min … max):    86.8 ms … 109.4 ms    26 runs
+
+Benchmark 2: optipng -o 4 -simulate ./tests/files/rgb_16_should_be_grayscale_8.png
+  Time (mean ± σ):     444.9 ms ±   0.3 ms    [User: 444.8 ms, System: 0.7 ms]
+  Range (min … max):   444.4 ms … 445.6 ms    10 runs
+
+Summary
+  ./target/release/oxipng -o4 -P ./tests/files/rgb_16_should_be_grayscale_8.png ran
+    5.01 ± 0.25 times faster than optipng -o 4 -simulate ./tests/files/rgb_16_should_be_grayscale_8.png
+
+```
+
+<details>
+<summary>Older benchmark</summary>
+
 Tested oxipng 5.0.0 (compiled on rustc 1.55.0-nightly (7a16cfcff 2021-07-11)) against OptiPNG version 0.7.7 on AMD Ryzen 7 4800H with Radeon Graphics with 16 logical cores
 
 ```
@@ -176,3 +217,4 @@ Summary
     5.16 ± 0.58 times faster than 'optipng -o 4 -simulate ./tests/files/rgb_16_should_be_grayscale_8.png'
 
 ```
+</details>