Skip to main content

qualia_core_db/medical/dicom_codecs/jpegls/
headers.rs

1//! ITU-T T.87 (JPEG-LS) markers, error types, budgets and coding parameters.
2use super::super::encapsulated::EncapError;
3use super::super::PixelError;
4
5pub const TS_JPEGLS_LOSSLESS: &str = "1.2.840.10008.1.2.4.80";
6pub const TS_JPEGLS_NEAR_LOSSLESS: &str = "1.2.840.10008.1.2.4.81";
7
8#[derive(Debug, Clone, Copy, PartialEq, Eq)]
9pub enum JpegLsError {
10    Encap(EncapError),
11    Pixel(PixelError),
12    Unsupported(&'static str),
13    OutputTooSmall,
14    ByteLimit,
15    FrameLimit,
16    FragmentLimit,
17    DimensionLimit,
18    Overflow,
19    CorruptStream(&'static str),
20    DimensionMismatch,
21    BitPrecisionMismatch,
22    LosslessModeViolation,
23}
24impl From<EncapError> for JpegLsError {
25    fn from(e: EncapError) -> Self {
26        match e {
27            EncapError::ByteLimit => Self::ByteLimit,
28            EncapError::FrameLimit => Self::FrameLimit,
29            EncapError::FragmentLimit => Self::FragmentLimit,
30            EncapError::DimensionLimit => Self::DimensionLimit,
31            EncapError::Overflow => Self::Overflow,
32            EncapError::Unsupported(s) => Self::Unsupported(s),
33            other => Self::Encap(other),
34        }
35    }
36}
37impl From<PixelError> for JpegLsError {
38    fn from(e: PixelError) -> Self {
39        Self::Pixel(e)
40    }
41}
42impl std::fmt::Display for JpegLsError {
43    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
44        write!(f, "DICOM JPEG-LS: {self:?}")
45    }
46}
47impl std::error::Error for JpegLsError {}
48
49#[derive(Clone, Copy, Debug)]
50pub struct JpegLsLimits {
51    pub max_part10_bytes: usize,
52    pub max_decoded_bytes: usize,
53    pub max_compressed_bytes: usize,
54    pub max_frames: u32,
55    pub max_fragments: usize,
56    pub max_width: u16,
57    pub max_height: u16,
58}
59impl Default for JpegLsLimits {
60    fn default() -> Self {
61        Self {
62            max_part10_bytes: 128 * 1024 * 1024,
63            max_decoded_bytes: 256 * 1024 * 1024,
64            max_compressed_bytes: 64 * 1024 * 1024,
65            max_frames: 4096,
66            max_fragments: 16384,
67            max_width: 16384,
68            max_height: 16384,
69        }
70    }
71}
72
73#[derive(Clone, Copy, Debug, PartialEq, Eq)]
74pub struct JpegLsFrameInfo<'a> {
75    pub source_blake3: [u8; 32],
76    pub transfer_syntax_uid: &'a str,
77    pub rows: u16,
78    pub columns: u16,
79    pub frames: u32,
80    pub samples_per_pixel: u16,
81    pub bits_allocated: u16,
82    pub bits_stored: u16,
83    pub signed: bool,
84    pub source_photometric: &'a str,
85    pub near_max: u8,
86    pub bytes: usize,
87}
88
89#[derive(Clone, Copy, Debug)]
90pub struct PresetParams {
91    pub maxval: u32,
92    pub t1: i32,
93    pub t2: i32,
94    pub t3: i32,
95    pub reset: i32,
96}
97
98#[derive(Clone, Copy, Debug)]
99#[allow(dead_code)]
100pub struct DerivedCoding {
101    pub maxval: i32,
102    pub t1: i32,
103    pub t2: i32,
104    pub t3: i32,
105    pub reset: i32,
106    pub near: i32,
107    pub range: i32,
108    pub qbpp: u8,
109    pub bpp: u8,
110    pub limit: u8,
111}
112
113pub fn derive_coding(
114    precision: u8,
115    near: u8,
116    preset: Option<PresetParams>,
117) -> Result<DerivedCoding, JpegLsError> {
118    let near_i = near as i32;
119    let default_max = (1u32 << precision) - 1;
120    let (maxval, t1, t2, t3, reset) = if let Some(p) = preset {
121        let mv = if p.maxval == 0 { default_max } else { p.maxval };
122        if mv == 0 || mv > 65535 || near_i >= mv as i32 {
123            return Err(JpegLsError::CorruptStream("invalid LSE MAXVAL/NEAR"));
124        }
125        let (dt1, dt2, dt3) = default_thresholds(mv as i32, near_i);
126        let rt1 = if p.t1 == 0 { dt1 } else { p.t1 };
127        let rt2 = if p.t2 == 0 { dt2 } else { p.t2 };
128        let rt3 = if p.t3 == 0 { dt3 } else { p.t3 };
129        let rrst = if p.reset == 0 { 64 } else { p.reset };
130        if rt1 < near_i + 1 || rt1 > rt2 || rt2 > rt3 || rt3 > mv as i32 || rrst < 3 {
131            return Err(JpegLsError::CorruptStream("invalid LSE thresholds/RESET"));
132        }
133        (mv as i32, rt1, rt2, rt3, rrst)
134    } else {
135        let mv = default_max as i32;
136        if near_i >= mv {
137            return Err(JpegLsError::CorruptStream("NEAR exceeds MAXVAL"));
138        }
139        let (dt1, dt2, dt3) = default_thresholds(mv, near_i);
140        (mv, dt1, dt2, dt3, 64)
141    };
142    let range = if near_i == 0 {
143        maxval + 1
144    } else {
145        (maxval + 2 * near_i) / (2 * near_i + 1) + 1
146    };
147    let bpp = precision.max(2);
148    let mut qbpp = 0u8;
149    while (1i32 << qbpp) < range {
150        qbpp += 1;
151    }
152    let qbpp = qbpp.max(2);
153    let limit = 2 * (bpp + bpp.max(8));
154    Ok(DerivedCoding { maxval, t1, t2, t3, reset, near: near_i, range, qbpp, bpp, limit })
155}
156
157pub fn default_thresholds(maxval: i32, near: i32) -> (i32, i32, i32) {
158    let clamp = |v: i32, lo: i32| v.max(lo).min(maxval);
159    if maxval >= 128 {
160        let factor = (maxval.min(4095) + 128) / 256;
161        let t1 = clamp(factor * (3 - 2) + 2 + 3 * near, near + 1);
162        let t2 = clamp(factor * (7 - 3) + 3 + 5 * near, t1);
163        let t3 = clamp(factor * (21 - 4) + 4 + 7 * near, t2);
164        (t1, t2, t3)
165    } else {
166        let factor = 256 / (maxval + 1);
167        let t1 = clamp(3 / factor + 3 * near, near + 1);
168        let t2 = clamp(7 / factor + 5 * near, t1);
169        let t3 = clamp(21 / factor + 7 * near, t2);
170        (t1, t2, t3)
171    }
172}
173
174#[derive(Clone, Debug)]
175#[allow(dead_code)]
176pub struct ParsedScan<'a> {
177    pub comp_indices: Vec<usize>,
178    pub near: u8,
179    pub ilv: u8,
180    pub point_transform: u8,
181    pub preset: Option<PresetParams>,
182    pub restart_interval: u16,
183    pub entropy_and_tail: &'a [u8],
184}
185
186#[allow(dead_code)]
187pub struct ParsedJpegLs<'a> {
188    pub precision: u8,
189    pub height: u16,
190    pub width: u16,
191    pub comp_ids: [u8; 4],
192    pub comp_count: u8,
193    pub scans: Vec<ParsedScan<'a>>,
194}
195
196#[inline]
197pub fn be_u16(b: &[u8], at: usize) -> Result<u16, JpegLsError> {
198    let s = b.get(at..at + 2).ok_or(JpegLsError::CorruptStream("truncated JPEG-LS marker"))?;
199    Ok(u16::from_be_bytes([s[0], s[1]]))
200}
201
202pub fn parse_jpegls_frame<'a>(data: &'a [u8]) -> Result<ParsedJpegLs<'a>, JpegLsError> {
203    if data.len() < 4 || data[0] != 0xFF || data[1] != 0xD8 {
204        return Err(JpegLsError::CorruptStream("missing JPEG-LS SOI"));
205    }
206    let mut pos = 2usize;
207    let mut sof: Option<(u8, u16, u16, u8, [u8; 4])> = None;
208    let mut preset: Option<PresetParams> = None;
209    let mut restart_interval = 0u16;
210    let mut scans = Vec::new();
211    let mut saw_eoi = false;
212
213    while pos < data.len() {
214        while pos < data.len() && data[pos] == 0xFF {
215            pos += 1;
216        }
217        if pos >= data.len() {
218            return Err(JpegLsError::CorruptStream("truncated JPEG-LS marker"));
219        }
220        let marker = data[pos];
221        pos += 1;
222        if marker == 0xD9 {
223            saw_eoi = true;
224            break;
225        }
226        if matches!(marker, 0x00 | 0x01 | 0xD0..=0xD8) {
227            continue;
228        }
229        let seg_len = be_u16(data, pos)? as usize;
230        if seg_len < 2 {
231            return Err(JpegLsError::CorruptStream("invalid JPEG-LS segment length"));
232        }
233        let payload_end = pos.checked_add(seg_len).ok_or(JpegLsError::Overflow)?;
234        let payload = data.get(pos + 2..payload_end).ok_or(JpegLsError::CorruptStream("truncated JPEG-LS segment"))?;
235        pos = payload_end;
236
237        match marker {
238            0xF7 => {
239                if sof.is_some() {
240                    return Err(JpegLsError::CorruptStream("duplicate SOF55"));
241                }
242                if payload.len() < 6 {
243                    return Err(JpegLsError::CorruptStream("invalid SOF55"));
244                }
245                let prec = payload[0];
246                let h = u16::from_be_bytes([payload[1], payload[2]]);
247                let w = u16::from_be_bytes([payload[3], payload[4]]);
248                let nf = payload[5];
249                if !(2..=16).contains(&prec) || !matches!(nf, 1 | 3) || payload.len() != 6 + 3 * nf as usize {
250                    return Err(JpegLsError::CorruptStream("unsupported SOF55 frame geometry"));
251                }
252                let mut ids = [0u8; 4];
253                for c in 0..nf as usize {
254                    ids[c] = payload[6 + 3 * c];
255                    let hv = payload[6 + 3 * c + 1];
256                    if hv != 0x11 {
257                        return Err(JpegLsError::Unsupported("subsampled JPEG-LS SOF55 unsupported"));
258                    }
259                }
260                sof = Some((prec, h, w, nf, ids));
261            }
262            0xF8 => {
263                if payload.is_empty() {
264                    return Err(JpegLsError::CorruptStream("empty LSE marker"));
265                }
266                match payload[0] {
267                    1 => {
268                        if payload.len() != 11 {
269                            return Err(JpegLsError::CorruptStream("invalid LSE preset parameters"));
270                        }
271                        preset = Some(PresetParams {
272                            maxval: u16::from_be_bytes([payload[1], payload[2]]) as u32,
273                            t1: u16::from_be_bytes([payload[3], payload[4]]) as i32,
274                            t2: u16::from_be_bytes([payload[5], payload[6]]) as i32,
275                            t3: u16::from_be_bytes([payload[7], payload[8]]) as i32,
276                            reset: u16::from_be_bytes([payload[9], payload[10]]) as i32,
277                        });
278                    }
279                    2 | 3 => return Err(JpegLsError::Unsupported("JPEG-LS LSE mapping tables unsupported")),
280                    _ => return Err(JpegLsError::Unsupported("unsupported JPEG-LS LSE id")),
281                }
282            }
283            0xDD => {
284                if payload.len() != 2 {
285                    return Err(JpegLsError::CorruptStream("invalid DRI marker"));
286                }
287                restart_interval = u16::from_be_bytes([payload[0], payload[1]]);
288            }
289            0xDA => {
290                let (_, _, _, nf, ids) = sof.ok_or(JpegLsError::CorruptStream("SOS before SOF55"))?;
291                if payload.is_empty() {
292                    return Err(JpegLsError::CorruptStream("empty SOS"));
293                }
294                let ns = payload[0];
295                if ns == 0 || ns > nf || payload.len() != 1 + 2 * ns as usize + 3 {
296                    return Err(JpegLsError::CorruptStream("invalid SOS length"));
297                }
298                let mut comp_indices = Vec::with_capacity(ns as usize);
299                for s in 0..ns as usize {
300                    let cs = payload[1 + 2 * s];
301                    let idx = (0..nf as usize)
302                        .find(|&c| ids[c] == cs)
303                        .ok_or(JpegLsError::CorruptStream("SOS references unknown component"))?;
304                    if comp_indices.contains(&idx) {
305                        return Err(JpegLsError::CorruptStream("duplicate component in SOS"));
306                    }
307                    comp_indices.push(idx);
308                }
309                let tail = &payload[1 + 2 * ns as usize..];
310                let near = tail[0];
311                let ilv = tail[1];
312                let pt = tail[2] & 0x0F;
313                if ilv > 2 || (ilv == 0 && ns != 1) || (ilv != 0 && ns != nf) {
314                    return Err(JpegLsError::CorruptStream("invalid JPEG-LS ILV/component count"));
315                }
316                if pt != 0 {
317                    return Err(JpegLsError::Unsupported("JPEG-LS point transform unsupported"));
318                }
319                let entropy_start = pos;
320                let scan_end = find_scan_end(data, &mut pos)?;
321                scans.push(ParsedScan {
322                    comp_indices,
323                    near,
324                    ilv,
325                    point_transform: pt,
326                    preset,
327                    restart_interval,
328                    entropy_and_tail: &data[entropy_start..scan_end],
329                });
330            }
331            0xE0..=0xEF | 0xFE => {}
332            _ => return Err(JpegLsError::Unsupported("unsupported JPEG-LS marker segment")),
333        }
334        if marker != 0xDA && pos < data.len() && data[pos] != 0xFF {
335            return Err(JpegLsError::CorruptStream("unexpected byte between JPEG-LS markers"));
336        }
337    }
338    let (prec, h, w, nf, ids) = sof.ok_or(JpegLsError::CorruptStream("missing SOF55"))?;
339    if !saw_eoi || scans.is_empty() {
340        return Err(JpegLsError::CorruptStream("missing EOI or SOS in JPEG-LS stream"));
341    }
342    Ok(ParsedJpegLs { precision: prec, height: h, width: w, comp_ids: ids, comp_count: nf, scans })
343}
344
345pub fn find_scan_end(data: &[u8], pos: &mut usize) -> Result<usize, JpegLsError> {
346    let mut i = *pos;
347    while i < data.len() {
348        if data[i] == 0xFF {
349            if i + 1 >= data.len() {
350                return Err(JpegLsError::CorruptStream("truncated JPEG-LS entropy scan"));
351            }
352            let next = data[i + 1];
353            if next <= 0x7F {
354                i += 2;
355                continue;
356            }
357            if (0xD0..=0xD7).contains(&next) {
358                i += 2;
359                continue;
360            }
361            *pos = i;
362            return Ok(i);
363        }
364        i += 1;
365    }
366    Err(JpegLsError::CorruptStream("unterminated JPEG-LS scan before EOI"))
367}