FITS I/O#

lsst.images.fits Package#

Archive implementations for the FITS file format.

The archives this package define a FITS-based meta format with the following layout:

  • A no-data primary HDU with the special header cards INDXADDR, INDXSIZE, JSONADDR, and JSONSIZE, which provide the offsets to and sizes of two special HDUs at the end of the file (see below). The primary header may also hold arbitrary cards exported by the top-level type being serialized or propagated as opaque metadata from a previous read.

  • Any number of “normal” image, compressed-image, and binary table HDUs. These have unique EXTNAME values that are the all-caps variants of a JSON Pointer (IETF RFC 6901) path in the special JSON HDU (see below), with no EXTVER or EXTLEVEL.

  • A special binary table HDU holding JSON data. This binary table has a single variable-length array byte column (i.e. TFORM='PB') that holds UTF-8 JSON data. There is always at least one row, which holds the JSON representation of the top-level object being serialized. Additional rows may be present to hold additional JSON blocks that are logically nested within the main one, but have been moved outside it to keep the main block more compact (the main JSON block will have pointers back to these).

  • A special binary table HDU that acts as an index into all others, by holding byte offsets and sizes for all preceding HDUs along with their EXTNAME, XTENSION, and ZIMAGE header values.

When images and tables are saved to a FitsOutputArchive, “normal” HDUs are added to hold their binary data, and a small Pydantic model is returned with a reference to that HDU for inclusion in the JSON tree.

Functions#

add_offset_wcs(header, *, x, y[, key])

Add a trivial FITS WCS to a header that applies the appropriate offset to map FITS array coordinates to a logical pixel grid.

read(cls, path, *[, page_size, partial])

Read an object from a FITS file.

strip_butler_cards(header)

Strip header keywords added by butler provenance that would be incorrect if propagated to a downstream file.

strip_legacy_exposure_cards(header)

Strip header keywords added by lsst.afw.image.Exposure.

strip_wcs_cards(header)

Strip WCS cards from a FITS header.

write(obj, filename[, compression_options, ...])

Write an object with a serialize method to a FITS file.

Classes#

ExtensionKey([name, ver])

The identifiers for a single FITS extension HDU within a file.

FitsCompressionAlgorithm(value[, names, ...])

FITS compression algorithms supported by this package.

FitsCompressionOptions(*[, algorithm, ...])

Configuration options for FITS compression.

FitsDitherAlgorithm(value[, names, module, ...])

FITS quantization dither algorithms supported by this package.

FitsInputArchive(stream)

An implementation of the serialization.InputArchive interface that reads from FITS files.

FitsOpaqueMetadata(headers, ...)

Opaque metadata that may be carried around by a serializable type to propagate serialization options and opaque information without that type knowing how it was serialized.

FitsOutputArchive(hdu_list[, ...])

An implementation of the serialization.OutputArchive interface that writes to FITS files.

FitsQuantizationOptions(*, dither, level[, seed])

Quantization options for FITS compression.

InvalidFitsArchiveError

The error type raised when the content of a FITS file presumed to have been written by FitsOutputArchive is not self-consistent.

PrecompressedImage(header, data)

Already-compressed FITS HDUs that are attached to high-level objects via FitsOpaqueMetadata, allowing lossy-compressed pixel values to be round-tripped exactly.

ReadResult(deserialized, metadata, butler_info)

Struct used as the return value for read.

Variables#

ExtensionHDU

Type alias.