fitsread

Read data from FITS file

Syntax

data = fitsread(filename)

data = fitsread(filename,"raw")

data = fitsread(filename,extname)

data = fitsread(filename,extname,index)

data = fitsread(filename,___,Name=Value)

Description

data = fitsread(filename) reads the primary data of the Flexible Image Transport System (FITS) file specified by filename and returns it as an array. The fitsread function replaces undefined data values with NaN values and scales numeric data by the slope and intercept values, always returning double precision values.

data = fitsread(filename,"raw") does not scale the data read from the file or replace undefined data values with NaN values. The returned data maintains the class type specified in the file.

data = fitsread(filename,extname) reads data from the FITS file extension specified by extname. The FITS file contains primary data and can optionally contain additional components, called extensions.

data = fitsread(filename,extname,index) reads data from the FITS file extension specified by extname and index.

data = fitsread(filename,___,Name=Value) reads data from the FITS file with additional options using one or more name-value arguments. For example, TableColumns=[3,5] reads the third and fifth columns of data in the FITS file.

Examples

Read FITS File

Read primary data from a FITS file.

data = fitsread("tst0012.fits");

Examine the output variable data.

whos data

  Name        Size             Bytes  Class     Attributes

  data      109x102            88944  double              

Read Raw Data from FITS File

Read primary data from a FITS file as raw data.

data = fitsread("tst0012.fits","raw");

Examine the output variable data.

whos data

  Name        Size             Bytes  Class     Attributes

  data      109x102            44472  single              

Read FITS File with Image Extension

Explore the extensions of a FITS file and read data from the image extension.

List the contents of a FITS file, including any extensions if present.

info = fitsinfo("tst0012.fits");
disp(info.Contents)

    {'Primary'}    {'Binary Table'}    {'Unknown'}    {'Image'}    {'ASCII Table'}

Read data from the image extension of the FITS file.

imageData = fitsread("tst0012.fits","image");
whos imageData

  Name            Size              Bytes  Class     Attributes

  imageData      31x73x5            90520  double              

Read Subsample of FITS File

Read a subsample of data from a FITS file.

First, get information about the FITS file.

info = fitsinfo("tst0012.fits");

Query the sizes of each dimension of the image extension.

info.Image.Size

ans = 1×3

    31    73     5

Store the row and column sizes.

rowend = info.Image.Size(1);
colend = info.Image.Size(2);

Read every other row and column from the fifth element of the third dimension of the FITS file.

 primaryData = fitsread("tst0012.fits","image",Info=info, ...
              PixelRegion={[1 2 rowend],[1 2 colend],5});
 size(primaryData)

ans = 1×2

    16    37

Read Specified Rows from FITS File ASCII Table

Read every other row from the ASCII table of a FITS file.

Determine the number of rows in the ASCII table.

info = fitsinfo("tst0012.fits");
rowend = info.AsciiTable.Rows

rowend = 
53

Read every other row from the ASCII table.

tableData = fitsread("tst0012.fits","asciitable",Info=info, ...
                     TableRows=[1:2:rowend])

tableData=1×8 cell array
    {27x1 cell}    {27x1 double}    {27x1 double}    {27x1 double}    {27x1 double}    {27x1 cell}    {27x1 cell}    {27x1 double}

Read Specified Columns of a FITS File Binary Table

Read all data for the first, second, and fifth columns of the binary table of a FITS file.

Determine the number of rows in the binary table.

info = fitsinfo("tst0012.fits");
rowend = info.BinaryTable.Rows

rowend = 
11

Read first, second, and fifth columns of the binary table.

tableData = fitsread("tst0012.fits","binarytable",Info=info, ...
                     TableColumns=[1 2 5])

tableData=1×3 cell array
    {11x1 cell}    {11x13 double}    {11x3 double}

Input Arguments

filename — Name of FITS file

string scalar | character vector

Name of FITS file, specified as a string scalar or character vector.

• If the file is located in the current folder or in a folder on the MATLAB^® path, specify the name of the file in filename.

• If the file is located neither in the current folder or in a folder on the MATLAB path, specify the full or relative path of the file in filename.

Example: "myFile.fits"

Example: "C:\myFolder\myFile.fits"

Example: "myFolder\myFile.fits"

extname — Data array or extension name

"primary" | "asciitable" | "binarytable" | "image" | "unknown"

Data array or extension name, specified as a string scalar or a character vector. The FITS file contains primary data and can optionally contain any number of optional components, called extensions. To determine the contents of the FITS file, view the Contents field of the structure returned by fitsinfo.

extname	Description
"primary"	Read data from the primary data array.
"asciitable"	Read data from the ASCII table extension as a one-dimensional cell array.
"binarytable"	Read data from the binary table extension as a one-dimensional cell array.
"image"	Read data from the image extension.
"unknown"	Read data from the unknown extension.

index — Index

scalar

Index, specified as a scalar indicating which extension to read if multiple extensions of the same type exist.

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Example: data = fitsread("tst0012.fits",PixelRegion={[1 2 100],[1 2 100]})

Info — Information

structure array

Information, specified as a structure array specifying the location of the data to read. You can obtain this information structure array using the fitsinfo function. Specifying Info can significantly improve performance, especially when reading multiple images from the file.

PixelRegion — Pixel region

cell array of vectors

Pixel region, specified as a cell array of vectors. Each vector corresponds to a dimension of the data. To specify a subregion to read from the Nth dimension, use the Nth vector in the cell array. Specify each vector in the cell array in one of these ways.

Vector Format	Description
start	Start point within the dimension. The default stop point is the end of the dimension.
[start stop]	Start and stop points within the dimension.
[start increment stop]	Start and stop points within the dimension and the increment by which to read.

The pixel region parameter is valid only for the primary or image extensions.

TableColumns — Columns to read

one-dimensional array

Columns to read, specified as a one-dimensional array containing the indices of columns to read from the ASCII or binary table extension. The vector must contain valid indices into the table data specified in increasing order. This parameter is valid only for the ASCII or binary extensions.

TableRows — Rows to read

one-dimensional array

Rows to read, specified as a one-dimensional array containing the indices of rows to read from the ASCII or binary table extension. The vector must contain valid indices into the table data specified in increasing order. This parameter is valid only for the ASCII or binary extensions.

Tips

• MATLAB reads FITS image data in the order that it appears in the file, but some software packages for reading and writing FITS image data assume that the image data is stored in an order in which the bottom row of the image is first. Consequently, FITS image data displayed in MATLAB may appear flipped in the up-down direction (that is, about a horizontal axis) when compared to the same data displayed using other software packages. To flip an image in MATLAB, you can use the flipud function on the output of fitsread before displaying the image.

Version History

Introduced before R2006a