Crate j2k_native 

Internal pure-Rust JPEG 2000 codec engine for j2k.

This module tree was imported from the dicom-toolkit-jpeg2000 0.5.0 crate and adapted in-repo so j2k no longer depends on an external production decoder crate.

dicom-toolkit-jpeg2000 is the JPEG 2000 engine used by dicom-toolkit-rs. It is a maintained fork of the original hayro-jpeg2000 project with DICOM-focused extensions, including native-bit-depth decode for 8/12/16-bit images and pure-Rust JPEG 2000 encoding.

The crate can decode raw JPEG 2000 codestreams (.j2c) and still-image JP2/JPH wrappers. It implements the JPEG 2000 core coding system (ISO/IEC 15444-1) and HTJ2K block coding (ISO/IEC 15444-15) through the support boundary documented in docs/public-support.md. The remaining declared gaps are tracked there.

The crate offers both a high-level 8-bit decode path for general image use and a native-bit-depth decode path for integrations such as DICOM, plus encoder APIs for emitting raw JPEG 2000 and HTJ2K codestreams.

Example

use j2k_native::{DecodeSettings, Image};

let data = std::fs::read("image.jp2").unwrap();
let image = Image::new(&data, &DecodeSettings::default()).unwrap();

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

let bitmap = image.decode().unwrap();

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

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 raw throughput and memory allocations), with remaining optimization work planned.

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.

The crate is no_std compatible but requires an allocator to be available.

Structs

Bitmap

A bitmap storing the decoded result of the image.

ComponentPlane

A borrowed decoded component plane.

DecodeSettings

Settings to apply during decoding.

DecodedComponents

Borrowed decoded component planes for an image.

DecodedNativeComponents

Owned decoded native-bit-depth component planes for an image.

DecoderContext

A decoder context for decoding JPEG2000 images.

EncodeComponentPlane

Borrowed component-plane samples for reversible 5/3 component-plane encode.

EncodeOptions

Encoding options for JPEG 2000.

EncodeRoiRegion

Rectangular region-of-interest request for JPEG 2000 maxshift encoding.

EncodeTypedComponentPlane

Borrowed component-plane samples with per-component precision metadata.

Image

A JPEG2000 image or codestream.

J2kCodestreamComponentHeader

Parsed SIZ component metadata.

J2kCodestreamHeaderMetadata

Parsed JPEG 2000 codestream metadata from the main header.

NativeComponentPlane

One owned decoded component plane at native bit depth.

RawBitmap

Raw decoded pixel data at native bit depth (no 8-bit scaling).

Reversible53CoefficientImage

Reversible 5/3 source coefficients ready for HTJ2K code-block recoding.

Enums

ColorError

Errors related to color space and component handling.

ColorSpace

The color space of the image.

CpuDecodeParallelism

CPU parallelism policy for native JPEG 2000 decode.

DecodeError

The main error type for JPEG 2000 decoding operations.

DecodeErrorClass

Backend-neutral classification used by codec adapters.

DecodingError

Errors related to decoding operations.

DirectPlanUnsupportedReason

Structured reasons why a direct JPEG 2000 device plan cannot be built.

EncodeError

Error returned by native JPEG 2000 and HTJ2K encode operations.

EncodeProgressionOrder

JPEG 2000 packet progression orders supported by the encoder.

FormatError

Errors related to JP2 file format and box parsing.

J2kCodestreamHeaderError

Error returned by inspect_j2k_codestream_header.

MarkerError

Errors related to codestream markers.

TileError

Errors related to tile processing.

ValidationError

Errors related to image dimensions and validation.

Functions

encode

Encode pixel data into a JPEG 2000 codestream.

encode_component_planes_53

Encode reversible 5/3 component planes into a classic J2K or HTJ2K codestream.

encode_htj2k

Encode pixel data into an HTJ2K codestream.

encode_typed_component_planes_53

Encode reversible 5/3 typed component planes into a classic J2K or HTJ2K codestream.

encode_with_roi_regions

Encode pixel data into a JPEG 2000 codestream with rectangular ROI maxshift.

inspect_j2k_codestream_header

Inspect a raw JPEG 2000 codestream main header without decoding tile data.

irreversible_quantization_step_for_subband

Compute the exact irreversible 9/7 quantization step tuple the native encoder writes for one subband under a global plus per-subband profile.

looks_like_j2k_codestream

Return whether bytes start with the raw JPEG 2000 SOC marker.

Type Aliases

EncodeResult

Result type for JPEG 2000 and HTJ2K encoding operations.

Result

Result type for JPEG 2000 decoding operations.