Notes for developers

The FITS standard

The FITS format is described in the FITS Standard Document.

The CFITSIO sub-module

EasyFITS makes use of the Clang Julia package to automatically build file deps/deps.jl with constants, types, and low level functions to call the functions of the CFITSIO library with arguments of the correct type. All these are available in the EasyFITS.CFITSIO sub-module.

Calls to functions in the CFITSIO library

When calling functions of the CFITSIO library, there are several things to take care of:

• Passing correct arguments. This is partially ensured by the type assertions in the @ccall macro. It is also necessary to check whether a pointer to some opaque structure in the library is valid.

• Preserving objects from being destroyed while being in use. Of course, this is automatically done by Julia for Julia objects, but must be handled for references or pointers to objects provided by the CFITSIO library.

When an object obj is specified for an argument of type Ptr{T} to be passed to a C function, Julia ccall does something like:

ref = Base.cconvert(Ptr{T}, obj)
ptr = Base.unsafe_convert(Ptr{T}, ref)
result = GC.@preserve ref call_some_c_function(..., ptr, ...)

Here ref is an object (by default, Base.cconvert(Ptr{T},obj) yields obj itself) to be used with Base.unsafe_convert(Ptr{T},ref) to get the pointer and to be preserved from being garbage collected in order to warrant that the pointer remains valid.

Thanks to this mechanism, it is quite simple to ensure that valid pointers to opaque structures of the CFITSIO library be passed to a function of this library. For example, the code below is how is handled a pointer to a fitsfile C structure in our code:

isnull(ptr::Ptr{T}) where {T} = ptr === Ptr{T}(0)
check(ptr::Ptr) = isnull(ptr) ? error("invalid NULL pointer") : ptr
get_handle(file::FitsFile) = getfield(obj, :handle)
get_file(hdu::AbstractHDU) = getfield(hdu, :file)
Base.unsafe_convert(Ptr{CFITSIO.fitsfile}, obj::FitsFile) = check(get_handle(obj))
Base.cconvert(Ptr{CFITSIO.fitsfile}, hdu::AbstractHDU) = get_file(hdu)

Private methods isnull and check are introduced for readability. Private methods get_handle and get_file are two of the private accessors introduced to hide the fields of a FITS file object and let some other public properties be implemented. The former yields the pointer to the fitsfile C structure that is managed by a FitsFile object, while the latter yields the FitsFile object storing the HDU as it is the one that must be used and preserved when calling a C function requiring a pointer to a fitsfile C structure.

Note that FitsFile objects have a finalizer that automatically releases resources such as the associated fitsfile C structure when the object is garbage collected.

Helper functions

The following non-exported functions are provided for meta-programming and for dealing with the types of arguments in calls to the functions of the CFITSIO library.

EasyFITS.cfunc(pfx::Union{AbstractString,Symbol}, T::Type) -> sym

EasyFITS.ctype(T) -> T′

EasyFITS.cpointer(arr::AbstractArray) -> ptr::Ptr{ctype(eltype(arr))}

Pixel types

The following table lists conventions used by CFITSIO for pixel types, that is the BITPIX keyword in FITS image extensions.

Types without a value in the BITPIX column are converted by the CFITSIO library into the other signed/unsigned type using special values of the BSCALE and BZERO keywords to allow for the reciprocal conversion. This is explicitly allowed by the FITS Standard (version 4.0).

The above equivalence rules are implemented by the following two non-exported functions.

EasyFITS.type_to_bitpix(T)

EasyFITS.type_from_bitpix(b) -> T

Array data types

The following table lists conventions used by CFITSIO for array element types.

Complex types float complex and double complex are stored as pairs of single/double precision floating-point values (this is not guaranteed by C99 standard so strict equivalence does not hold here).

The above equivalence rules are implemented by the following two non-exported functions.

EasyFITS.type_to_code(T)

EasyFITS.type_from_code(c) -> T

Column data types

The following table lists the correspondences between the TFORMn letter in FITS table extensions and the column data type.

A few non-standard TFORM letters are allowed by CFITSIO. These are converted by the library into other types using TSCALE and TZERO keywords to allow for the reciprocal conversion following the same principles as for the BITPIX code and the BSCALE and BZERO keywords.

The Type Code column indicates the code used by CFITSIO (it is not always consistent with the C types as defined in the above table, so my guess is that this code is only used to keep track of the column data type internally).

The above equivalence rules are implemented by the following two non-exported functions.

EasyFITS.type_to_letter(T)

EasyFITS.type_from_letter(c) -> T