Writing FITS files

fitsy.image(data, header=None, primary=True)

Build an image HDU from a numpy array.

Parameters:

  • data (numpy.ndarray) – Image pixels (any supported FITS dtype: u8, i16, i32, i64, f32, f64). The returned HDU’s NAXIS list is the reverse of data.shape (numpy is row-major while FITS is fastest-axis-first).

  • header (dict, optional) – Extra header cards to merge in. Values may be scalars or (value, comment) tuples.

  • primary (bool, optional) – If True (default) and this is the first HDU written, mark it as the primary HDU. Subsequent calls become image extensions.

Returns:

ImageBuilder – Pass to write().

fitsy.compressed_image(data, header=None, *, tile_shape=None, extname=None)

Tile-compress a numpy array into a BINTABLE HDU (ZIMAGE).

The result is identical in structure to a CFITSIO/fpack-produced compressed image extension: a BINTABLE with ZIMAGE = T whose rows hold one compressed tile each. Astropy and funpack will transparently decompress it; fitsy.open will too.

Parameters:

  • data (numpy.ndarray) – Image pixels (any supported FITS dtype).

  • header (dict, optional) – Extra cards merged into the synthesized image header before compression. Structural keywords (BITPIX, NAXIS*, etc.) are ignored.

  • tile_shape (sequence[int], optional) – Tile shape in FITS axis order (tile[0] = NAXIS1 direction). Length must equal data.ndim. Default is (NAXIS1, 1, 1, ...) per Pence & Seaman Sec.3 – one row per tile, which is the convention fpack uses.

  • extname (str, optional) – EXTNAME keyword on the resulting BINTABLE. Default "COMPRESSED_IMAGE".

Notes

The current Rust core only emits ZCMPTYPE = 'GZIP_1' compressed tiles. The output is fully standards compliant and readable by every FITS library; if you need RICE/HCOMPRESS use the Rust API directly or run fpack -r on the output.

fitsy.bintable(columns, units=None, extname=None)

Build a BINTABLE HDU from a column dictionary.

Parameters:

  • columns (dict[str, sequence]) –

    One entry per column. All columns must share the same row count. Supported value kinds:

    • numpy bool/u8/i16/i32/i64/f32/f64 arrays (1-D, or 2-D for fixed-repeat columns)

    • list[str] -> nA (right-padded to the longest string)

    • list[complex] -> M (C128)

    • list[list[float]] -> 1PD variable-length column (heap-stored, f64 element type)

  • units (dict[str, str], optional) – Per-column TUNITn strings. Keys must match column names in columns; entries for unknown columns are ignored.

  • extname (str, optional) – Sets the EXTNAME keyword for this extension.

Returns:

BinTableBuilder – Pass to write().

fitsy.ascii_table(columns, formats=None, tnulls=None, units=None, extname=None)

Build an ASCII TABLE HDU from a column dictionary.

Parameters:

  • columns (dict[str, sequence]) –

    One entry per column. Supported value kinds:

    • list[int] or numpy int array -> I{w} (use None cells for TNULL; combine with tnulls={col: "-9999"})

    • list[float] or numpy float array -> E{w}.{d} by default

    • list[str] -> A{maxlen}

  • formats (dict[str, str], optional) – Per-column override for the auto-chosen TFORM.

  • tnulls (dict[str, str], optional) – TNULL sentinel string for integer columns containing None.

  • units (dict[str, str], optional) – Per-column TUNIT strings.

  • extname (str, optional) – Sets the EXTNAME keyword.

Returns:

AsciiTableBuilder – Pass to write().

fitsy.write(path, hdus, overwrite=False, *, checksums=False)

Write a sequence of HDU builders to disk.

Parameters:

  • path (str or pathlib.Path) – Destination path. Overwritten if it already exists.

  • hdus (list) – Builders returned by image(), bintable(), or ascii_table(). The first item must be an image (it becomes the primary HDU); for table-only files pass fitsy.image(np.zeros((0,))) first.

  • overwrite (bool, optional) – If False (the default), raise FileExistsError rather than truncating an existing file at path.

  • checksums (bool, optional) – If True, compute and stamp CHECKSUM and DATASUM cards on every emitted HDU (FITS Checksum Proposal). Defaults to False.

Examples

>>> import numpy as np, fitsy
>>> fitsy.write("out.fits", [
...     fitsy.image(np.zeros((10, 10), dtype=np.float32)),
... ])
fitsy.append(path, data, header=None)

Append one image HDU to an existing FITS file.

The HDU is streamed in place at the end of the file – existing HDUs are not read or rewritten. The Python data array is converted to a non-primary (XTENSION = ‘IMAGE ‘) HDU before being written. Matches astropy.io.fits.append semantics.

fitsy.setval(path, key, value, *, ext=None, comment=None)

Set one header keyword in path (rewrites the file).

fitsy.delval(path, key, *, ext=None)

Remove one header keyword from path (rewrites the file).

class fitsy.ImageBuilder

Bases: object

Opaque image HDU spec produced by image().

Pass to write() as part of a list of builders.

class fitsy.BinTableBuilder

Bases: object

Opaque BINTABLE HDU spec produced by bintable().

class fitsy.AsciiTableBuilder

Bases: object

Opaque ASCII TABLE HDU spec produced by ascii_table().