fits_get_num_hdus(f::FITSFile)

Return the number of HDUs in the file.

Example

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

julia> f = fits_create_file(fname);

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

julia> fits_create_binary_tbl(f, 0, [("col1", "1J", "units")]);

julia> close(f)

julia> f = fits_open_file(fname, CFITSIO.READONLY);

julia> fits_get_num_hdus(f)
2

julia> close(f)

fits_get_hdu_num(f::FITSFile)

Return the index of the current HDU in the FITS file. The primary HDU is numbered 1, the first extension HDU is numbered 2, etc.

Example

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

julia> f = fits_create_file(fname);

julia> fits_create_empty_img(f)

julia> fits_create_binary_tbl(f, 0, [("col1", "1J"), ("col2", "1E")])

julia> fits_get_hdu_num(f)
2

julia> fits_movabs_hdu(f, 1) # move to the primary HDU
:image_hdu

julia> fits_get_hdu_num(f)
1

julia> fits_movabs_hdu(f, 2) # move to the binary table HDU
:binary_table

julia> fits_get_hdu_num(f)
2

julia> close(f)

fits_get_hdu_type(f::FITSFile)

Return the type of the current HDU as a symbol. Possible symbols are: :image_hdu, :ascii_table, or :binary_table. If the HDU is not one of these types, it returns :unknown.

Example

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

julia> f = fits_create_file(fname);

julia> fits_create_empty_img(f)

julia> fits_get_hdu_type(f)
:image_hdu

julia> fits_create_binary_tbl(f, 0, [("col1", "1J"), ("col2", "1E")])

julia> fits_get_hdu_type(f)
:binary_table

julia> close(f)

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.

Example

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

julia> f = fits_create_file(fname);

julia> fits_create_empty_img(f)

julia> fits_create_binary_tbl(f, 0, [("col1", "1J"), ("col2", "1E")])

julia> fits_movabs_hdu(f, 2)
:binary_table

julia> fits_movabs_hdu(f, 1)
:image_hdu

julia> close(f)

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.

Example

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

julia> f = fits_create_file(fname);

julia> fits_create_empty_img(f)

julia> fits_create_binary_tbl(f, 0, [("col1", "1J"), ("col2", "1E")])

julia> fits_movabs_hdu(f, 2)
:binary_table

julia> fits_movrel_hdu(f, -1) # move back to the image HDU
:image_hdu

julia> fits_movrel_hdu(f, 1) # move forward to the binary table HDU
:binary_table

julia> close(f)

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.

Example

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

julia> f = fits_create_file(fname);

julia> fits_create_empty_img(f)

julia> fits_write_key(f, "EXTNAME", "MyImage", "Name of the Image")

julia> fits_create_binary_tbl(f, 0, [("col1", "1J"), ("col2", "1E")], "MyTable")

julia> fits_movnam_hdu(f, "MyImage")

julia> fits_get_hdu_type(f), fits_get_hdu_num(f)
(:image_hdu, 1)

julia> fits_movnam_hdu(f, "MyTable")

julia> fits_get_hdu_type(f), fits_get_hdu_num(f)
(:binary_table, 2)

julia> close(f)

fits_copy_file(fin::FITSFile, fout::FITSFile, previous::Bool, current::Bool, following::Bool)

Copy all or a part of the HDUs from the input file fin, and append them to the output file fout. The flags previous, current and following specify which HDUs are to be copied.

• If previous is true, all the HDUs prior to the current input HDU are copied.
• If current is true, the current input HDU is copied.
• If following is true, all the HDUs following the current input HDU are copied.

These flags may be combined, so if all are set to true then all the HDUs are copied from fin to fout.

On exit, the input is unchanged, and the last HDU in the output is set as the current HDU.

Example

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

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

julia> fin = fits_create_file(fname_in);

julia> fits_create_empty_img(fin);

julia> fits_write_key(fin, "KEY1", 1, "First keyword");

julia> fits_create_binary_tbl(fin, 0, [("col1", "1J"), ("col2", "1E")], "MyTable");

julia> fout = fits_create_file(fname_out);

julia> fits_copy_file(fin, fout, true, true, true);

julia> fits_get_hdu_num(fout)
2

julia> fits_get_hdu_type(fout)
:binary_table

julia> fits_movabs_hdu(fout, 1) # move to the primary HDU
:image_hdu

julia> fits_read_key_str(fout, "NAXIS")
("0", "number of data axes")

julia> fits_read_key_str(fout, "KEY1")
("1", "First keyword")

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

fits_copy_hdu(fin::FITSFile, fout::FITSFile, morekeys::Integer = 0)

Copy the current HDU from the input file fin and append it to the output file fout. Space may be reserved for morekeys additional keywords in the output header.

Example

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

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

julia> fin = fits_create_file(fname_in);

julia> fits_create_empty_img(fin)

julia> fits_write_key(fin, "KEY1", 1, "First keyword")

julia> fout = fits_create_file(fname_out);

julia> fits_copy_hdu(fin, fout)

julia> fits_get_hdu_num(fout)
1

julia> fits_get_hdu_type(fout)
:image_hdu

julia> fits_read_key_str(fout, "NAXIS")
("0", "number of data axes")

julia> fits_read_key_str(fout, "KEY1")
("1", "First keyword")

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

fits_copy_data(fin::FITSFile, fout::FITSFile)

Copy the data (not the header) from the current HDU in fin to the current HDU in fout. This will overwrite pre-existing data in the output HDU.

Example

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

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

julia> fin = fits_create_file(fname_in);

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

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

julia> fits_write_key(fin, "KEY1", 1, "First keyword")

julia> fout = fits_create_file(fname_out);

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

julia> fits_copy_data(fin, fout)

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

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

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

julia> fits_read_key_str(fout, "KEY1") # the header isn't copied
ERROR: CFITSIO has encountered an error. Error code 202: keyword not found in header
[...]

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

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.

Example

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

julia> f = fits_create_file(fname);

julia> fits_create_empty_img(f)

julia> fits_create_binary_tbl(f, 0, [("col1", "1J"), ("col2", "1E")])

julia> fits_get_hdu_num(f)
2

julia> fits_get_hdu_type(f)
:binary_table

julia> fits_delete_hdu(f) # delete the binary table HDU
:image_hdu

julia> fits_get_hdu_num(f)
1

julia> fits_get_hdu_type(f)
:image_hdu

julia> close(f)

fits_write_chksum(f::FITSFile)

Compute and write the DATASUM and CHECKSUM keyword values for the CHDU into the current header. If the keywords already exist, their values will be updated only if necessary (i.e., if the file has been modified since the original keyword values were computed).

Example

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

julia> f = fits_create_file(fname);

julia> fits_create_binary_tbl(f, 0, [("col1", "1J", "units")]);

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

julia> fits_write_chksum(f); # write the checksum keywords

julia> fits_read_key_str(f, "DATASUM", comment = nothing)
("6", nothing)

julia> fits_read_key_str(f, "CHECKSUM", comment = nothing)
("9TbBESbA9SbACSbA", nothing)

julia> close(f)

fits_update_chksum(f::FITSFile)

Update the CHECKSUM keyword value in the CHDU, assuming that the DATASUM keyword exists and already has the correct value.

Example

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

julia> f = fits_create_file(fname);

julia> fits_create_binary_tbl(f, 0, [("col1", "1J", "units")]);

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

julia> fits_write_chksum(f); # write the checksum keywords

julia> fits_read_key_str(f, "DATASUM", comment = nothing)
("6", nothing)

julia> fits_read_key_str(f, "CHECKSUM", comment = nothing)
("5UdCATZB7TdBATZB", nothing)

julia> fits_write_key(f, "TEST", "test", "test comment"); # modify the header

julia> fits_update_chksum(f); # update the CHECKSUM keyword

julia> fits_read_key_str(f, "CHECKSUM", comment = nothing)
("Y3amY0UjY0ZjY0Zj", nothing)

julia> close(f)

fits_verify_chksum(f::FITSFile)

Verify if the checksum of the data and the HDU matches the stored values. Returns a tuple of CFITSIO.ChecksumVerificationStatus values, indicating the status of the data and HDU checksums. For either value, a status of MISSING indicates that the corresponding keyword is not present, while a status of MISMATCH indicates that the keyword is present but the value is incorrect. Finally, a value of VERIFIED indicates that the checksum was validated successfully.

Example

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

julia> f = fits_create_file(fname);

julia> fits_create_binary_tbl(f, 0, [("col1", "1J", "units")]);

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

julia> fits_verify_chksum(f) # no checksum keywords present
(CFITSIO.MISSING, CFITSIO.MISSING)

julia> fits_write_chksum(f); # write the checksum keywords

julia> fits_verify_chksum(f)
(CFITSIO.VERIFIED, CFITSIO.VERIFIED)

julia> close(f)