CFITSIO.jl

bitpix_from_type(::Type) -> Cint

Return the FITS BITPIX code for the given Julia type

type_from_bitpix(::Integer) -> Type

Return the Julia type from the FITS BITPIX code

cfitsio_typecode(::Type) -> Cint

Return the CFITSIO type code for the given Julia type

fits_create_file(filename::AbstractString)

Create and open a new empty output FITSFile. This methods uses the extended file name syntax to create the file.

See also fits_create_diskfile which does not use the extended filename parser.

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.

fits_clobber_file(filename::AbstractString)

Like fits_create_file, but overwrites filename if it exists.

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.

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.

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)

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)

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)

fits_close_file(f::FITSFile)

Close a previously opened FITS file.

fits_delete_file(f::FITSFile)

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

fits_file_name(f::FITSFile)

Return the name of the file associated with object f.

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.

fits_get_num_hdus(f::FITSFile)

Return the number of HDUs in the file.

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.

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.

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.

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.

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.

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.

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.

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.

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

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

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

Write a user specified keyword record into the CHU.

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

Delete the keyword record at the specified index.

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

Delete the keyword named keyname.

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.

fits_get_img_size(f::FITSFile)

Get the dimensions of the image.

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.

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.

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.

See also: fits_write_pixnull

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

Write the entire array data into the FITS file.

See also: fits_write_pixnull, fits_write_subset

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.

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.

See also: fits_write_pix

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

See also: fits_write_pix

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.

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.

See also: fits_read_pixnull

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.

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.

See also: fits_read_pix

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.

See also: fits_read_pix

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.

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.

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.

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

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.

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

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.

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.

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.

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.

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.

libcfitsio_version() -> VersionNumber

Return the version of the underlying CFITSIO library

Example

julia> libcfitsio_version()
v"3.37.0"