fits_copy_header(fin::FITSFile, fout::FITSFile)

Copy the header (not the data) associated with the current HDU from fin to fout. If the current HDU in fout is not empty, it will be closed and a new HDU will be appended. An empty output HDU will be created with the header but no data.

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_header(fin, fout)

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_delete_key(f::FITSFile, keyname::String)

Delete the keyword named keyname.

Example

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

julia> f = fits_create_file(fname);

julia> fits_create_empty_img(f)

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

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

julia> fits_delete_key(f, "KEY1") # delete the keyword

julia> fits_read_key_str(f, "KEY1")
ERROR: CFITSIO has encountered an error. Error code 202: keyword not found in header
[...]

julia> close(f)

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

Delete the keyword record at the specified index.

Example

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

julia> f = fits_create_file(fname);

julia> fits_create_empty_img(f)

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

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

julia> fits_delete_record(f, 7) # delete the keyword

julia> fits_read_key_str(f, "KEY1")
ERROR: CFITSIO has encountered an error. Error code 202: keyword not found in header
[...]

julia> close(f)

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

Example

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

julia> f = fits_clobber_file(fname);

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

julia> nkeywords, _ = fits_get_hdrspace(f)
(8, -1)

julia> [fits_read_keyn(f, i) for i in 1:nkeywords]
8-element Vector{Tuple{String, String, String}}:
 ("SIMPLE", "T", "file does conform to FITS standard")
 ("BITPIX", "32", "number of bits per data pixel")
 ("NAXIS", "2", "number of data axes")
 ("NAXIS1", "2", "length of data axis 1")
 ("NAXIS2", "2", "length of data axis 2")
 ("EXTEND", "T", "FITS dataset may contain extensions")
 ("COMMENT", "", "  FITS (Flexible Image Transport System) format is defined in 'Astronomy")
 ("COMMENT", "", "  and Astrophysics', volume 376, page 359; bibcode: 2001A&A...376..359H")

julia> close(f)

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

Read the value of a keyword as a Clong, as well as the comment associated with the keyword.

Example

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

julia> f = fits_create_file(fname);

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

julia> fits_read_key_lng(f, "NAXIS1")
(100, "length of data axis 1")

julia> close(f)

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

Read the value associated with the keyword as a String, along with the comment.

Example

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

julia> f = fits_create_file(fname);

julia> fits_create_empty_img(f)

julia> fits_read_key_str(f, "SIMPLE")
("T", "file does conform to FITS standard")

julia> close(f)

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

Read the physical unit of the keyword keyname in the header.

Example

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

julia> f = fits_create_file(fname);

julia> fits_create_empty_img(f)

julia> fits_write_key(f, "Velocity", 2.0, "Velocity of the object")

julia> fits_write_key_unit(f, "Velocity", "m/s")

julia> fits_read_key_unit(f, "Velocity")
"m/s"

julia> fits_read_keyword(f, "Velocity")
("2.", "[m/s] Velocity of the object")

julia> close(f)

See also fits_write_key_unit to write a unit to a keyword.

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.

Example

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

julia> f = fits_create_file(fname);

julia> fits_create_empty_img(f)

julia> fits_read_keyn(f, 1)
("SIMPLE", "T", "file does conform to FITS standard")

julia> fits_read_keyn(f, 3)
("NAXIS", "0", "number of data axes")

julia> close(f)

fits_read_keyword(f::FITSFile, keyname::String) -> (value, comment)

Return the specified keyword value and comment (as a tuple of strings), throws and error if the keyword is not found.

Example

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

julia> f = fits_create_file(fname);

julia> fits_create_empty_img(f)

julia> fits_read_keyword(f, "SIMPLE")
("T", "file does conform to FITS standard")

julia> close(f)

fits_read_record(f::FITSFile, keynum::Int)::String

Return the keynum-th header record in the CHU. The first keyword in the header is at keynum = 1.

Example

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

julia> f = fits_create_file(fname);

julia> fits_create_empty_img(f)

julia> fits_read_record(f, 1)
"SIMPLE  =                    T / file does conform to FITS standard"

julia> fits_read_record(f, 3)
"NAXIS   =                    0 / number of data axes"

julia> close(f)

fits_update_key(f::FITSFile, key::String, value, comment::Union{String,Ptr{Nothing},Nothing} = nothing)

Update the value of an existing keyword in the FITS header, or add a new keyword if it does not exist. This function is a convenience wrapper that calls the appropriate ffuk* function based on the type of value.

If comment is provided, it is added to the keyword comment field. If value is Nothing, the keyword is set to a null value. If value is a string, it is checked to be ASCII compliant. If value is a floating-point number, it is written as a double-precision value. If value is a boolean, it is written as an integer (1 for true, 0 for false).

Example

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

julia> f = fits_create_file(fname);

julia> fits_create_empty_img(f)

julia> fits_update_key(f, "NEWKEY", 2, "This is a new keyword")

julia> fits_read_key_str(f, "NEWKEY")
("2", "This is a new keyword")

julia> fits_update_key(f, "NEWKEY", 3.14, "Updated value")

julia> fits_read_key_str(f, "NEWKEY")
("3.14", "Updated value")

julia> fits_update_key(f, "NEWKEY", true, "Boolean value")

julia> fits_read_key_str(f, "NEWKEY")
("T", "Boolean value")

julia> fits_update_key(f, "NEWKEY", "Value", "String value")

julia> fits_read_key_str(f, "NEWKEY")
("Value", "String value")

julia> close(f)

fits_write_comment(f::FITSFile, comment::String)

Append to the keyword COMMENT in the FITS header. If the keyword does not exist, it is created.

Example

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

julia> f = fits_create_file(fname);

julia> fits_create_empty_img(f)

julia> fits_write_comment(f, "This is a comment")

julia> fits_read_record(f, 7)
"COMMENT This is a comment"

julia> close(f)

fits_write_date(f::FITSFile)

Write the current date and time into the FITS header. If a DATE keyword already exists, it is replaced by the new value. The date is written in the format YYYY-MM-DDThh:mm:ss (ISO 8601).

Example

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

julia> f = fits_create_file(fname);

julia> fits_create_empty_img(f)

julia> fits_write_date(f)

julia> fits_read_key_str(f, "DATE")
("2025-05-28T10:41:08", "file creation date (YYYY-MM-DDThh:mm:ss UT)")

julia> close(f)

fits_write_history(f::FITSFile, history::String)

Append to the keyword HISTORY in the FITS header. If the keyword does not exist, it is created.

Example

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

julia> f = fits_create_file(fname);

julia> fits_create_empty_img(f)

julia> fits_write_history(f, "This is a history entry")

julia> fits_read_record(f, 7)
"HISTORY This is a history entry"

julia> close(f)

fits_write_key(f::FITSFile, keyname::String, value, comment::Union{String, Nothing} = nothing)

Write a keyword of the appropriate data type into the CHU. If comment is nothing, the keyword is written without a comment.

Example

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

julia> f = fits_create_file(fname);

julia> fits_create_empty_img(f)

julia> fits_write_key(f, "NEWKEY", 2, "This is a new keyword")

julia> fits_read_key_str(f, "NEWKEY")
("2", "This is a new keyword")

julia> close(f)

fits_write_key_unit(f::FITSFile, keyname::String, unit::String)

Write the physical units string into an existing keyword record. The keyword must already exist in the header. The unit string is enclosed in square brackets at the beginning of the keyword comment field.

Example

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

julia> f = fits_create_file(fname);

julia> fits_create_empty_img(f)

julia> fits_write_key(f, "Velocity", 2.0, "Velocity of the object")

julia> fits_write_key_unit(f, "Velocity", "m/s")

julia> fits_read_key_unit(f, "Velocity")
"m/s"

julia> fits_read_keyword(f, "Velocity")
("2.", "[m/s] Velocity of the object")

julia> close(f)

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

Write a user specified keyword record into the CHU. This is a low–level routine which can be used to write any arbitrary record into the header. It is not recommended to use this function unless you know what you are doing. It is typically used to write hierarchical keywords in the ESO convention, which allows keyword names longer than 8 characters. It is also used to write comments or history entries directly into the header. If the keyword already exists, it is replaced by the new value. If the keyword does not exist, it is added to the header.

Example

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

julia> f = fits_create_file(fname);

julia> fits_create_empty_img(f)

julia> fits_write_record(f, "HIERARCH ESO OBS ID = '12345'")

julia> fits_read_record(f, 7)
"HIERARCH ESO OBS ID = '12345'"

julia> close(f)