Skip to main content

Crate openreadout_codecs

Crate openreadout_codecs 

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

featurecodecs
zstdzstd_decode, zstd1_decode (Zstandard, via ruzstd)
jpegjpeg_decode, jpeg_decode_tiff and their _limited forms (baseline, progressive, lossless)
jpegxrjpegxr_decode (JPEG XR, as in CZI files; openreadout-jpegxr, a safe port of jxrlib)
jpeglsjpegls_decode_limited (JPEG-LS lossless and near-lossless, single component; pure_jpegls)
jpeg2000jpeg2000_decode and jpeg2000_decode_limited (rust-j2k, fallback dicom-toolkit-jpeg2000)
lzwlzw_decode (TIFF LZW)
deflatezlib_decode
lz4lz4_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§

BloscHeader
Header fields of a Blosc 1 chunk.
JpegMarkers
What a JPEG stream’s markers say about its colour coding, read up to the first scan (SOS) without decoding anything. See jpeg_markers.
Raster
A decoded raster: interleaved samples, no row padding.
Zstd1Header
Parsed “zstd1” prefix used by CZI compression id 6: header_size, chunk_kind, flags.

Enums§

BloscCompressor
The compressor recorded in a Blosc header (flags bits 5–7).
CodecError
Codec failure.
JpegColor
How jpeg_decode_tiff treats 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 (compression 2), 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 (compression 0) the chunk is the bit-shuffled data itself, cut into blocks of block_elems elements (0: the library’s default). expected is 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_decompress in c-blosc (BSD-3).
chunked_decode
Decode a chunked payload to expected_len bytes (0 = unknown). bytes_per_sample is 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 by rust-j2k (pure Rust, no unsafe, OpenJPEG-style mid-point reconstruction), with dicom-toolkit-jpeg2000 for codestreams it does not support (see j2k.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 than max_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 exceed max_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_limited at a reduced size: shift 1, 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). tables is the abbreviated table-specification stream of the JPEGTables tag (SOI, DQT/DHT segments, EOI), spliced in front of the chunk; color says 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 as jpeg_decode.
jpeg_decode_tiff_limited
jpeg_decode_tiff with the frame-size bound of jpeg_decode_limited.
jpeg_markers
Scan the marker segments of a JPEG stream (tables first when given, as for a TIFF JPEGTables tag) up to the first SOS. Only segment lengths are followed; nothing is decoded. Fails when the stream does not start with SOI or 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 with CodecError::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 by jxl-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 at MAX_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 than max_bytes. Backed by lerc-rs.
lz4_block_decode
One raw LZ4 block (no frame, no size prefix) that decodes to exactly expected bytes.
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.bin and 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_len caps 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 0x00 control byte; no .xz container and no dictionary-size byte). expected_len is 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_len bytes 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 exactly expected bytes.
unshuffle_hilo
Undo the HiLo byte 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 by image-webp (pure Rust, no unsafe).
zlib_decode
zlib/deflate (used by some ND2 chunks and by OME-TIFF). With a nonzero expected_len at most that many bytes are inflated (callers only use that prefix).
zstd1_decode
Decode a zstd1 payload into interleaved samples of bytes_per_sample bytes.
zstd1_header
Parse the zstd1 header; returns the header and the offset of the zstd frame.
zstd_decode
Decompress a plain zstd frame. expected_len is a sanity bound (0 = unknown); decoding stops one byte past it, so a decompression bomb costs at most expected_len + 1 bytes.

Type Aliases§

Result
Result alias of this crate.