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.)