CFITSIO.jl

GitHub Build Status PkgEval Coverage

This module provides an interface familiar to users of the CFITSIO C library. It can be used with

using CFITSIO

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 following tables give the correspondances between CFITSIO "types", the BITPIX keyword and Julia types.

Type Conversions

CFITSIO Types

CODECFITSIOJulia
intCint
longClong
LONGLONGInt64

FITS BITPIX

CODECFITSIOJulia
8BYTE_IMGUint8
16SHORT_IMGInt16
32LONG_IMGInt32
64LONGLONG_IMGInt64
-32FLOAT_IMGFloat32
-64DOUBLE_IMGFloat64

CFITSIO Aliases

CODECFITSIOJuliaComments
10SBYTE_IMGInt8written as: BITPIX = 8, BSCALE = 1, BZERO = -128
20USHORT_IMGUint16written as: BITPIX = 16, BSCALE = 1, BZERO = 32768
40LONG_IMGUint32written as: BITPIX = 32, BSCALE = 1, BZERO = 2147483648

FITS Table Data Types

CODECFITSIOJulia
1TBIT
11TBYTECuchar, Uint8
12TSBYTECchar, Int8
14TLOGICALBool
16TSTRINGString
20TUSHORTCushort
21TSHORTCshort
30TUINTCuint
31TINTCint
40TULONGCulong
41TLONGClong
42TFLOATCfloat
81TLONGLONGInt64
82TDOUBLECdouble
83TCOMPLEXComplex{Cfloat}
163TDBLCOMPLEXComplex{Cdouble}

File access

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
CFITSIO.fits_movabs_hduFunction
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.

source
CFITSIO.fits_movrel_hduFunction
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.

source
CFITSIO.fits_movnam_hduFunction
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.

source

Header Keyword Routines

CFITSIO.fits_get_hdrspaceFunction
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.

source
CFITSIO.fits_read_keywordFunction
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.

source
CFITSIO.fits_read_recordFunction
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.

source
CFITSIO.fits_read_keynFunction
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.

source
CFITSIO.fits_write_keyFunction
fits_write_key(f::FITSFile, keyname::String, value, comment::String)

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

source
CFITSIO.fits_hdr2strFunction
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.

source

Image HDU Routines

CFITSIO.fits_create_imgFunction
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.

source
CFITSIO.fits_write_pixFunction
fits_write_pix(f::FITSFile, fpixel::Vector{Int}, nelements::Int, data::StridedArray)

Write pixels from data into the FITS file. The data needs to be stored contiguously in memory.

source
CFITSIO.fits_read_pixFunction
fits_read_pix(f::FITSFile, fpixel::Vector{Int}, nelements::Int, data::Array)

Read pixels from the FITS file into data.

source

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.

CFITSIO.fits_create_ascii_tblFunction
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:

  1. The name of the column.
  2. 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.

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

source
CFITSIO.fits_create_binary_tblFunction
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).

source
CFITSIO.fits_get_coltypeFunction
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.
source
CFITSIO.fits_insert_rowsFunction
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.

source
CFITSIO.fits_delete_rowsFunction
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.

source
CFITSIO.fits_read_colFunction
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.

source
CFITSIO.fits_write_colFunction
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.
source

Miscellaneous

CFITSIO.libcfitsio_versionFunction
libcfitsio_version() -> VersionNumber

Return the version of the underlying CFITSIO library

Example

julia> libcfitsio_version()
v"3.37.0"
source