Skip to main content

openreadout_jpegxr/
lib.rs

1//! Memory-safe JPEG XR decoder (ITU-T T.832 | ISO/IEC 29199-2).
2//!
3//! A `forbid(unsafe_code)` Rust port of the decoder path of Microsoft's jxrlib ("JPEG XR Device
4//! Porting Kit", BSD 2-clause, see `LICENSE`), written to replace a machine translation of the
5//! same library that could write past its buffers. The port keeps jxrlib's arithmetic and its
6//! macroblock schedule, so decoded pixels are bit-identical to jxrlib's (which is what
7//! imagecodecs, czifile and ZEISS libCZI use). Malformed codestreams give an [`Error`], never a
8//! panic or an out-of-bounds access; reads past the end of the data stop decoding.
9//!
10//! Supported: every codec sub-version, spatial and frequency bitstream order, tiles (soft and
11//! hard), all overlap modes, internal Y-only, 4:2:0, 4:2:2, 4:4:4 and N-component planes,
12//! scaled and unscaled arithmetic, flexbits trimming and dropped subbands, and output as grey,
13//! RGB/BGR or N-channel samples of 8/16 bit unsigned, 16/32 bit fixed point, half and single
14//! float. Not supported (clean [`Error::Unsupported`]): alpha planes, CMYK, RGBE, packed
15//! 5/6/10-bit and bilevel formats, YCC outputs and non-identity orientation tags.
16//!
17//! ```no_run
18//! let bytes = std::fs::read("tile.jxr")?;
19//! let img = openreadout_jpegxr::decode(&bytes, 1 << 30)?;
20//! println!("{}x{} x{} {:?}", img.width, img.height, img.channels, img.sample);
21//! # Ok::<(), Box<dyn std::error::Error>>(())
22//! ```
23#![forbid(unsafe_code)]
24#![warn(missing_docs)]
25// Short names mirror jxrlib's (a, b, c, d, p0, p1 ...) so the port can be read against it.
26#![allow(clippy::many_single_char_names)]
27// The port keeps jxrlib's control flow: sequential reads in `if` chains (each call consumes bits),
28// sign tests as if/else chains, index loops over parallel tables.
29#![allow(
30    clippy::same_functions_in_if_condition,
31    clippy::comparison_chain,
32    clippy::needless_range_loop,
33    clippy::items_after_statements
34)]
35
36mod bits;
37mod decoder;
38mod header;
39mod huff;
40mod output;
41mod quant;
42mod transform;
43mod w;
44
45use header::{bd, cf};
46
47/// Decoding failure.
48#[derive(Debug, Clone, PartialEq, Eq)]
49#[non_exhaustive]
50pub enum Error {
51    /// The data is not a valid JPEG XR file or codestream.
52    Decode(String),
53    /// A valid feature this decoder does not implement.
54    Unsupported(String),
55}
56
57impl Error {
58    pub(crate) fn decode(msg: &str) -> Self {
59        Error::Decode(msg.to_string())
60    }
61    pub(crate) fn unsupported(msg: &str) -> Self {
62        Error::Unsupported(msg.to_string())
63    }
64}
65
66impl std::fmt::Display for Error {
67    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
68        match self {
69            Error::Decode(m) => write!(f, "invalid JPEG XR data: {m}"),
70            Error::Unsupported(m) => write!(f, "unsupported JPEG XR feature: {m}"),
71        }
72    }
73}
74
75impl std::error::Error for Error {}
76
77/// Result alias of this crate.
78pub type Result<T> = std::result::Result<T, Error>;
79
80/// Sample type of a decoded image. Multi-byte samples are little-endian.
81#[derive(Debug, Clone, Copy, PartialEq, Eq)]
82#[non_exhaustive]
83pub enum SampleType {
84    /// Unsigned 8-bit.
85    U8,
86    /// Unsigned 16-bit.
87    U16,
88    /// Signed 16-bit fixed point (JPEG XR "16bppGrayFixedPoint" and friends).
89    I16,
90    /// IEEE half-precision float (bits).
91    F16,
92    /// Signed 32-bit fixed point.
93    I32,
94    /// IEEE single-precision float.
95    F32,
96}
97
98impl SampleType {
99    /// Bytes per sample.
100    pub fn bytes(self) -> usize {
101        match self {
102            SampleType::U8 => 1,
103            SampleType::U16 | SampleType::I16 | SampleType::F16 => 2,
104            SampleType::I32 | SampleType::F32 => 4,
105        }
106    }
107}
108
109/// Size and sample layout of a codestream, read from its headers only.
110#[derive(Debug, Clone, PartialEq, Eq)]
111pub struct Info {
112    /// Width in pixels.
113    pub width: u32,
114    /// Height in pixels.
115    pub height: u32,
116    /// Samples per pixel.
117    pub channels: u32,
118    /// Sample type.
119    pub sample: SampleType,
120    /// True when the three colour samples are stored B, G, R (JPEG XR "BGR" pixel formats).
121    pub bgr: bool,
122}
123
124/// A decoded image: `width * height * channels` interleaved samples, no row padding.
125#[derive(Debug, Clone)]
126pub struct Image {
127    /// Width in pixels.
128    pub width: u32,
129    /// Height in pixels.
130    pub height: u32,
131    /// Samples per pixel.
132    pub channels: u32,
133    /// Sample type.
134    pub sample: SampleType,
135    /// True when the three colour samples are stored B, G, R.
136    pub bgr: bool,
137    /// The samples.
138    pub data: Vec<u8>,
139}
140
141/// Pixel format of the container (jxrlib `PKPixelInfo` rows that are decodable).
142#[derive(Debug, Clone, Copy)]
143struct PixelFormat {
144    channels: usize,
145    bd: u8,
146    bits_per_unit: usize,
147    bgr: bool,
148    unsupported: Option<&'static str>,
149}
150
151const GUID_PREFIX: [u8; 15] = [
152    0x24, 0xC3, 0xDD, 0x6F, 0x03, 0x4E, 0xFE, 0x4B, 0xB1, 0x85, 0x3D, 0x77, 0x76, 0x8D, 0xC9,
153];
154const GUID_32BPP_RGB: [u8; 16] = [
155    0x95, 0x6B, 0x8C, 0xD9, 0xFE, 0x3E, 0xD6, 0x47, 0xBB, 0x25, 0xEB, 0x17, 0x48, 0xAB, 0x0C, 0xF1,
156];
157const GUID_96BPP_RGB_FLOAT: [u8; 16] = [
158    0x8F, 0xD7, 0xFE, 0xE3, 0xDB, 0xE8, 0xCF, 0x4A, 0x84, 0xC1, 0xE9, 0x7F, 0x61, 0x36, 0xB3, 0x27,
159];
160
161const fn pf(channels: usize, _cf: u8, bd: u8, bits: usize, bgr: bool) -> PixelFormat {
162    PixelFormat {
163        channels,
164        bd,
165        bits_per_unit: bits,
166        bgr,
167        unsupported: None,
168    }
169}
170
171const fn pf_no(what: &'static str) -> PixelFormat {
172    PixelFormat {
173        channels: 0,
174        bd: 0,
175        bits_per_unit: 0,
176        bgr: false,
177        unsupported: Some(what),
178    }
179}
180
181fn pixel_format(guid: &[u8]) -> Option<PixelFormat> {
182    if guid == GUID_32BPP_RGB {
183        return Some(pf(3, cf::RGB, bd::B8, 32, false));
184    }
185    if guid == GUID_96BPP_RGB_FLOAT {
186        return Some(pf(3, cf::RGB, bd::B32F, 96, false));
187    }
188    if guid.len() != 16 || guid[..15] != GUID_PREFIX {
189        return None;
190    }
191    Some(match guid[15] {
192        0x08 => pf(1, cf::Y_ONLY, bd::B8, 8, false),
193        0x0b => pf(1, cf::Y_ONLY, bd::B16, 16, false),
194        0x13 => pf(1, cf::Y_ONLY, bd::B16S, 16, false),
195        0x3e => pf(1, cf::Y_ONLY, bd::B16F, 16, false),
196        0x3f => pf(1, cf::Y_ONLY, bd::B32S, 32, false),
197        0x11 => pf(1, cf::Y_ONLY, bd::B32F, 32, false),
198        0x0d => pf(3, cf::RGB, bd::B8, 24, false),
199        0x0c => pf(3, cf::RGB, bd::B8, 24, true),
200        0x0e => pf(3, cf::RGB, bd::B8, 32, true),
201        0x15 => pf(3, cf::RGB, bd::B16, 48, false),
202        0x12 => pf(3, cf::RGB, bd::B16S, 48, false),
203        0x3b => pf(3, cf::RGB, bd::B16F, 48, false),
204        0x40 => pf(3, cf::RGB, bd::B16S, 64, false),
205        0x42 => pf(3, cf::RGB, bd::B16F, 64, false),
206        0x18 => pf(3, cf::RGB, bd::B32S, 96, false),
207        0x41 => pf(3, cf::RGB, bd::B32S, 128, false),
208        0x1b => pf(3, cf::RGB, bd::B32F, 128, false),
209        n @ 0x20..=0x25 => {
210            let c = usize::from(n - 0x20) + 3;
211            pf(c, cf::NCOMPONENT, bd::B8, c * 8, false)
212        }
213        n @ 0x26..=0x2b => {
214            let c = usize::from(n - 0x26) + 3;
215            pf(c, cf::NCOMPONENT, bd::B16, c * 16, false)
216        }
217        0x0f | 0x10 | 0x16 | 0x17 | 0x19 | 0x1a | 0x1d | 0x1e | 0x3a | 0x2c..=0x39 => {
218            pf_no("pixel formats with an alpha channel")
219        }
220        0x1c | 0x1f | 0x54 | 0x55 => pf_no("CMYK pixel formats"),
221        0x09 | 0x0a | 0x14 => pf_no("packed 5/6/10-bit RGB pixel formats"),
222        0x05 => pf_no("bilevel (black and white) pixel format"),
223        0x3d => pf_no("RGBE pixel format"),
224        0x44..=0x53 => pf_no("YCC pixel formats"),
225        _ => return None,
226    })
227}
228
229fn le16(d: &[u8], at: usize) -> Result<u16> {
230    d.get(at..at + 2)
231        .map(|b| u16::from_le_bytes([b[0], b[1]]))
232        .ok_or_else(|| Error::decode("container directory runs past the end of the data"))
233}
234
235fn le32(d: &[u8], at: usize) -> Result<u32> {
236    d.get(at..at + 4)
237        .map(|b| u32::from_le_bytes([b[0], b[1], b[2], b[3]]))
238        .ok_or_else(|| Error::decode("container directory runs past the end of the data"))
239}
240
241/// The codestream and pixel format of a JPEG XR file (jxrlib `ReadContainer`, `ParsePFD`).
242fn container(data: &[u8]) -> Result<(&[u8], Option<PixelFormat>)> {
243    if data.starts_with(b"WMPHOTO") {
244        return Ok((data, None));
245    }
246    if data.len() < 8 || &data[..2] != b"II" || data[2] != 0xBC || data[3] > 1 {
247        return Err(Error::decode("not a JPEG XR file (no II BC header)"));
248    }
249    let ifd = le32(data, 4)? as usize;
250    let count = le16(data, ifd)?;
251    if count == 0 || count == u16::MAX {
252        return Err(Error::decode("empty image directory"));
253    }
254    let (mut guid, mut offset, mut bytes) = (None, None, 0u32);
255    for i in 0..usize::from(count) {
256        let at = ifd + 2 + 12 * i;
257        let tag = le16(data, at)?;
258        let n = le32(data, at + 4)?;
259        let value = le32(data, at + 8)?;
260        match tag {
261            0xBC01 => {
262                let o = value as usize;
263                guid =
264                    Some(data.get(o..o + 16).ok_or_else(|| {
265                        Error::decode("pixel format runs past the end of the data")
266                    })?);
267            }
268            0xBC02 => {
269                if n != 1 {
270                    return Err(Error::decode("invalid orientation tag"));
271                }
272                if value != 0 {
273                    return Err(Error::unsupported("rotated or flipped orientation"));
274                }
275            }
276            0xBCC0 => {
277                if n != 1 {
278                    return Err(Error::decode("invalid image offset tag"));
279                }
280                offset = Some(value as usize);
281            }
282            0xBCC1 => {
283                if n != 1 {
284                    return Err(Error::decode("invalid image byte count tag"));
285                }
286                bytes = value;
287            }
288            _ => {}
289        }
290    }
291    let guid = guid.ok_or_else(|| Error::decode("no pixel format tag"))?;
292    let format = pixel_format(guid).ok_or_else(|| Error::unsupported("unknown pixel format"))?;
293    if let Some(why) = format.unsupported {
294        return Err(Error::unsupported(why));
295    }
296    let offset = offset.ok_or_else(|| Error::decode("no image offset tag"))?;
297    let rest = data
298        .get(offset..)
299        .ok_or_else(|| Error::decode("image offset past the end of the data"))?;
300    let stream = if bytes == 0 {
301        rest
302    } else {
303        &rest[..rest.len().min(bytes as usize)]
304    };
305    Ok((stream, Some(format)))
306}
307
308/// Everything decided from the headers before decoding.
309struct Plan<'a> {
310    stream: &'a [u8],
311    img: header::ImageHeader,
312    plane: header::PlaneHeader,
313    plane_end: u64,
314    info: Info,
315    cf_ext: u8,
316    px_samples: usize,
317    rgb: bool,
318}
319
320fn sample_type(b: u8) -> Result<SampleType> {
321    Ok(match b {
322        bd::B8 => SampleType::U8,
323        bd::B16 => SampleType::U16,
324        bd::B16S => SampleType::I16,
325        bd::B16F => SampleType::F16,
326        bd::B32S => SampleType::I32,
327        bd::B32F => SampleType::F32,
328        _ => {
329            return Err(Error::unsupported(
330                "bit depth (bilevel, packed or 32-bit unsigned)",
331            ));
332        }
333    })
334}
335
336fn plan(data: &[u8]) -> Result<Plan<'_>> {
337    let (stream, format) = container(data)?;
338    let (img, plane, plane_end) = header::read_headers(stream)?;
339    if img.alpha {
340        return Err(Error::unsupported("alpha image plane"));
341    }
342    if matches!(plane.cf, cf::CMYK) {
343        return Err(Error::unsupported("CMYK colour format"));
344    }
345    let sample = sample_type(img.output_bd)?;
346    // jxrlib `WMPhotoValidate`: the output colour format follows the header, adjusted to the
347    // internal one.
348    let int = plane.cf;
349    let mut ext = img.output_cf;
350    if int == cf::NCOMPONENT {
351        ext = cf::NCOMPONENT;
352    }
353    if int == cf::YUV_422 && ext == cf::YUV_420 {
354        ext = cf::YUV_422;
355    }
356    if int == cf::YUV_444 && (ext == cf::YUV_422 || ext == cf::YUV_420) {
357        ext = cf::YUV_444;
358    }
359    if img.output_cf == cf::RGB && ext != cf::Y_ONLY && ext != cf::NCOMPONENT {
360        ext = cf::RGB;
361    }
362    if img.output_cf == cf::RGBE {
363        return Err(Error::unsupported("RGBE output"));
364    }
365    let effective = if int == cf::Y_ONLY { cf::Y_ONLY } else { ext };
366    let written = match effective {
367        cf::RGB => 3,
368        cf::Y_ONLY if ext == cf::RGB => 3,
369        cf::Y_ONLY => 1,
370        cf::YUV_444 | cf::NCOMPONENT => plane.channels,
371        _ => return Err(Error::unsupported("YCC or CMYK output colour format")),
372    };
373    let (channels, px_samples, bgr) = match format {
374        Some(f) => {
375            if f.bd != img.output_bd {
376                return Err(Error::decode(
377                    "pixel format and codestream bit depths disagree",
378                ));
379            }
380            let px_samples = f.bits_per_unit / 8 / sample.bytes();
381            if px_samples < written || px_samples < f.channels {
382                return Err(Error::decode(
383                    "pixel format too small for the coded channels",
384                ));
385            }
386            (f.channels, px_samples, f.bgr)
387        }
388        None => (written, written, false),
389    };
390    let width = u32::try_from(img.width).map_err(|_| Error::decode("image too wide"))?;
391    let height = u32::try_from(img.height).map_err(|_| Error::decode("image too tall"))?;
392    Ok(Plan {
393        stream,
394        info: Info {
395            width,
396            height,
397            channels: channels as u32,
398            sample,
399            bgr: bgr && channels >= 3,
400        },
401        cf_ext: ext,
402        px_samples,
403        rgb: !bgr,
404        img,
405        plane,
406        plane_end,
407    })
408}
409
410/// Read the size and sample layout without decoding pixels.
411pub fn probe(data: &[u8]) -> Result<Info> {
412    Ok(plan(data)?.info)
413}
414
415/// Decode a JPEG XR file (`II BC` container) or bare codestream (`WMPHOTO`). Refuses, before
416/// allocating anything large, images whose decoded size or working memory exceeds `max_bytes`.
417pub fn decode(data: &[u8], max_bytes: usize) -> Result<Image> {
418    let p = plan(data)?;
419    let Info {
420        width,
421        height,
422        channels,
423        sample,
424        bgr,
425    } = p.info.clone();
426    let sb = sample.bytes();
427    let too_big = || {
428        Error::Unsupported(format!(
429            "a {width}x{height} image is larger than the decode limit"
430        ))
431    };
432    let px = (width as usize)
433        .checked_mul(height as usize)
434        .ok_or_else(too_big)?;
435    let out_len = px
436        .checked_mul(p.px_samples * sb)
437        .filter(|&n| n <= max_bytes)
438        .ok_or_else(too_big)?;
439    let full_w = p.img.width + p.img.extra_left + p.img.extra_right;
440    let mb_w = usize::try_from(full_w.div_ceil(16)).map_err(|_| too_big())?;
441    // Two macroblock rows of 32-bit coefficients per channel, plus chroma upsampling rows.
442    let work = (mb_w + 2)
443        .checked_mul(256 * 4 * 2 * (p.plane.channels + 2))
444        .filter(|&n| n <= max_bytes.max(256 << 20))
445        .ok_or_else(too_big)?;
446    let _ = work;
447    let uv_res_change = p.cf_ext != cf::Y_ONLY
448        && ((p.plane.cf == cf::YUV_420 && p.cf_ext != cf::YUV_420)
449            || (p.plane.cf == cf::YUV_422 && p.cf_ext != cf::YUV_422));
450    let res_len = if uv_res_change { mb_w * 256 } else { 0 };
451    let mut out = output::Output {
452        cf_int: p.plane.cf,
453        cf_ext: p.cf_ext,
454        bd: p.img.output_bd,
455        scaled: p.plane.scaled,
456        shift: p.plane.shift,
457        exp_bias: p.plane.exp_bias,
458        rgb: p.rgb,
459        channels: p.plane.channels,
460        width: width as usize,
461        height: height as usize,
462        left: p.img.extra_left as usize,
463        top: p.img.extra_top as usize,
464        mb_w,
465        px_samples: p.px_samples,
466        sample_bytes: sb,
467        uv_res_change,
468        res_u: vec![0; res_len],
469        res_v: vec![0; res_len],
470        data: vec![0; out_len],
471    };
472    let mut dec = decoder::Decoder::new(p.stream, p.img, p.plane, p.plane_end)?;
473    debug_assert_eq!(dec.mb_width(), mb_w);
474    dec.run(&mut out)?;
475    output::fixup_gray_to_rgb(&mut out);
476    let channels_us = channels as usize;
477    let data = if p.px_samples == channels_us {
478        out.data
479    } else {
480        let (src, dst) = (p.px_samples * sb, channels_us * sb);
481        let mut v = Vec::with_capacity(px * dst);
482        for pxl in out.data.chunks_exact(src) {
483            v.extend_from_slice(&pxl[..dst]);
484        }
485        v
486    };
487    Ok(Image {
488        width,
489        height,
490        channels,
491        sample,
492        bgr,
493        data,
494    })
495}