j2k_types/
wavelet.rs

1// SPDX-License-Identifier: MIT OR Apache-2.0
2
3//! Framework-independent native wavelet output contracts.
4
5use alloc::vec::Vec;
6
7pub use crate::{
8    J2kRect as WaveletRect, J2kSubBandType as WaveletBandKind,
9    J2kWaveletTransform as WaveletTransform,
10};
11
12/// Requested tiles, components, resolution indices, and band orientations.
13///
14/// Empty lists select all values. Lists are sets: duplicates do not duplicate
15/// output, which always follows codestream tile/component/resolution order.
16/// Resolution 0 is the coarsest LL band; 1 through N contain detail bands in
17/// order from coarsest to finest. A nonempty resolution list must be valid for
18/// every selected tile component. Selections matching no band are errors.
19///
20/// Unselected bands are not entropy-decoded. Packet headers are still parsed,
21/// and active-tile coefficient storage is still allocated. This is not a
22/// promise of proportional I/O or memory savings, or incremental refinement.
23#[derive(Debug, Clone, Default)]
24pub struct WaveletSelection {
25    /// Row-major tile indices. Empty selects every tile.
26    pub tiles: Vec<u32>,
27    /// Codestream component indices, before inverse color transformation.
28    pub components: Vec<u16>,
29    /// Resolution indices: 0 for LL, then coarsest-to-finest detail levels.
30    pub resolutions: Vec<u8>,
31    /// Band orientations; LL exists only at resolution 0.
32    pub bands: Vec<WaveletBandKind>,
33}
34
35/// Owned, row-major coefficients in a band.
36#[derive(Debug, PartialEq)]
37pub enum WaveletSamples {
38    /// Exact reversible 5/3 coefficients, after ROI maxshift inversion.
39    I64(Vec<i64>),
40    /// Dequantized irreversible 9/7 coefficients, including the decoder's
41    /// midpoint reconstruction for truncated coding passes.
42    F32(Vec<f32>),
43}
44
45/// One band in component coordinates, before inverse wavelet reconstruction.
46#[derive(Debug)]
47pub struct WaveletBand {
48    /// Low/high filtering along x, followed by y.
49    pub kind: WaveletBandKind,
50    /// Codestream resolution index: 0 is LL; larger indices are finer detail.
51    pub resolution: u8,
52    /// Band coordinates, including nonzero origins and odd-size geometry.
53    pub rect: WaveletRect,
54    /// Dequantization multiplier already applied to the returned coefficients.
55    /// This is 1 for reversible output. Values are not normalized for a model.
56    pub quantization_step: f32,
57    /// Samples in rows of `rect.width()` elements.
58    pub samples: WaveletSamples,
59}
60
61/// Selected bands from one codestream component in one tile.
62#[derive(Debug)]
63pub struct WaveletComponent {
64    /// Original codestream component index.
65    pub index: u16,
66    /// Component tile rectangle at full component resolution.
67    pub rect: WaveletRect,
68    /// Source component precision in bits.
69    pub precision: u8,
70    /// Whether source samples are signed, before unsigned level shifting.
71    pub signed: bool,
72    /// Horizontal and vertical sample spacing in the image reference grid.
73    pub sampling: (u8, u8),
74    /// Reversible 5/3 or irreversible 9/7 transformation.
75    pub transform: WaveletTransform,
76    /// Number of wavelet decomposition levels in this component tile.
77    pub decomposition_levels: u8,
78    /// Selected bands in resolution order, with HL, LH, HH within each level.
79    pub bands: Vec<WaveletBand>,
80}
81
82/// Selected component coefficients belonging to one independently coded tile.
83#[derive(Debug)]
84pub struct WaveletTile {
85    /// Original row-major tile index.
86    pub index: u32,
87    /// Tile rectangle in the image reference grid.
88    pub rect: WaveletRect,
89    /// Whether the first three components are in the codestream's transformed
90    /// color domain (RCT for reversible, ICT for irreversible coding), not RGB.
91    pub uses_color_transform: bool,
92    /// Selected components. JP2 palette, channel, and ICC transformations have
93    /// not been applied; indices refer to codestream components.
94    pub components: Vec<WaveletComponent>,
95}
96
97/// Native coefficients extracted without inverse DWT, color conversion, or packing.
98#[derive(Debug)]
99pub struct WaveletImage {
100    /// Full image rectangle in the reference grid.
101    pub rect: WaveletRect,
102    /// Selected tiles. Tile boundaries are preserved, never stitched silently.
103    pub tiles: Vec<WaveletTile>,
104}
j2k_types/wavelet.rs

j2k_types/
wavelet.rs
