Compression configuration¶

Passed to rustfits.FITS.create_image_hdu() and rustfits.FITS.create_table_hdu() via the compress= and quantize= arguments.

Algorithm configs¶

class rustfits.Gzip1(*, tile_shape=None, heap_format=Ellipsis, level=None)¶

Bases: object

Configuration for GZIP_1 tile compression.

Stores each tile as a single gzip-framed stream over the pixel bytes in FITS big-endian order. No quantization, no preprocessing — the simplest of the FITS Tile Compression algorithms. Pairs well with mostly-uniform integer data; for noisy data RICE_1 typically compresses tighter.

heap_format¶: Descriptor format for the on-disk heap ('P' or 'Q').

level¶: zlib compression level (0-9), or None for the codec default (6). Write-only: always None on reopened HDUs — gzip framing doesn’t record the level.

tile_shape¶: Tile shape in numpy axis order (slowest first), or None when the algorithm-default tile shape should be used at create time.

zcmptype¶: FITS-spec ZCMPTYPE string for this algorithm.

class rustfits.Gzip2(*, tile_shape=None, heap_format=Ellipsis, level=None)¶

Bases: object

Configuration for GZIP_2 tile compression.

Like GZIP_1 but with a byte-shuffle preprocessor applied before compression: bytes are reordered so that all most-significant bytes of every pixel come first, then all second-most-significant bytes, and so on down to the least-significant. The shuffle decorrelates the byte streams, producing longer runs of similar values that deflate compresses tighter than the interleaved layout of GZIP_1. For 1-byte data the shuffle is a no-op, so GZIP_2 and GZIP_1 produce identical output on u1 images.

heap_format¶: Descriptor format for the on-disk heap ('P' or 'Q').

level¶: zlib compression level (0-9), or None for the codec default (6). Write-only: always None on reopened HDUs — gzip framing doesn’t record the level.

tile_shape¶: Tile shape in numpy axis order (slowest first), or None when the algorithm-default tile shape should be used at create time.

zcmptype¶: FITS-spec ZCMPTYPE string for this algorithm.

class rustfits.Rice1(*, tile_shape=None, heap_format=Ellipsis, blocksize=32)¶

Bases: object

Configuration for RICE_1 tile compression.

Rice coding over per-pixel deltas: for each block of blocksize pixels the encoder picks a split parameter k from a per-block entropy heuristic, encodes the high bits unary and the low k bits raw. Strong on smooth-but-noisy integer imagery; cfitsio uses this as the default compression for many surveys.

Supports BYTEPIX ∈ {1, 2, 4} (u1, i2, i4 in numpy terms). BYTEPIX=8 (i64) is rejected: no canonical FITS writer produces such files (cfitsio refuses, astropy silently downcasts to i32), so they would be unreadable outside rustfits. Use Gzip2 for i64 data — within ~5% of RICE compression on real imagery and universally readable.

blocksize¶: RICE block size in pixels (default 32). Number of pixels the encoder groups into one Rice-coded block.

heap_format¶: Descriptor format for the on-disk heap ('P' or 'Q').

tile_shape¶: Tile shape in numpy axis order (slowest first), or None when the algorithm-default tile shape should be used at create time.

zcmptype¶: FITS-spec ZCMPTYPE string for this algorithm.

class rustfits.Hcompress1(*, tile_shape=None, heap_format=Ellipsis, scale=0, smooth=False)¶

Bases: object

Configuration for HCOMPRESS_1 tile compression.

2-D wavelet-like H-transform with quadtree bit-plane encoding. Designed for astronomical images where the smoothing pass can substantially reduce visible blockiness at higher compression ratios. Supports BYTEPIX ∈ {1, 2, 4} (u1, i2, i4 in numpy terms); BYTEPIX=8 (i8) is rejected — the FITS Tile Compression Convention has no 64-bit HCOMPRESS variant and cfitsio’s encoder family doesn’t produce one.

Two algorithm parameters: scale (quantization level — 0 or 1 for lossless, larger for more compression at the cost of precision) and smooth (post-decompression smoothing pass that reduces block artifacts — has no effect at scale <= 1 since nothing is quantized). Tiles must be 2-D; 1-D and 3-D images are rejected at create time.

heap_format¶: Descriptor format for the on-disk heap ('P' or 'Q').

scale¶: HCOMPRESS quantization scale (0 or 1 for lossless; larger for lossy with higher compression).

smooth¶: Whether HCOMPRESS’s read-time smoothing pass is enabled (reduces block artifacts at lossy scales; no effect at scale <= 1).

tile_shape¶: Tile shape in numpy axis order (slowest first), or None when the algorithm-default tile shape should be used at create time.

zcmptype¶: FITS-spec ZCMPTYPE string for this algorithm.

class rustfits.Plio1(*, tile_shape=None, heap_format=Ellipsis)¶

Bases: object

Configuration for PLIO_1 tile compression (IRAF Pixel List encoding). RLE for non-negative integer masks built via increments; output is i16 BE shorts (TFORM1=`1PI`). Supports integer ZBITPIX = 8 / 16 / 32; not meaningful for floats.

Read side: full support — hdu.compression returns this object when ZCMPTYPE=PLIO_1. Write side: not yet implemented (the encoder is a Phase 7 follow-up). Until then, passing compress=Plio1(…) to create_image_hdu raises NotImplementedError.

heap_format¶: Descriptor format for the on-disk heap ('P' or 'Q').

tile_shape¶: Tile shape in numpy axis order (slowest first), or None when the algorithm-default tile shape should be used at create time.

zcmptype¶: FITS-spec ZCMPTYPE string for this algorithm.

Quantization¶

class rustfits.Quantize(*, level=4.0, method=Ellipsis, seed=0)¶

Bases: object

Quantization parameters for float-image compression.

FITS Tile Compression of floating-point images works by quantizing each tile to i32, then compressing the quantized values with one of the integer compression algorithms (Rice1, Gzip1, Hcompress1, etc.). This pyclass carries the quantization parameters separately from the algorithm config:

fits.create_image_hdu(
    "f4", shape,
    compress=Rice1(tile_shape=(100, 100)),
    quantize=Quantize(level=4.0, method="dither1"),
)

The orthogonal split mirrors cfitsio’s separate fits_set_quantize_level / fits_set_quantize_method calls. Integer HDUs never see quantize=; float HDUs use a default Quantize when the argument is omitted.

Parameters:

level (float, default 4.0) – Quantization level. Positive values mean “N sigma per quanta”: the per-tile bscale is set to tile_noise / level so each quantization step covers 1/level of the noise. Larger level = finer steps = higher fidelity + larger compressed output. cfitsio’s default is 4.0 (with dithering) or 16.0 (without). Negative values mean “fixed bscale = -level” (skip noise estimation).
method (str, default 'dither1') – Dithering scheme: ‘no_dither’ (NO_DITHER: simple round-to- nearest, no dither), ‘dither1’ (SUBTRACTIVE_DITHER_1: add a pseudorandom offset before rounding so quantization noise is white), ‘dither2’ (SUBTRACTIVE_DITHER_2: like dither1 but reserves a sentinel for NaN so float-NaN survives the round-trip). cfitsio’s default is SUBTRACTIVE_DITHER_1. To skip quantization entirely (lossless raw float GZIP), pass quantize=None (or omit the kwarg) to create_image_hdu — do NOT construct a Quantize at all.
seed (int, default 0) – ZDITHER0 random seed, recorded as a header card. Zero means “pick one automatically” at create time (cfitsio uses a checksum of the data). Positive values are passed through verbatim — useful when reproducible output across runs matters.

level¶: Quantization level (N sigma per quanta, or fixed bscale when negative). See the class docstring.

method¶: Short Pythonic name of the dither scheme ('no_dither' / 'dither1' / 'dither2'). See zquantiz for the FITS-spec form.

seed¶: Random seed (ZDITHER0). 0 means “pick one automatically at create time”; positive values pass through verbatim for reproducible output.

zquantiz¶: FITS-spec ZQUANTIZ string this Quantize would emit on write — exposed for symmetry with the algorithm-config classes’ zcmptype.