Wolfram Language & System Documentation Center

FITS (.fits, .fit)

  • Import and Export fully support the image, ASCII table, and binary table extensions of the FITS file format.

Background & Context

    • MIME types: application/fits, image/fits
    • FITS scientific image and data format.
    • Standard format for the exchange and archival storage of astronomical data.
    • Endorsed by NASA and the International Astronomical Union.
    • FITS is an acronym for Flexible Image Transport System.
    • Allows multiple header-data units (HDUs).
    • Each HDU can be an image, an ASCII table or a binary table.
    • Image HDUs can only store arrays of single-channel 2D images.
    • Binary and ASCII table HDUs can only store 2D data.
    • Elements of a binary table can be multidimensional arrays.
    • Stores spectral data and raster images as arrays.
    • Developed in 1979 by Don Wells, Eric Greisen, and others.

Import & Export

  • Import["file.fits"] imports a FITS file as an image or an array of data values, depending on the HDU type, for a single HDU file.
  • Import["file.fits"] returns an association of the form <|1->hdu1,…|> for all HDUs in the file.
  • Import["file.fits",elem] imports the specified element from a FITS file.
  • Import["file.fits",{elem, i}] returns elem stored in the i^(th) HDU.
  • The import format can be specified with Import["file","FITS"] or Import["file",{"FITS",elem,…}].
  • Export["file.fits",expr] exports images and graphics as an image to a FITS file, at their raster sizes.
  • Export["file.fits",expr] exports string and numeric arrays as a table to a FITS file.
  • Export["file.fits",1->expr1,…] exports expri to the i^(th) HDU.
  • See the following reference pages for full general information:
  • Import, Exportimport from or export to a file
    CloudImport, CloudExportimport from or export to a cloud object
    ImportString, ExportStringimport from or export to a string
    ImportByteArray, ExportByteArrayimport from or export to a byte array

Import Elements

  • General Import elements:
  • "Elements" list of elements and options available in this file
    "Summary"summary of the file
    "Rules"list of rules for all available elements
  • Structure elements:
  • "HDUCount"number of HDUs
    "Summary"summary of the file
    "SummarySlideView"slide-view summary of all HDUs
  • All elements of a FITS file are imported as a numbered association, returned in the form 1val1,2val2,….
  • Data representation elements:
  • "Data"array of pixel values or table elements
    "Plaintext"representation of image and table extensions as a string
    "RawData"raw data as stored in the file
  • Additional elements, available for image HDUs:
  • "Graphics"raster image, given as a Graphics object
    "Image"raster image, given as an Image object
    "IndeterminateMask"a SparseArray representing indeterminate values in the image
  • Additional elements, available for binary and ASCII table HDUs:
  • "TableData"representation of table extension
    "TableHeaders"table column headers
    "TableUnits"units of measurement corresponding to the table columns
  • Import and Export by default use the "Image" element for image HDUs and the "Data" element for binary and ASCII table HDUs.
  • Subelements for partial data import can be given in one of the following forms:
  • {elem,hdu}for any element
    {elem,hdu,rows,cols}for data elements of single-image and table HDUs
    {elem,hdu,spec1,spec2,…,rows,cols}for data elements of higher-dimensional image HDUs
  • Part specification for hdu, speci, rows and cols can be any of the following:
  • Allall HDUs
    nnth HDU
    n;;mHDU n through m
    n;;m;;sfrom n through m with steps of s
    {n1,n2,…}specific HDUs ni
  • Advanced elements:
  • "BitDepth"bits used to represent gray-level pixels in the file
    "Channels"the number of color channels used in the file
    "ColorSpace"color encoding used in the file
    "DataType"data type used to store image or table data in the file
    "Dimensions"data dimensions
    "Extension"type of the HDU extension
    "ImageSize"raster dimensions of a single frame
    "Range"minimum and maximum raw data values
  • General metadata elements:
  • "MetaInformation"processed metadata
    "RawMetaInformation"raw metadata as stored in the file
  • Information about the recording device and environment:
  • "Airmass"relative airmass
    "Declination"declination setting of the telescope axis
    "Device"recording instrument (e.g. camera)
    "Equinox"equinox for the celestial coordinate system used in this file, typically given in years
    "ExposureTime"photographic exposure time in seconds
    "HourAngle"hour angle of the depicted object when the image was taken
    "ObservationDate"date and time the observation was made
    "RightAscension"right ascension setting of the telescope axis
    "SiderealTime"sidereal time (LST)
    "Telescope"telescope that captured the image
  • Bibliographic information elements:
  • "Author"person who compiled the image information
    "Reference"bibliographic reference associated with this file
  • Other common metadata elements:
  • "Comments"comments for each piece of data or image stored in the file
    "History"description of how the data or image has been processed
    "Object"name of the observed object
    "Observer"person who recorded the data or image
    "Organization"organization or institution responsible for creating this file
  • Metadata field names are converted to all caps on export to conform with FITS standard.

Options

  • Import and Export option:
  • DataReversedAutomaticwhether to reverse the order of rows
  • Import options:
  • ColorFunctionAutomatichow each cell should be colored
    ImageSizeAutomaticoverall image size
    "Gamma"1.0gamma correction parameter used for rendering
    "IncludeExtensions"AllHDU extensions to import
    "IncludeHeaders"Falsewhether to import table headers
  • Export options:
  • "Append"Falsewhether to append to an existing file
    "CompressionMethod"Nonecompression algorithm to use on export
    MetaInformationNonemetainformation per header to be added on export
  • Possible settings for "CompressionMethod" include "GZIP", "GZIPShuffled", "Rice", "HCompress" and "PLIO".

Examples

open all close all

Basic Examples  (3)

Import a FITS file containing image data:

Import a FITS file with multiple HDUs:

Export an image to FITS:

Scope  (7)

Import  (2)

Import all HDUs:

Import image HDUs only:

Import metadata such as data dimensions:

Summary of a FITS image file:

Summary of a multi-HDU file:

Export  (5)

Export an image:

Export a table with columns that conform in type:

Note that table data cannot be stored in the first HDU:

Create a multi-HDU file:

Create a multi-HDU file with explicit extensions:

Export a table with multidimensional elements:

Import Elements  (44)

Available Elements  (2)

List of available elements:

Import all elements as a list of rules:

Data Representation  (17)

"Data"  (2)

Import the image data:

Construct the images using the proper type:

Import a binary table:

"DataType"  (1)

Import the type of data stored in a FITS file:

"Graphics"  (2)

Import image data stored in a file as a Graphics object:

Import part of graphics:

"Image"  (2)

Import image data stored in a file as an Image object:

Import part of image:

"Plaintext"  (1)

Import the data stored in a file as a string:

"Range"  (1)

Import the range of data values stored in a file:

For "Image" HDUs, this is the same as the min and max of raw data:

For tabular HDUs, the range is computable only for numeric parts of the table:

"RawData"  (2)

Import the raw data stored in a file:

Construct the images using the proper type:

Import part of raw data:

"TableData"  (3)

Import table data from a file:

The "TableData" element imports only the table HDUs:

Import part of table data:

"TableHeaders"  (2)

Import the table column headers stored in a file:

The "TableHeaders" element imports headers only from the table HDUs:

"TableUnits"  (1)

Import the units of measurement corresponding to the table columns stored in a file:

Advanced Import Elements  (6)

"BitDepth"  (1)

Import the number of bits used to represent the data stored in a file:

"Dimensions"  (1)

Import the dimensions of data stored in a file:

"Extension"  (1)

Import the types of HDUs stored in the file:

"ImageSize"  (1)

Import the size of each image frame stored in a file:

"Summary"  (1)

Import the summary of a file:

"SummarySlideView"  (1)

Import the summary of all HDUs stored in a file:

Metadata Elements  (19)

"Airmass"  (1)

Get the relative airmass of an image date stored in a file:

"Author"  (1)

Get the name of the person who compiled the data stored in a file:

"Comments"  (1)

Get the comments stored in a FITS file:

"Declination"  (1)

Get the declination setting of the telescope axis:

"Device"  (1)

Get the manufacturer of the recording equipment:

"Equinox"  (1)

Get the equinox for the celestial coordinate system used in this file:

"ExposureTime"  (1)

Get the photographic exposure time in seconds:

"History"  (1)

Get the description of how the data stored in a file has been processed:

"HourAngle"  (1)

Get the hour angle of the depicted object when the image was taken:

"MetaInformation"  (1)

Get the processed metadata from a file:

"Object"  (1)

Get the name of the observed object:

"ObservationDate"  (1)

Get the date and time the observation was made:

"Observer"  (1)

Get the name of the person who recorded the data stored in a file:

"Organization"  (1)

Get the name of the organization or institute the created the data stored in a file:

"RawMetaInformation"  (1)

Get the raw metadata from a file:

"Reference"  (1)

Get the bibliographic reference associated with a file:

"RightAscension"  (1)

Get the right ascension setting of the telescope axis:

"SiderealTime"  (1)

Get the sidereal time (LST) stored in a file:

"Telescope"  (1)

Get the telescope name used for capturing the data stored in a file:

Export Elements  (4)

"Data"  (2)

Export expression as data:

"Rules"  (2)

Export data as list of rules:

Export data and metadata as a list of rules:

Import Options  (6)

ColorFunction  (1)

By default, the image data is imported as an Image object with no color function applied:

Apply a specific color function on import:

DataReversed  (1)

By default, image data stored in a file is reversed only if that is specified in the metadata:

Force the image data to be reversed during the import:

ImageSize  (1)

By default, images are imported in their full resolution:

Specify the raster size of the imported image:

"Gamma"  (1)

By default, gamma correction is not applied:

Apply a gamma correction:

Apply a gamma correction as well as a color function:

"IncludeExtensions"  (1)

By default, all the applicable types of HDUs present in a FITS file are imported:

Import all HDUs present:

Import the element only for "Image" HDUs:

Import an element for multiple types of HDUs:

"IncludeHeaders"  (1)

By default, the headers are not present in the imported table data:

Import data with no table headers:

Export Options  (3)

Append  (1)

Export an image:

By default, the second export to the same file will overwrite it:

DataReversed  (1)

By default, image data is not reversed during the export:

Force image data to be reversed during the export:

"CompressionMethod"  (1)

By default, no compression is applied during the export:

Compare the file sizes using different compression methods:

Possible Issues  (2)

File names containing '(' and '[' characters are not supported:

Note that the file with those special characters cannot be imported either:

Binary table data cannot store multidimensional cells that contain string values: