Appendix A: Embedding ASDF in FITS
While ASDF is designed to replace all of the existing use cases of FITS, there will still be cases where files need to be produced in FITS. Even then, it would be nice to take advantage of the highly-structured nature of ASDF to store content that can not easily be represented in FITS in a FITS file. This appendix describes a convention for embedding ASDF content in a FITS file.
The content of the ASDF file is placed in the data portion of an extra
image extension named ASDF (EXTNAME = 'ASDF'). (By
convention, the datatype is unsigned 8-bit integers (BITPIX = 8)
and is one-dimensional (NAXIS = 1), but this is not strictly
necessary.)
Rather than including a copy of the large data arrays in the ASDF
extension, the ASDF content may refer to binary data stored in regular
FITS extensions elsewhere in the same file. The convention for doing
this is to set the source property of a
ndarray object to a special string
identifier for a FITS reference. These values come in two forms:
fits:EXTNAME,EXTVER: WhereEXTNAMEandEXTVERuniquely identify a FITS extension.fits:INDEX: WhereINDEXis the zero-based index of a FITS extension.
The fits:EXTNAME,EXTVER form is preferred, since it allows for
rearranging the FITS extensions in the file without the need to update
the content of the ASDF extension, and thus such rearrangements
could be performed by a non-ASDF-aware FITS library.
Such “FITS references” simply point to the binary content of the data
portion of a FITS header/data unit. There is no enforcement that the
datatype of the ASDF ndarray matches the
BITPIX of the FITS extension, or expectation that an explicit conversion
would be performed if they don’t match. It is up to the writer of the file to
keep the ASDF and FITS datatype descriptions in sync.
The following is a schematic of an example FITS file with an ASDF extension. The ASDF content references the binary data in two FITS extensions elsewhere in the file.
HDU 0:
┌─────────────────────────────────────┐
│SIMPLE = T │
│BITPIX = -64 │
│NAXIS = 2 │
│NAXIS1 = 512 │
│NAXIS2 = 512 │
│EXTEND = T │
│EXTNAME = 'SCI ' │
│END │
├─────────────────────────────────────┤
│...data... │<──┐
└─────────────────────────────────────┘ │
HDU 1: │
┌─────────────────────────────────────┐ │
│XTENSION= 'IMAGE ' │ │
│BITPIX = -64 │ │
│NAXIS = 2 │ │
│NAXIS1 = 512 │ │
│NAXIS2 = 512 │ │
│EXTNAME = 'DQ ' │ │
│END │ │
├─────────────────────────────────────┤ │
│...data... │<──┼───┐
└─────────────────────────────────────┘ │ │
HDU 2: │ │
┌─────────────────────────────────────┐ │ │
│XTENSION= 'IMAGE ' │ │ │
│BITPIX = 8 │ │ │
│NAXIS = 1 │ │ │
│NAXIS1 = 361 │ │ │
│EXTNAME = 'ASDF ' │ │ │
│END │ │ │
├─────────────────────────────────────┤ │ │
│#ASDF 1.0.0 │ │ │
│%YAML 1.1 │ │ │
│%TAG ! tag:stsci.edu:asdf/ │ │ │
│--- !core/asdf-1.0.0 │ │ │
│model: │ │ │
│ sci: │ │ │
│ data: !core/ndarray-1.0.0 │ │ │
│ source: fits:SCI,1 ──────────┼───┘ │
│ datatype: float64 │ │
│ byteorder: little │ │
│ shape: [512] │ │
│ wcs: ...WCS info... │ │
│ dq: │ │
│ data: !core/ndarray-1.0.0 │ │
│ source: fits:DQ,1 ──────────┼───────┘
│ datatype: float64 │
│ byteorder: little │
│ shape: [512] │
│ wcs: ...WCS info... │
│... │
└─────────────────────────────────────┘