Crate fits_well 

A blazing-fast reader and writer for FITS (Flexible Image Transport System) files — the standard data format of astronomy.

Layering

The format’s structure maps onto a stack of layers, so the hot decode path stays lean and the semantic layers compute only on demand. WCS (§8) and time (§9) are dependency-free pure math, always compiled and surfaced directly as Header getters (Header::wcs, Header::time); tiled compression carries a dependency and stays behind the compression feature.

bytes ─► block layer ─► HDU layer ─► header model ─► typed data
        (2880 grid,    (boundary    (ordered        (images,
         padding,       scan, lazy   records +       tables,
         I/O quantum)   seeking)     keyword index)  heap, VLAs)

• BLOCK_SIZE — the 2880-byte block grid, padding rules, and rounding math.
• Bitpix — the array element type selector (BITPIX).
• Header, Value — an ordered header model (an internal Card list) that round-trips byte-for-byte, with a side index for O(1) keyword lookup; it also parses the WCS and time layers on request (Header::wcs/Header::time).
• HduKind — HDU classification and the data-unit sizing formula that makes boundaries computable from headers alone (no data read required).
• FitsReader — lazy, seeking access to the HDU sequence of a file.

Status

The structural spine (blocks, headers, HDU boundaries, lazy reading) plus typed image decode/encode (Image), the multi-HDU writer (FitsWriter), ASCII/binary tables, WCS, time coordinates, and tiled image+table compression are implemented and tested — see each module’s docs for its design.

Re-exports

pub use bitvec;

pub use num_complex;

Structs

AsciiColumn

One ASCII-table column.

AsciiColumnReader

A handle to one column of an AsciiTable, from AsciiTable::column_by_idx or AsciiTable::column_by_name. Decode through it without re-passing the descriptor: raw for the typed values, physical for the scaled plane. Borrows the table, so it cannot outlive it.

AsciiTable

A parsed ASCII table plus its row bytes.

AsciiWriteColumn

One column to write into an ASCII table: data (Text/I64/F64 only), the fixed field width in characters, and the decimal count for floats.

BinTable

A binary table’s structure plus its data unit.

BitColumn

A binary table’s X (bit-array) column as a borrowed, 2-D bit view — from ColumnReader::bits (rectangular, nrows × repeat) or ColumnReader::vla_bits (jagged PX/QX). Bits are MSB-first (§7.3.2) and viewed in place over the data unit (zero-copy), so this borrows the table and can’t outlive it.

ChecksumReport

Result of FitsReader::verify_checksum. A field is None when its keyword is absent.

Column

One column of a binary table: its TFORMn format, optional name/unit, the TSCALn/TZEROn/TNULLn metadata, and its byte offset within a row.

ColumnReader

A handle to one column of a BinTable, from BinTable::column_by_idx or BinTable::column_by_name. Decode through it without re-passing the column descriptor: raw for the typed values, physical for the scaled f64 plane, unsigned/complex/ bits for the special kinds, and vla (+ vla_physical/vla_bits) for variable-length P/Q columns. Borrows the table, so it cannot outlive it.

Complex

A complex number in Cartesian form.

CompressOptionscompression

Write-time tuning for crate::FitsWriter::write_compressed_image. Each field applies only to the codecs that use it; the rest ignore it. Every field defaults to conventional behavior, so CompressOptions::default() (row tiling) or CompressOptions::tiled(shape) is the common case.

DataUnit

A data unit read from the source: the full block-padded bytes plus the range within them holding the actual data. The bytes after data_range are FITS block fill, not part of the data array.

Datetime

A calendar datetime (proleptic Gregorian, UTC-agnostic). second may reach 60.x to represent a leap second; the JD arithmetic rolls it over naturally.

EpochTime

A time from a JEPOCH/BEPOCH keyword: its MJD and the scale the keyword implies (TDB for JEPOCH, ET ≈ TT for BEPOCH).

FitsReader

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.

FitsTime

A header’s time coordinate frame (§9): the reference epoch, scale, unit, and the resolved global time keywords.

FitsWriter

Writes FITS HDUs to a byte sink. The first HDU written becomes the primary array; subsequent images/tables are written as extensions.

GtiInterval

A Good Time Interval as absolute MJD (§9.7).

Hdu

One Header/Data Unit located by the reader.

Header

A parsed header unit: an ordered list of content cards plus a side index for O(1) keyword lookup.

HeaderEntry

A read-only view of one stored header record, yielded by Header::iter.

Image

An N-dimensional image: a flat, Fortran-ordered buffer (axis 0 varies fastest), the axis lengths from NAXISn, and the scaling map that turns its stored (raw) samples into physical values.

MmapSourcemmap

A memory-mapped file source: the kernel pages the file in on access, and data units decode straight from the mapping (no staging copy, no read syscalls). The owned memmap2::Mmap keeps the mapping alive for the reader’s lifetime.

PhaseAxis

The §9.6 'PHASE' axis folding parameters: the zero-phase reference time CZPHSia and the period CPERIia, in TIMEUNIT relative to the time reference (the TSTART convention).

RandomGroups

A decoded random-groups primary array.

RawImage

An image read from an HDU, in whichever form the reader could give cheaply — returned by crate::FitsReader::read_image for both plain and tiled- compressed images, so callers needn’t know which they have. Carries the shape, BITPIX, and Scaling; the pixels are exposed lazily through decode, u8, physical, and unsigned.

Scaling

The linear BSCALE/BZERO map from a stored value to its physical value, plus the integer BLANK sentinel marking undefined pixels.

SliceSource

An in-memory byte source: the whole file already resident as a slice (e.g. an mmap, or bytes read up front). Fetches return a zero-copy borrow, so a decode reads straight from these bytes with no staging copy.

StreamSource

A streaming Read + Seek source. Each fetch seeks and copies the range out — there is no resident image to borrow, so reads cost one extra memory pass.

TDisp

A parsed TDISPn display format: the format letter, field width, optional decimal places (.d/.m), and optional exponent width (a trailing Ee).

Tform

A parsed TFORMn value: a repeat count, an element kind, and (for the P/Q variable-length-array descriptors) the kind of the array elements in the heap. The rTa form’s trailing (emax) size hint is not retained.

TimeBounds

The global bound / duration / error time keywords (§9.4, §9.5, §9.7), as read by Header::time_bounds. Start/end are absolute MJD; the rest are in TIMEUNIT.

Wcs

A parsed world coordinate system for one (optionally alternate) axis set.

WriteColumn

One column to write into a binary table: its name, optional unit, data, and the number of elements per row (repeat). For ColumnData::Text, repeat is the fixed character width of the field.

Enums

AsciiKind

The value type of an ASCII-table column.

Bitpix

The physical element type of an array, selected by the BITPIX keyword.

ColumnData

A decoded column, flattened across all rows in row order. For array columns (repeat > 1) each row contributes repeat consecutive elements; for A, each row contributes one String. Values are raw (big-endian decoded but not TSCALn/TZEROn-scaled).

DitherMethodcompression

Float-quantization dithering for crate::FitsWriter::write_compressed_image (ZQUANTIZ, §10.2). Applies only when compressing a float image; the integer codecs ignore it.

Epoch

A reference epoch: Julian (J2000.0) or Besselian (B1950.0).

FitsError

HduKind

The structural kind of an HDU, inferred from its mandatory keywords.

ImageArrayndarray

An image as an N-dimensional ndarray array, tagged by element type — the n-D analog of ImageData, from Image::into_ndarray / RawImage::to_ndarray. Requires the ndarray feature.

ImageData

An owned, host-endian sample buffer, tagged by its BITPIX element type.

ImageView

A borrowed, host-endian view of an image’s samples, tagged by BITPIX — the zero-/low-copy counterpart to the owned ImageData, returned by crate::FitsReader::read_image_view. Match it exactly like ImageData, but the slices borrow the reader’s reused decode scratch (or, for BITPIX = 8, the source bytes directly), so a view is valid only until the next read — ideal for a hot loop that processes each image and moves on, since reusing one scratch across reads pays the output allocation (and its page faults) once and even reuses it across different BITPIX. For samples you need to keep, use the owned RawImage::decode.

Projection

A celestial projection algorithm — the 3-letter CTYPE code.

SampleType

The effective element type of an image’s physical samples — the analogue of cfitsio’s image “equivalent type”. BITPIX records only the stored width and signedness; the FITS unsigned and signed-byte conventions then layer a BZERO offset on top (BSCALE == 1 with BZERO = 2^(n-1), or BZERO = -128 for signed bytes), so the values actually mean an unsigned (or signed-byte) integer. This enum is what RawImage::physical / RawImage::unsigned yield, resolved up front from BITPIX + Scaling without touching the pixels — so a caller can pick a code path (e.g. a per-type normalization range) without re-deriving the BZERO convention itself.

TDispKind

The format letter of a TDISPn display format (§7.3.4, Table 20).

TformKind

The element type of a binary-table column, from the letter of its TFORMn code (Table 18).

TimeAxisKind

A time-related WCS axis type (§9.6).

TimeScale

A FITS time scale (TIMESYS / CTYPEi).

UnsignedView

A typed integer realization of the FITS unsigned (and signed-byte) storage conventions — BSCALE == 1 with BZERO the sign-bit offset. Values are exact (no f64 rounding), recovered by flipping the stored sign bit.

Value

The typed value of a valued keyword record (§4.2).

Constants

BLOCK_SIZE

The fundamental layout unit: 2880 bytes = 36 × 80-byte cards.

CARD_SIZE

A keyword record (card) is 80 bytes of restricted ASCII.

Traits

Source

A seekable byte source the reader fetches HDU header and data units from. Sealed — implemented only by this crate’s source types, never externally.

Type Aliases

MmapReadermmap

A FitsReader over a memory-mapped file — the type FitsReader::open_mmap returns. Requires the mmap feature.

Result

SliceReader

A FitsReader over an in-memory byte slice — the type FitsReader::from_bytes returns. The lifetime is that of the borrowed bytes.

StreamReader

A FitsReader over a seeking byte source (Read + Seek, e.g. a File) — the type FitsReader::open returns. A friendlier name for FitsReader<StreamSource<R>>.