Image · CFITSIO.jl

Image HDU Routines

CFITSIO.fits_get_img_dim — Function

fits_get_img_dim(f::FITSFile)

Return the number of dimensions in the current image HDU.

Example

julia> fname = joinpath(mktempdir(), "test.fits");

julia> f = fits_create_file(fname);

julia> fits_create_img(f, Int64, (2,2))

julia> fits_get_img_dim(f)
2

julia> close(f)

source

CFITSIO.fits_get_img_size — Function

fits_get_img_size(f::FITSFile)

Return the size along each dimension in the current Image HDU.

Example

julia> fname = joinpath(mktempdir(), "test.fits");

julia> f = fits_create_file(fname);

julia> fits_create_img(f, Int64, (2,2))

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

julia> fits_get_img_size(f, Val(2))
(2, 2)

julia> close(f)

source

CFITSIO.fits_get_img_type — Function

fits_get_img_type(f::FITSFile)

Return the datatype (bitpix) of the current image HDU. This may be converted to a Julia type by using the function type_from_bitpix.

Example

julia> fname = joinpath(mktempdir(), "test.fits");

julia> f = fits_create_file(fname);

julia> fits_create_img(f, Int64, (2,2))

julia> fits_get_img_type(f)
64

julia> type_from_bitpix(fits_get_img_type(f))
Int64

julia> close(f)

source

CFITSIO.fits_get_img_param — Function

fits_get_img_param(f::FITSFile)

Return the bitpix, number of dimensions and the size along each dimension of the current image HDU.

Example

julia> fname = joinpath(mktempdir(), "test.fits");

julia> f = fits_create_file(fname);

julia> fits_create_img(f, Int64, (2,2))

julia> fits_get_img_param(f)
(64, 2, [2, 2])

julia> close(f)

source

CFITSIO.fits_create_img — Function

fits_create_img(f::FITSFile, T::Type, naxes::Union{Vector{<:Integer}, Tuple{Vararg{Integer}}})

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

Example

julia> fname = joinpath(mktempdir(), "test.fits");

julia> f = fits_create_file(fname);

julia> fits_create_img(f, Int64, [2, 2])

julia> fits_get_img_dim(f)
2

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

julia> fits_get_img_type(f)
64

julia> type_from_bitpix(fits_get_img_type(f))
Int64

julia> fits_create_img(f, Int64, (1, 3, 2))

julia> fits_get_img_dim(f)
3

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

julia> close(f)

source

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.

Example

julia> fname = joinpath(mktempdir(), "test.fits");

julia> f = fits_create_file(fname);

julia> a = rand(2, 2);

julia> fits_create_img(f, a)

julia> fits_get_img_dim(f)
2

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

julia> type_from_bitpix(fits_get_img_type(f))
Float64

julia> close(f)

source

CFITSIO.fits_create_empty_img — Function

fits_create_empty_img(f::FITSFile)

Create an empty image HDU with no dimensions, and of type Int. See fits_create_img.

Example

julia> fname = joinpath(mktempdir(), "test.fits");

julia> f = fits_create_file(fname);

julia> fits_create_empty_img(f)

julia> fits_get_img_dim(f)
0

julia> fits_get_img_size(f)
Int64[]

julia> close(f)

source

CFITSIO.fits_insert_img — Function

fits_insert_img(f::FITSFile, T::Type,
                naxes::Union{Vector{<:Integer}, Tuple{Vararg{Integer}}}; prepend_primary::Bool = false)

Insert a new image extension immediately following the current HDU (CHDU), or insert a new primary array at the beginning of the file.

A new primary array may be inserted at the beginning of the FITS file by calling fits_insert_img with prepend_primary set to true. In this case, the existing primary HDU is converted to an image extension, and the new primary array will become the CHDU.

The inserted array has an eltype T and size naxes.

fits_insert_img(f::FITSFile, a::AbstractArray{<:Real}; prepend_primary::Bool = false)

Insert a new image HDU with an element type of eltype(a) and a size of size(a) that is capable of storing the array a. The flag prepend_primary may be specified to insert a new primary array at the beginning of the FITS file.

Example

julia> fname = joinpath(mktempdir(), "test.fits");

julia> f = fits_create_file(fname);

julia> fits_insert_img(f, Int64, [2, 2])

julia> fits_get_img_dim(f)
2

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

julia> type_from_bitpix(fits_get_img_type(f))
Int64

julia> fits_insert_img(f, Float64, (3, 4, 5), prepend_primary=true)

julia> fits_get_img_dim(f)
3

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

julia> type_from_bitpix(fits_get_img_type(f))
Float64

julia> fits_get_hdu_num(f)
1

julia> a = rand(2, 2);

julia> fits_insert_img(f, a)

julia> fits_get_img_dim(f)
2

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

julia> type_from_bitpix(fits_get_img_type(f))
Float64

julia> fits_get_hdu_num(f)
2

julia> fits_get_num_hdus(f)
3

julia> close(f)

source

CFITSIO.fits_write_pix — Function

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.

The arguments fpixel and nelements are optional, and are necessary if only a section of the array is to be written out. If these are not provided, the entire data array is written to the FITS file.

Note

The HDU must have been created previously, and its length must match the number of elements being written.

Note

data needs to be stored contiguously in memory.

Example

julia> fname = joinpath(mktempdir(), "test.fits");

julia> f = fits_create_file(fname);

julia> fits_create_img(f, Int64, (2,))

julia> A = [1 3; 2 4]
2×2 Matrix{Int64}:
 1  3
 2  4

julia> fits_write_pix(f, first.(axes(A)), 2, A) # write the first two elements from A

julia> B = similar(A, 2);

julia> fits_read_pix(f, B);

julia> B
2-element Vector{Int64}:
 1
 2

julia> fits_create_img(f, Float64, size(A))

julia> fits_write_pix(f, A) # write the entire array, implicitly casting to Float64

julia> Bf = similar(A, Float64);

julia> fits_read_pix(f, Bf);

julia> Bf
2×2 Matrix{Float64}:
 1.0  3.0
 2.0  4.0

julia> close(f)

source

CFITSIO.fits_write_pixnull — Function

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.

For integer FITS arrays, the FITS null value is defined by the BLANK keyword (an error is returned if the BLANK keyword doesn’t exist). For floating point FITS arrays, NaN of the appropriate type will be written into the FITS file.

Note

The HDU must have been created previously, and its size must match the number of elements being written.

Note

data needs to be stored contiguously in memory.

Example

julia> fname = joinpath(mktempdir(), "test.fits");

julia> f = fits_create_file(fname);

julia> fits_create_img(f, Int64, (2, 2));

julia> fits_write_key(f, "BLANK", 0, "Null value for integer arrays");

julia> fits_write_pixnull(f, [1, 1], 4, [1 3; 2 4], 3);

julia> B = zeros(Int64, 2, 2);

julia> fits_read_pix(f, B);

julia> B
2×2 Matrix{Int64}:
 1  0
 2  4

julia> fits_create_img(f, Float64, (2, 2));

julia> fits_write_pixnull(f, [1.0 3.0; 2.0 4.0], 1.0);

julia> Bf = zeros(Float64, 2, 2);

julia> fits_read_pix(f, Bf);

julia> Bf
2×2 Matrix{Float64}:
 NaN    3.0
   2.0  4.0

julia> close(f);

source

CFITSIO.fits_write_subset — Function

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 HDU must have been created previously, and its size must match the number of elements being written.

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.

Example

julia> fname = joinpath(mktempdir(), "test.fits");

julia> f = fits_create_file(fname);

julia> fits_create_img(f, Int64, (3, 2))

julia> A = reshape([1:9;], 3, 3)
3×3 Matrix{Int64}:
 1  4  7
 2  5  8
 3  6  9

julia> fits_write_subset(f, [1, 1], [3, 2], A)

julia> B = zeros(Int64, 3, 2);

julia> fits_read_pix(f, B);

julia> B
3×2 Matrix{Int64}:
 1  4
 2  5
 3  6

julia> close(f)

source

CFITSIO.fits_read_pix — Function

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.

Example

julia> fname = joinpath(mktempdir(), "test.fits");

julia> f = fits_create_file(fname);

julia> fits_create_img(f, Int64, (2, 2))

julia> fits_write_pix(f, [1 3; 2 4])

julia> B = zeros(Int64, 2, 2);

julia> fits_read_pix(f, [1, 1], 4, B);

julia> B
2×2 Matrix{Int64}:
 1  3
 2  4

julia> fits_create_img(f, Float64, (2, 2))

julia> fits_write_pix(f, [1.0 3.0; NaN 4.0])

julia> Bf = zeros(Float64, 2, 2);

julia> fits_read_pix(f, [1, 1], 4, 2.0, Bf); # replace NaN with 2.0

julia> Bf
2×2 Matrix{Float64}:
 1.0  3.0
 2.0  4.0

julia> close(f)

source

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.

Example

julia> fname = joinpath(mktempdir(), "test.fits");

julia> f = fits_create_file(fname);

julia> fits_create_img(f, Int64, (2, 2))

julia> A = [1 3; 2 4]
2×2 Matrix{Int64}:
 1  3
 2  4

julia> fits_write_pix(f, A)

julia> B = similar(A);

julia> fits_read_pix(f, B);

julia> B
2×2 Matrix{Int64}:
 1  3
 2  4

julia> close(f)

See also: fits_read_pix

source

CFITSIO.fits_read_imghdr — Function

fits_read_imghdr(f::FITSFile, maxdim::Integer = 99)

Read the header of an image HDU, where maxdim represents the maximum number of dimensions to read. By default, maxdim == 99 will read the size along every dimension of the image. The function returns the values of SIMPLE::Bool, BITPIX::Int, NAXIS::Int, NAXES::Vector{Int}, PCOUNT::Int, GCOUNT::Int, and EXTEND::Bool. The length of NAXES is set equal to min(NAXIS, maxdim).

The BITPIX value indicates the data type of the image, and it may be converted to a Julia type using the type_from_bitpix function.

Note

PCOUNT is typically 0 for image HDUs, and GCOUNT is typically 1 for modern files.

Example

julia> fname = joinpath(mktempdir(), "test.fits");

julia> f = fits_create_file(fname);

julia> fits_create_img(f, Int32, (100, 200))

julia> fits_read_imghdr(f)
(true, 32, 2, [100, 200], 0, 1, true)

julia> close(f)

source

CFITSIO.fits_copy_image_section — Function

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.

Example

julia> fin_name = joinpath(mktempdir(), "test_in.fits");

julia> fout_name = joinpath(mktempdir(), "test_out.fits");

julia> fin = fits_create_file(fin_name);

julia> fout = fits_create_file(fout_name);

julia> A = reshape([1:16;], 4, 4)
4×4 Matrix{Int64}:
 1  5   9  13
 2  6  10  14
 3  7  11  15
 4  8  12  16

julia> fits_create_img(fin, A)

julia> fits_write_pix(fin, A)

julia> fits_copy_image_section(fin, fout, "1:2,1:3");

julia> B = zeros(Int64, 2, 3);

julia> fits_read_pix(fout, B);

julia> B
2×3 Matrix{Int64}:
 1  5   9
 2  6  10

julia> foreach(close, (fin, fout));

source

CFITSIO.fits_write_null_img — Function

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. For Integer arrays, the BLANK keyword sets the null value, while for Float64 arrays, the NAN value is used.

Example

julia> fname = joinpath(mktempdir(), "test.fits");

julia> f = fits_create_file(fname);

julia> A = Float64[1 2; 3 4]
2×2 Matrix{Float64}:
 1.0  2.0
 3.0  4.0

julia> fits_create_img(f, A)

julia> fits_write_pix(f, A)

julia> fits_write_null_img(f, 1, 2)

julia> B = zeros(Float64, 2, 2);

julia> fits_read_pix(f, B);

julia> B
2×2 Matrix{Float64}:
 NaN  2.0
 NaN  4.0

julia> fits_write_pix(f, A) # reset the image

julia> fits_write_null_img(f, 3, 2) # set the last two pixels to null

julia> fits_read_pix(f, B);

julia> B
2×2 Matrix{Float64}:
 1.0  NaN
 3.0  NaN

julia> close(f)

source

CFITSIO.fits_resize_img — Function

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.

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

source

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

source

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

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

source

CFITSIO.fits_get_img_equivtype — Function

fits_get_img_equivtype(f::FITSFile)

Return the equivalent datatype (bitpix) of the current image HDU. This is the same as fits_get_img_type except that it returns the bitpix value for the equivalent type, which is the type that would be used if the image were to be read as an array. The equivalent type is determined by the BSCALE and BZERO keywords in the header. If the image is not scaled, the equivalent type is the same as the type returned by fits_get_img_type.

Example

julia> fname = joinpath(mktempdir(), "test.fits");

julia> f = fits_create_file(fname);

julia> fits_create_img(f, Int16, (2,2))

julia> fits_write_key(f, "BSCALE", 0.1, "Scale factor for the image")

julia> fits_write_key(f, "BZERO", 0.0, "Zero point for the image")

julia> fits_get_img_equivtype(f)
-32

julia> type_from_bitpix(fits_get_img_equivtype(f))
Float32

julia> fits_get_img_type(f)
16

julia> type_from_bitpix(fits_get_img_type(f))
Int16

julia> close(f)

source