.. _raster.fits:

================================================================================
FITS -- Flexible Image Transport System
================================================================================

.. shortname:: 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 <http://heasarc.gsfc.nasa.gov/docs/software/fitsio/fitsio.html>`__,
which you must have on your system in order for FITS support to be
enabled (see :ref:`notes on CFITSIO linking <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
<https://fits.gsfc.nasa.gov/standard40/fits_standard40aa-le.pdf#subsection.8.3>`_)
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
<https://agupubs.onlinelibrary.wiley.com/doi/full/10.1029/2018EA000388>`_. 

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 :cpp:func:`GDALRasterBand::GetOffset` / :cpp:func:`GDALRasterBand::SetOffset`
and :cpp:func:`GDALRasterBand::GetScale` / :cpp:func:`GDALRasterBand::SetScale` GDAL functions and no more
referred as metadata.

NOTE: Implemented as ``gdal/frmts/fits/fitsdataset.cpp``.

.. _notes-on-cfitsio-linking:

Notes on CFITSIO linking in GDAL
--------------------------------
Linux
^^^^^
From source
"""""""""""
Install CFITSIO headers from your distro (eg, cfitsio-devel on Fedora; libcfitsio-dev on Debian-Ubuntu), then compile GDAL as usual. CFITSIO will be automatically detected and linked.

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

Starting from Debian 10, Ubuntu 18.04 GDAL is packaged disabling CFITSIO link (see https://bugs.debian.org/422537): having GDAL linked against CFITSIO asks for recompile from source.

MacOSX
^^^^^^
The last versions of the MacOSX packages are not linked against CFITSIO.
Install CFITSIO as described in the `official documentation <https://heasarc.gsfc.nasa.gov/docs/software/fitsio/fitsio_macosx.html>`__.

Driver capabilities
-------------------

.. supports_createcopy::

.. supports_create::

.. supports_georeferencing::

.. supports_virtualio::
