# FITS -- Flexible Image Transport System

Driver short name

FITS

Build dependencies

libcfitsio

FITS is a format used mainly by astronomers, but it is a relatively simple format that supports arbitrary image types and multi-spectral images, and so has found its way into GDAL. FITS support is implemented in terms of the standard CFITSIO library, which you must have on your system in order for FITS support to be enabled (see notes on CFITSIO linking). Both reading and writing of FITS files is supported.

Starting from version 3.0 georeferencing system support is implemented via the conversion of WCS (World Coordinate System) keywords. Only Latitude - Longitude systems (see the FITS standard document) have been implemented, those for which remote sensing processing is commonly used. As 3D Datum information is missing in FITS/WCS standard, Radii and target bodies are translated using the planetary extension proposed here.

Non-standard header keywords that are present in the FITS file will be copied to the dataset's metadata when the file is opened, for access via GDAL methods. Similarly, non-standard header keywords that the user defines in the dataset's metadata will be written to the FITS file when the GDAL handle is closed.

Note to those familiar with the CFITSIO library: The automatic rescaling of data values, triggered by the presence of the BSCALE and BZERO header keywords in a FITS file, is disabled in GDAL < v3.0. Those header keywords are accessible and updatable via dataset metadata, in the same was as any other header keywords, but they do not affect reading/writing of data values from/to the file. Starting from version 3.0 BZERO and BSCALE keywords are managed via standard `GDALRasterBand::GetOffset()` / `GDALRasterBand::SetOffset()` and `GDALRasterBand::GetScale()` / `GDALRasterBand::SetScale()` GDAL functions and no more referred as metadata.

## Multiple image support

Starting with GDAL 3.2, Multi-Extension FITS (MEF) files that contain one or more extensions following the primary HDU are supported. When more than 2 image HDUs are found, they are reported as subdatasets.

The connection string for a given subdataset/HDU is `FITS:"filename.fits":hdu_number`

## Binary table support

Starting with GDAL 3.2, binary tables will be exposed as vector layers (update and creation support from GDAL 3.2.1).

The FITS data types are mapped to OGR data types as the following:

Data types
TFORM value | TSCAL, TOFFSET value | Occurrence count | OGR field type | OGR field subtype
--- | --- | --- | --- | ---
'L' (Logical) | ignored | 1 | OFTInteger | OFSTBoolean
'L' (Logical) | ignored | > 1 | OFTIntegerList | OFSTBoolean
'X' (bit) | ignored | each bit mapped to a OGR field | OFTInteger | OFSTNone
'B' (unsigned byte) | 1, 0 (unsigned byte) or 1, -128 (signed byte) | 1 | OFTInteger | OFSTNone
'B' (unsigned byte) | 1, 0 (unsigned byte) or 1, -128 (signed byte) | > 1 | OFTIntegerList | OFSTNone
'I' (16 bit signed integer) | 1, 0 | 1 | OFTInteger | OFSTInt16
'I' (16 bit integer, interpreted as unsigned) | 1, 32768 | 1 | OFTInteger | OFSTNone
'I' (16 bit signed integer) | other than (1,0) and (1,32768) | 1 | OFTReal | OFSTNone
'I' (16 bit integer) | 1, 0 | >1 | OFTIntegerList | OFSTInt16
'I' (16 bit integer, interpreted as unsigned) | 1, 32768 | >1 | OFTIntegerList | OFSTNone
'I' (16 bit signed integer) | other than (1, 0) and (1, 32768) | > 1 | OFTRealList | OFSTNone
'J' (32 bit signed integer) | 1, 0 | 1 | OFTInteger | OFSTNone
'J' (32 bit integer, interpreted as unsigned) | 1, 2147483648 | 1 | OFTInteger | OFSTNone
'J' (32 bit signed integer) | other than (1, 0) and (1, 2147483648) | 1 | OFTReal | OFSTNone
'J' (32 bit integer) | 1, 0 | >1 | OFTIntegerList | OFSTNone
'J' (32 bit integer, interpreted as unsigned) | 1, 2147483648 | >1 | OFTIntegerList | OFSTNone
'J' (32 bit signed integer) | other than (1, 0) and (1, 2147483648) | > 1 | OFTRealList | OFSTNone
'K' (64 bit signed integer) | 1, 0 | 1 | OFTInteger64 | OFSTNone
'K' (64 bit signed integer) | other than (1, 0) | 1 | OFTReal | OFSTNone
'K' (64 bit signed integer) | 1, 0 | > 1 | OFTInteger64 | OFSTNone
'K' (64 bit signed integer) | other than (1, 0) | > 1 | OFTRealList | OFSTNone
'A' (character) | ignored | if TFORM='Axxx' and no TDIM header | OFTString | OFSTNone
'A' (character) | ignored | TDIM for 2D field, or variable length ('PA') | OFTStringList | OFSTNone
'E' (single precision floating point) | 1, 0 | 1 | OFTReal | OFSTFloat32
'E' (single precision floating point) | other than (1, 0) | 1 | OFTReal | OFSTNone
'E' (single precision floating point) | 1, 0 | > 1 | OFTRealList | OFSTFloat32
'E' (single precision floating point) | other than (1, 0) | > 1 | OFTRealList | OFSTNone
'D' (double precision floating point) | any | 1 | OFTReal | OFSTNone
'D' (double precision floating point) | any | > 1 | OFTRealList | OFSTNone
'C' (single precision complex) | any | 1 | OFTString whose value is of the form "x + yj" | OFSTNone
'C' (single precision complex) | any | > 1 | OFTStringList whose values are of the form "x + yj" | OFSTNone
'M' (double precision complex) | any | 1 | OFTString whose value is of the form "x + yj" | OFSTNone
'M' (double precision complex) | any | > 1 | OFTStringList whose values are of the form "x + yj" | OFSTNone

Fields with a repeat count > 1 expressing fixed size arrays, or fields using array descriptors 'P' and 'Q' for variable length arrays are mapped to OGR OFTxxxxxList data types. The potential 2D structure of such field has no direct equivalence in OGR, so OGR will expose a linear structure. For fixed size arrays, the user can retrieve the value of the TDIMxx header in the layer metadata to recover the dimensionality of the field.

Fields that have TSCAL and/or TZERO headers are automatically scaled and offset to the physical value (only applies to numeric data types)

TNULL headers are used for integer numeric data types and for a single-occurrence field to set a OGR field to NULL.

## Layer creation options

Layer creation options can be specified in command-line tools using the syntax `-lco <NAME>=<VALUE>` or by providing the appropriate arguments to `GDALDatasetCreateLayer()` (C) or `Dataset.CreateLayer` (Python). The following layer creation options are available:

- REPEAT_{fieldname}=<integer>: For a given field (substitute {fieldname} by its name) of type IntegerList, Integer64List or RealList, specify a fixed number of elements. Otherwise those fields will be created as variable-length FITS columns, which can have performance impact on creation.

- COMPUTE_REPEAT=[AT_FIELD_CREATION​/​AT_FIRST_FEATURE_CREATION]: Defaults to `AT_FIELD_CREATION`. For fields of type IntegerList, Integer64List or RealList, specifies when they are mapped to a FITS column type. The default is AT_FIELD_CREATION, and implies that they will be created as variable-length FITS columns, unless a `REPEAT_{fieldname}` option is specified. When AT_FIRST_FEATURE_CREATION is specified, the number of elements in the first feature will be taken into account to create fixed-size FITS columns.

When using ogr2ogr or `GDALVectorTranslate()` with a FITS source, the FITS header will be taken into account, in particular to help to determine the FITS data type of target columns.

## Examples

- Listing subdatasets in a MEF .fits:

  >     $ gdalinfo ../autotest/gdrivers/data/fits/image_in_first_and_second_hdu.fits

  >     Driver: FITS/Flexible Image Transport System
  >     Files: ../autotest/gdrivers/data/fits/image_in_first_and_second_hdu.fits
  >     Size is 512, 512
  >     Metadata:
  >     EXTNAME=FIRST_IMAGE
  >     Subdatasets:
  >     SUBDATASET_1_NAME=FITS:"../autotest/gdrivers/data/fits/image_in_first_and_second_hdu.fits":1
  >     SUBDATASET_1_DESC=HDU 1 (1x2, 1 band), FIRST_IMAGE
  >     SUBDATASET_2_NAME=FITS:"../autotest/gdrivers/data/fits/image_in_first_and_second_hdu.fits":2
  >     SUBDATASET_2_DESC=HDU 2 (1x3, 1 band)
  >     Corner Coordinates:
  >     Upper Left  (    0.0,    0.0)
  >     Lower Left  (    0.0,  512.0)
  >     Upper Right (  512.0,    0.0)
  >     Lower Right (  512.0,  512.0)
  >     Center      (  256.0,  256.0)

- Opening a given raster HDU:

  >     $ gdalinfo FITS:"../autotest/gdrivers/data/fits/image_in_first_and_second_hdu.fits":1

  >     Driver: FITS/Flexible Image Transport System
  >     Files: none associated
  >     Size is 1, 2
  >     Metadata:
  >     EXTNAME=FIRST_IMAGE
  >     Corner Coordinates:
  >     Upper Left  (    0.0,    0.0)
  >     Lower Left  (    0.0,    2.0)
  >     Upper Right (    1.0,    0.0)
  >     Lower Right (    1.0,    2.0)
  >     Center      (    0.5,    1.0)
  >     Band 1 Block=1x1 Type=Byte, ColorInterp=Undefined

- Listing potential binary tables in a FITS file:

  >     $ ogrinfo my.fits

- Converting a GeoPackage layer into a FITS binary table:

  >     $ ogr2ogr out.fits my.gpkg my_table

## Other

NOTE: Implemented as fitsdataset.cpp.

## Notes on CFITSIO linking in GDAL

### Linux

#### From source

Install CFITSIO headers from your distribution (eg, cfitsio-devel on Fedora; libcfitsio-dev on Debian-Ubuntu), then compile GDAL as usual. CFITSIO will be automatically detected and linked.

#### From distributions

On Fedora/CentOS install CFITSIO then GDAL with dnf (yum): cfitsio is automatically linked.

### MacOSX

The last versions of the MacOSX packages are not linked against CFITSIO. Install CFITSIO as described in the official documentation.

## Driver capabilities

Supports CreateCopy()

This driver supports the `GDALDriver::CreateCopy()` operation

Supports Create()

This driver supports the `GDALDriver::Create()` operation

Supports Georeferencing

This driver supports georeferencing

Supports VirtualIO

This driver supports virtual I/O operations (/vsimem/, etc.)