Next Previous Up Contents
Next: Column-oriented FITS
Up: Supported Output Formats
Previous: Supported Output Formats

#### 4.1.2.1 FITS

When saving in FITS format a new file is written consisting of two HDUs (Header+Data Units): a primary one (required by the FITS standard), and a single extension of type BINTABLE containing the table data.

There are a few variants of this format:

fits-basic
  The primary HDU contains only very minimal headers and no data.
fits-plus
  The primary HDU contains an array of bytes which stores the full table metadata as the text of a VOTable document, along with headers that mark this has been done. Most FITS table readers will ignore this altogether and treat the file just as if it contained only the table. When TOPCAT (or other STIL-based applications) read it however, they read out the metadata and make it available for use. In this way you can store your data in the efficient and widely portable FITS format without losing the additional metadata such as table parameters, column UCDs, lengthy column descriptions etc that may be attached to the table. Other, more standard schemes exist for combining the benefits of FITS and VOTable, but suffer from some disadvantages: `votable-fits-inline` is hard to process efficiently (in particular the data cannot easily be mapped into memory) and `votable-fits-href` requires that you keep your data in two separate files, which can get separated from each other. If you want to ensure that the metadata are available to other VOTable-aware programs, you should use one of the normal VOTable formats.
fits-var
  Behaves like `fits-basic`, but columns containing variable-length numeric array data are stored using the `P` and `Q` formats where appropriate, rather than padding smaller arrays to the size of the largest. This can make for more compact storage of variable-length array-valued column data but may also result in tables less suitable for streaming.
fits-healpix
  Used for storing HEALPix pixel data in a way that conforms to the HEALPix-FITS serialization convention. In most ways it behaves the same as `fits-basic`, but it will rearrange and rename columns as required to follow the convention, and it will fail if the table does not contain the required HEALPix metadata (`STIL_HPX_*` parameters).

In general, you can just let TOPCAT detect the format automatically and not worry about which of these variants is being used - if `fits-plus` is being used you just get some hidden benefits.

The FITS standard only supports BINTABLE extensions with a maximum of 999 columns. In TOPCAT versions up to v4.4, attempting to write a wider table to FITS format would fail. In v4.5 and later, a non-standard convention (described in SUN/252) is used so that tables with up to 2^31 columns can be written and re-read. Note however that if software unaware of this convention (e.g. CFITSIO or earlier versions of TOPCAT) is used to read such tables it will only see the first 998 columns written as intended, plus a column 999 containing an undescribed byte buffer.

Next Previous Up Contents
Next: Column-oriented FITS
Up: Supported Output Formats
Previous: Supported Output Formats

TOPCAT - Tool for OPerations on Catalogues And Tables
Starlink User Note253
TOPCAT web page: http://www.starlink.ac.uk/topcat/
Author email: m.b.taylor@bristol.ac.uk
Mailing list: topcat-user@jiscmail.ac.uk