Expand description
Pure-Rust decoders used by the format readers. No C toolchain is needed, which keeps the musl static builds simple. Every function returns owned bytes in the caller’s expected layout; nothing here knows about file formats.
Every decoder is bounded: output never grows past the caller’s expected size (plus one
byte to detect overlong streams), and size hints are only trusted up to
MAX_PREALLOC for up-front allocation.
Decoding failures are reported as CodecError values, never by exiting the process.
§Cargo features
All enabled by default. A disabled codec’s functions still exist and return
CodecError::NotCompiled.
| feature | codecs |
|---|---|
zstd | zstd_decode, zstd1_decode (Zstandard, via ruzstd) |
jpeg | jpeg_decode, jpeg_decode_tiff and their _limited forms (baseline, progressive, lossless) |
jpegxr | jpegxr_decode (JPEG XR, as in CZI files; openreadout-jpegxr, a safe port of jxrlib) |
jpegls | jpegls_decode_limited (JPEG-LS lossless and near-lossless, single component; pure_jpegls) |
jpeg2000 | jpeg2000_decode and jpeg2000_decode_limited (rust-j2k, fallback dicom-toolkit-jpeg2000) |
lzw | lzw_decode (TIFF LZW) |
deflate | zlib_decode |
lz4 | lz4_block_decode, lz4_sized_decode, hdf5_lz4_decode and LZ4 inside Blosc |
chunked_decode (CZI chunked compression) uses the zstd and lz4 features.
unshuffle_hilo, packbits_decode, lzf_decode, blosc_decode, blosclz_decode and
lzma2_decode (raw LZMA2 chunks) need no feature.
§Example
use openreadout_codecs::{packbits_decode, unshuffle_hilo};
// PackBits: a literal run of 2 bytes, then the byte 0xAA repeated 3 times.
let raw = packbits_decode(&[0x01, 0x10, 0x20, 0xFE, 0xAA], 5)?;
assert_eq!(raw, [0x10, 0x20, 0xAA, 0xAA, 0xAA]);
// "HiLo": all low bytes of 16-bit samples, then all high bytes.
assert_eq!(unshuffle_hilo(&[0x01, 0x02, 0xA0, 0xB0]), [0x01, 0xA0, 0x02, 0xB0]);Structs§
- Blosc
Header - Header fields of a Blosc 1 chunk.
- Jpeg
Markers - What a JPEG stream’s markers say about its colour coding, read up to the first scan
(
SOS) without decoding anything. Seejpeg_markers. - Raster
- A decoded raster: interleaved samples, no row padding.
- Zstd1
Header - Parsed “zstd1” prefix used by CZI compression id 6:
header_size,chunk_kind, flags.
Enums§
- Blosc
Compressor - The compressor recorded in a Blosc header (flags bits 5–7).
- Codec
Error - Codec failure.
- Jpeg
Color - How
jpeg_decode_tifftreats the colour components of the codestream.
Constants§
- MAX_
PREALLOC - Largest buffer a decoder pre-allocates from a caller-supplied size hint (64 MiB). Output beyond this grows on demand, so a lying size field cannot force a huge up-front allocation.
- MAX_
UNSIZED_ OUTPUT - Output cap for streams whose decoded size is unknown (
expected_len == 0): 1 GiB.
Functions§
- bitshuffle_
decode - The HDF5 bitshuffle filter (registered filter id 32008, bitshuffle library framing): with
LZ4 (
compression2), a big-endian u64 decoded size and u32 block size in bytes, then per block of whole elements a big-endian u32 compressed size and an LZ4 block holding the bit-shuffled block; the elements left over after the last whole block of 8 are stored as they are at the end. Without compression (compression0) the chunk is the bit-shuffled data itself, cut into blocks ofblock_elemselements (0: the library’s default).expectedis the decoded size when known (0: take it from the chunk). - blosc_
decode - Decode one Blosc 1 chunk (as written by c-blosc 1.x / numcodecs
Blosc). - blosc_
header - Parse the 16-byte Blosc header.
- blosclz_
decode - BloscLZ (the default Blosc compressor), following
blosclz_decompressin c-blosc (BSD-3). - chunked_
decode - Decode a chunked payload to
expected_lenbytes (0 = unknown).bytes_per_sampleis the size of one sample of the pixel type, needed to undo the HiLo split. - hdf5_
lz4_ decode - The HDF5 LZ4 filter (registered filter id 32004): a big-endian u64 decoded size and a big-endian u32 block size, then per block a big-endian u32 compressed size and the LZ4 block (stored as is when the compressed size equals the block’s decoded size).
- jpeg2000_
decode - Decode a JPEG 2000 codestream (raw J2K
FF 4F FF 51…or a JP2 file) at its native bit depth. Samples are interleaved; precisions above 8 bits come back as little-endian u16. Used for the frames of legacy (NIS-Elements 2.x) ND2 files, VSI/ETS tiles and Aperio SVS tiles. Backed byrust-j2k(pure Rust, nounsafe, OpenJPEG-style mid-point reconstruction), withdicom-toolkit-jpeg2000for codestreams it does not support (seej2k.rs). The caller converts colour: components come back as coded (after the codestream’s own RCT/ICT). Signed components (DICOM CT) come back as the two’s-complement bit pattern of i8 or i16. - jpeg2000_
decode_ limited jpeg2000_decode, refusing (before decoding) an image that would decode to more thanmax_bytes(counted at 2 bytes per sample).- jpeg_
decode - Decode a JPEG stream (ITU-T T.81): baseline and progressive 8-bit, sequential 12-bit
(extended process, Huffman coding, no chroma subsampling), lossless (SOF3) up to 16 bit.
Returns gray (
channels == 1) or R,G,B (channels == 3) samples; samples above 8 bits come back as little-endian u16. Progressive or subsampled 12-bit streams and CMYK are rejected with an error. - jpeg_
decode_ limited jpeg_decode, refusing (before decoding anything) a frame whose decoded size would exceedmax_bytes. Callers that know the tile or plane size pass a bound derived from it, so a few-byte stream declaring 60000 x 15000 pixels costs nothing.- jpeg_
decode_ reduced jpeg_decode_limitedat a reduced size:shift1, 2 or 3 decodes at 1/2, 1/4 or 1/8 of the width and height (rounded up) with jpeg-decoder’s reduced inverse DCT, as slide readers do for levels the file does not store. 8-bit streams only.- jpeg_
decode_ tiff - Decode a JPEG chunk of a TIFF (compression 7).
tablesis the abbreviated table-specification stream of theJPEGTablestag (SOI, DQT/DHT segments,EOI), spliced in front of the chunk;colorsays whether the components are already R, G, B (TIFF photometric RGB, decoded as coded) or YCbCr (photometric YCbCr, converted to R, G, B). Same decoder and output conventions asjpeg_decode. - jpeg_
decode_ tiff_ limited jpeg_decode_tiffwith the frame-size bound ofjpeg_decode_limited.- jpeg_
markers - Scan the marker segments of a JPEG stream (
tablesfirst when given, as for a TIFFJPEGTablestag) up to the firstSOS. Only segment lengths are followed; nothing is decoded. Fails when the stream does not start withSOIor a segment runs past the end before a frame header was seen. - jpegls_
decode_ limited - Decode a JPEG-LS stream (ITU-T T.87: lossless and near-lossless, one component), refusing
(before decoding) an image that would decode to more than
max_bytes(counted at 2 bytes per sample). Precisions up to 8 bits come back as u8, above as little-endian u16. Colour (multi-component) streams are refused withCodecError::Unsupported. - jpegxl_
decode_ limited - Decode a JPEG XL codestream or container (TIFF compression 50002/52546): the first frame,
colour channels then extra channels (alpha, …), interleaved; u8 up to 8 bits per sample,
little-endian u16 up to 16, f32 for float images. Refuses (before rendering) an image larger
than
max_bytes. Backed byjxl-oxide. - jpegxr_
decode - Decode a JPEG XR codestream (as embedded in CZI subblocks).
- jpegxr_
decode_ expect - Decode a JPEG XR codestream, refusing before any pixel allocation when the codestream’s
own dimensions differ from
expect(width, height), e.g. the geometry a CZI directory entry declares. Without an expectation the decoded size is capped atMAX_UNSIZED_OUTPUT. - lerc_
decode_ limited - Decode a LERC2 blob (TIFF compression 34887, after any deflate/zstd wrapping is removed) to
interleaved little-endian samples of the blob’s type (
channels= depth x bands); pixels its mask marks invalid are 0. Refuses (before decoding) an image larger thanmax_bytes. Backed bylerc-rs. - lz4_
block_ decode - One raw LZ4 block (no frame, no size prefix) that decodes to exactly
expectedbytes. - lz4_
sized_ decode - numcodecs
LZ4: a little-endian u32 decoded size, then one LZ4 block. - lzf_
decode - LZF decompression (the public liblzf scheme, as in Agilent
MSProfile.binand early Bruker TDF frames): a control byte below 32 copies that many plus one literal bytes; otherwise its top three bits are a back-reference length (an extra length byte follows when all three are set) and its low five bits, with the next byte, the distance back.max_lencaps the output (0 =MAX_UNSIZED_OUTPUT); a stream that would produce more is an error. - lzma2_
decode - Decode a raw LZMA2 stream (a run of chunks ended by a
0x00control byte; no.xzcontainer and no dictionary-size byte).expected_lenis the decoded size when the caller knows it (0 = unknown, capped at 1 GiB); a stream decoding to another size is an error. Returns the decoded bytes and the number of input bytes consumed (through the end byte). - lzw_
decode - TIFF-flavoured LZW (MSB-first, 8-bit symbols), as used by CZI compression id 2.
- packbits_
decode - Apple/TIFF PackBits run-length decoding (TIFF compression 32773). Stops when
expected_lenbytes have been produced (0 = decode the whole input). - snappy_
decode - A Snappy raw block (public format description,
format_description.txt): a varint decoded length, then literals and back references (1, 2 or 4-byte offsets). Must decode to exactlyexpectedbytes. - unshuffle_
hilo - Undo the
HiLobyte shuffle: input is all low bytes followed by all high bytes of 16-bit little-endian samples; output is the interleaved samples. - webp_
decode_ limited - Decode a WebP file (lossy VP8 or lossless VP8L; TIFF compression 50001) to 8-bit R,G,B, or
R,G,B,A when the file has alpha, refusing (before decoding) an image larger than
max_bytes. Backed byimage-webp(pure Rust, nounsafe). - zlib_
decode - zlib/deflate (used by some ND2 chunks and by OME-TIFF). With a nonzero
expected_lenat most that many bytes are inflated (callers only use that prefix). - zstd1_
decode - Decode a zstd1 payload into interleaved samples of
bytes_per_samplebytes. - zstd1_
header - Parse the zstd1 header; returns the header and the offset of the zstd frame.
- zstd_
decode - Decompress a plain zstd frame.
expected_lenis a sanity bound (0 = unknown); decoding stops one byte past it, so a decompression bomb costs at mostexpected_len + 1bytes.
Type Aliases§
- Result
- Result alias of this crate.