Known limitations

rustfits aims for parity with astropy and fitsio on the modern FITS feature set, but a handful of edge cases aren’t yet implemented (or are deliberately out of scope). This page lists them and shows the workaround where one exists.

Each item is tagged:

  • (not yet) — on the roadmap; will land when prioritized or when a user prompts for it. File an issue if you hit one.

  • (by design) — deliberately not supported; the workaround is the recommended path.

Tables

  • TNULL masking on VLA columns (not yet) — mask_null=True works for fixed B/I/J/K columns but raises on VLA columns with a TNULL card in the header. Read with mask_null=False and apply the mask yourself for now.

  • Variable-length columns with TDIMn (not yet) — TDIMn on a P/Q column would reshape each heap cell to the declared dims, useful for VLA-of-images, but with a quirk: the spec only allows ONE variable axis per cell, so fully variable (n, m) shapes aren’t expressible in FITS without padding.

  • ``TDISPn`` on write (by design) — the display-format hint isn’t emitted by rustfits’s writers. Add it by hand via header["TDISP1"] = ... if you need it; it’s informational per the spec.

Images

The image surface (read, slice, write, extend, __setitem__, BLANK / MaskedArray, BSCALE/BZERO, unsigned-int trick) is feature-complete for both uncompressed and tile-compressed HDUs. One narrow gap:

  • Per-tile ZBLANK column (not yet) — header-level ZBLANK on compressed integer images is supported. The convention also allows a per-tile column-form ZBLANK; rustfits doesn’t read it. Rare in practice — cfitsio typically emits the header form even for DITHER_2.

General

  • Multithreaded throughput (GIL release) (not yet) — rustfits releases the GIL only during remote (http / ftp) downloads. The heavy CPU paths — tile decode/encode, large chunked I/O, checksum — currently hold it, so several Python threads calling into rustfits serialize on those. Single-threaded use is unaffected (the common case). Releasing the GIL around the pure-Rust decode/encode spans is a targeted future change, gated on a real multithreaded workload — file an issue if you have one.

  • Random groups (GROUPS=T, PTYPEn) (by design) — legacy format; vanishingly rare in new files. Not on the roadmap.

Files and compression

  • Whole-file gzip is read-only (not yet) — a .gz path is decompressed into memory on open, so reads work, but r+ / w+ on a .gz raise. Write-back (recompress-on-close) isn’t implemented.

    More to the point, prefer per-HDU compression over whole-file compression. Tile-compressed images (the compress=... argument to create_image_hdu / write_image) and compressed tables (compress=... on create_table_hdu / write_table) generally beat a whole-file .gz on every axis that matters:

    • Storage — the tile-compression conventions apply the codec suited to the data (RICE / HCOMPRESS / GZIP with byte-shuffle, optional float quantization), so they typically compress tighter than gzipping the raw byte stream.

    • Memory — a .gz must be decompressed in full into RAM before any byte is readable (gzip isn’t seekable; FITS needs random access). Tile compression decodes only the tiles you touch, keeping peak memory near the size of your slice rather than the whole image or table.

    • Speed — partial and scattered reads pull only the needed tiles (and the per-tile cache makes repeated access cheap), whereas whole-file gzip pays the full-decompress cost up front on every open.

    To write a compressed file, write a plain .fits and choose tile/HDU compression per HDU — see the compression sections of the image and table guides.

Cross-tool interop caveats

These aren’t rustfits limitations per se — they’re points where the FITS ecosystem disagrees and rustfits picks one side.

  • astropy ``1PX(N)`` parser — astropy 7.2.0 rejects bit- packed VLA columns (1PX/1QX) with VerifyError during column setup. rustfits writes spec-conforming 1PX(maxbits) headers, but astropy can’t currently read them; fitsio (built on cfitsio) reads them fine. See the pinning test test_astropy_pxqx_documented_limitation.

  • astropy ``CompImageHDU`` verify_checksum — astropy’s verify_checksum for compressed HDUs has its own internal bug (TypeError on _compute_checksum(None)) that triggers on its own writes too. rustfits’s self-verify is correct; we don’t cross-verify ZHECKSUM against astropy.

  • i8 (``TLONGLONG``) RICE compression — cfitsio’s encoder doesn’t support 64-bit RICE; fitsio refuses the write. rustfits rejects compress=Rice1() + i8 dtype upfront and points at compress=Gzip2(...) instead. Files we wrote with i64 RICE would be unreadable everywhere except rustfits.