Struct FitsReader 

pub struct FitsReader<S> { /* private fields */ }

A FITS file opened over a seekable byte source. Opening scans HDU boundaries from headers alone (no data is read); data units are fetched on demand.

Implementations

impl<R: Read + Seek> FitsReader<StreamSource<R>>

pub fn open(source: R) -> Result<StreamReader<R>>

Open a seekable byte source (file, cursor). Data units are copied into the reader’s scratch on demand; for an in-memory file prefer FitsReader::from_bytes, which decodes straight from the bytes.

impl<'a> FitsReader<SliceSource<'a>>

pub fn from_bytes(bytes: &'a [u8]) -> Result<SliceReader<'a>>

Open an in-memory FITS file — the whole thing as a byte slice (e.g. an mmap, or bytes already in RAM). Data units decode straight from the borrowed bytes with no staging copy, and no scratch allocation.

impl FitsReader<MmapSource>

pub fn open_mmap(path: impl AsRef<Path>) -> Result<MmapReader>

Available on crate feature mmap only.

Memory-map a FITS file and read it zero-copy: data units decode straight from the mapped pages (no staging copy, no read syscalls). Best for large files and random HDU access. Requires the mmap feature.

impl<S: Source> FitsReader<S>

pub fn hdus(&self) -> &[Hdu]

The scanned HDU records, read-only and in file order — each carrying its parsed Header and HduKind. Index, iterate, or .len() the slice; pick an index for a read_* method (or use FitsReader::image_indices / FitsReader::hdu_index to find one).

pub fn hdu_index(&self, name: &str, version: Option<i64>) -> Option<usize>

Index of the extension named name by its EXTNAME keyword (compared case-insensitively, as EXTNAME is conventionally matched), or None. When version is Some, also require a matching EXTVER (which defaults to 1 where the card is absent, §4.4.1) — the way duplicate extensions like ('SCI', 1) and ('SCI', 2) are told apart. The primary array has no EXTNAME. Pair the returned index with a read_* method.

pub fn image_indices(&self) -> Vec<usize>

The indices of every HDU FitsReader::read_image can read as an image: image extensions, tiled-compressed images, and a non-empty primary array (an empty NAXIS = 0 primary is a container, not an image, and is skipped). A FITS file may hold any number of images — pick an index from this list to pass to FitsReader::read_image without inspecting HduKind yourself.

pub fn read_data_raw(&mut self, index: usize) -> Result<DataUnit>

Read the raw, still-encoded (big-endian, unscaled) data unit into a fresh, caller-owned buffer. The returned DataUnit carries the full block-padded bytes plus the range of actual data within them, so a decoder consumes DataUnit::data and the block fill is never mistaken for samples.

This is the owned form, backing the table readers (which keep the bytes as the parsed table’s storage). Image and random-groups reads instead stage through the reader’s reused internal scratch — see FitsReader::read_image.

pub fn read_image(&mut self, index: usize) -> Result<RawImage<'_>>

Read an HDU’s image as a RawImage, transparently handling both plain and tiled-compressed (ZIMAGE) images — the caller doesn’t need to know which. Errors with FitsError::NotAnImage for tables, random groups, and unmodelled extensions.

A plain image is zero-copy: its big-endian bytes are viewed in place over the source (or the reader’s reused scratch for a seeking source), decoded only when you ask. A compressed image is decompressed into an owned buffer (with the compression feature; without it a ZIMAGE HDU reads as a plain BINTABLE, so this returns FitsError::NotAnImage). Either way, reach for the samples via RawImage::u8 (zero-copy BITPIX = 8), RawImage::decode (host-endian), or RawImage::physical (scaled). The result borrows the reader, so handle one image before reading the next.

pub fn read_image_view<'a>( &'a mut self, index: usize, scratch: &'a mut Vec<u64>, ) -> Result<ImageView<'a>>

Read an image as a borrowed, host-endian ImageView, byte-swapping into the caller-owned scratch — the fast, low-copy path for a loop that processes each image and moves on. Where read_image.decode() allocates a fresh owned buffer per call (page-fault-bound — profiling found that dominates a plain typed read), this reuses scratch, so a hot loop pays the output allocation once and reuses it across reads — even across differing BITPIX. The caller owns scratch, so the reader retains nothing image-sized; pass the same Vec each call and drop it when the loop ends.

scratch is Vec<u64> so the swapped samples stay 8-byte aligned for the typed views. A BITPIX = 8 image needs no swap and the view borrows the source bytes directly (zero-copy, scratch untouched); a compressed image is decompressed and copied into scratch. The view borrows the reader and scratch, so handle one image before reading the next. For samples you need to keep, use RawImage::decode.

pub fn read_table(&mut self, index: usize) -> Result<BinTable>

Read a BINTABLE extension and parse its column structure. Decode individual columns lazily with BinTable::column_by_idx. Errors with FitsError::NotABinTable for any other HDU kind.

pub fn read_ascii_table(&mut self, index: usize) -> Result<AsciiTable>

Read an TABLE (ASCII table) extension and parse its column structure. Errors with FitsError::NotAnAsciiTable for any other HDU.

pub fn read_groups(&mut self, index: usize) -> Result<RandomGroups>

Read and decode a random-groups primary array (§6). Errors with FitsError::NotRandomGroups for any other HDU.

pub fn read_compressed_table(&mut self, index: usize) -> Result<BinTable>

Available on crate feature compression only.

Read a tiled-compressed table (§10.3) — a BINTABLE with ZTABLE = T — and uncompress it into the original BinTable. Fixed-width columns only (GZIP_1/GZIP_2/RICE_1). Requires the compression feature.

pub fn verify_checksum(&mut self, index: usize) -> Result<ChecksumReport>

Verify the DATASUM/CHECKSUM integrity keywords of an HDU (§J). Each field of the report is None if that keyword is absent, else Some(true) when it matches the recomputed checksum.

Trait Implementations

impl<S: Debug> Debug for FitsReader<S>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.