FITS stucture
Introduction
The Application Programming Interface (API) for CamiFITS is based on 6 FITS-object structs with dedicated object-casting procedures to enforce the FITS standard . The API elements are typically called internally by one of the Basic tools but is made available in the documentation to provide insight in the structure of CamiFITS.
FITS-objects
CamiFITS.FITS
— TypeFITS
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}`)
CamiFITS.FITS_filnam
— TypeFITS_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
: forp#.fits
this isp#
(::String
).prefix
: forp#.fits
this isp
(::String
).numerator
: forp#.fits
this is#
, a serial number (e.g., '3') or a range (e.g., '3-7') (::String
).extension
: forp#.fits
this is.fits
(::String
)
CamiFITS.FITS_HDU
— TypeFITS_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.
CamiFITS.FITS_header
— TypeFITS_header
Object to hold the header information of a FITS_HDU
.
The fields are:
.card
: the array ofcards
(::Vector{FITS_card}
).map
: Dictionarykeyword => recordindex
(::Dict{String, Int}
)
CamiFITS.FITS_card
— TypeFITS_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
)
CamiFITS.FITS_dataobject
— TypeFITS_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 thehdutype
(::Any)
FITS-object casting
The ordering of the FITS-object casting procedures is illustrated in the flow diagram below.
The use of the casting procedures is recommended over direct application of the FITS-object strucs to ensure conformance to the FITS standard .
CamiFITS.cast_FITS_filnam
— Methodcast_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")
CamiFITS.cast_FITS_dataobject
— Methodcast_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 '"
CamiFITS.cast_FITS_header
— Methodcast_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
CamiFITS.cast_FITS_card
— Methodcast_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 ")
CamiFITS.cast_FITS_HDU
— Methodcast_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
CamiFITS.cast_FITS
— MethodFITS(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 ofFITS_HDU
s (::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
FITS methods
CamiFITS.fits_zero_offset
— Methodfits_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
CamiFITS.fits_apply_offset
— Methodfits_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
CamiFITS.fits_remove_offset
— Methodfits_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
Fortran objects
CamiFITS.FORTRAN_format
— TypeFORTRAN_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-object casting
CamiFITS.cast_FORTRAN_format
— Methodcast_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)
FORTRAN-related methods
CamiFITS.FORTRAN_eltype_char
— MethodFORTRAN_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', '-', '-']
CamiFITS.parse_FITS_TABLE
— Methodparse_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"]