 |
EleFits
5.0.0
A modern C++ API on top of CFITSIO
|
The structure and contents of a FITS file, and how they relate to EleFits.
Why so, when there are many nice examples already available? Because this one shows the mapping between the components of a FITS file, and the classes we implemented. Of course, feel free to have a look at the others, like that of the FITS support office or even the FITS standard.
At the end of some sections, a "see also" paragraph points to other documentation pages, or to more advanced topics out of the scope of this introductory page but which are good to know.
Definitions of the introduced terms are recalled in a glossary at the bottom of the page.
The simplest form of FITS file is as Single Image FITS (SIF) file, which is the initial FITS format, as described in 1981. A SIF file only consists of a header unit, full of metadata, followed by a data unit, full of... data.
The header unit is a block of ASCII characters, organized in chunks of 80 characters named records. Most records are keyword records, which store a key-value pair as follows:
KEY = VALUE
The key is at most 8-character long.
The value can be:
T or F);BOOL = T INT = 3 FLOAT = 3.00e8 COMPLEX = (28.06, 19.89) STRING = 'HEY'
A comment can be appended, separated from the value by a slash (/):
KEYWORD = VALUE / comment
And a unit can be inserted between the slash and the comment, enclosed in square brackets:
KEYWORD = VALUE / [unit] comment
| EleFits | Standard | CFITSIO | Example |
|---|---|---|---|
| Record | Keyword record | Keyword or Keyword record | EXPTIME = 1500.0 / [s] exposure time |
| Keyword | Name | Name or Keyword | EXPTIME |
| Value | Value | Value | 1500.0 |
| Raw comment | Comment | Comment | [s] exposure time |
| Unit | Unit | Unit | s |
| Comment | Unnamed | Comment or Unnamed | exposure time |
COMMENT)The data unit of a SIF file is an n-dimensional array, like a 0D nothing, a 1D vector, a 2D image, a 3D data cube, a 4D color video, or whatever fancier array you wish (with n < 1000, but this should not be a show-stopper in general).
Pixels are stored contiguously (in row-major order) in binary format, and the properties of the image are stored in the header unit as special records. For example, the size of the image is given by the values associated with keys NAXIS1, NAXIS2, NAXIS3... The pixel value type can be an 8- to 64-bit integer, or a 32- or 64-bit floating-point. The value type is also encoded in the header unit with keyword BITPIX. Here is a typical Primary header unit:
Raster's documentation.BZERO)During several decades, the format definition has drammatically evolved, but with backward compatibility in mind. The header unit and data unit are still the building blocks of a FITS file. In 1994, FITS has become a multi-image format, where Header and Data Units (HDUs), made of one header unit and one data unit, are written in sequence. The first HDU is referred to as Primary array, Primary HDU, or simply Primary, and is made exactly like a SIF file (in other words, a SIF file is a FITS file with one HDU). The subsequent HDUs, if any, are named extensions. FITS files with extensions are known as Multi-Extension FITS (MEF) files.
Another major improvement of the standard is the support for tabular data in 1995. As opposed to values in arrays, the values in tables can have different types (although the values of a same column share the same type). Table HDUs are necessarily extensions: the Primary is always an image HDU. This means that files which store only tabular data start with a header-only Primary, that is, an image HDU with empty array.
There are two types of table HDUs: ASCII tables and binary tables. ASCII tables are hardly used anymore, and are not supported at all by EleFits. Binary tables are sequences of rows, themselves made of entries. Obviously, they can be seen as columns made of entries, but the FITS file is written row-wise. Binary table entries can be scalar (one element per entry) or vector (several elements per entry). In the latter case, entries can even be multidimensional, and seen as rasters like in image data units.
A more recent addition to the standard is binary tables with vector columns of varying size, i.e. the entries of a single column have different value counts. This is not supported by EleFits.
A FITS file is composed of contiguous HDUs, themselves made of an ASCII header unit, and a binary data unit. The first HDU is named Primary, and is necessarily an image, which may be empty. The following HDUs are named extensions, and they may be images or binary tables.
Header units are a sequence of records, image data units are n-D arrays, and binary table data units are a sequence of rows which represent scalar or vector entries.
There is almost a 1-to-1 mapping of the FITS and EleFits structures:
| File structure | Class structure |
|---|---|
SIF file
| |
MEF file
| MefFile
|
At file level:
In an HDU:
In a header:
In an image data unit:
In a binary table data unit: