Main Content

fitsread

Read data from FITS file

Description

example

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

example

data = fitsread(filename,'raw') reads the primary data of the FITS file without adjustment. This syntax does not scale the data read from the file, replace undefined values with NaN. The returned data maintains the class type specified in the file.

example

data = fitsread(filename,extname) reads data from the FITS file extension specified by extname. The FITS file contains primary data and can optionally contain any number of optional components, called extensions in FITS terminology.

example

data = fitsread(filename,extname,index) also specifies the index when several of the same extension type exist.

example

data = fitsread(filename,___,Name,Value) reads data from the FITS file with additional options using one or more Name-Value arguments. For example, TableColumns specifies which columns to read.

Examples

collapse all

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

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');

Read a subsample of data from a FITS file.

First, get information about the FITS file.

info = fitsinfo('tst0012.fits')
info = struct with fields:
       Filename: '/mathworks/devel/bat/Bdoc23b/build/matlab/toolbox/matlab/demos/tst0012.fits'
    FileModDate: '12-Mar-2001 18:37:46'
       FileSize: 109440
       Contents: {'Primary'  'Binary Table'  'Unknown'  'Image'  'ASCII Table'}
    PrimaryData: [1x1 struct]
    BinaryTable: [1x1 struct]
        Unknown: [1x1 struct]
          Image: [1x1 struct]
     AsciiTable: [1x1 struct]

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 });

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;

Read every other row from the ASCII table.

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

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;

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

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

Input Arguments

collapse all

File name, specified as a character vector or string scalar.

Data array or extension name, specified as a character vector or a string scalar. The FITS file contains primary data and can optionally contain any number of optional components, called extensions in FITS terminology. 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, 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.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

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

Information, specified as the structure array specifying the location of the data to read. The information structure array can be obtained through fitsinfo. Specifying Info can significantly improve performance, especially when reading multiple images from the file.

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. Each vector in the cell array must be formatted as one of the following.

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 of the dimension and the increment by which to read.

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

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 unique and valid indices into the table data specified in increasing order. This parameter is valid only for the ASCII or binary extensions.

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 unique and 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