FITS

Object to hold a single .fits file.

The fields are

• .filnam:: the .fits filename (:String)
• .hdu: the collection of header-data-unit objects (::Vector{FITS_HDU}`)

FITS_HDU

Object to hold a single "Header and Data Unit" (HDU).

The fields are

• .hduindex:: identifier (a file may contain more than one HDU) (:Int)
• .header: the header object (::FITS_header)
• .dataobject: the data object (::FITS_dataobject)

NB. An empty data block (.dataobject = nothing) conforms to the standard.

FITS_card

Object to hold the card information of the FITS_header object.

The fields are:

• .cardindex: identifier of the header record (::Int)
• .record: the full record on the card (::String)
• .keyword: name of the corresponding header record (::String)
• .val: value of the corresponding header record (::Any)
• .comment: comment on the corresponding header record (::String)

FITS_dataobject

Object to hold the data of the FITS_HDU of given hdutype.

The fields are:

• .hdutype: accepted types are 'PRIMARY', 'IMAGE' and 'TABLE' (::String)
• .data: in the from appropriate for the hdutype (::Any)

FITS_filnam

mutable FITS object to hold the decomposed name of a .fits file.

The fields are: " .value: for p#.fits this is p#.fits (::String)

• .name: for p#.fits this is p# (::String)
• .prefix: for p#.fits this is p (::String)
• .numerator: for p#.fits this is #, a serial number (e.g., '3') or a range (e.g., '3-7') (::String)
• .extension: for p#.fits this is .fits (::String)

FITS_header

Object to hold the header information of a FITS_HDU.

The fields are:

• .card: the array of cards (::Vector{FITS_card})
• .map: Dictionary keyword => recordindex (::Dict{String, Int})

FORTRAN_format

Object to hold a FORTRAN format specifier decomposed in its fields.

Accepted datatype specifiers are: Aw, Iw, Fw.d, Ew.d, Dw.d

Accepted output formating specifiers are: Aw, Iw.m, Bw.m, Ow.m, Zw.m, Fw.d, Ew.dEe, ENw.d, ESw.d, Gw.dEe, Dw.dEe. Notation: w - width, m (optional) - minimum number of digits, d - number of digits to right of decimal, e - number of digits in exponent N/S (optional) indicates engineering/scientific formating of the E type.

The fields are:

• .datatype: primary FORTRAN datatype (::String)
• .char: primary FORTRAN datatype character (::Char)
• .EngSci: secundary datatype character - N for engineering/ S for scientific (::Union{Char,Nothing})
• .width: width of numeric field (::Int)
• .nmin: minimum number of digits displayed (::Int)
• .ndec: number of digits to right of decimal (::Int)
• .nexp: number of digits in exponent (::Int)

FORTRAN_eltype_char(T::Type)

FORTRAN datatype description character for julia type T:

Bool => 'L', UInt8 => 'B', Int16 => 'I', UInt16 => 'I', Int32 => 'J', UInt32 => 'J', Int64 => 'K', UInt64 => 'K', Float32 => 'E', Float64 => 'D', ComplexF32 => 'C', ComplexF64 => 'M'

The character '-' is returned for non-primitive FORTRAN datatypes and for primitive datatypes not included in the FITS standard.

Examples:

julia> T = Type[Bool, Int8, UInt8, Int16, UInt16, Int32, UInt32, Int64, UInt64];

julia> print([FORTRAN_eltype_char(T[i]) for i ∈ eachindex(T)])
Int8: datatype not part of the FITS standard
['L', '-', 'B', 'I', 'I', 'J', 'J', 'K', 'K']

julia> T = [Float16, Float32, Float64, ComplexF32, ComplexF64];

julia> print([FORTRAN_eltype_char(T[i]) for i ∈ eachindex(T)])
Float16: datatype not part of the FITS standard
['-', 'E', 'D', 'C', 'M']

julia> T = [String, Vector{Char}, FITS];

julia> print([FORTRAN_eltype_char(T[i]) for i ∈ eachindex(T)])
Vector{Char}: not a FORTRAN datatype
FITS: not a FORTRAN datatype
['A', 'A', '-', '-']

FITS(filnam::String, hdu::Vector{FITS_HDU})

Object to hold a single .fits file.

The fields are

• .filnam: filename of the corresponding .fits file (::String)
• .hdu: array of FITS_HDUs (::Vector{FITS_HDU})

Example:

julia> data = [11 21 31; 12 22 23; 13 23 33];

julia> d = cast_FITS_dataobject("image", data);

julia> h = cast_FITS_header(d);

julia> hdu = cast_FITS_HDU(1, h, d);

julia> f = cast_FITS("test.fits", [hdu]);

julia> f.hdu[1].dataobject.data
3×3 Matrix{Int64}:
 11  21  31
 12  22  23
 13  23  33

cast_FITS_HDU(hduindex::Int, header::FITS_header, data::FITS_dataobject)

Create the FITS_HDU object for given hduindex, header and data.

Example:

julia> data = [11 21 31; 12 22 23; 13 23 33];

julia> d = cast_FITS_dataobject("image", data);

julia> h = cast_FITS_header(d);

julia> hdu = cast_FITS_HDU(1, h, d);

julia> hdu.dataobject.data
3×3 Matrix{Int64}:
 11  21  31
 12  22  23
 13  23  33

cast_FITS_card(cardindex::Int, record::String)

Create the FITS_card object for record with index cardindex.

Example:

julia> record = "SIMPLE  =                    T / file does conform to FITS standard             ";

julia> card = cast_FITS_card(1, record);

julia> card.cardindex, card.keyword, card.value, card.comment
(1, "SIMPLE", true, "file does conform to FITS standard             ")

cast_FITS_dataobject(hdutype::String, data)

Create the FITS_dataobject object for given hduindex constructed from the data in accordance to the specified hdutype: PRIMARY, IMAGE, ARRAY, TABLE (ASCII table) or BINTABLE (binary table).

Example:

julia> data = [11,21,31,12,22,23,13,23,33];

julia> data = reshape(data,(3,3));

julia> d = cast_FITS_dataobject("image", data)
FITS_dataobject("'IMAGE   '", [11 12 13; 21 22 23; 31 23 33])

julia> d.data
3×3 Matrix{Int64}:
 11  12  13
 21  22  23
 31  23  33

julia> d.hdutype
"'IMAGE   '"

cast_FITS_filnam(filnam::String)

Create the FITS_filnam object to decompose filnam into its name, prefix, numerator and extension.

Example:

julia> filnam = "T23.01.fits";

julia> n = cast_FITS_filnam(filnam);

julia> n.name, n.prefix, n.numerator, n.extension
("T23.01", "T23.", "01", ".fits")

cast_FITS_header(dataobject::FITS_dataobject)

Create the FITS_header object from the dataobject. The dataobject-input mode is used by fits_create to ceate the header object as part of creating the FITS object starting from Julia data input.

Example:

julia> data = [11 21 31; 12 22 23; 13 23 33];

julia> d = cast_FITS_dataobject("image", data);

julia> h = cast_FITS_header(d);

julia> h.map
Dict{String, Int64} with 7 entries:
  "BITPIX"   => 2
  "NAXIS2"   => 5
  "XTENSION" => 1
  "NAXIS1"   => 4
  ""         => 36
  "NAXIS"    => 3
  "END"      => 6

cast_FITS_header(record::Vector{String})

Create the FITS_header object from a block of (a multiple of) 36 single-record strings (of 80 printable ASCII characters). The record-input mode is used by fits_read after reading the header records from disk (see casting diagram above).

Example:

julia> record = [rpad("KEYWORD$i",8) * "'" * rpad("$i",70) * "'" for i=1:3];

julia> blanks = [repeat(' ', 80) for i = 1:36-length(record)];

julia> append!(record, blanks);         # to conform to the FITS standard

julia> h = cast_FITS_header(record);

julia> h.map
Dict{String, Int64} with 4 entries:
  "KEYWORD3" => 3
  "KEYWORD2" => 2
  "KEYWORD1" => 144
  ""         => 36

cast_FORTRAN_format(format::String)

Decompose the format specifier format into its fields and cast this into the FORTRAN_format object. Allowed format specifiers are of the types: Aw, Iw.m, Bw.m, Ow.m, Zw.m, Fw.d, Ew.dEe, ENw.d, ESw.d, Gw.dEe, Dw.dEe, with: w - width, m(optional) - minimum number of digits, d - number of digits to right of decimal, e - number of digits in exponent; N/S (optional) indicates engineering/scientific formating of the E type.

Examples:

julia> cast_FORTRAN_format("I10")
FORTRAN_format("Iw", 'I', nothing, 10, 0, 0, 0)

julia> cast_FORTRAN_format("I10.12")
FORTRAN_format("Iw.m", 'I', nothing, 10, 12, 0, 0)

julia> F = cast_FORTRAN_format("E10.5E3")
FORTRAN_format("Ew.dEe", 'E', nothing, 10, 0, 5, 3)

julia> F.Type, F.TypeChar, F.EngSci, F.width, F.nmin, F.ndec, F.nexp
("Ew.dEe", 'E', nothing, 10, 0, 5, 3)  

fits_add_key!(f::FITS, hduindex::Int, key::String, val::Any, com::String)

Add a header record of given 'key, value and comment' to 'HDU[hduindex]' of file with name 'filnam'

Example:

julia> filnam = "minimal.fits";

julia> f = fits_create(filnam; protect=false);

julia> fits_add_key!(f, 1, "KEYNEW1", true, "This is the new key");

julia> fits_info(f)

File: minimal.fits
hdu: 1
hdutype: 'PRIMARY '
DataType: Any
Datasize: (0,)

Metainformation:
SIMPLE  =                    T / file does conform to FITS standard
BITPIX  =                   64 / number of bits per data pixel
NAXIS   =                    1 / number of data axes
NAXIS1  =                    0 / length of data axis 1
EXTEND  =                    T / FITS dataset may contain extensions
KEYNEW1 =                    T / This is the new key
END

Any[]

fits_apply_offset(data)

Shift the UInt range of values onto the Int range by substracting from the data the appropriate integer offset value as specified by the BZERO keyword.

NB. Since the FITS format does not support a native unsigned integer data type (except UInt8), unsigned values of the types UInt16, UInt32 and UInt64, are stored as native signed integers of the types Int16, Int32 and Int64, respectively, after substracting the appropriate integer offset specified by the (positive) BZERO keyword value. For the byte data type (UInt8), the converse technique can be used to store signed byte values (Int8) as native unsigned values (UInt) after subtracting the (negative) BZERO offset value.

This method is included and used in storing of data to ensure backward compatibility with software not supporting native values of the types Int8, UInt16, UInt32 and UInt64.

Example:

julia> fits_apply_offset(UInt32[0])
1-element Vector{Int32}:
 -2147483648

julia> fits_apply_offset(Int8[0])
1-element Vector{UInt8}:
 0x80

julia> Int(0x80)
128

fits_collect(fileStart::String, fileStop::String [; protect=true[], msg=true]])

Combine "fileStart" with "fileStop" (with mandatory ".fits" extension)

Key:

• protect::Bool: overwrite protection
• msg::Bool: allow status message

Example:

julia> for i=1:5
           data = [0 0 0; 0 i 0; 0 0 0]
           fits_create("T$i.fits", data; protect=false)
       end

julia> f = fits_collect("T1.fits", "T5.fits"; protect=false);
'T1-T5.fits': file created

julia> fits_info(f)[:,:,2]

File: T1-T5.fits
hdu: 1
hdutype: 'PRIMARY '
DataType: Int64
Datasize: (3, 3, 5)

Metainformation:
SIMPLE  =                    T / file does conform to FITS standard
BITPIX  =                   64 / number of bits per data pixel
NAXIS   =                    3 / number of data axes
NAXIS1  =                    3 / length of data axis 1
NAXIS2  =                    3 / length of data axis 2
NAXIS3  =                    5 / length of data axis 3
EXTEND  =                    T / FITS dataset may contain extensions
END

3×3 Matrix{Int64}:
 0  0  0
 0  2  0
 0  0  0

julia> for i = 1:5 rm("T$i.fits") end

julia> rm("T1-T5.fits"); f = nothing

fits_copy(filnam1 [, filnam2=""] [; protect=true]])

Copy filnam1 to filnam2 (with mandatory .fits extension) Key:

• protect::Bool: overwrite protection
• msg::Bool: allow status message

Examples:

julia> fits_create("test1.fits"; protect=false);

julia> fits_copy("test1.fits", "test2.fits"; protect=false);
'test1.fits' was copied under the name 'test2.fits'

julia> rm.(["test1.fits", "test2.fits"]);

fits_create(filnam [, data [; protect=true]])

Create .fits file of given filnam and return Array of HDUs. Key:

• data: data primary hdu (::DataType)
• protect: overwrite protection (::Bool)

Examples:

julia> filnam = "test.fits";

julia> f = fits_create(filnam, data; protect=false);

julia> fits_info(f)

File: test.fits
hdu: 1
hdutype: 'PRIMARY '
DataType: Int64
Datasize: (3, 3)

Metainformation:
SIMPLE  =                    T / file does conform to FITS standard
BITPIX  =                   64 / number of bits per data pixel
NAXIS   =                    2 / number of data axes
NAXIS1  =                    3 / length of data axis 1
NAXIS2  =                    3 / length of data axis 2
EXTEND  =                    T / FITS dataset may contain extensions
END

3×3 Matrix{Int64}:
 11  21  31
 12  22  23
 13  23  33

julia> rm("minimal.fits"); f = nothing

fits_delete_key!(f::FITS, hduindex::Int, key::String)

Delete a header record of given key, value and comment from the FITS_HDU f of given hduindex.

Examples:

julia> filnam = "minimal.fits";

julia> f = fits_create(filnam; protect=false);

julia> fits_add_key!(f, 1, "KEYNEW1", true, "This is the new key");

julia> cardindex = get(f.hdu[1].header.map,"KEYNEW1", nothing)
8

julia> keyword = f.hdu[1].header.card[cardindex].keyword
"KEYNEW1"

julia> cardindex = get(f.hdu[1].header.map,"KEYNEW1", nothing)
8

julia> fits_delete_key!(f, 1, "KEYNEW1");

julia> cardindex = get(f.hdu[1].header.map,"KEYNEW1", nothing)

julia> fits_delete_key!(f, 1, "NAXIS");
ERROR: FITSError: 17 - illegal keyword deletion (mandatory keyword)
Stacktrace:
 [1] fits_delete_key!(f::FITS, hduindex::Int64, key::String)
   @ CamiFITS c:\Users\walra\.julia\dev\CamiFITS.jl\src\fits_public_sector.jl:495
 [2] top-level scope
   @ REPL[24]:1

fits_edit_key!(f::FITS, hduindex::Int, key::String, val::Any, com::String)

Edit a header record of given 'key, value and comment' to 'HDU[hduindex]' of file with name 'filnam'

Example:

julia> using Dates

julia> data = DateTime("2020-01-01T00:00:00.000");

julia> strExample="minimal.fits";

julia> f = fits_create(strExample; protect=false);

julia> fits_add_key!(f, 1, "KEYNEW1", true, "this is record 5");

julia> fits_edit_key!(f, 1, "KEYNEW1", data, "record 5 changed to a DateTime type");

julia> fits_info(f.hdu[1])
hdu: 1
hdutype: 'PRIMARY '
DataType: Any
Datasize: (0,)

Metainformation:
SIMPLE  =                    T / file does conform to FITS standard
BITPIX  =                   64 / number of bits per data pixel
NAXIS   =                    1 / number of data axes
NAXIS1  =                    0 / length of data axis 1
EXTEND  =                    T / FITS dataset may contain extensions
KEYNEW1 = '2020-01-01T00:00:0' / record 5 changed to a DateTime type
END

Any[]

fits_extend!(f::FITS, data_extend; hdutype="IMAGE")
fits_extend!(filnam::String, data_extend; hdutype="IMAGE")

HDU array in which the FITS object f or FITS file filnam is extended with the data of data_extend in the format of the specified hdutype.

Examples:

julia> filnam = "example.fits";

julia> fits_create(filnam; protect=false);

julia> table = let
        [true, 0x6c, 1081, 0x0439, 1.23, 1.01f-6, 1.01e-6, 'a', "a", "abc"],
        [false, 0x6d, 1011, 0x03f3, 23.2, 3.01f-6, 3.01e-6, 'b', "b", "abcdef"]
        end;

julia> fits_extend!(filnam, table; hdutype="table");

julia> fits_info(filnam, 2; hdr=false)
2-element Vector{String}:
 " 1 108 1081 1081  1.23 1.01E-6 1.01D-6 a a    abc"
 " 0 109 1011 1011 23.20 3.01E-6 3.01D-6 b b abcdef"

julia> rm(filnam)

fits_info(f::FITS [, hduindex=1] [; nr=false [, hdr=true]])
fits_info(hdu::FITS_HDU; nr=false, hdr=true)

Metafinformation and data of a given FITS_HDU object with optional record numbering.

• hduindex: HDU index (::Int - default: 1 = primary hdu)
• nr: include cardindex (::Bool - default: false)
• hdr: show header (::Bool)

Example:

To demonstrate fits_info we first create the fits object f for subsequent inspection.

julia> filnam = "minimal.fits";

julia> f = fits_create(filnam; protect=false);

julia> fits_info(f)

File: minimal.fits
hdu: 1
hdutype: 'PRIMARY '
DataType: Any
Datasize: (0,)

Metainformation:
SIMPLE  =                    T / file does conform to FITS standard
BITPIX  =                   64 / number of bits per data pixel
NAXIS   =                    1 / number of data axes
NAXIS1  =                    0 / length of data axis 1
EXTEND  =                    T / FITS dataset may contain extensions
END

Any[]

julia> rm(filnam); f = nothing

fits_info(filnam::String [, hduindex=1] [; nr=true [, hdr=true]])

Same as above but creating the fits object by reading filnam from disc and with default record nubering.

• hduindex: HDU index (::Int - default: 1 = primary hdu)
• nr: include cardindex (::Bool - default: true)
• hdr: show header (::Bool)

Example:

julia> filnam = "minimal.fits";

julia> fits_create(filnam; protect=false);

julia> fits_info(filnam)

File: minimal.fits
hdu: 1
hdutype: 'PRIMARY '
DataType: Any
Datasize: (0,)

  nr | Metainformation:
---------------------------------------------------------------------------------------
   1 | SIMPLE  =                    T / file does conform to FITS standard
   2 | BITPIX  =                   64 / number of bits per data pixel
   3 | NAXIS   =                    1 / number of data axes
   4 | NAXIS1  =                    0 / length of data axis 1
   5 | EXTEND  =                    T / FITS dataset may contain extensions
   6 | END

Any[]

julia> rm(filnam)

fits_keyword(keyword::String [; msg=true])
fits_keyword([; hdutype="all" [, msg=true]])

Description of the reserved keywords of the FITS standard:

(blanks), ALL, AUTHOR, BITPIX, BLANK, BLOCKED, BSCALE, BUNIT, BZERO, CDELTn, COMMENT, CROTAn, CRPIXn, CRVALn, CTYPEn, DATAMAX, DATAMIN, DATE, DATE-OBS, END, EPOCH, EQUINOX, EXTEND, EXTLEVEL, EXTNAME, EXTVER, GCOUNT, GROUPS, HISTORY, INSTRUME, NAXIS, NAXISn, OBJECT, OBSERVER, ORIGIN, PCOUNT, PSCALn, PTYPEn, PZEROn, REFERENC, SIMPLE, TBCOLn, TDIMn, TDISPn, TELESCOP, TFIELDS, TFORMn, THEAP, TNULLn, TSCALn, TTYPEn, TUNITn, TZEROn, XTENSION,

where n = 1,...,nmax as specified for the keyword. Use the keyword "ALL" to dump the full list of keyword descriptions.

The descriptions are based on appendix C to FITS standard - version 4.0, which is not part of the standard but included for convenient reference.

julia> fits_keyword("naxisn");
KEYWORD:    NAXISn
REFERENCE:  FITS Standard - version 4.0 - Appendix C
CLASS:      general
STATUS:     mandatory
HDU:        primary, groups, extension, array, image, ASCII-table, bintable,
VALUE:      integer
RANGE:      [0:]
COMMENT:    size of the axis
DEFINITION: The value field of this indexed keyword shall contain a non-negative integer,  
representing the number of elements along axis n of a data array.
The NAXISn must be present for all values n = 1,...,NAXIS, and for no other values of n.   
A value of zero for any of the NAXISn signifies that no data follow the header in the HDU. 
If NAXIS is equal to 0, there should not be any NAXISn keywords.

julia> fits_keyword()
FITS defined keywords:
(blanks) AUTHOR   BITPIX   BLANK    BLOCKED  BSCALE   BUNIT    BZERO    
CDELTn   COMMENT  CROTAn   CRPIXn   CRVALn   CTYPEn   DATAMAX  DATAMIN  
DATE     DATE-OBS END      EPOCH    EQUINOX  EXTEND   EXTLEVEL EXTNAME  
EXTVER   GCOUNT   GROUPS   HISTORY  INSTRUME NAXIS    NAXISn   OBJECT   
OBSERVER ORIGIN   PCOUNT   PSCALn   PTYPEn   PZEROn   REFERENC SIMPLE   
TBCOLn   TDIMn    TDISPn   TELESCOP TFIELDS  TFORMn   THEAP    TNULLn   
TSCALn   TTYPEn   TUNITn   TZEROn   XTENSION

HDU options: 'primary', 'extension', 'array', 'image', 'ASCII-table', 'bintable'

reference: FITS Standard - version 4.0 - Appendix C

fits_read(filnam::String)

Read .fits file and return Array of FITS_HDUs

Example:

julia> filnam = "minimal.fits";

julia> fits_create(filnam; protect=false);

julia> f = fits_read(filnam);

julia> fits_info(f)
hdu: 1
hdutype: PRIMARY
DataType: Any
Datasize: (0,)

Metainformation:
SIMPLE  =                    T / file does conform to FITS standard
BITPIX  =                   64 / number of bits per data pixel
NAXIS   =                    1 / number of data axes
NAXIS1  =                    0 / length of data axis 1
BZERO   =                  0.0 / offset data range to that of unsigned integer
BSCALE  =                  1.0 / default scaling factor
EXTEND  =                    T / FITS dataset may contain extensions
END

Any[]

julia> rm(filnam); f = nothing

fits_record_dump(filnam [, hduindex=0] [; hdr=true [, dat=true [, nr=true [, msg=true]]]])

Listing of all single-line records (card records) as read from filnam on disc. The dump proceeds without casting of FITS objects; i.e., without FITS-conformance testing.

• hduindex: HDU index (::Int - default: 1 = primary hdu)
• hdr: show header (::Bool - default: true)
• dat: show data (::Bool - default: true)
• nr: include record numbers (::Bool - default: true)
• msg: print message (::Bool)

Example:

julia> filnam = "test.fits";

julia> data = [typemin(UInt32),typemax(UInt32)];

julia> fits_create(filnam, data; protect=false);

julia> dump = fits_record_dump(filnam; msg=false);

julia> for i=3:8 println(dump[i]) end
   3 | NAXIS   =                    1 / number of data axes
   4 | NAXIS1  =                    2 / length of data axis 1
   5 | BSCALE  =                  1.0 / default scaling factor
   6 | BZERO   =           2147483648 / offset data range to that of unsigned integer
   7 | EXTEND  =                    T / FITS dataset may contain extensions
   8 | END

julia> dump[37]
"  37 | UInt8[0x80, 0x00, 0x00, 0x00, 0x7f, 0xff, 0xff, 0xff, 0x00, 0x00, 0x00, ⋯, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00]"]"

julia> rm(filnam); f = data = dump = nothing

fits_remove_offset(data, bzero::Real)

Shift the Int range of values onto the UInt range by adding to the data the appropriate integer offset value as specified by the BZERO keyword.

NB. Since the FITS format does not support a native unsigned integer data type (except UInt8), unsigned values of the types UInt16, UInt32 and UInt64, are recovered from stored native signed integers of the types Int16, Int32 and Int64, respectively, by adding the appropriate integer offset specified by the (positive) BZERO keyword value. For the byte data type (UInt8), the converse technique can be used to recover the signed byte values (Int8) from the stored native unsigned values (UInt) by adding the (negative) BZERO offset value.

This method is included and used in reading stored data to ensure backward compatibility with software not supporting native values of the types Int8, UInt16, UInt32 and UInt64.

Example:

julia> fits_remove_offset(Int32[-2147483648])
1-element Vector{UInt32}:
 0x00000000

julia> Int(0x00000000)
0

julia> fits_remove_offset(UInt8[128])
1-element Vector{Int8}:
 0

fits_rename_key!(filnam::String, hduindex::Int, keyold::String, keynew::String)

Rename the key of a header record of file with name 'filnam'

Example:

julia> filnam="minimal.fits";

julia> f = fits_create(filnam; protect=false);

julia> fits_add_key!(f, 1, "KEYNEW1", true, "this is a new record");

julia> fits_rename_key!(f, 1, "KEYNEW1",  "KEYNEW2");

julia> fits_info(f.hdu[1])
hdu: 1
hdutype: 'PRIMARY '
DataType: Any
Datasize: (0,)

Metainformation:
SIMPLE  =                    T / file does conform to FITS standard
BITPIX  =                   64 / number of bits per data pixel
NAXIS   =                    1 / number of data axes
NAXIS1  =                    0 / length of data axis 1
BZERO   =                  0.0 / offset data range to that of unsigned integer
BSCALE  =                  1.0 / default scaling factor
EXTEND  =                    T / FITS dataset may contain extensions
COMMENT    Extended FITS HDU   / http://fits.gsfc.nasa.gov/
KEYNEW2 =                    T / this is a new record
END

Any[]

fits_save_as(f::FITS, filnam::String [; protect=true])

Save the FITS object under the name filnam. Key:

• protect::Bool: overwrite protection

julia> f = fits_create("minimal.fits"; protect=false);

julia> fits_save_as(f, "kanweg.fits"; protect=false);

julia> f = fits_read("kanweg.fits");

julia> fits_info(f)
File: kanweg.fits
hdu: 1
hdutype: PRIMARY
DataType: Any
Datasize: (0,)

Metainformation:
SIMPLE  =                    T / file does conform to FITS standard
BITPIX  =                   64 / number of bits per data pixel
NAXIS   =                    1 / number of data axes
NAXIS1  =                    0 / length of data axis 1
BZERO   =                  0.0 / offset data range to that of unsigned integer
BSCALE  =                  1.0 / default scaling factor
EXTEND  =                    T / FITS dataset may contain extensions
COMMENT    Extended FITS HDU   / http://fits.gsfc.nasa.gov/
END

Any[]

fits_terminology([term::String [; test=false]])

Description of the defined terms from FITS standard:

ANSI, ASCII, ASCII NULL, ASCII character, ASCII digit, ASCII space, ASCII text, Array, Array value, Basic FITS, Big endian, Bit, Byte, Card image, Character string, Conforming extension, Data block, Deprecate, Entry, Extension, Extension type name, FITS, FITS Support Office, FITS block, FITS file, FITS structure, Field, File, Floating point, Fraction, Group parameter value, HDU Header and Data Unit., Header, Header block, Heap, IAU, IAUFWG, IEEE, IEEE NaN, IEEE special values, Indexed keyword, Keyword name, Keyword record, MEF, Mandatory keyword, Mantissa, NOST, Physical value, Pixel, Primary HDU, Primary data array, Primary header, Random Group, Record, Repeat count, Reserved keyword, SIF, Special records, Standard extension.

julia> fits_terminology()
FITS defined terms:
ANSI, ASCII, ASCII NULL, ASCII character, ..., SIF, Special records, Standard extension.

julia> fits_terminology("FITS")
FITS:
Flexible Image Transport System.

julia> get(dictDefinedTerms, "FITS", nothing)
"Flexible Image Transport System."

julia> fits_terminology("p")
p:
Not one of the FITS defined terms.
suggestions: Physical value, Pixel, Primary HDU, Primary data array, Primary header.

see FITS Standard - https://fits.gsfc.nasa.gov/fits_standard.html

fits_zero_offset(T::Type)

Zero offset a as used in linear scaling equation

f(x) = a + b x,

where b is the scaling factor.

The default value is a = 0.0 for Real numeric types. For non-real types a = nothing.

Example:

julia> T = Type[Any, Bool, Int8, UInt8, Int16, UInt16, Int32, UInt32,
                  Int64, UInt64, Float16, Float32, Float64];

julia> o = (0.0, 0.0, -128, 0.0, 0.0, 32768,
                   0.0, 2147483648, 0.0, 9223372036854775808, 0.0, 0.0, 0.0);

julia> sum([fits_zero_offset(T[i]) == o[i] for i ∈ eachindex(T)]) == 13
true

parse_FITS_TABLE(hdu::FITS_HDU)

Parse FITS_TABLE (ASCII table) into a Vector of its columns for further processing by the user. Default formatting in ISO 2004 FORTRAN data format specified by keys "TFORMS1" - "TFORMSn"). Display formatting in ISO 2004 FORTRAN data format ("TDISP1" - "TDISPn") prepared for user editing.

Example:

strExample = "example.fits"
data = [10, 20, 30]
fits_create(strExample, data; protect=false)

t1 = Float16[1.01E-6,2.0E-6,3.0E-6,4.0E-6,5.0E-6]
t2 = [0x0000043e, 0x0000040c, 0x0000041f, 0x0000042e, 0x0000042f]
t3 = [1.23,2.12,3.,4.,5.]
t4 = ['a','b','c','d','e']
t5 = ["a","bb","ccc","dddd","ABCeeaeeEEEEEEEEEEEE"]
data = [t1,t2,t3,t4,t5]
fits_extend(strExample, data, "TABLE")

f = fits_read(strExample)
d = f[2].header.dict
d = [get(d,"TFORM\$i",0) for i=1:5]; println(strip.(d))
  SubString{String}["'E6.1    '", "'I4      '", "'F4.2    '", "'A1      '", "'A20     '"]

f[2].dataobject.data                            # this is the table hdu
  5-element Vector{String}:
   "1.0e-6 1086 1.23 a a                    "
   "2.0e-6 1036 2.12 b bb                   "
   "3.0e-6 1055 3.0  c ccc                  "
   "4.0e-6 1070 4.0  d dddd                 "
   "5.0e-6 1071 5.0  e ABCeeaeeEEEEEEEEEEEE "

parse_FITS_TABLE(f[2])
  5-element Vector{Vector{T} where T}:
   [1.0e-6, 2.0e-6, 3.0e-6, 4.0e-6, 5.0e-6]
   [1086, 1036, 1055, 1070, 1071]
   [1.23, 2.12, 3.0, 4.0, 5.0]
   ["a", "b", "c", "d", "e"]
   ["a                   ", "bb                  ", "ccc                 ", "dddd                ", "ABCeeaeeEEEEEEEEEEEE"]