2022-01-06 00:59:32 +00:00
# [qoi](https://crates.io/crates/qoi)
2022-01-02 22:40:25 +00:00
2022-01-06 00:59:32 +00:00
[](https://github.com/aldanor/qoi-rust/actions?query=branch%3Amaster)
[](https://crates.io/crates/qoi)
[](https://docs.rs/qoi)
2022-01-02 22:40:25 +00:00
[](https://opensource.org/licenses/Apache-2.0)
[](https://opensource.org/licenses/MIT)
2022-01-03 11:51:39 +00:00
[](https://github.com/rust-secure-code/safety-dance)
2022-01-02 22:40:25 +00:00
2022-01-03 17:57:25 +00:00
Fast encoder/decoder for [QOI image format ](https://qoiformat.org/ ), implemented in pure and safe Rust.
2022-01-04 00:10:55 +00:00
- One of the [fastest ](#benchmarks ) QOI encoders/decoders out there.
2022-01-03 17:57:25 +00:00
- Compliant with the [latest ](https://qoiformat.org/qoi-specification.pdf ) QOI format specification.
2022-01-03 11:25:25 +00:00
- Zero unsafe code.
- Supports decoding from / encoding to `std::io` streams directly.
2022-01-03 17:57:25 +00:00
- `no_std` support.
2022-01-03 11:25:25 +00:00
- Roundtrip-tested vs the reference C implementation; fuzz-tested.
2022-12-16 21:12:43 +00:00
### Note about this fork
This fork implements a slight improvement to the original specs, which leaves unused the `QOI_OP_RGBA` chunk flag with RGB.
Here, we use this flag for the new `QOI_OP_RUN2` chunk. It's like the `QOI_OP_RUN` chunk, but followed by two bytes representing `run` (BE). (only for RGB, as the flag is already used for RGBA)
The decoder remains fully compatible with the original one (except when using `QOI_OP_RGBA` in a RGB image). The encoder is fully compatible for RGBA, not for RGB (except using the `reference` feature).
Why this? Because it enables significant improvements for compressing images with large uniform areas (such as screen captures), or for encoding a diff-filtered video stream where successive frames often have identical regions. (see [syeve ](https://framagit.org/ZettaScript/syeve ) for the video encoding)
2022-01-03 11:25:25 +00:00
### Examples
```rust
2022-01-06 00:59:32 +00:00
use qoi::{encode_to_vec, decode_to_vec};
2022-01-03 22:52:42 +00:00
let encoded = encode_to_vec(& pixels, width, height)?;
let (header, decoded) = decode_to_vec(&encoded)?;
assert_eq!(header.width, width);
assert_eq!(header.height, height);
assert_eq!(decoded, pixels);
2022-01-03 11:25:25 +00:00
```
### Benchmarks
```
2022-01-06 00:12:32 +00:00
decode:Mp/s encode:Mp/s decode:MB/s encode:MB/s
qoi.h 282.9 225.3 978.3 778.9
2022-01-06 00:59:32 +00:00
qoi-rust 427.4 290.0 1477.7 1002.9
2022-01-03 11:25:25 +00:00
```
2022-01-02 22:40:25 +00:00
2022-01-06 00:12:32 +00:00
- Reference C implementation:
[phoboslab/qoi@00e34217 ](https://github.com/phoboslab/qoi/commit/00e34217 ).
- Benchmark timings were collected on an Apple M1 laptop.
- 2846 images from the suite provided upstream
([tarball](https://phoboslab.org/files/qoibench/qoi_benchmark_suite.tar)):
all pngs except two with broken checksums.
- 1.32 GPixels in total with 4.46 GB of raw pixel data.
2022-01-03 22:58:27 +00:00
Benchmarks have also been run for all of the other Rust implementations
of QOI for comparison purposes and, at the time of writing this document,
this library proved to be the fastest one by a noticeable margin.
2022-01-04 11:52:45 +00:00
### Rust version
2022-10-16 23:42:55 +00:00
The minimum required Rust version for the latest crate version is 1.61.0.
2022-01-04 11:52:45 +00:00
2022-01-03 18:57:54 +00:00
### `no_std`
This crate supports `no_std` mode. By default, std is enabled via the `std`
feature. You can deactivate the `default-features` to target core instead.
In that case anything related to `std::io` , `std::error::Error` and heap
allocations is disabled. There is an additional `alloc` feature that can
be activated to bring back the support for heap allocations.
2022-01-02 22:40:25 +00:00
### License
2022-01-03 11:51:39 +00:00
This project is dual-licensed under MIT and Apache 2.0.
