FITS image extensions

FITS image extensions store multi-dimensional arrays with numerical values exactly as regular Julia arrays. In EasyFITS, a FITS image extension in an open file is represented by an object of type FitsImageDHU{T,N} with T the element type and N the number of dimensions.

Image HDU properties

An image HDU has the following properties:

Reading a FITS image

To read the data stored by the Header Data Unit (HDU) object hdu of type FitsImageDHU HDU as an array arr, call read as:

arr = read(hdu)

The result is of type Array{T,N} if hdu isa FitsImageDHU{T,N} holds. To choose another element type, say, S, just do:

arr = read(Array{S}, hdu)

This is similar but more efficient than any of:

arr = S.(read(hdu))
arr = convert(Array{S}, read(hdu))

For type-stability, the expected number of dimension, say N, may also be specified. For example, any of:

arr = read(Array{Float32,2}, hdu)
arr = read(Matrix{Float32}, hdu)

ensure that arr will be a 2-dimensional image with pixels of type Float32.

Call read! to overwrite the elements of an existing array with the contents of the FITS image extension. For example:

read!(arr, hdu)

An hyper-rectangular sub-image can be read using the same syntax as for a Julia view by specifying indices and/or index ranges after the hdu argument. Index ranges may have non-unit steps but steps must all be positive. For example:

arr = read(hdu, :, :, 2)

yields the 2nd slice in a 3-dimensional FITS image.

The result is similar to:

arr = read(R, hdu)[:,:,2]

but should be more efficient as no array other than the result is allocated and fewer values are read.

Call read! instead of read to overwrite the contents of an existing array. Following the previous example, reading the next slice could be done by:

read!(arr, hdu, :, :, 3)

Creating an image extension

To create a new FITS image extension in an open FITS file, there are several possibilities:

hdu = FitsImageHDU(file, dims...; bitpix=...)
hdu = FitsImageHDU{T}(file, dims...)
hdu = FitsImageHDU{T,N}(file, dims...)

with pixel type specified by its Julia data-type via the parameter T or by its FITS BITPIX code via the keyword bitpix and image size given by dims.... The number of dimensions N can be inferred from the image size but may be explicitly specified for better type-stability.

If the FITS file is currently empty then a primary array is created, otherwise a new image extension is appended to the file.

The returned hdu is an object to manage the new extension is returned which can be used to push header cards and then to write the data.

If the array arr to be written is available, the element type and dimensions can be inferred from arr itself:

hdu = FitsImageHDU(file, arr)
hdu = FitsImageHDU{T}(file, arr)
hdu = FitsImageHDU{T,N}(file, arr)

where T = eltype(arr) and N = ndims(arr) are assumed if these parameters are not explicitly specified. Specifying a different pixel type than eltype(arr) is possible, conversion will automatically be performed when writing the array values.

For example:

hdu = FitsImageHDU(file, arr)
hdu["KEY1"] = val1             # add a 1st header record
hdu["KEY2"] = (val2, str2)     # add a 2nd header record
hdu["KEY3"] = (nothing, str3)  # add a 3rd header record
write(hdu, arr)                # write data

will create a new Header Data Unit (HDU) storing array arr with 3 additional header records: one named "KEY1" with value val1 and no comments, another named "KEY2" with value val2 and comment string str2, and yet another one named "KEY3" with no value and with comment string str3. Note that special names "COMMENT", "HISTORY", and "" indicating commentary entries have no associated, only a comment string, say str which can be specified as str or as (nothing,str).