WCS Formats

This page describes data format conventions for images and cubes pixelized with World Coordinate Systems (WCS). WCS is a system for describing transformations between pixel/world coordinates and sky coordinates. The conventions described here are extensions to the FITS WCS standard which allow for serializing more complex data structures such as sparse maps or maps with non-regular geometry (e.g. a different pixel size in each image plane).

The format splits the specification of an image into two HDUs: an Image HDU and a BANDS HDU. The image HDU contains the image data while the BANDS HDU is an optional extension that stores information about non-spatial dimensions.

There are two supported WCS formats:

  • IMAGE Format: This is the standard FITS image format whereby data is stored in a FITS ImageHDU. With the exception of handling of non-spatial dimensions images generated with this format follow standard FITS format conventions.
  • SPARSE Format: This is a sparse data format for FITS images which uses a BinTableHDU to store pixel values.

By default multi-dimensional maps are assumed to have the same projection in each image plane with the WCS projection specified in the header keywords.

Both formats support the specification of non-regular multi-dimensional geometries through the inclusion of CRPIX, CEDLT, and CRVAL columns in the BANDS HDU. A non-regular geometry is one in which each image plane may have a different pixelization (e.g. different pixel size or image extent). The CRPIX, CEDLT, and CRVAL override the pixelization of the base WCS projection (defined in the IMAGE HDU header) in each image plane.

Sample Files

  • Counts Cube: FITS
  • Counts Cube (Multi-resolution/non-regular): FITS
  • Counts Cube (SPARSE Format): FITS

Image HDU

The IMAGE HDU contains the map data and can be formatted according to either the IMAGE Format or SPARSE Format scheme.

WCS FITS Header Keywords

The keywords listed here are those required by the FITS WCS specification.

  • CRPIX{IDX}, type: float
    • Pixel coordinate of reference point for axis {IDX}.
  • CDELT{IDX}, type: float
    • Coordinate increment at reference point for axis {IDX}.
  • CTYPE{IDX}, type: float
    • Coordinate system and projection code for axis {IDX}.
  • CRVAL{IDX}, type: float
    • Coordinate value at reference point for axis {IDX}.

Extra Header Keywords

These are extra keywords that are not part of the FITS WCS specification but are required for some features of the GADF format.

  • WCSSHAPE, type: string, optional
    • Comma-separated list with the number of pixels in each dimension in row-major order, e.g. (4,5,3) would correspond to a 4x5 image with three image planes. For non-regular geometries the image dimension should be the maximum across all image planes. This keyword is optional for maps in the IMAGE Format format.
  • BANDSHDU, type: string, optional
    • Name of HDU containing the BANDS table. If undefined the extension name should be EBOUNDS or ENERGIES. See BANDS HDU for additional details.

IMAGE Format

The IMAGE format uses an ImageHDU to store map values. Dimensions of the image are directly inferred from the data member of the HDU. This is the standard format for WCS-based maps.


The SPARSE WCS format uses the same conventions as the Sparse HEALPix Format. This format uses a BinTableHDU to store map values with one row per pixel.


  • PIX – ndim: 1, unit: None, type: int
    • Dimension: nrows
    • Flattened pixel index in a given image plane (band). Indices are flattened assuming a column-major ordering for the image. The row to band mapping is defined by the CHANNEL column.
  • CHANNEL – ndim: 1, unit: None, type: int
    • Dimension: nrows
    • Band index. This column is optional for maps with a single band. For efficiency it is recommended to represent this column with a 16-bit integer.
  • VALUE – ndim: 1, unit: None, type: float or int
    • Dimension: nrows
    • Amplitude in pixel indexed by PIX and CHANNEL.