Home
Manual
Packages
Global Index
Keywords
Quick Reference
|
functions in fits.i -
_fits_bintable_header
|
_fits_bintable_header(fh, nbytes, nrows, tfields)
Set/update header information in FITS handle FH for a binary table
extension. NBYTES is the number of bytes per row of the table, NROWS
is the number of table rows and TFIELDS is the number of fields
(columns in the table). FITS card "XTENSION" with value "BINTABLE"
must already exists in the header (this is not checked). FITS cards
"BITPIX", "NAXIS", "NAXIS1", "NAXIS2", "PCOUNT", "GCOUNT", and
"TFIELDS" get created/updated by this routine. The value of PCOUNT is
computed by the routine and returned to the caller.
|
SEE ALSO:
|
fits,
fits_new_bintable,
fits_write_bintable
|
_fits_digitize
|
_fits_digitize - char -> number conversion array;
_fits_multiplier - multiplier;
_fits_alphabet - allowed characters in FITS keys;
_fits_max_id - maximum possible ID value.
Private arrays used to convert FITS keyword to/from numerical
identifiers. If you experiment a strange behaviour of FITS routines,
it may be because one of these arrays get corrupted; in that case,
just run subroutine fits_init to reinitialize things (you may also
have to rehash your FITS handles: see fits_rehash).
|
SEE ALSO:
|
fits,
fits_init,
fits_rehash,
fits_id,
fits_key
|
_fits_format_comment
|
_fits_format_comment(key)
-or- _fits_format_comment(key, text)
Private routine to format FITS commentary card, return an array of
80-character string(s). Text comment, if longer than 72 characters,
will result in more than one comment cards.
|
SEE ALSO:
|
fits,
fits_set
|
_fits_format_complex
|
_fits_format_complex(key, value)
-or- _fits_format_complex(key, value, comment)
Private routine to format FITS complex card, return a 80-character
string.
|
SEE ALSO:
|
fits,
fits_set
|
_fits_format_integer
|
_fits_format_integer(key, value)
-or- _fits_format_integer(key, value, comment)
Private routine to format FITS integer card, return a 80-character
string.
|
SEE ALSO:
|
fits,
fits_set
|
_fits_format_logical
|
_fits_format_logical(key, value)
-or- _fits_format_logical(key, value, comment)
Private routine to format FITS logical card, return a 80-character
string.
|
SEE ALSO:
|
fits,
fits_set
|
_fits_format_real
|
_fits_format_real(key, value)
-or- _fits_format_real(key, value, comment)
Private routine to format FITS real card, return a 80-character
string.
Note: FITS standard imposes that the ASCII representation of a real
number makes 20 characters; the full precision of 64-bit values
can not be represented with this restriction.
|
SEE ALSO:
|
fits,
fits_set
|
_fits_format_string
|
_fits_format_string(key, value)
-or- _fits_format_string(key, value, comment)
Private routine to format FITS string card, return a 80-character
string.
Note: enclose input string in quotes, replacing each quote in input
string by 2 quotes. Since opening quote should appear in
column 11 and closing quote in columns 20 to 80 of the FITS
card, make sure that string is not longer than 68 characters
(too long strings get silently truncated).
|
SEE ALSO:
|
fits,
fits_set
|
_fits_get_cards
|
_fits_get_cards(fh, cards, ids)
Stores in variables CARDS and IDS the FITS cards and numerical
identifiers from header in FITS handle FH. The returned value is the
number of FITS cards (including empty ones).
|
SEE ALSO:
|
fits,
fits_set
|
_fits_id
|
_fits_id(hdr)
Return array of numerical identifier for FITS header data HDR which
must be an array(char, 80, N). Any invalid FITS key will have its
identifier set to -1.
|
SEE ALSO:
|
fits,
fits_id,
fits_key,
fits_rehash
|
_fits_id_simple
|
_fits_id_simple _fits_id_bitpix _fits_id_naxis
_fits_id_end _fits_id_comment _fits_id_history
_fits_id_xtension _fits_id_bscale _fits_id_bzero
_fits_id_gcount _fits_id_pcount
Numerical identifers of common FITS keywords. If you experiment a
strange behaviour of FITS routines, it may be because one of these
values get corrupted; in that case, just run subroutine fits_init to
reinitialize things.
|
SEE ALSO:
|
fits,
fits_init
|
_fits_id_special
|
_fits_id_special
Private array of all numerical identifers of common FITS keys:
"SIMPLE", "BITPIX", "NAXIS", "END", "", "COMMENT", "HISTORY", and
"XTENSION".
|
SEE ALSO:
|
fits,
fits_init
|
_fits_key
|
_fits_key(id)
Private routine used by fits_key, only useful if ID is a valid scalar
numerical identifier.
|
SEE ALSO:
|
fits_key
|
_fits_match_id
|
fits_match(fh, pattern)
Return array of int's which are non-zero where FITS card names in FITS
handle FH match PATTERN. PATTERN must be a scalar string or a
numerical identifier. As a special case, if PATTERN is of the form
"KEYWORD#" (i.e. last character of PATTERN is a '#'), then any human
readable integer will match the '#', e.g. "NAXIS#" will match "NAXIS3"
and "NAXIS11" but not "NAXIS" nor "QNAXIS4.
Global/extern variable _fits_match_id is set with the numerical
identifier of PATTERN (without last '#' if any).
|
SEE ALSO:
|
fits,
fits_get_cards,
fits_rehash
|
_fits_parse_comment
|
fits_parse(card);
-or- fits_parse(card, id);
Return value of a single FITS card (CARD is a scalar string). The
type of the scalar result is as follow:
- string for a string or a commentary FITS card
- char ('T' for true or 'F' for false) for a logical FITS card
- long for an integer FITS card
- double for a real FITS card
- complex for a complex FITS card
In order to save a call to fits_id, if ID is non-nil it is assumed to
be the numerical identifier of the card, i.e. fits_id(CARD).
The comment part of CARD is stored into external symbol
_fits_parse_comment which is a string (possibly nil) for a valued card
and void (i.e. []) for a commentary card.
If the SAFE keyword is true, the routine returns an empty result in
case of error.
|
SEE ALSO:
|
fits,
fits_get,
fits_id
|
_fits_strict
|
_fits_strict
Private flag: apply strict FITS compliance? Never change this flag
directly but rather call `fits_init'.
|
SEE ALSO:
|
fits,
fits_init
|
_fits_true
|
_fits_true
_fits_false
True/false FITS values ('T' and 'F' respectively). */
|
_fits_warn
|
_fits_warn, msg;
Private FITS routine: print out warning message MSG. */
|
fits
|
fits - an introduction to Yorick interface to FITS files.
The routines provided by this (standalone) package are aimed at
reading/writing FITS (Flexible Image Transport System) files from/to
Yorick. These routines attempt to follow the FITS standard (version
1.1) as defined in NOST report [1]. Nevertheless the user may be
aware of some limitations (some of which are unavoidable with such a
"flexible" format as FITS):
- It is still possible to produce a non-standard FITS file because
(for obvious efficiency reasons) routines in this package cannot
check everything. At least, FITS routines check that compliant
FITS keywords are used and that mandatory cards (SIMPLE/XTENSION,
BITPIX, NAXIS, ...) get written in the correct order and with
correct value types (see fits_set). Nevertheless, the user has to
know only very little about FITS standard to be able to produce
valid FITS files.
- In this version of the package, headers of any FITS extension can
be read/produced but you can only read/write Yorick array data or
binary tables, i.e. corresponding to primary data and FITS "IMAGE"
or "BINTABLE" extensions (see fits_read_array, fits_write_array,
fits_read_bintable, and fits_write_bintable). Support for standard
extensions (such as ASCII table "TABLE") is planned but not yet
done.
- There is no special handling of IEEE special values NaN,
+/-Infinity (using such values is likely to raise a floating point
error catched by Yorick).
- You cannot read/write compressed FITS files. You'll have to
pre-decompress or post-compress files (you can use Yorick "system"
function to that end).
- It is (not yet) possible to re-open an existing FITS file to modify
it. But it would be very easy to allow for appending extensions to
an existing file (should be provided very soon).
Some simple driver routines are provided to allow for reading/writing
Yorick arrays from/to FITS file and may be sufficient for basic usage
(see fits_read and fits_write).
READING AN EXISTING FITS FILE
There is a simplified driver fits_read (which see) to read data in an
existing FITS file. The following example demontrates how to read the
contents of a FITS file with the basic routines:
fh = fits_open(name); // open existing file and read
// header of 1st (primary) HDU
data1 = fits_read_array(fh); // read all "image" data in 1st HDU
slice = fits_read_array(fh, which=n); // read N-th data slice in current
// HDU
fits_next_hdu, fh; // move to next HDU and read header
data2 = fits_read_array(fh); // read data of secondary HDU
...;
CREATING A NEW FITS FILE:
There is a (very) simplified driver fits_write (which see) to create a
new FITS file to store a Yorick array. The following examples
demontrate how to write a moderately complex FITS file with the basic
routines (assuming DATA1 is a 2-dimensional array):
fh = fits_open(name, 'w'); // create new file
fits_set, fh, "SIMPLE", 'T', "true FITS file";
fits_set, fh, "BITPIX", bitpix, "bits per pixel";
fits_set, fh, "NAXIS", naxis, "number of dimensions";
fits_set, fh, "NAXIS1", dim1, "length of 1st dimension";
fits_set, fh, "NAXIS2", dim2, "length of 2nd dimension";
fits_set, fh, "EXTEND", 'T', "this file may contain FITS extensions";
fits_set, fh, ... // set any number of other cards with
... // several calls to fits_set
fits_write_header, fh; // write header part of current HDU
fits_write_array, fh, data1; // write data part of current HDU
fits_new_hdu, fh, "IMAGE"; // append new "IMAGE" extension
fits_set, fh, "BITPIX", bitpix, "bits per pixel";
fits_set_dims, fh, dimsof(data2); // set all dimensions in one call
fits_set, fh, ... // set any number of other cards with
...
fits_write_header, fh; // write header part of extension
fits_write_array, fh, data2; // write data part of extension
fits_close, fh; // close stream of FITS handle, the
// header can still be examined
Note that the cards with the dimensions of the data array (NAXIS,
NAXIS1, ...) which are explicitly set with fits_set for the primary
header can also be instanciated in a more simple way thanks to the
function fits_set_dims as shown for the second HDU.
Alternatively, The function fits_create can be used to open a new file
and setup a basic primary header. In this case, the first lines of
the above examples become:
fh = fits_create(name, 'w', extend=1,
bitpix=fits_bitipix_of(data1),
dimslist=dimsof(data1));
fits_set, fh, ... // set any number of other cards with
... // several calls to fits_set
fits_write_header, fh; // write header part of current HDU
fits_write_array, fh, data1; // write data part of current HDU
If you intend to write more than one HDU, do not forget to set card
EXTEND to true in the primary header (this is done in the two examples
above with fits_open and with fits_create).
LIST OF ROUTINES
By convention, in this Yorick package, all public symbols (routines or
variables) are prefixed with "fits_" and all private symbols are
prefixed with "_fits_". The following (public) routines are provided:
File routines:
fits_check_file - check whether a file may be a FITS file
fits_open - open existing FITS file or create new FITS file
fits_close - close file stream in FITS handle
fits_create - creates a new FITS file with minimal header
fits_filename - get full path name of FITS stream
Header/HDU routines:
fits_current_hdu - returns number of current HDU
fits_goto_hdu - go to a given HDU number
fits_list - get list of extensions in a FITS file
fits_next_hdu - move to next HDU and parse the header part
fits_pad_hdu - pad current HDU to a multiple of 2880 bytes
fits_rewind - goto first (primary) HDU
fits_new_hdu - start a new FITS extension
fits_read_header - read header part of current HDU
fits_write_header - write header part of current HDU
Card routines:
fits_delete - delete card(s) from header of current HDU
fits_get - get value of FITS card(s) in current HDU
fits_get_bitpix - get BITPIX value
fits_get_bscale - get BSCALE value
fits_get_bzero - get BZERO value
fits_get_cards - get all cards matching a pattern
fits_get_comment - get value(s) of COMMENT card(s)
fits_get_coordinate - get coordinate information for a given axis
fits_get_data_size - get size of data part in current HDU.
fits_get_dims - get dimension list of array data
fits_get_gcount - get GCOUNT value
fits_get_history - get value(s) of HISTORY card(s)
fits_get_keywords - get list of defined keywords
fits_get_naxis - get NAXIS value
fits_get_pcount - get PCOUNT value
fits_get_xtension - get name of FITS primary/extension HDU
fits_move_card - move FITS card
fits_parse - parse FITS card(s)
fits_set - set value of FITS card(s) in current HDU
fits_set_dims - set FITS card(s) for dimension list of array
Reading/writing data (also see binary table routines):
fits_read - simple driver to read "IMAGE" or "BINTABLE" data
fits_write - simple driver to write "IMAGE" data
fits_new_image - creates a new "IMAGE" HDU
fits_read_array - read array data from current HDU
fits_write_array - write array data in current HDU
Binary tables:
fits_new_bintable - creates a new "BINTABLE" HDU
fits_read_bintable - read binary table from current HDU
fits_write_bintable - write binary table in current HDU
fits_pack_bintable - make table columns into a single array
Expert users routines:
fits_get_special - get FITS value of mandatory FITS key
fits_init - (re)initialize FITS internals
fits_id - get numerical identifier of a single card
fits_ids - get numerical identifier of FITS card(s)
fits_key - converts numerical identifier into string
fits_match - find FITS card(s) which match a pattern
fits_rehash - recalculate the numerical identifiers of cards
Miscellaneous routines:
fits_best_scale - compute best BSCALE and BZERO parameters
fits_bitpix_info - get description of FITS bits-per-pixel value
fits_bitpix_of - compute FITS bits-per-pixel value
fits_bitpix_type - convert FITS bits-per-pixel value to data type
fits_check_bitpix - test if FITS bits-per-pixel value is valid
fits_date - get current time as standard FITS date string
fits_is_integer - checks whether argument is integer
fits_is_integer_scalar - checks whether argument is integer scalar
fits_is_real_scalar - checks whether argument is real scalar
fits_is_scalar - checks whether argument is scalar or not
fits_is_string_scalar - checks whether argument is scalar string or not
fits_map - map scalar function onto array argument
fits_move - move element of an array in-place
fits_nth - format a string in the form: "1st", "2nd", ...
fits_tolower - convert string(s) to lower case letters
fits_toupper - convert string(s) to upper case letters
fits_trim - removes trailing spaces
CHANGES WITH RESPECT TO "OLD" FITS PACKAGES
This package is intended to be used in place of the old "fits.i"
(written by me and distributed along with Yorick) which had too many
limitations and restrictions to allow for further extensions. However
the API provided by this novel package is quite different from the old
one (in particular the FITS header is no longer stored into a Yorick
structure but in some "opaque" object: a FITS handle). Hopefully the
new package provides all the routines needed to deal with this opaque
handle but the name of the routines (all prefixed with "fits_") and
their calling sequences have changed.
The new FITS interface was written with the aim of being:
(1) conformable with FITS standards (although try to be not too strict
when _reading_ files)
(2) flexible and extensible
(3) fast (e.g. fits_get takes ~ 150 microseconds for a FITS header
with 200 cards on an PIII @ 1GHz)
FITS HANDLE
In this package, a FITS handle (denoted FH in the documentation) to a
FITS file is intended to be an "opaque" object. Actually, it is a
list of 4 items organized as follow:
_lst(cards, ids, descr, stream)
cards = vector of strings which are the header cards of the
current HDU;
ids = vector of card identifier values (this is for fast search
of cards);
descr = descriptor, vector of long integers:
DESCR(1)= current HDU number (1 for primary HDU);
DESCR(2)= file address of the current HDU
DESCR(3)= file address of the data part for the current HDU
DESCR(4)= file address of the next HDU in read mode,
number of written bytes in write mode
DESCR(5)= file mode: 'r' (read) or 'w' (write)
stream = void (no associated file) or stream for input or output;
Of course the end-user should never directly access the items of the
FITS handle but rather use the provided FITS routines (so that, in
order to warant portability of the user level code, it will be
sufficient to only modify routines in this package whenever the
internals of the FITS handle change).
WISH LIST
The following is a list of missing features or things I would like to
test:
1. Implement support for "random groups" records (FITS keywords
GROUPS, PCOUNT and GCOUNT) and other "standard" FITS extensions
(only "IMAGE" and "BINTABLE" are implemented): ASCII table, ...
2. Extensively test the package (this is mainly because I lack
of sample FITS files written by other software).
3. Deal with compressed FITS files; this will be possible thanks to
the "channel" interface in Yeti (my own extension of Yorick).
4. Enhance the consistency checks (for instance, in the current
version, you can read/write an "image" into a "table" extension).
GLOSSARY
HDU - Header and Data Unit
Indexed Keyword -
REFERENCES
[1] "Definition of Flexible Image Transport System (FITS)", NASA/Science
Office of Standards and Technology, report NOST 100-1.1, September 29,
1995.
[2] "A User's Guide for the Flexible Image Transport System (FITS)"
http://archive.stsci.edu/fits/users_guide/
|
fits_best_scale
|
fits_best_scale(bitpix, data)
-or- fits_best_scale(bitpix, cmin, cmax)
Returns [BSCALE,BZERO] where BSCALE and BZERO are optimal values for
rescaling to BITPIX file type. BITPIX must correspond to an integer
type (BITPIX = 8, 16 or 32). The array DATA contains all the physical
values to save to the file; alternatively, CMIN and CMAX give the
minimal and maximal values in physical data.
|
SEE ALSO:
|
fits,
fits_write
|
fits_bitpix_of
|
fits_bitpix_of(x)
-or- fits_bitpix_of(x, native=1)
Return FITS bits-per-pixel value BITPIX for binary data X which can be
an array or a data type (structure definition). If keyword NATIVE is
true, the routine assumes that binary data will be read/write to/from
FITS file using native machine data representation. The default is to
conform to FITS standard and to assume that XDR binary format will be
used in FITS file.
|
SEE ALSO:
|
fits,
fits_bitpix_type,
fits_check_bitpix
|
fits_check_file
|
fits_check_file(filename)
-or- fits_check_file(filename, errmode)
Returns 1/0 depending whether FILENAME is a valid FITS file or not.
If ERRMODE is true (non-nil and non-zero), unreadable file results in
false result otherwise it is a runtime error. Note that the checking
is very simple: it is sufficient that the first FITS card in the first
2880 bytes has keyword "SIMPLE" with logical value 'T' (true).
|
SEE ALSO:
|
fits
|
fits_close
|
fits_close(fh)
Closes stream in FITS handle FH. The header information stored in FH
remain unchanged (e.g. you can keep editing the header in FH). The
returned value is FH. Note that if you destroy all references to
handle FH, the associated file (if any) gets automatically closed by
Yorick.
|
SEE ALSO:
|
fits,
fits_pad_hdu,
fits_open,
close
|
fits_create
|
fits_create(filename)
Creates a new FITS file FILENAME and returns a FITS handle with
mandatory cards (i.e. SIMPLE, BITPIX, NAXIS, NAXISn) and some optional
cards (i.e. EXTEND, BSCALE and BZERO) already initialized.
Keyword BITPIX can be used to set FITS "bits-per-pixel" (default
is BITPIX=8, i.e. byte data).
Keyword DIMLIST should be used to specify the dimension list of the
array data that is intended to be written in primary HDU. The value
of DIMLIST is similar to the result returned by dimsof.
Keyword EXTEND can be used to indicate whether the file may contains
FITS extensions. It is probably a good idea to always use EXTEND=1.
Keyword TEMPLATE can be set with an existing FITS handle to copy some
FITS cards of the template into the new header. The FITS card that
are _never_ copied are: "SIMPLE", "XTENSION", "BITPIX", "NAXIS",
"NAXIS#" (with # an integer), "BSCALE" and "BZERO"; the other cards
get copied. See keywords BSCALE and BZERO if you specifically want to
set these values.
Keywords BSCALE and BZERO can be used to specify physical value scale
and offset. See fits_write_array to figure out how keywords BITPIX,
BSCALE and BZERO are used to convert data values into file values.
Keywords HISTORY and COMMENT can be set to add some comments in the
new handle. The values of these keywords may be array of strings.
Keywords ENCODING and OVERWRITE have the same meaning as in fits_open
routine (to see).
|
SEE ALSO:
|
fits,
fits_open,
fits_set,
fits_set_dims
|
fits_date
|
fits_date()
Returns current Universal Time date as a string conforming to FITS
standard: "DD/MM/YY"
|
SEE ALSO:
|
fits,
rdline,
popen
|
fits_delete
|
fits_delete, fh, pattern;
Delete all cards matching PATTERN from current header of FITS handle
FH (see fits_match for the syntax of PATTERN).
|
SEE ALSO:
|
fits,
fits_match
|
fits_filename
|
fits_filename(fh)
Return path name of file associated with FITS handle FH (in fact the
argument may also be any Yorick open stream).
|
SEE ALSO:
|
fits
|
fits_get
|
fits_get(fh, pattern, comment)
Get (array of) value(s) for FITS cards matching PATTERN (see
fits_match) in current header of FITS handle FH. If present, argument
COMMENT is an output symbol where the corresponding comment part of
selected card(s) will be stored. In order to avoid namespace clash
due to Yorick's scoping rules, COMMENT should be declared as a local
symbol in the calling function, e.g.:
local comment;
value = fits_get(fh, pattern, comment);
If no cards match PATTERN, the value of keyword DEFAULT is returned
and COMMENT is set to the null string.
If multiple cards match PATTERN, they must have the same value type
unless keyword PROMOTE is true, in which case the routine promotes all
card values to a suitable "highest" type.
Request fo commentary cards (i.e. PATTERN is "HISTORY", "COMMENT", or
"") may returns several cards.
|
SEE ALSO:
|
fits,
fits_match,
fits_parse
|
fits_get_bscale
|
fits_get_bscale(fh)
-or- fits_get_bzero(fh)
Get BSCALE and BZERO values for FITS handle FH. These parameters are
used to convert file values into physical values according to:
physical_value = BZERO + BSCALE * file_value
if the corresponding card is missing, BSCALE and BZERO default to 1.0
and 0.0 respectively.
|
SEE ALSO:
|
fits,
fits_get,
fits_read_array,
fits_write_array
|
fits_get_cards
|
fits_get_cards(fh, pattern);
Return cards from FITS handle FH which match PATTERN (see fits_match
for the syntax of PATTERN).
|
SEE ALSO:
|
fits,
fits_match
|
fits_get_data_size
|
fits_get_data_size(fh)
-or- fits_get_data_size(fh, fix)
Computes the number of bytes in data part of current HDU of FITS
handle FH. This value is computed according to the header part of FH
and may be different from the number of bytes actually written in the
data part of the current HDU.
|
SEE ALSO:
|
fits,
fits_read_header
|
fits_get_dims
|
fits_get_dims(fh)
-or- fits_get_dims(fh, fix)
Get all NAXIS* values from current HDU in FITS handle FH and return
vector [NAXIS, NAXIS1, NAXIS2, ...]. If the value of any of the
"NAXIS#" card is zero, then there is no data in the current unit and
fits_get_dims returns [] (nil) in this case. See fits_get_special for
the meaning of FIX.
|
SEE ALSO:
|
fits,
fits_get_special,
fits_get_bitpix,
fits_get_naxis
|
fits_get_gcount
|
fits_get_gcount(fh)
-or- fits_get_pcount(fh)
Get PCOUNT and GCOUNT values for FITS handle FH. PCOUNT shall be an
integer equal to the number of parameters preceding each group
(default value 0). GCOUNT shall be an integer equal to the number of
random groups present (default value 1). The total number of bits in
the data array (exclusive of fill that is needed after the data to
complete the last record) is given by the following expression:
NBITS = abs(BITPIX)*GCOUNT*(PCOUNT + NAXIS1*NAXIS2*...*NAXISm)
|
SEE ALSO:
|
fits,
fits_get,
fits_get_bitpix,
fits_read_array,
fits_write_array
|
fits_get_keywords
|
fits_get_keywords(fh)
-or- fits_get_keywords(fh, ordered)
Get list of FITS keywords defined in current HDU of FITS handle HF.
The returned value is an array of strings. If ORDERED is true (non-nil
and non-zero), the keywords get sorted. Note: the "END" keyword is
always missing in a (non-corrupted) FITS handle.
|
SEE ALSO:
|
fits,
sort,
strtok
|
fits_get_special
|
fits_get_special(fh, key, id, location, fix)
Get value of a special FITS card given its key string, numerical
identifier and absolute LOCATION (1 for first FITS card). If FIX is
true, various further verifications are made and, if FITS strict
checking mode is off, the header may be fixed in case of unambiguous
error.
|
SEE ALSO:
|
fits,
fits_get_bitpix,
fits_get_naxis,
fits_get_dims,
fits_parse
|
fits_get_xtension
|
fits_get_xtension(fh)
Get XTENSION value from current HDU in FITS handle FH. The returned
value is a scalar string with the name of the extension; "IMAGE" is
returned for the primary HDU.
|
SEE ALSO:
|
fits,
fits_get,
fits_parse
|
fits_goto_hdu
|
fits_goto_hdu(fh, hdu)
Move FITS handle FH to Header Data Unit number HDU (starting at 1 for
the primary HDU) and parse the header part of the new unit. Contents
of FH is updated with header part of new HDU. To allow for linked
calls, the returned value is FH.
|
SEE ALSO:
|
fits,
fits_next_hdu,
fits_read_header,
fits_rewind
|
fits_ids
|
fits_id(card)
-or- fits_ids(cards)
Convert FITS card(s) or FITS card name(s) into unique numerical
identifier. CARD is a scalar string and CARDS (with an S) is an array
of string(s) (including a scalar). Only the keyword part (characters
1:8) of CARD(S) is relevant; cards shorter than 8 characters yield the
same identifier as if they were padded (right filled) with spaces. In
other words, all the values returned by the following expressions are
identical:
fits_id("SIMPLE = T / conforming FITS file");
fits_id("SIMPLE ");
fits_id("SIMPLE");
|
SEE ALSO:
|
fits,
fits_key,
fits_rehash
|
fits_info
|
fits_info, fh;
-or- fits_info, fh, hdu
-or- fits_info, filename;
-or- fits_info, filename, hdu;
Prints header contents of current HDU in FITS handle FH or all HDU's
in FITS file FILENAME. If argument HDU is given, only this header unit
get printed out (HDU may be an array).
|
SEE ALSO:
|
fits,
fits_open
|
fits_init
|
fits_init;
(Re)initializes FITS private data. Normally you do not have to call
this routine because this routine is automatically called when
"fits2.i" is parsed by Yorick. You may however need to explicitely
call fits_init if you suspect that some FITS private data get
corrupted or if you want to tune FITS strict/sloopy behaviour.
If keyword SLOOPY is true (non-nil and non-zero) some discrepancy is
allowed (for reading FITS file only); otherwise strict FITS compliance
is applied. If SLOOPY is true, lower case Latin letters have the same
meaning as their upper case counterparts, most control characters
become identical to regular spaces.
According to FITS standard, the only characters permitted for keywords
are upper case (capital) Latin alphabetic, numbers, hyphen, and
underscore. Leading and embedded blanks are forbidden. If you cannot
read a FITS file because it does not confrom to this rule, you can use
keyword ALLOW (a string or an array of characters) to allow additional
characters for FITS keywords. For instance:
fits_init, allow="/."; // fix for invalid headers made by IRAF
make characters '/' and '.' acceptable in FITS keywords. Note that
you must apply fits_rehash (to see) to _every_ FITS handle in use
whenever you change the set of allowed characters (because this will
probably corrupt the values of numerical identifiers of FITS card) ...
It is therefore a good idea to change the set of allowed characters
before using any FITS routines.
Keyword BLANK can be used to add more characters that should be
considered as blanks (spaces) when parsing FITS header/keywords. The
value of BLANK must be a string or an array of characters, for
instance: BLANK="\t\r\v\n". Note that this break strict compliance to
FITS standard.
|
SEE ALSO:
|
fits,
fits_rehash
|
fits_key
|
fits_key(id)
Convert (array of) FITS numerical identifier(s) ID into the
corresponding string FITS keyword(s) without trailing spaces.
|
SEE ALSO:
|
fits,
fits_id
|
fits_list
|
fits_list, fh;
-or- fits_list(fh)
Get the names of the FITS extensions in FH. FH can be the name of a
FITS file or a FITS handle FH (the input handle is left unchanged).
When called as a subroutine, the list is printed to terminal; when
called as a function, the returned value is a string array with the
names of the FITS extensions in FH.
|
SEE ALSO:
|
fits,
fits_read_header,
fits_next_hdu
|
fits_map
|
fits_map(op, src)
Map scalar function OP onto array argument SRC to mimics element-wise
unary operation.
|
SEE ALSO:
|
fits
|
fits_move
|
fits_move, a, i, j;
Move I-th element of array A in place of J-th element. The operation
is done in-place.
|
SEE ALSO:
|
fits,
fits_move_card
|
fits_move_card
|
fits_move_card(fh, from, to);
Change location of FROM-th card to index TO into FITS handle FH. The
operation is made in place.
|
SEE ALSO:
|
fits,
fits_move
|
fits_new_bintable
|
fits_new_bintable(fh)
-or- fits_new_bintable(fh, comment)
Starts a new binary table FITS extension. This routine starts a new
FITS extension with name "BINTABLE" and pre-set FITS cards needed to
describe the table with fake values (the correct values will be set
when fits_write_bintable is called to actually write the table).
After calling this routine, the user can add new FITS cards (but not
XTENSION, BITPIX, NAXIS, NAXIS1, NAXIS2, GCOUNT, nor PCOUNT).
Optional argument COMMENT is the comment string for the XTENSION card.
The returned value is FH.
|
SEE ALSO:
|
fits,
fits_write_bintable
|
fits_new_hdu
|
fits_new_hdu(fh, xtension)
-or- fits_new_hdu(fh, xtension, comment)
Starts a new extension in FITS file open for writing. FH is the FITS
handle, XTENSION is the name of the FITS extension and COMMENT is an
optional string comment. After calling fits_new_hdu, there is no need
to call:
fits_set, FH, "XTENSION", XTENSION, COMMENT;
since this is already done by this routine. However, beware that FITS
standard requires that, if any extension is present in the file, that
the keyword "EXTEND" with logical value 'T' (true) must appear in the
primary header.
|
SEE ALSO:
|
fits,
fits_pad_hdu,
fits_set,
fits_write_header,
fits_write_array
|
fits_new_image
|
fits_new_image(fh, data)
-or- fits_new_image(fh, bitpix=..., dimlist=...)
Starts a new image (array) FITS extension in handle FH and returns FH.
This routine starts a new FITS extension with name "IMAGE" and pre-set
FITS cards needed to describe the array data according to keywords:
BITPIX, DIMLIST, BZERO, and BSCALE. If argument DATA is given, it is
used to guess the bits per pixel and the dimension list if not
specified by the keywords BITPIX and DIMSLIST respectively.
|
SEE ALSO:
|
fits,
fits_write_array
|
fits_next_hdu
|
fits_next_hdu(fh)
Move FITS handle FH to next Header Data Unit and parse the header part
of the new unit. Contents of FH is updated with header part of new
HDU. To allow for linked calls, the returned value is FH.
|
SEE ALSO:
|
fits,
fits_goto_hdu,
fits_read_header,
fits_rewind
|
fits_nth
|
fits_nth(n)
Returns a string in the form "1st", "2nd", "3rd" or "#th" where # is
the human readable value of integer N.
|
SEE ALSO:
|
fits,
fits_set_dims
|
fits_open
|
fits_open(filename)
-or- fits_open(filename, filemode)
Opens the FITS file FILENAME according to FILEMODE. The returned
value is a FITS handle used in most other FITS routines. FILEMODE is
one of:
"r" or 'r' - read mode, the header of the primary HDU get read and
is parsed.
"w" or 'w' - write mode, new file is created (unless keyword
OVERWRITE is true, FILENAME must not already exists).
"a" or 'a' - append mode, stream get positionned at last HDU, the
header of the last HDU get read and parsed.
The default FILEMODE is "r" -- open an existing FITS file for reading.
Keyword ENCODING can be used to change the data encoding of the FITS
file which is "xdr" for a regular FITS file (XDR means eXternal Data
Representation, which is natively used by all IEEE compliant big
endian machine). The value of the keyword is a string like:
"xdr", "sun" - eXternal Data Representation (the default)
"native" - native data representation (i.e. no conversion)
"i86", "pc" - IEEE little endian machines
...
see documentation for "__sun" for a list of supported encodings. Note
that using an encoding different from IEEE big endian (or XDR)
violates FITS standard.
Keyword OVERWRITE can be used to force overwriting of an existing file
(otherwise it is an error to create a file that already exists).
|
SEE ALSO:
|
fits,
fits_read_header,
fits_write_header,
fits_get,
fits_set,
fits_read_array,
fits_write_array,
fits_next_hdu,
fits_new_hdu,
fits_rewind,
__sun
|
fits_pack_bintable
|
fits_pack_bintable(ptr)
-or- fits_pack_bintable(ptr(list))
Packs binary table PTR into a single array; PTR must be a pointer
array (e.g. as the one returned by fits_read_bintable which see). The
argument can be PTR(LIST) to select or re-order some fields: LIST is a
vector of indices of selected and re-ordered fields. The returned
array is NROWS-by-NCOLS where NROWS is the first dimension of all
fields (which must be the same) and NCOLS is the sum of the second
dimension of all fields.
|
SEE ALSO:
|
fits_read_bintable
|
fits_pad_hdu
|
fits_pad_hdu(fh)
Fix file size in handle FH to a multiple of FITS blocking factor (2880
bytes) by writting null or space characters at the end of the file and
update FH offsets accordingly. FH must be open for writing.
|
SEE ALSO:
|
fits,
fits_close,
fits_new_hdu
|
fits_read
|
fits_read(filename)
-or- local fh; a = fits_read(filename, fh)
Open FITS file FILENAME and read data. FH is an optional output
symbol where the FITS handle will be stored for future use such as
moving to a FITS extension in the same file and reading its
header/data. (Note: a FITS handle is a Yorick list that contains a
file handle and all header information from the current HDU.)
By default, the data get read from the first HDU but this can be
changed with the HDU keyword (default HDU=1, i.e. primary HDU).
Keyword ENCODING has the same meaning as in fits_open (which see).
Keywords WHICH and RESCALE have the same meaning as in fits_read_array
(which see). These keywords are ignored if HDU to read is not primary
HDU nor an "image" extension.
Keywords PACK and SELECT have the same meaning as in
fits_read_bintable (which see).
|
SEE ALSO:
|
fits,
fits_write,
fits_open,
fits_read_array,
fits_read_bintable
|
fits_read_array
|
fits_read_array(fh)
Gets "image" (actually a Yorick array) from current HDU of FITS handle
FH. Note that the result may be [] (nil) if the current unit contains
no data.
Keyword WHICH may be used to indicate which sub-array should be
returned. WHICH always applies to the last dimension of the "image"
data stored in current HDU. For instance, if the array DATA with
dimensions (235,453,7) is stored in the current FITS HDU, the
sub-array DATA(,,4) can be obtained by:
fits_read_array(FH, which=4);
If keyword RESCALE is true, returned values get rescaled according to
FITS keywords BSCALE and BZERO. If RESCALE=2 and one of BSCALE and/or
BZERO exists in the FITS header and BITPIX was 8, 16, 32, or -32, a
single precision array (float) is returned. If RESCALE is not set
(nil), the default is to rescale data values if BSCALE is not 1 or
BZERO is not 0 (i.e. the default is RESCALE=1). In order to get raw
data (i.e. as written in the file), use RESCALE=0.
|
SEE ALSO:
|
fits,
fits_open
|
fits_read_bintable
|
fits_read_bintable(fh)
Reads a binary table in current HDU of FITS handle FH and returns the
fields of the table as a pointer array (i-th field of the table is
pointed by i-th pointer element). Empty fields and fields for
unsupported data types (bit array and array descriptor) result in a
null pointer (&[]). The geometry of the arrays pointed by the result
will be NROWS-by-NCOLS(i) where NROWS is the number of rows in the
table and NCOLS(i) is the repeat count of the i-th field in the table
(see fits_write_bintable). If NCOLS(i) = 1, the i-th pointer element
is the address of a NROWS vector, i.e. not a NROWS-by-1 array.
Keyword SELECT can be used to retain only some fields (or re-order
them) of the table. For instance, use SELECT=[2,5,3] to return only
2nd, 5th and 3rd fields (in that order) of the table. The fields can
also be selected by their names, e.g. SELECT=["flux","distance"] (note
that trailing spaces and case is not significant for the field names).
If keyword PACK is true, fits_pack_bintable (which see) is used to
pack the columns of the binary table into a single array (possibly
after selection/re-ordering by SELECT).
If keyword TRIM is true, then trailing spaces get removed from string
fields (this has no effect if RAW_STRING is true).
If keyword RAW_STRING is true, fields made of char's ('A' format) are
returned as arrays of char's. The default is to convert 'A' format
fields into 1-by-NROWS array of strings.
If keyword RAW_LOGICAL is true, logical fields ('L' format) are
returned as arrays of char's. The default is to convert 'L' format
fields into array of int's as follows: 'T' -> 1 (true), 'F' -> 0
(false), and any other character -> -1 (bad). The 'bad' value can be
set by keyword BAD (default is -1).
|
SEE ALSO:
|
fits,
fits_write_bintable,
fits_pack_bintable
|
fits_read_bintable_as_hashtable
|
fits_read_bintable_as_hashtable(fh)
-or- fits_read_bintable_as_hashtable(fh, h)
Read binary table in current HDU (see fits_read_bintable) of FITS
handle FH and make it into a hash table. If optional argument H is
given, it must be an existing hash table to be augmented with the
contents of the binary table. The (augmented) hash table is returned.
This function can only be used with the hash table extension.
The members of the hash table get named after the value of the
'TTYPEn' card converted to lowercase (where n is the field number).
For missing 'TTYPEn' cards, the value of keyword FORMAT is used to
define the member name as swrite(format=FORMAT,n). The default value
for FORMAT is "_%d". If FORMAT is specified, it must contain exactly
one directive to write an integer and no other format directives. If
a card 'TUNITn' exists, its value is stored into member with "_units"
appended to the corresponding field name.
Keywords SELECT, RAW_STRING, RAW_LOGICAL and BAD have the same meaning
as in fits_read_bintable.
|
SEE ALSO:
|
fits_read_bintable,
swrite,
h_new
|
fits_read_header
|
fits_read_header(fh)
(Re)read and parse header of current HDU of FITS handle FH.
Contents of FH is updated with header part of new HDU. To allow
for linked calls, the returned value is FH. If the current HDU
is empty (i.e. last HDU in the file), the header will be empty.
|
SEE ALSO:
|
fits,
fits_open,
fits_read_array,
fits_next_hdu
|
fits_rehash
|
fits_rehash(fh);
(Re)compute array of numerical identifier for FITS handle FH (operation
is done in-place) and return FH.
|
SEE ALSO:
|
fits,
fits_id
|
fits_set
|
fits_set, fh, key, value;
-or- fits_set, fh, key, value, comment;
Set (or adds) FITS card in header of FITS handle FH. KEY is the card
name (FITS keyword) and must be a scalar string, VALUE is the scalar
value of the card and COMMENT is an optional string comment.
Commentary cards -- for which KEY is one of "COMMENT, "HISTORY" or ""
(blank) -- get appended to the existing cards in the header of FH (if
the VALUE of a commentary card is too long, it may occupy several FITS
cards). For any other kind of cards, the new card replaces the
existing one, if any; or get appended to the existing cards. Special
cards that must appear in a precise order ("SIMPLE", "BITPIX", "NAXIS"
and "NAXIS#") must be added in the correct order (their value can be
modified afterward). The "END" card is not needed since it will be
automatically written when required.
|
SEE ALSO:
|
fits,
fits_open
|
fits_set_dims
|
fits_set_dims(fh, dimlist)
Set NAXIS and NAXIS1, NAXIS2, ... values into current HDU of FITS
handle FH according to dimension list DIMLIST. DIMLIST may be empty.
|
SEE ALSO:
|
fits,
fits_get_dims
|
fits_tolower
|
fits_tolower(s)
-or- fits_toupper(s)
Converts a string or an array of strings S to lower/upper case letters.
|
SEE ALSO:
|
fits,
fits_trim
|
fits_write
|
fits_write, filename, data;
-or- fits_write(filename, data)
Creates a new FITS file FILENAME and write array DATA in primary HDU.
When called as a function, the result is a FITS handle that can be
used to append extensions to the file.
FITS "bits-per-pixel" can be specified by keyword BITPIX; otherwise,
BITPIX is automatically guessed from the data type (see
fits_bitpix_of).
Keywords EXTEND, TEMPLATE, HISTORY COMMENT, BSCALE, BZERO, ENCODING
and OVERWRITE have the same meaning as in fits_create (to see).
If BITPIX is explicitely specified and corresponds to an integer file
type (8, 16 or 32) and neither BSCALE nor BZERO are specified, optimal
BSCALE and BZERO values will be automatically computed thanks to
fits_best_scale (which see).
|
SEE ALSO:
|
fits,
fits_best_scale,
fits_bitpix_of,
fits_create,
fits_write_header,
fits_write_array
|
fits_write_array
|
fits_write_array, fh, data;
Write array DATA into curent HDU of FITS handle FH. DATA is a
so-called "image" in FITS jargon but it can be a numerical array of
any-dimension. FITS cards BITPIX, BSCALE and BZERO are taken into
account to convert data values into file values. The file values are:
(DATA - BZERO)/BSCALE
with BZERO=0 and BSCALE=1 by default (i.e. if not found in FH) or if
keyword RESCALE is explicitely set to zero. The values are further
subject to rounding to the nearest integer and clipping for positive
BITPIX. If keyword RESCALE is explicitely set to false (zero), the
file values get written without BSCALE/BZERO scale conversion.
The N dimensions of DATA must match the values of the NAXIS1, NAXIS2,
..., NAXISn cards of the FITS file (it is assumed that the header
information stored in FH are synchronized to the header actually
written) extra dimensions in the FITS file are considered as possible
data slices. By default, the first data slice get written. Keyword
WHICH may be used to write a given slice of data. The value WHICH may
be less or equal zero to choose a slice with respect to the last one.
EXAMPLE:
The following example creates a FITS file with a 100-by-45-by-4-by-7
"image" data made of random values computed and written one 100-by-45
slice at a time:
fh = fits_create("newfile.fits", bitpix=16, dimlist=[4,100,45,4,7],
bscale=1e-4, bzero=0.0);
fits_write_header, fh;
nslices = 4*7; // product of last FITS dimensions
for (i=1 ; i<=nslices ; ++i)
fits_write_array, fh, random(100, 45), which=i;
fits_close, fh;
|
SEE ALSO:
|
fits,
fits_write,
fits_write_header
|
fits_write_bintable
|
fits_write_bintable(fh, ptr)
Writes contents of pointer PTR in a binary table in FITS handle FH.
Arrays pointed by PTR become the fields of the table (in the same
order as in PTR) and must all have 1 or 2 dimensions with the same
first dimension (i.e. the number of rows in the table), second
dimensions can have any values and may all be different: they count as
the number of 'columns' of the field. In other words:
*PTR(i) = i-th field in the table, is an NROWS-by-NCOLS(i) array
where NROWS is the number of rows in the table and
NCOLS(i) is the repeat count of the i-th field; it can
also be simply a NROWS element vector if NCOLS(i) = 1.
In the current version of the routine, only arrays of numbers (char,
short, int, long, float, double or complex) and vectors of strings
(you can use several vectors to circumvent this limitation) are
supported. Before writing the data part of a binary table, you must
creates proper header:
fits_new_bintable, fh; // starts a new binary table
fits_set, fh, "...", ...; // (optional) set more info. in header
fits_set, ...;
fits_write_bintable, fh, ptr; // write binary table
fits_write_bintable automatically guess the format of the fields in
the binary table and accordingly set FITS cards "TFORM#" (with # equal
to the field number) in the header of the binary table.
If keyword LOGICAL is true (non nil and non-zero) then arrays of int's
in PTR are considered as logical arrays and saved as arrays of
characters: 'F' for false, 'T' for true or '\0' for bad/invalid value.
Following Yorick's convention, a "false" value is integer zero in the
arrays of int's and a "true" is any non-zero integer. However, if
LOGICAL has the special value 2, then strictly positive integers are
treated as "true" values and strictly negative integers are treated as
invlaid values. Note that this only affect arrays of int's (not
long's nor short's nor char's). The default is to save arrays of
int's as array of 32 bits integers.
The returned value is FH.
|
SEE ALSO:
|
fits,
fits_new_bintable,
fits_read_bintable
|
fits_write_header
|
fits_write_header(fh)
Write header information of FITS handle FH into current HDU of
associated file. It is possible to re-write header as long as this
would not overwrite existing written data if any (i.e. the new header,
rounded up to a multiple of 2880 bytes, must not be longer than the
old one or there must be no data written.
|
SEE ALSO:
|
fits,
fits_open,
fits_write,
fits_write_array
|
fitsHeader
|
obsolete FITS routines
In order to help you to upgrade your code and use the new FITS API,
you can use the following equivalence table:
fitsAddComment, hdr, str; ==> fits_set, fh, "COMMENT", str;
fitsAddHistory, hdr, str; ==> fits_set, fh, "HISTORY", str;
fitsWrite, name, data; ==> fits_write, name, data;
fitsWrite, name, data, hdr; ==> fits_write_array, fh, data;
fitsRead(name); ==> fits_read(name);
data = fitsRead(name, hdr); ==> data = fits_read(name, fh);
where NAME is the file name, STR is a string comment, HDR is the
header structure (obsolete but see fitsMakeOldHeader), FH is
the (new) FITS handle and DATA is an array of numbers.
The following old routines have no real equivalent:
fitsHeader
fitsFixHeader
fitsRescale
|
SEE ALSO:
|
fits
|
FitsHeader
|
FitsHeader - a Yorick structure defined to store (part of) FITS
header information. The structure has the following members:
bitpix - bits-per-pixel: 8 pixel values are unsigned bytes
16 pixel values are signed 2-byte integers
32 pixel values are signed 4-byte integers
-32 pixel values are 4-byte floating points
-64 pixel values are 8-byte floating points
naxis - number of axis
axis(k) - number of pixel along k-th axis
bscale - pixelValue = BZERO+BSCALE*fileValue
bzero - pixelValue = BZERO+BSCALE*fileValue
bunit - brightness unit
datamax - maximum data value in the file
datamin - minimum data value in the file
object - image name
date - date of file creation (dd/mm/yy)
date_obs - date of data acquisition (dd/mm/yy)
origin - institution
instrume - data acquisition instrument
telescop - data acquisition telescope
observer - observer name/identification
history - newline separated history lines
comment - newline separated comment lines
epoch - epoch of coordinate system (year)
crval(k) - coord = CRVAL+(pixel-CRPIX)*CDELT
crpix(k) - coord = CRVAL+(pixel-CRPIX)*CDELT
cdelt(k) - coord = CRVAL+(pixel-CRPIX)*CDELT
ctype(k) - type of physical coordinate
crota(k) - rotation angle of axis No. #
|
SEE ALSO:
|
fits,
fitsMakeOldHeader
|
|