The high-level interface consists of a number of functions that are written in S-lang and are designed to take some of the tedium out of performing standard operations on fits files. To illustrate this point, consider the creation of a fits file with a binary table extension called called ``COSXSINX'':
variable data = struct { x, cosx, sinx };
data.x = [0:2*PI:0.01];
data.cosx = cos(data.x);
data.sinx = sin(data.x);
fits_write_binary_table ("foo.fits", "COSXSINX", data);
It can't get much easier than that!
In general the high-level functions take an argument that represents
the fits file to be manipulated. It may be either an already open
file pointer such as one returned by fits_open_file
, or the
name of a file to be opened. In the documentation for the functions,
this fact is indicated by
Fits_File_Type or String_Type fd;
showing that the file descriptor may be either an open file pointer
or a string.
If specified as a string, then a fits file of that name will be opened in a mode that is compatible with the operation being performed, with the current HDU (header-data unit) set to the first ``most interesting'' one. Here, ``first most interesting'' means the first HDU with a non-zero value for the NAXIS keyword.
For example, sometimes one simply wants to read some keywords from a
file. In such a case it is not necessary to explicitly call
fits_open_file
. Rather simply pass the name of the file to
the appropriate function:
(object, ra_targ, dec_targ)
= fits_read_key ("foo.fits", "OBJECT", "RA_TARG", "DEC_TARG");
It may be necessary to specify which HDU should be used if the
``first most interesting'' one is not the desired HDU. The easiest way
to do that is to specify the extension using CFITSIO's virtual file
syntax, e.g.,
(object, ra_targ, dec_targ)
= fits_read_key ("foo.fits+1", "OBJECT", "RA_TARG", "DEC_TARG");
(object, ra_targ, dec_targ)
= fits_read_key ("foo.fits[EVENTS]", "OBJECT", "RA_TARG", "DEC_TARG");
If one is going to make a number of calls to functions in the high-level interface using the same file, then it is a good idea to explicitly open the file, e.g.,
fptr = fits_open_file ("foo.fits[EVENTS]", "w");
opens the file for both reading and writing and sets the current HDU
to the ``EVENTS'' extension.
The object returned by the fits_open_file
function is an
object of type Fits_File_Type
. It is automatically destroyed
when it goes out of scope. When this happens, the fits file
attached to it will be silently closed. Consider:
define write_image_to_file (file, img)
{
variable fptr = fits_open_file ("new.fits", "c");
fits_write_image (fptr, NULL, img, NULL, NULL);
fits_write_date (fptr);
}
Here, the write_image_to_file
function will create a new file
called new.fits
and write the specified image to the file. In
this example, the file pointer object was not explicitly closed.
Since the fptr
variable goes out of scope when the function
returns, the cfitsio module will silently close the file. While
this is a convenient feature for many purposes, it is always better
to explicitly close a file when it has been modified. The reason
for this is that CFITSIO writes to internal buffers and then
flushes those to the disk. Often some buffers will not get written
to the disk until the file is closed. If the disk is full, or
something else goes wrong then the file will not be properly closed
resulting in a incomplete or corrupt file. Hence it is strongly
recommended that one explicitly close a file after writing to a
file, i.e.,
define write_image_to_file (file, img)
{
variable fptr = fits_open_file ("new.fits", "c");
fits_write_image (fptr, NULL, img, NULL, NULL);
fits_write_date (fptr);
fits_close_file (fptr);
}
The high-level interface contains several functions for manipulating header keywords and records.
The fits_read_key
may be used to read the values of one or
more keywords. Suppose that the file casA.fits
contains the
following keywords in an extension called ``EVENTS'':
TELESCOP= 'CHANDRA ' / Telescope
INSTRUME= 'ACIS ' / Instrument
DETNAM = 'ACIS-7 ' / Detector
GRATING = 'NONE ' / Grating
OBJECT = 'CAS A ' / Source name
RA_NOM = 350.91781217089 / Nominal RA
DEC_NOM = 58.792819089577 / Nominal Dec
ROLL_NOM= 323.38710408328 / Nominal Roll
The fits_read_key
function may be used to read, e.g, the
OBJECT and RA_NOM keywords:
(obj, ra) = fits_read_key ("casA.fits[EVENTS]", "OBJECT", "RA_NOM");
After the function call, the variables obj
and ra
will
have the data types String_Type
and Double_Type
, resp.
If the requested keyword does not exist in the header, the function
will return NULL
to signal its not existence:
exptime = fits_read_key ("casA.fits[EVENTS]", "EXPTIME");
if (exptime == NULL)
{
message ("*** Warning: EXPTIME does not exist. Assuming 3.2);
exptime = 3.2;
}
The fits_read_key_struct
is an alternative to
fits_read_key
that returns a structure with field names that
correspond to the keyword names. In most cases, a field name will
just be the lower case version of the keyword name. However, if the
keyword name does not start with an alphabetic character or contains
a hyphen, then it will be normalized as follows:
keys = fits_read_key_struct ("foo.fits", "OBJECT", "2CRVL3",
"DATE-OBS");
After the function call, keys
will be a structure with the 3
fields: object
, _2crvl3
, and date_obs
. If any
of these keywords do not exist in the header, the value of the
corresponding structure field will be NULL.
The fits_update_key
function may be used to write or update
the value of a keyword. If a keyword of the specified name exists,
then the value of the keyword will be updated to the new value.
Otherwise a new keyword will be appended to the header.
Other specialized keyword writing routines include
fits_write_date
, which write the current date in the required
format, and fits_write_chksum
, which computes and updates the
checksum of the HDU. Finally the fits_write_comment
and
fits_write_history
functions may be used to write comments
and history records to the header, respectively.
There are a several functions for reading binary tables. The
simplest one, fits_read_table
reads the entire binary table
into a structure, whose fields correspond to the names of the columns
in the table. (If a column has a name that contains non-alphanumeric
characters, or does not start with an alphabetic character, then the
structure field name for the column will be undergo the normalization
process described for keywords.) For example, consider a file called
foo.fits
with a binary table whose structure is defined by the
FITS header:
XTENSION= 'BINTABLE'
BITPIX = 8
NAXIS = 2
NAXIS1 = 34
NAXIS2 = 500
PCOUNT = 0
GCOUNT = 1
TFIELDS = 4
TTYPE1 = 'TIME '
TFORM1 = 'D '
TTYPE2 = 'X '
TFORM2 = 'E '
TTYPE3 = 'Y '
TFORM3 = 'E '
TTYPE4 = 'PHAS '
TFORM4 = '9I '
EXTNAME = 'EXAMPLE '
TDIM4 = '(3,3) '
This header shows that the binary table is 500 rows in length and
contains 4 columns with names TIME, X, Y, and PHAS. The table may be
read via
tbl = fits_read_table ("foo.fits[EXAMPLE]");
assigning a structure to the tbl
variable. The structure has
fields with names time
, x
, y
, and phas
,
which be displayed via
vmessage ("tbl.time = %S", tbl.time);
vmessage ("tbl.x = %S", tbl.x);
vmessage ("tbl.y = %S", tbl.y);
vmessage ("tbl.phas = %S", tbl.y);
producing:
tbl.time = Double_Type[500]
tbl.x = Float_Type[500]
tbl.y = Float_Type[500]
tbl.z = Short_Type[500,3,3]
Note that the fits_read_table
function not only read the data
in a way that preserved the data type, but it also correctly
identified the phas
column as one containing a 3x3 image in
every row!
Often one is interested in only a few columns of a table. Instead of
reading the entire table, which could use a lot of memory for a large
table, the fits_read_table
function may also be used to read
just the specified columns, e.g.,
tbl = fits_read_table ("foo.fits[EXAMPLE]", "x", "y");
will read just the X
and Y
columns.
An alternative interface with much the same functionality is provided
by the fits_read_col
function. Instead of returning the data
as a structure, it returns the data as multiple return values, e.g.,
t = fits_read_col ("foo.fits[EXAMPLE]", "time");
(x,y) = fits_read_col ("foo.fits[EXAMPLE]", "x", "y");
The fits_read_cell
function may be used to read a single cell
in the table. For example
phas = fits_read_cell ("foo.fits[EXAMPLE]", "phas", 4);
will return the 3x3 array of the ``phas'' column in the fourth row.
Finally, the fits_read_cells
function may be used to read a
specified range of rows in the table. For instance,
(x,y) = fits_read_cells ("foo.fits[EXAMPLE]", "x", "y", 1, 1000);
will read the first 1000 rows of the X
and Y
columns in
the table.
The high-level interface has several functions that are useful for
the creation of a binary table. Chief among them is the
fits_write_binary_table
function, which supports several
methods of calling it. The simplest use was illustrated earlier.
Here more complicated uses will be considered.
As a first step, suppose that the binary table is to contain data for the Lissajous curve constructed as follows:
A_x = 10.0; omega_x = 3.0; phi_x = 0.0;
A_y = 20.0; omega_y = 7.0; phi_y = 1.0;
t = [0:100:0.01];
x = A_x * cos (omega_x*t + phi_x);
y = A_y * cos (omega_y*t + phi_y);
The goal is to write out arrays t
, x
, and y
to a
binary table called LISSAJOUS, and with columns of the corresponding
names. The easiest way is to use:
data = struct {t, x, y}; data.t = t; data.x = x; data.y = y;
fits_write_binary_table ("foo.fits", "LISSAJOUS", data);
Now suppose that it is desired to write the parameters defining the
Lissajous pattern as keywords and to write a history record to the
file. One way to do this is via the fits_update_key
,
fits_write_history
, and fits_write_comment
functions:
fp = fits_open_file ("foo.fits[LISSAJOUS]");
fits_write_comment (fp, "This table contains data for a Lissajous pattern");
fits_update_key (fp, "A_X", A_x, "x(t) Amplitude");
fits_update_key (fp, "A_Y", A_y, "y(t) Amplitude");
fits_update_key (fp, "OMEGA_X", omega_x, "x(t) omega");
fits_update_key (fp, "OMEGA_Y", omega_y, "y(t) omega");
fits_update_key (fp, "PHI_X", phi_x, "x(t) phase");
fits_update_key (fp, "PHI_Y", phi_y, "y(t) phase");
fits_write_history (fp, "This was written as an example for the " +
"documentation of the slang cfitsio module");
fits_close_file (fp);
The advantage of using the fits_update_key
is that it allows
control over the comment associated with the keyword; however,
repeated calls to fits_update_key
can become tedious.
A simpler mechanism to achieve this goal is to pass the keywords and
history information to the fits_write_binary_table
function as
an optional arguments,
keys = struct {A_x, omega_x, phi_x, A_y, omega_y, phi_y};
set_struct_fields (keys, A_x, omega_x, phi_x, A_y, omega_y, phi_y);
hist = struct {history, comment};
hist.comment = "This table contains data for a Lissajous pattern";
hist.history = "This was written as an example for the " +
"documentation of the slang cfitsio module";
fits_write_binary_table ("foo.fits", "LISSAJOUS", data, keys, hist);
to produce:
XTENSION= 'BINTABLE' / binary table extension
BITPIX = 8 / 8-bit bytes
NAXIS = 2 / 2-dimensional binary table
NAXIS1 = 24 / width of table in bytes
NAXIS2 = 10000 / number of rows in table
PCOUNT = 0 / size of special data area
GCOUNT = 1 / one data group (required keyword)
TFIELDS = 3 / number of fields in each row
TTYPE1 = 't ' / label for field 1
TFORM1 = 'D ' / data format of field: 8-byte DOUBLE
TTYPE2 = 'x ' / label for field 2
TFORM2 = 'D ' / data format of field: 8-byte DOUBLE
TTYPE3 = 'y ' / label for field 3
TFORM3 = 'D ' / data format of field: 8-byte DOUBLE
EXTNAME = 'LISSAJOUS' / name of this binary table extension
A_X = 10
OMEGA_X = 3
PHI_X = 0
A_Y = 20
OMEGA_Y = 7
PHI_Y = 1
COMMENT This table contains data for a Lissajous pattern
HISTORY This was written as an example for the documentation of the slang cfitsi
HISTORY o module
It is important to note that in the the above examples, the name of
the file to contain the binary table was explicitly passed to the
fits_write_binary_table
function. This causes
fits_write_binary_table
to create a new file containing
the binary table, and if a file of that name exists, it will be
deleted before the new one is created.
To append a table to an existing file, first open it using the
fits_open_file
function, and then use the file pointer in
place of the name:
fp = fits_open_file ("foo.fits", "w"); % <<-- note the "w"
.
.
fits_write_binary_table (fp, ....);
fits_close_file (fp);
This technique must also be used to create a file containing
multiple binary tables:
fp = fits_open_file ("foo.fits", "c"); % <<-- note the "c"
.
.
fits_write_binary_table (fp, ....); % first table
.
.
fits_write_binary_table (fp, ....); % second table
fits_close_file (fp);
Dealing with FITS images in S-lang is easy as long as one understands
that FITS stores images in FORTRAN column-major order, whereas
S-lang utilizes a C row-major order. That is, the first
dimension of a FITS array varies fastest whereas it is the last
dimension of a S-lang array that varies fastest. This difference is
automatically accounted for by the underlying cfitsio
module. In other words, images may be used in S-lang scope as
ordinary S-lang arrays where the first dimension varies slowest, and
the cfitsio
module will make the necessary translations when
reading or writing an image from a file. An easy way to remember the
S-lang or C ordering is that for a 2-d array, the first index is a
row index and the second a column--- the same as matrices are indexed
in linear algebra. Do not fall into the trap of indexing a S-lang array
the same as you would of indexing a point in Cartesian space (x,y),
instead think in terms of rows and columns.
The fits_read_img
may be used to read the image from the
primary FITS HDU or a FITS image extension. It is not designed to
read images that are stored in binary tables--- there are other
functions for that purpose. The fits_read_img
function
simply returns the data as an array of the appropriate type and
dimensions (in row-major order) with any scaling defined via the
BZERO and BSCALE header keywords applied.
Writing an image HDU is somewhat more involved than reading one because in addition to writing the image data, the header must first be set up to describe the image. Fortunately, the high-level functions make this easy.
Suppose that one has created an image array via, e.g., the
histogram
module's hist2d
function from the X and Y
columns of a binary table:
(x,y) = fits_read_col ("evt2.fits[EVENTS]", "X","Y");
xgrid = 3840.5 + [0:1023:2];
ygrid = 3840.5 + [0:1023:2];
img = hist2d (y, x, ygrid, xgrid);
and that one wants to write this out to a fits file called
img.fits
. The simplest way to do this is using
fits_write_image_hdu
:
fits_write_image_hdu ("img.fits", NULL, img);
Note that the data-type of the image array controls the type of image
written to the fits file. If the image array is an array of
Double_Type
s, then the image will be written with BITPIX set
to -64. To have such an array out as 16 bit integers, then the array
must first be scaled to the range of a 16 bit integer and then
typecast to Int16_Type
:
int16_image = typecast (img, Int16_Type);
Additional keywords may be written to the image HDU using the
fits_update_key
function. And like
fits_write_binary_table
, the fits_write_image_hdu
function takes optional parameters that specify additional keywords,
history, and comments to be written. The reader is referred to the
discussion of the fits_write_binary_table
function for more
information.
The FITS package includes a set of routines for reading and writing WCS keywords in the form proposed by Greisen and Calabretta. Although they are part of the high-level interface, the routines are somewhat experimental and as such must be loaded separately via:
require ("fitswcs");
The routines in this interface deal with a structure that describes the WCS via the following fields:
The number of axes to transform (Int_Type)
Specifies the WCS transformation (String_Type[naxis])
Units (String_Type[naxis])
WCS values at the reference pixel (Double_Type[naxis])
The coordinates of the reference pixel (Double_Type[naxis])
Species the gradient at the reference pixel (Double_Type[naxis])
An array used to linearly transform the WCS. (Double_Type[naxis,naxis] or NULL)
An array of addition parameters used to specify the WCS (NULL in most cases)
An array of additional string parameters (NULL in most cases).
A name given to this coordinate system.
While the user is encouraged to understand the FITS WCS conventions
and the precise meanings of these fields, the fitswcs
interface
provides routines to make the use of this structure as transparent
as possible for the most common uses. A few examples will
illustrate this.
Consider once again the example of creating a FITS image by binning two columns of a FITS binary table:
(x,y) = fits_read_col ("evt2.fits[EVENTS]", "X","Y");
xgrid = 3840.5 + [0:1023:2];
ygrid = 3840.5 + [0:1023:2];
img = hist2d (y, x, ygrid, xgrid);
fits_write_image_hdu ("img.fits", NULL, img);
Unfortunately the resulting file will contain none of the WCS
information that was attached to the X and Y columns from which the
image was constructed. One might be tempted to simply copy that
information to the output file with the aid of the fitswcs
routines via
wcs = fitswcs_get_column_wcs ("evt2.fits[EVENTS]", ["Y", "X"]);
fitswcs_put_img_wcs ("img.fits", wcs);
The problem with this approach is that the WCS read from the binary
table does not describe the image created from it because it knows
nothing about how the image was binned nor how the image pixel
coordinates relate back to the X and Y columns. That information is
contained in the definition of the grids passed to the hist2d
function:
xgrid = 3840.5 + [0:1023:2];
ygrid = 3840.5 + [0:1023:2];
These grids describe a simple linear transformation from image pixel
coordinates to the (X,Y) coordinates of the binary table. Since the
transformation is linear, the fitswcs_bin_wcs
function may be
used to transform the WCS:
wcs = fitswcs_bin_wcs (wcs, ygrid, xgrid);
It is the transformed WCS that is to be written out:
fitswcs_put_img_wcs ("img.fits", wcs);
It is important to note the order in which the X and Y arguments were used. Recall that FITS stores images in a FORTRAN column-major order whereas S-lang uses a row-major order. For this reason, ``row-like'' parameters come before ``column-like'' parameters in statements such as
img = hist2d (y, x, ygrid, xgrid);
wcs = fitswcs_get_column_wcs ("evt2.fits[EVENTS]", ["Y", "X"]);
wcs = fitswcs_bin_wcs (wcs, ygrid, xgrid);
Sometimes it is useful to attach more than one coordinate system to
an image. For example, it is useful to have a coordinate system
that maps the pixel coordinates back to (X,Y) coordinates from which
they were derived. The fitswcs_new_img_wcs
may be used to
construct a linear WCS corresponding to the linear coordinate grids
of the image:
wcsP = fitswcs_new_img_wcs (ygrid, xgrid);
wcsP.wcsname = "PHYSICAL";
fitswcs_put_img_wcs ("img.fits", wcsP, 'P');
Note that the WCS was given the name ``PHYSICAL''. While not
required, this enables this alternate coordinate system to be
displayed as the physical system by the DS9 image display program.
Consider a FITS file hydra.fits
containing an
image HDU with the following FITS header:
SIMPLE = T / file does conform to FITS standard
BITPIX = -32 / number of bits per data pixel
NAXIS = 4 / number of data axes
NAXIS1 = 657 / length of data axis
NAXIS2 = 657 / length of data axis
NAXIS3 = 1 / length of data axis
NAXIS4 = 1 / length of data axis
CTYPE1 = 'RA---SIN'
CRVAL1 = 139.5235701
CRPIX1 = 330
CDELT1 = -0.0004166666768
CTYPE2 = 'DEC--SIN'
CRVAL2 = -12.0955450949
CRPIX2 = 328
CDELT2 = 0.0004166666768
PC1_1 = 1
PC1_2 =-1.7318465835227e-09
PC2_1 = 1.7318465835227e-09
PC2_2 = 1
CTYPE3 = 'FREQ '
CRVAL3 = 332902343.75
CRPIX3 = 1
CDELT3 = 2490234.5
CTYPE4 = 'STOKES '
CRVAL4 = 1
CRPIX4 = 1
CDELT4 = 1
This particular image had so-called ``degenerate axes'' added, which
had the effect of increasing its dimensionality from 2 to 4. As such,
this image may be rejected by some image display programs that expect
a 2-d image. In fact,
img = fits_read_img ("hydra.fits");
wcs = fitswcs_get_img_wcs ("hydra.fits");
will read the image as a Float_Type[1,1,657,657]
object, and
the WCS as a 4-d with wcs.ctype equal to
["STOKES", "FREQ", "DEC--SIN", "RA---SIN"]
The degenerate dimensions may be removed from the image via
img = img[0,0,*,*];
producing a 2d image of type Float_Type[657,657]
. The
corresponding wcs may be obtained using the fitswcs_slice
function to extract the last two dimensions of the WCS:
wcs = fitswcs_slice (wcs, [2,3]);
Another use of the fitswcs_slice
is to reorder the dimensions
of the WCS. For example, earlier it was pointed out that when
constructing an image from columns in a table, that one read the WCS
in a row-major order. If the reverse order was used when obtaining
the WCS from the columns of a binary table, e.g.,
wcs = fitswcs_get_column_wcs ("evt2.fits[EVENTS]", ["X", "Y"]);
then it would have been necessary to reverse the order of the
dimensions of the WCS structure. The fitswcs_slice
may be
used to swap the dimensions of the WCS, e.g.,
wcs = fitswcs_slice (wcs, [1,0]);
Retrieve all error messages from the CFITSIO error stack
String_Type[] fits_read_errmsgs ()
This function returns all the error messages from the CFITSIO error message stack as an array of strings.
Using this function will cause the error message stack to be cleared.
Set the verbosity level of the cfitsio error messages
fits_set_verbose_errors (Int_Type level)
When a call to a function in the high-level interface fails, a error
message will get generated. By default, all messages from the
underlying cfitsio error stack are printed. This behavior may be
turned off by calling this function with level
equal to 0.
Open a fits file
Fits_File_Type fits_open_file (String_Type filename, String_Type mode)
The fits_open_file
function can be used to open and existing fits
file for reading or updating, or to create a new fits file, depending upon
the value of the mode
parameter. Specifically, if mode
is
"r"
, the file will be opened for reading. If mode
is "w"
,
the file will be opened for updating (both reading and writing). Otherwise,
mode
must be "c"
, which indicates that a new file is to be created.
In the latter case, if a file already exists with the specified name, it will
get deleted and a new one created in its place.
If the function fails, it will signal an error; otherwise an open file pointer will be returned.
Close a fits file
fits_close_file (Fits_File_Type f)
The fits_close_file
closes a previously opened fits file. The function
will signal an error if the operation fails.
This function could fail if it fails to write out any buffered data because of filesystem errors (disk full, etc.).
Move to an extension that looks interesting
fits_move_to_interesting_hdu (fp [, hdu_type]
Fits_File_Type fp;
Int_Type hdu_type;
The function move the fits file pointer fp
forward to an HDU that looks
interesting. By definition, an interesting HDU is one in which NAXIS is
non-zero. The first parameter fp
must be a pointer to an already open
fits file. The second parameter, if present, may be used to specifiy the
type of HDU, e.g., either an image (hdu_type=_FITS_IMAGE_HDU
) or a
binary table (hdu_type=_FITS_BINARY_TBL
).
If the function fails to find an interesting HDU of the appropriate type, an exception will be generated.
Check for the existence of a keyword
Int_Type fits_key_exists (fd, key)
Fits_File_Type or String_Type fd;
String_Type key;
The fits_key_exists
function checks for the existence of a specified
keyword in the file specified by the descriptor fd
, which must specify
the name of a file or an open file pointer.
If the specified key exists, the function return 1
, otherwise it returns 0
.
Get the column numbers of specified columns
column_num = fits_get_colnum (fd, column_name)
Fits_File_Type or String_Type fd;
String_Type column_name;
This function returns the column number of the column with the specified name.
The file-descriptor fd
must specify the name of a file, or an open
fits file pointer.
Check for the existence of a binary table column
Int_Type fits_binary_table_column_exists (fd, col)
Fits_File_Type or String_Type fd;
String_Type col;
This function may be used to determine whether or not a named column
exists in a binary table. The table is specified via the fd
parameter which must either be the name of a file containing the binary
table, or an file pointer.
If the specified column exists, 1
will be returned; otherwise the function
will return 0
.
Read one or more columns from a FITS binary table
(x1, ...xN) = fits_read_col (file, c1, ... cN)
Fits_File_Type or String_Type file;
Int_Type or String_Type c1, ...cN;
This function returns one or more vectors containing objects in the
specified columns of the binary table indicated by file
. If
file
is a string, then the file will be opened via the virtual
file specification implied by file
. Otherwise, file
should represent an already opened FITS file. The column parameters
may either be strings denoting the column names, or integers
representing the column numbers.
Read one or more columns from a FITS binary table
struct = fits_read_col_struct (file, col1, ...)
Fits_File_Type or String_Type file;
String_Type col1, ...;
This function works exactly like fits_read_col
except it returns the
values in a structure. See the documentation on that function for more
information.
fits_read_col,
fits_read_key_struct,
fits_read_row,
fits_read_header
Read a cell from a FITS binary table
X = fits_read_cell (file, c, r)
Fits_File_Type or String_Type file;
Int_Type r, c;
This function returns the object in the column c
and row
r
of the binary table indicated by file
. If file
is a string, then the file will be opened via the virtual file
specification implied by file
. Otherwise, file
should
represent an already opened FITS file.
Read a row from a FITS binary table
Struct_Type fits_read_cell (file, r)
Fits_File_Type or String_Type file;
Int_Type r;
This function returns a structure containing the data in the columns
of the row r
of the binary table indicated by file
. If
file
is a string, then the file will be opened via the virtual
file specification implied by file
. Otherwise, file
should represent an already opened FITS file.
Read a FITS header
Struct_Type fits_read_header (file)
Fits_File_Type or String_Type file;
This function reads the header of the fits file given by the
file
parameter and returns it as a structure. If file
is
a string, then the file will be opened via the virtual file
specification implied by file
. Otherwise, file
should
represent an already opened FITS file.
Read a FITS table
Struct_Type fits_read_table (file [,columns...])
Fits_File_Type or String_Type file;
fits_read_table
reads the data in a table of the FITS file
specified by file
and returns it as a structure. If the optional
column name parameters are specified, then only those columns will be read.
Otherwise, the entire table will be returned.
If file
is a string, then the file will be opened via the virtual file
specification implied by file
. Otherwise, file
should
represent an already opened FITS file.
fits_read_col,
fits_read_cell,
fits_read_row,
fits_read_header
Read one or more keywords from a FITS file
(val1,...) = fits_read_key (file, key1, ...)
Fits_File_Type or String_Type file;
String_Type key1, ...;
fits_read_key
reads the values of one or more keywords in the fits
file specified by file
and returns them. If file
is a string, then the file will be opened via the virtual file
specification implied by file
. Otherwise, file
should
represent an already opened FITS file. If any of the keywords do not exist,
a value of NULL
will be returned for the corresponding keyword.
fits_read_key_struct,
fits_read_col,
fits_read_cell,
fits_read_row,
fits_read_header
Read one or more keywords from a FITS file
struct = fits_read_key (file, key1, ...)
Fits_File_Type or String_Type file;
String_Type key1, ...;
This function works exactly like fits_read_key
excepts returns the
values in a structure. See the documentation on that function for more
information.
fits_read_key,
fits_read_col,
fits_read_cell,
fits_read_row,
fits_read_header
Prepare a binary table
fits_create_binary_table (file, extname, nrows, ttype, tform, tunit)
Fits_File_Type or String_Type file;
String_Type extname;
Int_Type nrows;
String_Type ttype[];
String_Type tform[];
String_Type tunit[];
This creates a new binary table with the specified structure. The parameters
ttype
, tform
, and tunit
are string arrays that specify
the column names, column data type, and column units, respectively.
The binary table will be given the extension name extname
.
Write a binary table
fits_write_binary_table (file, extname, sdata, [skeys [,hist]])
Fits_File_Type or String_Type file;
String_Type extname;
Struct_Type sdata;
Struct_Type skeys;
Struct_Type hist;
The fits_write_binary_table
function creates a new binary table in
the specified file. The parameter file
specifies either a filename or
an open file pointer. The extname
parameter specifies the extension
name of the binary table. The data written to table are specified in the
sdata
structure, where the name of the structure field specifies the
column name. If skeys
is non-NULL, then it is a structure indicating
additional keywords to be written to the header of the binary table. If the
optional parameter hist
is present and non-NULL, then it is a structure
whose fields indicate either comment or history information to be written
to the header.
The following code
variable data = struct { x, cosx, sinx };
data.x = [0:2*PI:0.01];
data.cosx = cos(data.x);
data.sinx = sin(data.x);
variable keys = struct { hduname, username};
keys.hduname = "COSXSINX";
keys.username = "John Doe";
variable hist = struct { history, comment};
hist.history = ["This is a history record", "This is another"];
hist.comment = ["This is a comment", "And this is another"];
fits_write_binary_table ("foo.fits", "COSXSINX", data, keys, hist);
produces a binary table with the header:
XTENSION= 'BINTABLE' / binary table extension
BITPIX = 8 / 8-bit bytes
NAXIS = 2 / 2-dimensional binary table
NAXIS1 = 24 / width of table in bytes
NAXIS2 = 629 / number of rows in table
PCOUNT = 0 / size of special data area
GCOUNT = 1 / one data group (required keyword)
TFIELDS = 3 / number of fields in each row
TTYPE1 = 'x ' / label for field 1
TFORM1 = 'D ' / data format of field: 8-byte DOUBLE
TTYPE2 = 'cosx ' / label for field 2
TFORM2 = 'D ' / data format of field: 8-byte DOUBLE
TTYPE3 = 'sinx ' / label for field 3
TFORM3 = 'D ' / data format of field: 8-byte DOUBLE
EXTNAME = 'COSXSINX' / name of this binary table extension
HDUNAME = 'COSXSINX'
USERNAME= 'John Doe'
HISTORY This is a history record
HISTORY This is another
COMMENT This is a comment
COMMENT And this is another
This function provides no mechanism to mix comments and keyword records. As the example shows, this function places the comment and history records at the end of the table.
Update the value of a keyword
fits_update_key (fd, key, val [,comment])
String_Type or Fits_File_Type fd;
String_Type key;
Any type val;
String_Type comment;
The fits_update_key
function updates the value and comment fields
of an existing keyword with the specified name. If the keyword does not
exist, a new keyword will be appended to the end of the header.
Update the value of a logical (boolean) keyword
fits_update_logical (fd, key, val, comment)
String_Type or Fits_File_Type fd;
String_Type key;
Any type val;
String_Type comment;
The fits_update_logical
function updates the value and comment fields
of an existing keyword of the specified name with the specified boolean value.
If the keyword does not exist, a new keyword will be appended to the end of
the header.
Write a comment to the header
fits_write_comment (fd, comment)
Fits_File_Type or String_Type fd;
String_Type comment;
As the name indicates, this function writes a comment record to the specified
fits file. The file-descriptor fd
must either be the name of a fits
file or an open fits file pointer.
Write a history record to the header
fits_write_history (fd, history)
Fits_File_Type or String_Type fd;
String_Type history;
As the name indicates, this function writes a history record to the specified
fits file. The file-descriptor fd
must either be the name of a fits
file or an open fits file pointer.
Write the DATE keyword to the current HDU
fits_write_date (fd)
Fits_File_Type or String_Type fd;
The fits_write_date
function calls _fits_write_date
to write
the DATE to the header of the specified file descriptor, which must either
be the name of a fits file or an open fits file pointer.
Compute and write the DATASUM and CHECKSUM keywords
fits_write_chksum (fd)
Fits_File_Type or String_Type fd;
The fits_write_chksum
function calls _fits_write_comment
to
compute and write the DATASUM and CHECKSUM keywords to the
header of the specified file descriptor, which must either
be the name of a fits file or an open fits file pointer.
Verify the checksums for the current HDU
isok = fits_verify_chksum (fd [,dataok, hduok])
Fits_File_Type or String_Type fd;
Ref_Type dataok, hduok;
The fits_verify_chksum
function calls _fits_verify_chksum
to
verify the header and data checksums of the current HDU. A non-zero return value
signifies that the checksums are ok, otherwise the function returns 0 to indicate
that the checksums are invalid. The individual checksums of the HDU or data
can be checked through the use of the optional parameters.
Read all the records in a fits header
String_Type[] fits_read_records (Fits_File_Type or String_Type fp)
This function returns a list of all the header records associated with the fits file descriptor as an array of strings.
Write records to fits header
fits_write_records (fd, records)
Fits_File_Type or String_Type fd;
Array_Type records;
This function uses the _fits_write_record
function to write a series
of records to the current HDU.
Obtain the key classes for a set of cards
Int_Type[] = fits_get_keyclass (Array_Type cards)
This function uses the _fits_get_keyclass
function to obtain the
key-classes associated with one or more cards. The function returns an
integer-valued array of the same length as the cards
array.
Obtain set of header cards to those that are not associated with the cards describing the structure of the HDU:
variable cards = fits_read_records ("evt2.fits[EVENTS]");
variable classes = fits_get_keyclass (cards);
cards = cards[where (classes != _FITS_TYP_STRUC_KEY)];
Get the fits bitpix value for an array
Int_Type fits_get_bitpix (array)
This function may be used to obtain the bitpix value for a specified image array. The array must be an integer or floating point type, otherwise and error will be generated. The bitpix value is returned.
Read image data from a fits file
Array_Type fits_read_img (fd)
Fits_File_Type or String_Type fd;
This function reads an image from the specified file descriptor. The file descriptor must be either the name of an existing file, or an open file pointer. It returns the image upon sucess, or signals an error upon failure.
fits_read_table,
fits_read_col,
fits_open_file,
fits_write_img
Create a primary array or image extension
fits_create_image_hdu (fd, extname, type, dims)
Fits_File_Type or String_Type fd;
String_Type extname;
Array_Type dims;
DataType_Type type;
This function make use of the _fits_create_img
function to create an
image extension or primary array of the specified type and size. If the
extname
parameter is non-NULL, then an EXTNAME keyword will be
written out with the value of the extname parameter.
The dims
parameter must be a 1-d integer array that corresponds
to the dimensions of the array to be written.
If fd
is specified as a string, then a new file of that name will be
created. If a file by that name already exists, it will be deleted and
a new one created. If this behavior is undesired, then explicitly open the
file and pass this routine the resulting file pointer.
Write an image extension
fits_write_image_hdu (file, extname, image [,skeys [,hist]])
Fits_File_Type or String_Type file;
String_Type extname;
Any_Type image
Struct_Type skeys;
Struct_Type hist;
The fits_write_image_hdu
function creates a new image extension in
the specified file. The parameter file
specifies either a filename or
an open file pointer. The extname
parameter specifies the extension
name of the image, or NULL for the primary image. The image data written
to the file are specified by the image
parameter.
If the optional parameter skeys
is non-NULL, then it is a
structure indicating additional keywords to be written to the HDU.
If the optional parameter hist
is present and non-NULL,
then it is a structure whose fields indicate either comment or history
information to be written to the header.
The following code
variable img = [1:128*128]; reshape (img, [128,128]);
variable keys = struct { hduname, username};
keys.hduname = "MY_IMAGE";
keys.username = "John Doe";
variable hist = struct { history, comment};
hist.history = ["This is a history record", "This is another"];
hist.comment = ["This is a comment", "And this is another"];
fits_write_image_hdu ("foo.fits", NULL, img, keys, hist);
produces an image HDU with the header:
SIMPLE = T / file does conform to FITS standard
BITPIX = 32 / number of bits per data pixel
NAXIS = 2 / number of data axes
NAXIS1 = 128 / length of data axis 1
NAXIS2 = 128 / length of data axis 2
EXTEND = T / FITS dataset may contain extensions
COMMENT FITS (Flexible Image Transport System) format is defined in 'Astronomy
COMMENT and Astrophysics', volume 376, page 359; bibcode: 2001A&A...376..359H
HDUNAME = 'MY_IMAGE'
USERNAME= 'John Doe'
HISTORY This is a history record
HISTORY This is another
COMMENT This is a comment
COMMENT And this is another
This function provides no mechanism to mix comments and keyword records. As the example shows, this function places the comment and history records at the end of the table.
Write the image data to an Image HDU
fits_write_img (Fits_File_Type fptr, Any_Type data)
This function writes the image data out to current HDU, assumed to be an Image HDU.
Create a new-ndimensional linear WCS
wcs = fitswcs_new (Int_Type naxis)
This function returns a new WCS structure of the specified dimensionality that represents an identity (linear) transformation.
fitswcs_get_img_wcs,
fitswcs_get_column_wcs,
fitswcs_get_vector_wcs
Form a new wcs from one or more axes of another
new_wcs = fitswcs_slice (wcs, dims)
This function may be used to construct a new wcs from another by rearranging
its axes or by using a subset of them. The dims
argument specifies
the dimensions to use.
Suppose that wcs
represents a 4 dimensional WCS. Then
wcs2 = fitswcs_slice (wcs, [0,1]);
will result in a 2 dimensional WCS from the first 2 axis of the input WCS.
Similarly,
wcs2 = fitswcs_slice (wcs, [1,0]);
will produce a 2d WCS with the first two axes swapped.
fitswcs_get_img_wcs,
fitswcs_get_column_wcs,
fitswcs_get_vector_wcs
Read a WCS for a FITS image
wcs = fitswcs_get_img_wcs (fp [,alt])
The fitswcs_get_img_wcs
returns a structure representing a WCS from
the specified file descriptor fp
corresponding to an image HDU.
An optional parameter may be used to specified an alternate WCS.
wcs = fitswcs_get_img_wcs ("img.fits[IMAGE]", 'P');
fitswcs_put_img_wcs,
fitswcs_get_column_wcs,
fitswcs_get_vector_wcs
Get the WCS attached to one or more columns of a binary table
fitswcs_get_column_wcs (fp, columns-array [,alt]
This function may be used to obtain the WCS associated with one or more
columns of a binary table. The file descriptor fp
must specify
a binary table. The columns-array
parameter should be an array
of columns names. The third parameter is optional and is used to specify
an alternate WCS.
wcs = fitswcs_get_column_wcs ("evt1.fits[EVENTS]", ["X","Y"]);
fitswcs_put_column_wcs,
fitswcs_get_img_wcs,
fitswcs_get_vector_wcs
Get the WCS of an image in a specified table cell
wcs = fitswcs_get_vector_wcs (fp, column_name, row [,alt])
This function reads the WCS of an image in a specified cell of a binary
table given by fp
parameter. The second and third parameters specify
the column name and row number of the cell. An optional fourth parameter
may be used to obtain the corresponding alternate WCS.
This example reads the WCS associated with the image in the second row of the QEU column of the binary table with HDUNAME equal to AXAF_QEU1 in the file "HRCQEU.fits":
wcs = fitswcs_get_vector_wcs ("HRCQEU.fits[AXAF_QEU1], "QEU", 2);
The current implementation does not yet support references to the WCS of other cells.
Create a linear WCS for an image
wcs = fitswcs_new_img_wcs (grid0,grid1,...)
This function may be used to construct a linear WCS for an image with the specified grids. The grids are assumed to be linear.
Use the histogram module's hist2d function to create an image from the X and Y columns in a file, and the construct a corresponding WCS:
(x,y) = fits_read_col ("table.fits", "X", "Y");
gridx = [min(x):max(x):0.5];
gridy = [min(y):max(y):0.5];
img = hist2d (y,x,gridy,gridx);
wcs = fitswcs_new_img_wcs (gridy, gridx);
Write a WCS out to an image header
fitswcs_put_img_wcs (fp, wcs [,alt])
The fitswcs_put_img_wcs
may be used to write the specified wcs
out to the image HDU specified by the fp
parameter. An optional
third parameter may be used to specify an alternate WCS.
fp = fits_open_file ("img.fits", "w");
.
.
.
fits_put_img_wcs (fp, wcs, 'P');
fits_close_file (fp);
Write the WCS attached to one or more table columns
fitswcs_put_column_wcs (fp, wcs, columns-array [,alt])
This function may be used to attach a WCS to one or more columns of a binary
table. The dimensionality of the specified WCS must match the length of the
array specifying the column names. The first parameter, fp
must specify
a binary table extension. The fourth parameter is optional and may be used
to specify an alternate WCS.
fitswcs_put_column_wcs ("evt2.fits[EVENTS], wcs, ["X","Y"]);
fitswcs_get_column_wcs,
fitswcs_put_img_wcs,
fitswcs_get_img_wcs
Apply a linear transformation to a WCS
wcs1 = fitswcs_linear_transform_wcs (wcs, U0, A, X0)
wcs: The specified WCS to transform
U0,X0: 1-d arrays
A: 2-d array (or 1-d array representing a diagonal matrix)
This function may be used to create a new WCS by applying a linear
transformation to an existing one. This is useful when one
has a WCS associated with physical coordinates X
, and then
applies the linear transformation
U = U0 + A#(X-X0)
to the coordinates X. Then corresponding WCS for the resulting image is
given by
new_wcs = fitswcs_linear_transform_wcs (wcs, U0, A, X0);
The dimensionality of the WCS is limited to 2 in the current implementation.
This function may be used to obtain the wcs for a rebinned image
wcs1 = fitswcs_rebin_wcs (wcs, old_dims, new_dims...)
This function may be used to construct the WCS for a rebinned image from the WCS of of the unbinned image. The grid parameters specify the linear grids the new image.
new_img = hist2d_rebin (new_yrid, new_xgrid, old_ygrid, old_xgrid, old_img); new_wcs = fitswcs_rebin_wcs (old_wcs, array_shape(old_img), array_shape(new_img));
fitswcs_bin_wcs,
fitswcs_linear_transform_wcs,
fitswcs_slice
This function may be used to obtain the wcs for a rebinned image
wcs1 = fitswcs_rebin_wcs (wcs, grid0, grid1, ...)
This function may be used to construct the WCS for an image created
by binning a set of coordinates from, e.g., a pixel-list. The
wcs
parameter represents the wcs attached to the unbinnned
coordinates. The grid parameters specify the linear grids that were
used to create the image.
fitswcs_rebin_wcs,
fitswcs_linear_transform_wcs,
fitswcs_slice