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.

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}
CFITSIO.bitpix_from_typeFunction
bitpix_from_type(::Type) -> Cint

Return the FITS BITPIX code for the given Julia type

CFITSIO.cfitsio_typecodeFunction
cfitsio_typecode(::Type) -> Cint

Return the CFITSIO type code for the given Julia type

File access

CFITSIO.fits_create_diskfileFunction
fits_create_diskfile(filename::AbstractString)

Create and open a new empty output FITSFile. Unlike fits_create_file, this function does not use an extended filename parser and treats the string as is as the filename.

CFITSIO.fits_open_fileFunction
fits_open_file(filename::String, [mode = 0])

Open an existing data file.

Modes:

  • 0 : Read only (equivalently denoted by CFITSIO.R)
  • 1 : Read-write (equivalently denoted by CFITSIO.RW)

This function uses the extended filename syntax to open the file. See also fits_open_diskfile that does not use the extended filename parser and uses filename as is as the name of the file.

CFITSIO.fits_open_diskfileFunction
fits_open_diskfile(filename::String, [mode = 0])

Open an existing data file.

Modes:

  • 0 : Read only (equivalently denoted by CFITSIO.R)
  • 1 : Read-write (equivalently denoted by CFITSIO.RW)

This function does not use the extended filename parser, and uses filename as is as the name of the file that is to be opened. See also fits_open_file which uses the extended filename syntax.

CFITSIO.fits_open_tableFunction
fits_open_table(filename::String, [mode = 0])

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

Modes:

  • 0 : Read only (equivalently denoted by CFITSIO.R)
  • 1 : Read-write (equivalently denoted by CFITSIO.RW)
CFITSIO.fits_open_imageFunction
fits_open_image(filename::String, [mode = 0])

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

Modes:

  • 0 : Read only (equivalently denoted by CFITSIO.R)
  • 1 : Read-write (equivalently denoted by CFITSIO.RW)
CFITSIO.fits_open_dataFunction
fits_open_data(filename::String, [mode = 0])

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

Modes:

  • 0 : Read only (equivalently denoted by CFITSIO.R)
  • 1 : Read-write (equivalently denoted by CFITSIO.RW)
CFITSIO.fits_file_nameFunction
fits_file_name(f::FITSFile)

Return the name of the file associated with object f.

CFITSIO.fits_file_modeFunction
fits_file_mode(f::FITSFile)

Return the I/O mode of the FITS file, where 0 indicates a read-only mode and 1 indicates a read-write mode.

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.

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.

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.

CFITSIO.fits_delete_hduFunction
fits_delete_hdu(f::FITSFile)

Delete the HDU from the FITS file and shift the following HDUs forward. If f is the primary HDU in the file then it'll be replaced by a null primary HDU with no data and minimal header information.

Return a symbol to indicate the type of the new current 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.

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.

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.

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.

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.

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.

CFITSIO.fits_write_recordFunction
fits_write_record(f::FITSFile, card::String)

Write a user specified keyword record into the CHU.

CFITSIO.fits_delete_recordFunction
fits_delete_record(f::FITSFile, keynum::Int)

Delete the keyword record at the specified index.

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.

Image HDU Routines

CFITSIO.fits_create_imgFunction
fits_create_img(f::FITSFile, T::Type, naxes::Vector{<:Integer})

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

fits_create_img(f::FITSFile, A::AbstractArray)

Create a new primary array or IMAGE extension with the element type and size of A, that is capable of storing the entire array A.

CFITSIO.fits_insert_imgFunction
fits_insert_img(f::FITSFile, T::Type, naxes::Union{Vector{<:Integer}, Tuple{Vararg{Integer}}})

Insert a new image extension immediately following the CHDU, or insert a new Primary Array at the beginning of the file.

CFITSIO.fits_write_pixFunction
fits_write_pix(f::FITSFile, fpixel::Union{Vector{<:Integer}, Tuple{Vararg{Integer}}}, nelements::Integer, data::StridedArray)

Write nelements pixels from data into the FITS file starting from the pixel fpixel.

Note

data needs to be stored contiguously in memory.

See also: fits_write_pixnull

fits_write_pix(f::FITSFile, data::StridedArray)

Write the entire array data into the FITS file.

Note

data needs to be stored contiguously in memory.

See also: fits_write_pixnull, fits_write_subset

CFITSIO.fits_write_pixnullFunction
fits_write_pixnull(f::FITSFile, fpixel::Union{Vector{<:Integer}, Tuple{Vararg{Integer}}}, nelements::Integer, data::StridedArray, nulval)

Write nelements pixels from data into the FITS file starting from the pixel fpixel. The argument nulval specifies the values that are to be considered as "null values", and replaced by appropriate numbers corresponding to the element type of data.

Note

data needs to be stored contiguously in memory.

See also: fits_write_pix

fits_write_pixnull(f::FITSFile, data::StridedArray, nulval)

Write the entire array data into the FITS file. The argument nulval specifies the values that are to be considered as "null values", and replaced by appropriate numbers corresponding to the element type of data.

Note

data needs to be stored contiguously in memory.

See also: fits_write_pix

CFITSIO.fits_write_subsetFunction
fits_write_subset(f::FITSFile, fpixel::V, lpixel::V, data::StridedArray) where {V<:Union{Vector{<:Integer}, Tuple{Vararg{Integer}}}}

Write a rectangular section of the FITS image. The number of pixels to be written will be computed from the first and last pixels (specified as the fpixel and lpixel arguments respectively).

Note

The section to be written out must be contiguous in memory, so all the dimensions aside from the last one must span the entire axis range. The arguments fpixel and lpixel must account for this.

See also: fits_write_pix

CFITSIO.fits_read_pixFunction
fits_read_pix(f::FITSFile, fpixel::NTuple{Vector{<:Integer}, Tuple{Vararg{Integer}}}, nelements::Integer, [nulval], data::StridedArray)

Read nelements pixels from the FITS file into data starting from the pixel fpixel. If the optional argument nulval is specified and is non-zero, any null value present in the array will be replaced by it.

Note

data needs to be stored contiguously in memory.

See also: fits_read_pixnull, fits_read_subset

fits_read_pix(f::FITSFile, data::StridedArray, [nulval])

Read length(data) pixels from the FITS file into data starting from the first pixel. The optional argument nulval, if specified and non-zero, is used to replace any null value present in the array.

Note

data needs to be stored contiguously in memory.

See also: fits_read_pixnull

CFITSIO.fits_read_pixnullFunction
fits_read_pixnull(f::FITSFile, fpixel::Union{Vector{<:Integer}, Tuple{Vararg{Integer}}}, nelements::Integer, data::StridedArray, nullarray::Array{UInt8})

Read nelements pixels from the FITS file into data starting from the pixel fpixel. At output, the indices of nullarray where data has a corresponding null value are set to 1.

Note

data needs to be stored contiguously in memory.

See also: fits_read_pix

fits_read_pixnull(f::FITSFile, data::StridedArray, nullarray::Array{UInt8})

Read length(data) pixels from the FITS file into data starting from the first pixel. At output, the indices of nullarray where data has a corresponding null value are set to 1.

Note

data needs to be stored contiguously in memory.

See also: fits_read_pix

CFITSIO.fits_read_subsetFunction
fits_read_subset(f::FITSFile, fpixel::V, lpixel::V, inc::V, [nulval], data::StridedArray) where {V<:Union{Vector{<:Integer}, Tuple{Vararg{Integer}}}}

Read a rectangular section of the FITS image. The number of pixels to be read will be computed from the first and last pixels (specified as the fpixel and lpixel arguments respectively). The argument inc specifies the step-size in pixels along each dimension.

If the optional argument nulval is specified and is non-zero, null values in data will be replaced by it.

Note

data needs to be stored contiguously in memory, and will be populated contiguously with the pixels that are read in.

See also: fits_read_pix

CFITSIO.fits_copy_image_sectionFunction
fits_copy_image_section(fin::FITSFile, fout::FITSFile, section::String)

Copy a rectangular section of an image from fin and write it to a new FITS primary image or image extension in fout. The section specifier is described on the CFITSIO website.

CFITSIO.fits_write_null_imgFunction
fits_write_null_img(f::FITSFile, firstelem::Integer, nelements::Integer)

Set a stretch of elements to the appropriate null value, starting from the pixel number firstelem and extending over nelements pixels.

CFITSIO.fits_resize_imgFunction
fits_resize_img(f::FITSFile, T::Type, naxis::Integer, sz::Union{Vector{<:Integer}, Tuple{Vararg{Integer}}})

Modify the size, dimensions and optionally the element type of the image in f. The new image will have an element type T, be a naxis-dimensional image with size sz. If the new image is larger than the existing one, it will be zero-padded at the end. If the new image is smaller, existing image data will be truncated.

fits_resize_img(f::FITSFile, sz::Union{Vector{<:Integer}, Tuple{Vararg{Integer}}})

Resize the image to the new size sz. The element type is preserved, and the number of dimensions is set equal to length(sz).

fits_resize_img(f::FITSFile, T::Type)

Change the element type of the image to T, leaving the size unchanged.

Note

This method reinterprets the data instead of coercing the elements.

Example

julia> f = fits_clobber_file(tempname());

julia> a = [1 2; 3 4];

julia> fits_create_img(f, a);

julia> fits_write_pix(f, a);

julia> fits_get_img_size(f)
2-element Vector{Int64}:
 2
 2

julia> fits_resize_img(f, [3,3]);

julia> fits_get_img_size(f)
2-element Vector{Int64}:
 3
 3

julia> b = similar(a, (3,3));

julia> fits_read_pix(f, b); b
3×3 Matrix{Int64}:
 1  4  0
 3  0  0
 2  0  0

julia> fits_resize_img(f, [4]);

julia> b = similar(a, (4,));

julia> fits_read_pix(f, b); b
4-element Vector{Int64}:
 1
 3
 2
 4

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

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

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

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.

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.

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.

Miscellaneous

CFITSIO.libcfitsio_versionFunction
libcfitsio_version() -> VersionNumber

Return the version of the underlying CFITSIO library

Example

julia> libcfitsio_version()
v"3.37.0"