section f of routines in fits.i

functions in fits.i - f

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/  
  Keyword,  defined at i/fits.i   line 96

fitsAddComment


    fitsAddComment

SEE fitsHeader

fitsAddComment


    fitsAddComment

SEE fitsHeader

fitsAddHistory


    fitsAddHistory

SEE fitsHeader

fitsAddHistory


    fitsAddHistory

SEE fitsHeader

fitsFixHeader


    fitsFixHeader

SEE fitsHeader

fitsFixHeader


    fitsFixHeader

SEE fitsHeader

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

fitsMakeOldHeader


    fitsMakeOldHeader  


Keyword,  defined at i/fits.i   line 3491

SEE fitsOldHeaderMembers

fitsObsolete


    fitsObsolete  


Keyword,  defined at i/fits.i   line 3391

SEE fitsHeader

fitsOldHeaderKeywords


    fitsOldHeaderKeywords  


Keyword,  defined at i/fits.i   line 3491

SEE fitsOldHeaderMembers

fitsOldHeaderMembers


    fitsMakeOldHeader(fh)  


Convert header information in FITS handle FH into the obsolete FitsHeader  
structure.  
  
Keyword,  defined at i/fits.i   line 3491

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.  
Interpreted function, defined at i/fits.i   line 627

SEE ALSO: fits, fits_pad_hdu, fits_open, close

fits_coordinate


    fits_coordinate  


struct fits_coordinate {  
  long axis, length;  
  string ctype;  
  double crpix, crval, cdelt, crota;  
}

fits_coordinate


    fits_get_coordinate(fh, axis)  


Gets AXIS-th coordinate information for current HDU in FITS handle FH.  
By  default, the  result  is a  fits_coordinate  structure defined  as  
follows:  
  struct fits_coordinate {  
    long axis;    // axis number  
    long length;  // number of elements along this axis  
    string ctype; // name of the coordinate represented by this axis  
    double crpix; // location of a reference point (starting at 1)  
                  // along this axis  
    double crval; // value of the coordinate along this axis at the  
                  // reference point  
    double cdelt; // partial derivative of the coordinate with respect  
                  // to the pixel index along this axis, evaluated at  
                  // the reference point  
    double crota; // used to indicate a rotation from a standard  
                  // coordinate system described by the value of CTYPE  
                  // to a different coordinate system in which the  
                  // values in the array are actually expressed  
  }  
If keyword  SPAN is true, then the  result is a vector  that gives the  
coordinate of each element along given axis:  
   CDELT*(indgen(LENGTH) - CRPIX) + CRVAL  
Note that, if the axis length is zero, a nil value is returned.

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.  
Interpreted function, defined at i/fits.i   line 2906

SEE ALSO: fits

fits_match


    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).  
Interpreted function, defined at i/fits.i   line 2972

SEE ALSO: fits, fits_get_cards, fits_rehash

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.  
Interpreted function, defined at i/fits.i   line 1212