hayro-jpeg2000

A memory-safe, pure-Rust JPEG 2000 decoder.

hayro-jpeg2000 can decode both raw JPEG 2000 codestreams (.j2c) and images wrapped inside the JP2 container format. The decoder supports the vast majority of features defined in the JPEG2000 core coding system (ISO/IEC 15444-1) as well as some color spaces from the extensions (ISO/IEC 15444-2). There are still some missing pieces for some "obscure" features(like for example support for progression order changes in tile-parts), but all features that actually commonly appear in real-life images should be supported (if not, please open an issue!).

The decoder abstracts away most of the internal complexity of JPEG2000 and yields a simple 8-bit image with either greyscale, RGB, CMYK or an ICC-based color space, which can then be processed further according to your needs.

Example

use hayro_jpeg2000::{decode, DecodeSettings};

fn main() {
    let data = std::fs::read("image.jp2").expect("read JP2 file");
    let bitmap = decode(&data, &DecodeSettings::default()).expect("decode image");

    println!(
        "decoded {}x{} image in {:?} with alpha={}",
        bitmap.width,
        bitmap.height,
        bitmap.color_space,
        bitmap.has_alpha,
    );
}

If you want to see a more comprehensive example, please take a look at the example in GitHub, which shows you the main steps needed to convert a JPEG2000 image into PNG for example.

Testing

The decoder has been tested against 20.000+ images scraped from random PDFs on the internet and also passes a large part of the OpenJPEG test suite. So you can expect the crate to perform decently in terms of decoding correctness.

Performance

A decent amount of effort has already been put into optimizing this crate (both in terms of raw performance but also memory allocations). However, there are some more important optimizations that have not been implemented yet, so there is definitely still room for improvement (and I am planning on implementing them eventually).

Overall, you should expect this crate to have worse performance than OpenJPEG, but the difference gap should not be too large.

Safety

By default, the crate has the simd feature enabled, which uses the fearless_simd crate to accelerate important parts of the pipeline. If you want to eliminate any usage of unsafe in this crate as well as its dependencies, you can simply disable this feature, at the cost of worse decoding performance. Unsafe code is forbidden via a crate-level attribute.