| 1 |
# [qoi](https://crates.io/crates/qoi) |
| 2 |
|
| 3 |
[](https://github.com/aldanor/qoi-rust/actions?query=branch%3Amaster) |
| 4 |
[](https://crates.io/crates/qoi) |
| 5 |
[](https://docs.rs/qoi) |
| 6 |
[](https://opensource.org/licenses/Apache-2.0) |
| 7 |
[](https://opensource.org/licenses/MIT) |
| 8 |
[](https://github.com/rust-secure-code/safety-dance) |
| 9 |
|
| 10 |
Fast encoder/decoder for [QOI image format](https://qoiformat.org/), implemented in pure and safe Rust. |
| 11 |
|
| 12 |
- One of the [fastest](#benchmarks) QOI encoders/decoders out there. |
| 13 |
- Compliant with the [latest](https://qoiformat.org/qoi-specification.pdf) QOI format specification. |
| 14 |
- Zero unsafe code. |
| 15 |
- Supports decoding from / encoding to `std::io` streams directly. |
| 16 |
- `no_std` support. |
| 17 |
- Roundtrip-tested vs the reference C implementation; fuzz-tested. |
| 18 |
|
| 19 |
### Examples |
| 20 |
|
| 21 |
```rust |
| 22 |
use qoi::{encode_to_vec, decode_to_vec}; |
| 23 |
|
| 24 |
let encoded = encode_to_vec(&pixels, width, height)?; |
| 25 |
let (header, decoded) = decode_to_vec(&encoded)?; |
| 26 |
|
| 27 |
assert_eq!(header.width, width); |
| 28 |
assert_eq!(header.height, height); |
| 29 |
assert_eq!(decoded, pixels); |
| 30 |
``` |
| 31 |
|
| 32 |
### Benchmarks |
| 33 |
|
| 34 |
``` |
| 35 |
decode:Mp/s encode:Mp/s decode:MB/s encode:MB/s |
| 36 |
qoi.h 282.9 225.3 978.3 778.9 |
| 37 |
qoi-rust 427.4 290.0 1477.7 1002.9 |
| 38 |
``` |
| 39 |
|
| 40 |
- Reference C implementation: |
| 41 |
[phoboslab/qoi@00e34217](https://github.com/phoboslab/qoi/commit/00e34217). |
| 42 |
- Benchmark timings were collected on an Apple M1 laptop. |
| 43 |
- 2846 images from the suite provided upstream |
| 44 |
([tarball](https://phoboslab.org/files/qoibench/qoi_benchmark_suite.tar)): |
| 45 |
all pngs except two with broken checksums. |
| 46 |
- 1.32 GPixels in total with 4.46 GB of raw pixel data. |
| 47 |
|
| 48 |
Benchmarks have also been run for all of the other Rust implementations |
| 49 |
of QOI for comparison purposes and, at the time of writing this document, |
| 50 |
this library proved to be the fastest one by a noticeable margin. |
| 51 |
|
| 52 |
### Rust version |
| 53 |
|
| 54 |
The minimum required Rust version for the latest crate version is 1.61.0. |
| 55 |
|
| 56 |
### `no_std` |
| 57 |
|
| 58 |
This crate supports `no_std` mode. By default, std is enabled via the `std` |
| 59 |
feature. You can deactivate the `default-features` to target core instead. |
| 60 |
In that case anything related to `std::io`, `std::error::Error` and heap |
| 61 |
allocations is disabled. There is an additional `alloc` feature that can |
| 62 |
be activated to bring back the support for heap allocations. |
| 63 |
|
| 64 |
### License |
| 65 |
|
| 66 |
This project is dual-licensed under MIT and Apache 2.0. |