Libcfitsio submodule

The Libcfitsio submodule provides an interface familiar to users of the CFITSIO C library. It can be used with

using FITSIO.Libcfitsio

The functions exported by this module operate on FITSFile objects, which is a thin wrapper around a pointer to a CFITSIO fitsfile. For the most part, the functions are thin wrappers around the CFITSIO routines of the same names. Typically, they:

Convert from Julia types to C types as necessary.
Check the returned status value and raise an appropriate exception if non-zero.

Warning

Note that these functions do not check if the file is still open before trying to access it. A segmentation fault can result from trying to operate on a closed file. (The main FITSIO interface always checks if the file is open before any operation.)

File access

FITSIO.Libcfitsio.fits_create_file — Function.

fits_create_file(filename::AbstractString)

Create and open a new empty output FITSFile.

FITSIO.Libcfitsio.fits_clobber_file — Function.

fits_clobber_file(filename::AbstractString)

Like fits_create_file, but overwrites filename if it exists.

FITSIO.Libcfitsio.fits_open_file — Function.

fits_open_file(filename::String)

Open an existing data file.

FITSIO.Libcfitsio.fits_open_table — Function.

fits_open_table(filename::String)

Open an existing data file (like fits_open_file) and move to the first HDU containing either an ASCII or a binary table.

FITSIO.Libcfitsio.fits_open_image — Function.

fits_open_image(filename::String)

Open an existing data file (like fits_open_file) and move to the first HDU containing an image.

FITSIO.Libcfitsio.fits_open_data — Function.

fits_open_data(filename::String)

Open an existing data file (like fits_open_file) and move to the first HDU containing either an image or a table.

FITSIO.Libcfitsio.fits_close_file — Function.

fits_close_file(f::FITSFile)

Close a previously opened FITS file.

FITSIO.Libcfitsio.fits_delete_file — Function.

fits_delete_file(f::FITSFile)

Close an opened FITS file (like fits_close_file) and removes it from the disk.

FITSIO.Libcfitsio.fits_file_name — Function.

fits_file_name(f::FITSFile)

Return the name of the file associated with object f.

HDU Routines

The functions described in this section change the current HDU and to find their number and type. The following is a short example which shows how to use them:

num = fits_get_num_hdus(f)
println("Number of HDUs in the file: ", num)

for i = 1:num
    hdu_type = fits_movabs_hdu(f, i)
    println(i, ") hdu_type = ", hdu_type)
end

FITSIO.Libcfitsio.fits_get_num_hdus — Function.

fits_get_num_hdus(f::FITSFile)

Return the number of HDUs in the file.

FITSIO.Libcfitsio.fits_movabs_hdu — Function.

fits_movabs_hdu(f::FITSFile, hduNum::Integer)

Change the current HDU to the value specified by hduNum, and return a symbol describing the type of the HDU.

Possible symbols are: image_hdu, ascii_table, or binary_table. The value of hduNum must range between 1 and the value returned by fits_get_num_hdus.

FITSIO.Libcfitsio.fits_movrel_hdu — Function.

fits_movrel_hdu(f::FITSFile, hduNum::Integer)

Change the current HDU by moving forward or backward by hduNum HDUs (positive means forward), and return the same as fits_movabs_hdu.

FITSIO.Libcfitsio.fits_movnam_hdu — Function.

fits_movnam_hdu(f::FITSFile, extname::String, extver::Integer=0,
                hdu_type_int::Integer=-1)

Change the current HDU by moving to the (first) HDU which has the specified extension type and EXTNAME and EXTVER keyword values (or HDUNAME and HDUVER keywords).

If extver is 0 (the default) then the EXTVER keyword is ignored and the first HDU with a matching EXTNAME (or HDUNAME) keyword will be found. If hdu_type_int is -1 (the default) only the extname and extver values will be used to locate the correct extension. If no matching HDU is found in the file, the current HDU will remain unchanged.

Header Keyword Routines

FITSIO.Libcfitsio.fits_get_hdrspace — Function.

fits_get_hdrspace(f::FITSFile) -> (keysexist, morekeys)

Return the number of existing keywords (not counting the END keyword) and the amount of space currently available for more keywords.

FITSIO.Libcfitsio.fits_read_keyword — Function.

fits_read_keyword(f::FITSFile, keyname::String) -> (value, comment)

yields the specified keyword value and commend (as a tuple of strings), throws and error if the keyword is not found.

FITSIO.Libcfitsio.fits_read_record — Function.

fits_read_record(f::FITSFile, keynum::Int) -> String

Return the nth header record in the CHU. The first keyword in the header is at keynum = 1.

FITSIO.Libcfitsio.fits_read_keyn — Function.

fits_read_keyn(f::FITSFile, keynum::Int) -> (name, value, comment)

Return the nth header record in the CHU. The first keyword in the header is at keynum = 1.

FITSIO.Libcfitsio.fits_write_key — Function.

fits_write_key(f::FITSFile, keyname::String, value, comment::String)

Write a keyword of the appropriate data type into the CHU.

FITSIO.Libcfitsio.fits_write_record — Function.

fits_write_record(f::FITSFile, card::String)

Write a user specified keyword record into the CHU.

FITSIO.Libcfitsio.fits_delete_record — Function.

fits_delete_record(f::FITSFile, keynum::Int)

Delete the keyword record at the specified index.

FITSIO.Libcfitsio.fits_delete_key — Function.

fits_delete_key(f::FITSFile, keyname::String)

Delete the keyword named keyname.

FITSIO.Libcfitsio.fits_hdr2str — Function.

fits_hdr2str(f::FITSFile, nocomments::Bool=false)

Return the header of the CHDU as a string. If nocomments is true, comment cards are stripped from the output.

Image HDU Routines

FITSIO.Libcfitsio.fits_get_img_size — Function.

fits_get_img_size(f::FITSFile)

Get the dimensions of the image.

FITSIO.Libcfitsio.fits_create_img — Function.

fits_create_img(f::FITSFile, t::Type, naxes::Vector{Int})

Create a new primary array or IMAGE extension with a specified data type and size.

FITSIO.Libcfitsio.fits_write_pix — Function.

fits_write_pix(f::FITSFile, fpixel::Vector{Int}, nelements::Int, data::Array)

Write pixels from data into the FITS file.

FITSIO.Libcfitsio.fits_read_pix — Function.

fits_read_pix(f::FITSFile, fpixel::Vector{Int}, nelements::Int, data::Array)

Read pixels from the FITS file into data.

Table Routines

There are two functions to create a new HDU table extension: fits_create_ascii_table and fits_create_binary_table. In general, one should pick the second as binary tables require less space on the disk and are more efficient to read and write. (Moreover, a few datatypes are not supported in ASCII tables). In order to create a table, the programmer must specify the characteristics of each column by passing an array of tuples. Here is an example:

f = fits_create_file("!new.fits")
coldefs = [("SPEED", "1D", "m/s"),
           ("MASS", "1E", "kg"),
           ("PARTICLE", "20A", "Name")]
fits_create_binary_tbl(f, 10, coldefs, "PARTICLE")

This example creates a table with room for 10 entries, each of them describing the characteristics of a particle: its speed, its mass, and its name (codified as a 20-character string). See the documentation of fits_create_ascii_tbl for more details.

FITSIO.Libcfitsio.fits_create_ascii_tbl — Function.

fits_create_ascii_tbl(f::FITSFile, numrows::Integer, coldefs::Array{ColumnDef},
                      extname::String)

Append a new HDU containing an ASCII table.

The table will have numrows rows (this parameter can be set to zero), each initialized with the default value. In order to create a table, the programmer must specify the characteristics of each column. The columns are specified by the coldefs variable, which is an array of tuples. Each tuple must have three string fields:

The name of the column.
The data type and the repetition count. It must be a string made by a number (the repetition count) followed by a letter specifying the type (in the example above, D stands for Float64, E stands for Float32, A stands for Char). Refer to the CFITSIO documentation for more information about the syntax of this parameter.
The measure unit of this field. This is used only as a comment.

The value of extname sets the "extended name" of the table, i.e., a string that in some situations can be used to refer to the HDU itself.

Note that, unlike for binary tables, CFITSIO puts some limitations to the types that can be used in an ASCII table column. Refer to the CFITSIO manual for further information.

See also fits_create_binary_tbl for a similar function which creates binary tables.

FITSIO.Libcfitsio.fits_create_binary_tbl — Function.

fits_create_binary_tbl(f::FITSFile, numrows::Integer, coldefs::Array{ColumnDef},
                       extname::String)

Append a new HDU containing a binary table. The meaning of the parameters is the same as in a call to fits_create_ascii_tbl.

In general, one should pick this function for creating tables in a new HDU, as binary tables require less space on the disk and are more efficient to read and write. (Moreover, a few datatypes are not supported in ASCII tables).

FITSIO.Libcfitsio.fits_get_coltype — Function.

fits_get_coltype(f::FITSFile, colnum::Integer)

Provided that the current HDU contains either an ASCII or binary table, return information about the column at position colnum (counting from 1).

Return is a tuple containing

typecode: CFITSIO integer type code of the column.
repcount: Repetition count for the column.
width: Width of an individual element.

FITSIO.Libcfitsio.fits_insert_rows — Function.

fits_insert_rows(f::FITSFile, firstrow::Integer, nrows::Integer)

Insert a number of rows equal to nrows after the row number firstrow.

The elements in each row are initialized to their default value: you can modify them later using fits_write_col.

Since the first row is at position 1, in order to insert rows before the first one firstrow must be equal to zero.

FITSIO.Libcfitsio.fits_delete_rows — Function.

fits_delete_rows(f::FITSFile, firstrow::integer, nrows::Integer)

Delete nrows rows, starting from the one at position firstrow. The index of the first row is 1.

FITSIO.Libcfitsio.fits_read_col — Function.

fits_read_col(f, colnum, firstrow, firstelem, data)

Read data from one column of an ASCII/binary table and convert the data into the specified type T.

Arguments

f::FITSFile: the file to be read.
colnum::Integer: the column number, where the value of the first column is 1.
firstrow::Integer: the elements to be read start from this row.
firstelem::Integer: specifies which is the first element to be read, when each cell contains more than one element (i.e., the "repetition count" of the field is greater than one).
data::Array: at the end of the call, this will be filled with the elements read from the column. The length of the array gives the overall number of elements.

FITSIO.Libcfitsio.fits_write_col — Function.

fits_write_col(f, colnum, firstrow, firstelem, data)

Write some data in one column of a ASCII/binary table.

If there is no room for the elements, new rows will be created. (It is therefore useless to call fits_insert_rows if you only need to append elements to the end of a table.)

f::FITSFile: the file in which data will be written.
colnum::Integer: the column number, where the value of the first column is 1.
firstrow::Integer: the data wil be written from this row onwards.
firstelem::Integer: specifies the position in the row where the first element will be written.
data::Array: contains the elements that are to be written to the column of the table.