Crate j2k_native

Expand description

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 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 JPEG 2000 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 (for example support for progression order changes in tile-parts), but the features that commonly appear in real-world images are supported.

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 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.

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

Re-exports§

pub use error::ColorError;
pub use error::DecodeError;
pub use error::DecodingError;
pub use error::FormatError;
pub use error::MarkerError;
pub use error::Result;
pub use error::TileError;
pub use error::ValidationError;

Modules§

error: Error types for JPEG 2000 decoding.

Structs§

Bitmap: A bitmap storing the decoded result of the image.
ComponentPlane: A borrowed decoded component plane.
CpuOnlyJ2kEncodeStageAccelerator: Adapter CPU-only encode accelerator that always falls back to native stages.
DecodeSettings: Settings to apply during decoding.
DecodedComponents: Borrowed decoded component planes for an image.
DecoderContext: A decoder context for decoding JPEG2000 images.
EncodeOptions: Encoding options for JPEG 2000.
EncodedHtJ2kCodeBlock: Adapter encoded HTJ2K cleanup code-block payload for backend experimentation.
EncodedJ2kCodeBlock: Adapter encoded classic J2K code-block payload for backend experimentation.
HtCleanupEncodeDistribution: Adapter HTJ2K cleanup-encode shape counters for backend benchmarking.
HtCodeBlockBatchJob: Adapter HTJ2K batched code-block decode job for one sub-band.
HtCodeBlockDecodeJob: Adapter HTJ2K code-block job description for backend experimentation.
HtCodeBlockDecodeProfile: Adapter scalar HTJ2K phase timings for backend experimentation.
HtCodeBlockDecodeWorkspace: Adapter reusable scalar HTJ2K decode workspace for backend experimentation.
HtOwnedCodeBlockBatchJob: Adapter owned HTJ2K batched code-block decode job.
HtOwnedSubBandPlan: Adapter owned HTJ2K sub-band decode job.
HtSigPropBenchmarkState: Adapter HTJ2K SigProp benchmark state for backend experimentation.
HtSubBandDecodeJob: Adapter HTJ2K batched sub-band decode request for backend experimentation.
HtUvlcTableEntry: Adapter HTJ2K UVLC encoder table row for backend experimentation.
Image: A JPEG2000 image or codestream.
IrreversibleQuantizationStep: Public JPEG 2000 irreversible quantization step-size tuple.
IrreversibleQuantizationSubbandScales: Multipliers applied to irreversible 9/7 quantization step sizes by subband.
J2kCodeBlockBatchJob: Adapter classic J2K batched code-block decode job for one sub-band.
J2kCodeBlockDecodeJob: Adapter classic J2K code-block job description for backend experimentation.
J2kCodeBlockDecodeProfile: Adapter scalar classic J2K pass timings for backend experimentation.
J2kCodeBlockDecodeWorkspace: Reusable scratch for scalar classic J2K code-block decoding.
J2kCodeBlockSegment: Adapter classic J2K coded segment for backend experimentation.
J2kCodeBlockStyle: Adapter classic J2K code-block style for backend experimentation.
J2kCodestreamComponentHeader: Parsed SIZ component metadata.
J2kCodestreamHeaderMetadata: Parsed JPEG 2000 codestream metadata from the main header.
J2kDeinterleaveToF32Job: Adapter pixel deinterleave/level-shift job for backend experimentation.
J2kDirectColorPlan: Adapter RGB direct device plan for backend experimentation.
J2kDirectCpuScratch: Adapter reusable scratch for executing direct J2K RGB plans on the CPU.
J2kDirectGrayscalePlan: Adapter grayscale-only direct device plan for backend experimentation.
J2kDirectIdwtStep: Adapter single grayscale IDWT step for a direct device plan.
J2kDirectStoreStep: Adapter grayscale store step for a direct device plan.
J2kEncodeDispatchReport: Adapter encode-stage dispatch counters for backend experimentation.
J2kForwardDwt53Job: Adapter forward 5/3 DWT job for backend experimentation.
J2kForwardDwt53Level: Adapter forward 5/3 DWT detail level for backend experimentation.
J2kForwardDwt53Output: Adapter forward 5/3 DWT output for backend experimentation.
J2kForwardDwt97Job: Adapter forward irreversible 9/7 DWT job for backend experimentation.
J2kForwardDwt97Level: Adapter forward 9/7 DWT detail level for backend experimentation.
J2kForwardDwt97Output: Adapter forward 9/7 DWT output for backend experimentation.
J2kForwardIctJob: Adapter forward ICT job for backend experimentation.
J2kForwardRctJob: Adapter forward RCT job for backend experimentation.
J2kHtCodeBlockEncodeJob: Adapter HTJ2K code-block encode job for backend experimentation.
J2kHtSubbandEncodeJob: Adapter HTJ2K cleanup encode job for one unquantized sub-band.
J2kHtj2kTileEncodeJob: Adapter HTJ2K tile-body encode job for backend-resident full-tile paths.
J2kIdwtBand: Adapter single sub-band payload for backend experimentation.
J2kInverseMctJob: Adapter inverse MCT job for backend experimentation.
J2kOwnedCodeBlockBatchJob: Adapter owned classic J2K batched code-block decode job.
J2kOwnedSubBandPlan: Adapter owned classic J2K sub-band decode job.
J2kPacketizationCodeBlock: Adapter LRCP packetization code-block contribution for backend experimentation.
J2kPacketizationEncodeJob: Adapter LRCP packetization job for backend experimentation.
J2kPacketizationPacketDescriptor: Adapter explicit packet descriptor for backend packetization experimentation.
J2kPacketizationResolution: Adapter LRCP packetization resolution packet for backend experimentation.
J2kPacketizationSubband: Adapter LRCP packetization subband precinct for backend experimentation.
J2kQuantizeSubbandJob: Adapter sub-band quantization job for backend experimentation.
J2kRect: Adapter integer rectangle for backend experimentation.
J2kSingleDecompositionIdwtJob: Adapter single-decomposition IDWT job for backend experimentation.
J2kStoreComponentJob: Adapter component-store job for backend experimentation.
J2kSubBandDecodeJob: Adapter classic J2K batched sub-band decode request for backend experimentation.
J2kTier1CodeBlockEncodeJob: Adapter Tier-1 classic J2K code-block encode job for backend experimentation.
J2kTier1TokenSegment: Adapter Classic Tier-1 compact token segment for backend experimentation.
PrecomputedHtj2k53Component: Precomputed reversible 5/3 wavelet coefficients for one component.
PrecomputedHtj2k53Image: Precomputed reversible 5/3 wavelet image.
PrecomputedHtj2k97Component: Precomputed irreversible 9/7 wavelet coefficients for one component.
PrecomputedHtj2k97Image: Precomputed irreversible 9/7 wavelet image.
PreencodedHtj2k97CodeBlock: One preencoded HTJ2K code-block.
PreencodedHtj2k97CompactCodeBlock: One compact preencoded HTJ2K code-block.
PreencodedHtj2k97CompactComponent: Preencoded compact irreversible 9/7 HTJ2K component.
PreencodedHtj2k97CompactImage: Preencoded irreversible 9/7 HTJ2K code-block image backed by one compact payload buffer.
PreencodedHtj2k97CompactResolution: One component resolution’s compact preencoded HTJ2K subbands.
PreencodedHtj2k97CompactSubband: One compact preencoded HTJ2K subband split into code-blocks.
PreencodedHtj2k97Component: Preencoded irreversible 9/7 HTJ2K component.
PreencodedHtj2k97Image: Preencoded irreversible 9/7 HTJ2K code-block image.
PreencodedHtj2k97Resolution: One component resolution’s preencoded HTJ2K subbands.
PreencodedHtj2k97Subband: One preencoded HTJ2K subband split into code-blocks.
PrequantizedHtj2k97CodeBlock: One prequantized HTJ2K code-block.
PrequantizedHtj2k97Component: Prequantized irreversible 9/7 HTJ2K component.
PrequantizedHtj2k97Image: Prequantized irreversible 9/7 HTJ2K code-block image.
PrequantizedHtj2k97Resolution: One component resolution’s prequantized HTJ2K subbands.
PrequantizedHtj2k97Subband: One prequantized HTJ2K subband split into code-blocks.
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§

ColorSpace: The color space of the image.
CpuDecodeParallelism: CPU parallelism policy for native JPEG 2000 decode.
EncodeProgressionOrder: JPEG 2000 packet progression orders supported by the encoder.
HtCodeBlockDecodePhaseLimit: Adapter HTJ2K scalar decode phase limit for backend experimentation.
J2kCodestreamHeaderError: Error returned by inspect_j2k_codestream_header.
J2kDirectGrayscaleStep: Adapter grayscale-only direct device-plan step for backend experimentation.
J2kPacketizationBlockCodingMode: Adapter packetization block coding mode for backend experimentation.
J2kPacketizationProgressionOrder: Adapter packet progression order for backend packetization experimentation.
J2kSubBandType: Adapter classic J2K sub-band kind for backend experimentation.
J2kWaveletTransform: Adapter wavelet transform selector for backend experimentation.

Traits§

HtCodeBlockDecoder: Adapter HTJ2K code-block decode hook for backend experimentation.
J2kEncodeStageAccelerator: Adapter JPEG 2000 encode-stage accelerator for backend experimentation.

Functions§

collect_ht_cleanup_encode_distribution: Adapter HTJ2K cleanup-encode distribution helper for benchmark tuning.
decode_ht_code_block_scalar: Adapter scalar HTJ2K decoder helper for backend experimentation.
decode_ht_code_block_scalar_until_phase: Adapter scalar HTJ2K decoder helper that stops after the selected phase.
decode_ht_code_block_scalar_with_workspace: Adapter scalar HTJ2K decoder helper that reuses caller-owned scratch buffers.
decode_ht_code_block_scalar_with_workspace_profiled: Adapter scalar HTJ2K decoder helper that reuses scratch and records phase timings.
decode_ht_sigprop_benchmark_state: Adapter helper that runs only the HTJ2K significance-propagation phase.
decode_j2k_code_block_scalar: Adapter scalar classic J2K decoder helper for backend experimentation.
decode_j2k_code_block_scalar_profiled: Adapter scalar classic J2K decoder helper that records pass timings.
decode_j2k_code_block_scalar_with_workspace: Adapter scalar classic J2K decoder helper that reuses caller-provided scratch.
decode_j2k_code_block_scalar_with_workspace_profiled: Adapter scalar classic J2K decoder helper that records pass timings and reuses scratch.
decode_j2k_sub_band_scalar: Adapter scalar classic J2K batched decoder helper for backend experimentation.
deinterleave_reference: Adapter scalar pixel deinterleave/level-shift reference for CUDA stage parity.
encode: Encode pixel data into a JPEG 2000 codestream.
encode_ht_code_block_scalar: Adapter scalar HTJ2K cleanup-only encoder helper for backend experimentation.
encode_htj2k: Encode pixel data into an HTJ2K codestream.
encode_j2k_code_block_scalar_with_style: Adapter scalar classic J2K encoder helper for backend experimentation.
encode_j2k_packetization_scalar: Adapter scalar Tier-2 packetization helper for backend experimentation.
encode_precomputed_htj2k_53: Encode precomputed reversible 5/3 wavelet coefficients into an HTJ2K codestream.
encode_precomputed_htj2k_97: Encode precomputed irreversible 9/7 wavelet coefficients into an HTJ2K codestream.
encode_precomputed_htj2k_53_with_accelerator: Encode precomputed reversible 5/3 wavelet coefficients into an HTJ2K codestream using optional block encode and packetization hooks.
encode_precomputed_htj2k_53_with_mct: Encode precomputed reversible 5/3 wavelet coefficients into an HTJ2K codestream while controlling the output COD multi-component transform flag.
encode_precomputed_htj2k_53_with_mct_and_accelerator: Encode precomputed reversible 5/3 wavelet coefficients while controlling the output COD multi-component transform flag and using optional encode stage hooks.
encode_precomputed_htj2k_97_batch_with_accelerator: Encode multiple precomputed irreversible 9/7 wavelet images while sharing one HT code-block batch across all prepared tiles.
encode_precomputed_htj2k_97_with_accelerator: Encode precomputed irreversible 9/7 wavelet coefficients into an HTJ2K codestream using optional block encode and packetization hooks.
encode_preencoded_htj2k_97: Encode preencoded irreversible 9/7 HTJ2K code-block payloads into a codestream.
encode_preencoded_htj2k_97_compact_owned_with_accelerator: Encode compact preencoded irreversible 9/7 HTJ2K code-block payloads into a codestream, borrowing code-block ranges from one image-level payload buffer during packetization.
encode_preencoded_htj2k_97_owned_with_accelerator: Encode preencoded irreversible 9/7 HTJ2K code-block payloads into a codestream, consuming the image so code-block payloads can move into packet preparation without cloning.
encode_preencoded_htj2k_97_with_accelerator: Encode preencoded irreversible 9/7 HTJ2K code-block payloads into a codestream using optional packetization hooks.
encode_prequantized_htj2k_97: Encode prequantized irreversible 9/7 code-block coefficients into an HTJ2K codestream.
encode_prequantized_htj2k_97_with_accelerator: Encode prequantized irreversible 9/7 code-block coefficients into an HTJ2K codestream using optional block encode and packetization hooks.
encode_with_accelerator: Encode pixel data into a JPEG 2000 codestream using optional encode-stage hooks.
execute_direct_color_plan_rgb8_into: Execute a adapter direct RGB plan on the CPU and write an RGB8 output region.
execute_direct_color_plan_rgba8_into: Execute a adapter direct RGB plan on the CPU and write an RGBA8 output region.
forward_dwt53_reference: Adapter scalar forward 5/3 DWT reference for CUDA stage parity.
forward_rct_reference: Adapter scalar forward RCT reference for CUDA stage parity.
ht_uvlc_encode_table: Adapter HTJ2K cleanup encoder UVLC table for backend experimentation.
ht_uvlc_encode_table_bytes: Adapter HTJ2K cleanup encoder UVLC table packed for byte-addressed backends.
ht_uvlc_table0: Adapter HTJ2K UVLC table 0 for backend experimentation.
ht_uvlc_table1: Adapter HTJ2K UVLC table 1 for backend experimentation.
ht_vlc_encode_table0: Adapter HTJ2K cleanup encoder VLC table 0 for backend experimentation.
ht_vlc_encode_table1: Adapter HTJ2K cleanup encoder VLC table 1 for backend experimentation.
ht_vlc_table0: Adapter HTJ2K VLC table 0 for backend experimentation.
ht_vlc_table1: Adapter HTJ2K VLC table 1 for backend experimentation.
idwt_band_index: Maps an output coordinate within an IDWT step to the source sub-band index.
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.
pack_j2k_code_block_scalar_from_tier1_tokens: Adapter scalar Classic Tier-1 compact token packer for backend experimentation.
prepare_ht_sigprop_benchmark_state: Adapter helper that precomputes cleanup-derived SigProp inputs for benchmarks.
quantize_reversible_reference: Adapter scalar reversible sub-band quantization reference for CUDA stage parity.

Type Aliases§

J2kDirectBandId: Adapter identifier for one device-owned grayscale coefficient band.

Crate j2k_native

Crate j2k_native Copy item path

§Example

§Testing

§Performance

§Safety

Re-exports§

Modules§

Structs§

Enums§

Traits§

Functions§

Type Aliases§

Crate j2k_native