|
| 1 | +# Oxipng |
| 2 | + |
| 3 | +[](https://travis-ci.org/shssoichiro/oxipng) |
| 4 | +[](https://crates.io/crates/oxipng) |
| 5 | +[](https://github.com/shssoichiro/oxipng/blob/master/LICENSE) |
| 6 | + |
| 7 | +## Overview |
| 8 | + |
| 9 | +Oxipng is a multithreaded lossless PNG compression optimizer. It can be used via a command-line |
| 10 | +interface or as a library in other Rust programs. |
| 11 | + |
| 12 | +## Installing |
| 13 | + |
| 14 | +Oxipng can be downloaded from the [Releases](https://github.com/shssoichiro/oxipng/releases) link on the GitHub page. |
| 15 | + |
| 16 | +Oxipng can also be installed from Cargo, via the following command: |
| 17 | +``` |
| 18 | +cargo install oxipng |
| 19 | +``` |
| 20 | + |
| 21 | +Alternatively, oxipng can be built from source using the latest stable or nightly Rust: |
| 22 | +``` |
| 23 | +git clone https://github.com/shssoichiro/oxipng.git |
| 24 | +cd oxipng |
| 25 | +cargo build --release |
| 26 | +cp target/release/oxipng /usr/local/bin |
| 27 | +``` |
| 28 | + |
| 29 | +The current minimum supported Rust version is **1.20.0**. Oxipng may compile on earlier versions of Rust, |
| 30 | +but there is no guarantee. |
| 31 | + |
| 32 | +Oxipng follows Semantic Versioning. |
| 33 | + |
| 34 | +## Usage |
| 35 | + |
| 36 | +Oxipng is a command-line utility. Basic usage looks similar to the following: |
| 37 | + |
| 38 | +``` |
| 39 | +oxipng -o 4 -i 1 --strip safe *.png |
| 40 | +``` |
| 41 | + |
| 42 | +The most commonly used options are as follows: |
| 43 | +* Optimization: `-o 1` through `-o 6`, lower is faster, higher is better compression. |
| 44 | +The default (`-o 2`) is sufficiently fast on a modern CPU and provides 30-50% compression |
| 45 | +gains over an unoptimized PNG. `-o 4` is 6 times slower than `-o 2` but can provide 5-10% |
| 46 | +extra compression over `-o 2`. Using any setting higher than `-o 4` is unlikely |
| 47 | +to give any extra compression gains and is not recommended. |
| 48 | +* Interlacing: `-i 1` will enable [Adam7](https://en.wikipedia.org/wiki/Adam7_algorithm) |
| 49 | +PNG interlacing on any images that are processed. `-i 0` will remove interlacing from all |
| 50 | +processed images. Not specifying either will keep the same interlacing state as the |
| 51 | +input image. Note: Interlacing can add 25-50% to the size of an optimized image. Only use |
| 52 | +it if you believe the benefits outweight the costs for your use case. |
| 53 | +* Strip: Used to remove metadata info from processed images. Used via `--strip [safe,all]`. |
| 54 | +Can save a few kilobytes if you don't need the metadata. "Safe" removes only metadata that |
| 55 | +will never affect rendering of the image. "All" removes all metadata that is not critical |
| 56 | +to the image. You can also pass a comma-separated list of specific metadata chunks to remove. |
| 57 | +`-s` can be used as a shorthand for `--strip safe`. |
| 58 | + |
| 59 | +More advanced options can be found by running `oxipng -h`. |
| 60 | + |
| 61 | +## Library Usage |
| 62 | + |
| 63 | +Although originally intended to be used as an executable, oxipng can also be used as a library in |
| 64 | +other Rust projects. To do so, simply add oxipng as a dependency in your Cargo.toml, |
| 65 | +then `extern crate oxipng` in your project. You should then have access to all of the library |
| 66 | +functions [documented here](https://docs.rs/oxipng). The simplest |
| 67 | +method of usage involves creating an |
| 68 | +[Options struct](https://docs.rs/oxipng/0.13.0/oxipng/struct.Options.html) and |
| 69 | +passing it, along with an input filename, into the |
| 70 | +[optimize function](https://docs.rs/oxipng/0.13.0/oxipng/fn.optimize.html). |
| 71 | + |
| 72 | +## History |
| 73 | + |
| 74 | +Oxipng began as a complete rewrite of the OptiPNG project, |
| 75 | +which was assumed to be dead as no commit had been made to it since March 2014. |
| 76 | +(OptiPNG has since released a new version, after Oxipng was first released.) |
| 77 | +The name has been changed to avoid confusion and potential legal issues. |
| 78 | + |
| 79 | +The core goal of rewriting OptiPNG was to implement multithreading, |
| 80 | +which would be very difficult to do within the existing C codebase of OptiPNG. |
| 81 | +This also served as an opportunity to choose a more modern, safer language (Rust). |
| 82 | + |
| 83 | +## Contributing |
| 84 | + |
| 85 | +Any contributions are welcome and will be accepted via pull request on GitHub. Bug reports can be |
| 86 | +filed via GitHub issues. Please include as many details as possible. If you have the capability |
| 87 | +to submit a fix with the bug report, it is preferred that you do so via pull request, |
| 88 | +however you do not need to be a Rust developer to contribute. |
| 89 | +Other contributions (such as improving documentation or translations) are also welcome via GitHub. |
| 90 | + |
| 91 | +## License |
| 92 | + |
| 93 | +Oxipng is open-source software, distributed under the MIT license. |
| 94 | + |
| 95 | +## Benchmarks |
| 96 | + |
0 commit comments