pliocomp 0.4.0

PLIO (Pixel List I/O) mask compression, as used in FITS tile compression
Documentation

pliocomp

Crates.io Actions Status Documentation codecov Dependency status

pliocomp is a small, dependency-free Rust crate implementing PLIO (Pixel LIst I/O) mask compression, the run-length scheme used by IRAF and by the FITS tile-compression convention (section 6.3 of the standard) to store integer mask images losslessly.

PLIO is built for masks: arrays that are mostly zero, punctuated by runs of a constant non-negative "high value" that flag regions of interest (bad pixels, object footprints, quality flags, and the like). Such data compresses extremely well with a compact run-length instruction set. It is not meant for continuous-tone imagery, which expands rather than shrinks.

Installation

cargo add pliocomp

Usage

The crate exposes a single pair of inverse functions — a lossless codec:

Function Direction Meaning
pl_p2li(pxsrc, xs, lldst, npix) -> usize pixels → line list encode ("pixel to line list"), returns the list length
pl_l2pi(ll_src, xs, px_dst, npix) -> usize line list → pixels decode ("line list to pixel"), returns the pixel count 
use pliocomp::{pl_p2li, pl_l2pi};

// A mask line: mostly zero with a short run of a constant high value.
let pixels: Vec<i32> = vec![0, 0, 0, 5, 5, 5, 0, 0];

// Encode into a caller-sized line-list buffer (i16 words).
let mut line_list = vec![0i16; pixels.len() * 2 + 8];
let ll_len = pl_p2li(&pixels, 0, &mut line_list, pixels.len());

// Decode back into a pixel buffer.
let mut decoded = vec![0i32; pixels.len()];
let n = pl_l2pi(&line_list[..ll_len], 0, &mut decoded, pixels.len());

assert_eq!(&decoded[..n], &pixels[..]);

xs is the starting index into the pixel array and npix the pixel count; decoding supports clipping to a sub-range [xs, xs+npix) so a caller can expand part of a line without materializing the whole thing. The caller passes a pre-sized output buffer, and the returned length reports how much was actually written.

Round-trip caveats

PLIO can only represent non-negative values: negative inputs decode back as 0. This is a format limit, not a bug. Very large high values are also bounded by the i16 words the format is built on. See the algorithm document below for the full details.

Note: versions before 0.4.0 silently corrupted any pixel value larger than 12 bits (> 4095) on decode. If you rely on values above 4095, use 0.4.0 or later.

Algorithm

For a full description of the line-list format, the instruction opcodes, how the encoder and decoder work, and the format's limitations, see ALGORITHM.md.

References

Ported from

This crate is a port of the IRAF PLIO routines, with a secondary port of the cleaned-up pliocomp.c from CFITSIO (most gotos removed, magic constants named):

License

MIT