section of routines in fits.i

functions in fits.i -

 
 
 
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  
     demontrates 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, extend=1,  
                        bitpix=fits_bitpix_of(data1),  
                        dimlist=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_groups     - get GROUPS value  
       fits_get_history    - get value(s) of HISTORY card(s)  
       fits_get_keywords   - get list of defined keywords  
       fits_get_list       - get list of integer values  
       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_scalar - checks whether argument is integer scalar  
       fits_is_real_scalar - checks whether argument is real scalar  
       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_trimright      - removes trailing spaces  
       fits_strcmp         - compare strings according to FITS conventions  
    Copy routines (can be used to perform editing of FITS files):  
       fits_copy_header    - copy header part of current HDU;  
       fits_copy_data      - copy header data of current HDU;, dst, src;  
       fits_copy_hdu       - copy current HDU;  
   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,  
                             total number of written bytes in write mode;  
                   DESCR(5)= file mode: 'r' (read), or 'w' (write), or 'a'  
                             (append).  
        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).  
   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_info


             fits_bitpix_info(bitpix)  
 
     Return string information about FITS bits-per-pixel value.  
SEE ALSO: fits,   fits_bitpix_of,   fits_bitpix_type,  
fits_check_bitpix  
 
 
 
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_bitpix_type


             fits_bitpix_type(bitpix)  
          or fits_bitpix_type(bitpix, native=1)  
 
     Returns Yorick data  type given by FITS bits-per-pixel  value BITPIX.  If  
     keyword NATIVE is true, return the native data type matching BITPIX.  
SEE ALSO: fits,   fits_bitpix_of,   fits_bitpix_info,  
fits_check_bitpix  
 
 
 
fits_check_bitpix


             fits_check_bitpix(bitpix)  
 
     Test if FITS bits-per-pixel value BITPIX is valid.  
SEE ALSO: fits,   fits_bitpix_of,   fits_bitpix_type,  
fits_bitpix_info  
 
 
 
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,   open  
 
 
 
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_copy_data


 fits_copy_data  
 
SEE fits_copy_header  
 
 
 
fits_copy_hdu


 fits_copy_hdu  
 
SEE fits_copy_header  
 
 
 
fits_copy_header


             fits_copy_header, dst, src;  
          or fits_copy_data, dst, src;  
          or fits_copy_hdu, dst, src;  
 
     For all  these routines, SRC (the  source) and DST  (the destination) are  
     FITS handles, DST must be write/append mode.  
     The routine fits_copy_header copies the header part of the current HDU of  
     SRC into  DST.  SRC  and DST  are both FITS  handles.  DST  must be  in a  
     "fresh"  state,   that  is  just   after  a  fits_open,   fits_create  or  
     fits_new_hdu.   Nothing is  actually written  to the  destination stream,  
     fits_write_header must  be used  for that.  The  idea is  that additional  
     keywords can  be set in DST  (for instance history or  comments) prior to  
     actually writing the header.  
     The routine fits_copy_data  copies (writes) the data part  of the current  
     HDU of  SRC into  DST.  DST must  be in  the same state  as just  after a  
     fits_write_header.  
     The routine fits_copy_hdu copies the header and data parts of the current  
     HDU of SRC into DST.  The  data is automatically padded with zeroes.  The  
     call fits_copy_hdu, DST, SRC; is identical to:  
       fits_copy_header, dst, src;  
       fits_write_header, dst;  
       fits_copy_data, dst, src;  
       fits_pad_hdu, dst;  
     When called as functions, all these routines return DST.  
   EXAMPLES:  
     To copy an HDU with a new HISTORY card:  
       fits_copy_header, dst, src;  
       fits_set, dst, "HISTORY", "This HDU is a copy.";  
       fits_write_header, dst;  
       fits_copy_data, dst, src;  
     To sequentially copy several HDU's, call fits_new_hdu with a NULL or  
     empty extension name:  
       // Open input and output FITS files:  
       src = fits_open("input.fits");  
       dst = fits_open("output.fits", 'w');  
       // Copy & edit primary HDU:  
       fits_copy_header, dst, src;  
       fits_set, dst, "HISTORY", "This primary HDU is a copy.";  
       fits_write_header, dst;  
       fits_copy_data, dst, src;  
       // Copy & edit extensions:  
       while (! fits_eof(fits_next_hdu(src))) {  
         fits_new_hdu, dst, "";  // add undefined extension  
         fits_copy_header, dst, src;  
         fits_set, dst, "HISTORY", "This extension HDU is also a copy.";  
         fits_write_header, dst;  
         fits_copy_data, dst, src;  
       }  
       fits_close, dst;  
SEE ALSO: fits_open,   fits_create,   fits_new_hdu,  
fits_write_header  
 
 
 
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_current_hdu


             fits_current_hdu(fh);  
 
     Return number of current Header Data Unit in FITS handle FH.  
SEE ALSO: fits,   fits_read_header,   fits_rewind,  
fits_next_hdu  
 
 
 
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_eof


             fits_eof(fh)  
 
     Returns non-zero if FITS handle FH is at end of file.  
SEE ALSO: fits,   fits_open,   fits_next_hdu  
 
 
 
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,   filepath  
 
 
 
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.  
     The data type of the returned  value depends on the particular card type:  
     a char  ('T' or  'F') is returned  for a  logical-valued card, a  long is  
     returned  for  an  integer-valued  card,  a  double  is  returned  for  a  
     real-valued card, a complex is returned for a complex-valued card (either  
     integer or floating point), and a  string is returned for a commentary or  
     a string-valued card.  Trailing spaces (which are irrelevant according to  
     FITS  specifications)   get  discarded   from  the  returned   value  for  
     string-valued cards (not commentary cards).  
     If multiple  cards match PATTERN, their  values must be of  the same 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_bitpix


             fits_get_bitpix(fh)  
          or fits_get_bitpix(fh, fix)  
 
     Get BITPIX value from current HDU in FITS handle FH.  See  
     fits_get_special for the meaning of FIX.  
SEE ALSO: fits,   fits_check_bitpix,   fits_get_special,  
fits_get_naxis,   fits_get_dims  
 
 
 
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_bzero


 fits_get_bzero  
 
SEE fits_get_bscale  
 
 
 
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_comment


 fits_get_comment  
 
SEE fits_get_history  
 
 
 
fits_get_coordinate


 fits_get_coordinate  
 
SEE fits_coordinate  
 
 
 
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  
 
SEE fits_get_groups  
 
 
 
fits_get_groups


             fits_get_groups(fh)  
          or fits_get_gcount(fh)  
          or fits_get_pcount(fh)  
 
     Get GROUPS, PCOUNT or GCOUNT values  for FITS handle FH.  GROUPS shall be  
     a logical value:  'T' (true), if the current HDU  contains a random group  
     extension; 'F' (false),  otherwise.  The default value for  GROUPS is 'F'  
     (false).  PCOUNT shall  be an integer equals 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).  When GROUPS is  
     false, 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)  
     where NAXISm  is the length  of the last  axis; for a random  group (i.e.  
     when GROUPS is true), NAXIS1=0 and the total number of bits is:  
         NBITS = abs(BITPIX)*GCOUNT*(PCOUNT + NAXIS2*...*NAXISm)  
SEE ALSO: fits,   fits_get,   fits_get_bitpix,  
fits_read_array,   fits_write_array  
 
 
 
fits_get_history


             fits_get_history(fh)  
          or fits_get_comment(fh)  
 
     Get COMMENT  and HISTORY  values for  FITS handle FH.   The result  is an  
     array of string(s)  or nil if no  such cards exists in the  header of the  
     current unit.  
SEE ALSO: fits,   fits_get,   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_list


             fits_get_list(fh, key)  
 
      Get value of FITS card KEY in FH and returns it as a vector of integers.  
      This function  is intended  to parse, e.g.  the TDIM# cards  in BINTABLE  
      extensions.  The syntax of the card must be a string of the form:  
        '(ARG1,ARG2,...)'  
      where ARG1, etc are human readable integer values.  
SEE ALSO: fits_get  
 
 
 
fits_get_naxis


             fits_get_naxis(fh)  
          or fits_get_naxis(fh, fix)  
 
     Get NAXIS value from current HDU in FITS handle FH.  See fits_get_special  
     for the meaning of FIX.  
SEE ALSO: fits,   fits_get_special,   fits_get_bitpix,  
fits_get_dims  
 
 
 
fits_get_pcount


 fits_get_pcount  
 
SEE fits_get_groups  
 
 
 
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 in  upper case  letters with  the name  of the  
     extension (without trailing spaces);  "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_id


 fits_id  
 
SEE fits_ids  
 
 
 
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_ignore_short_file


             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.  
     Variable fits_ignore_short_file can be set true to ignore short FITS file  
     when reading the header.  If fits_ignore_short_file is -1, short FITS file  
     are silently ignored.  Otherwise, if fits_ignore_short_file is non-zero,  
     a warning is printed.  
SEE ALSO: fits,   fits_open,   fits_read_array,  
fits_next_hdu  
 
 
 
fits_index_of_table_field


             fits_index_of_table_field(fh, name)  
 
     Returns index(es) of FITS table  columns with their TTYPE# value matching  
     array of  string(s) NAME.  The table  header is read from  current HDU of  
     FITS handle FH.  
SEE ALSO: fits,   fits_read_bintable  
 
 
 
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  "fits.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_is_integer_scalar


             fits_is_integer_scalar(x);  
          or fits_is_real_scalar(x);  
          or fits_is_string_scalar(x);  
 
     Check whether X is a scalar of integer/real/string type.  
SEE ALSO: is_scalar,   is_integer,   is_real,   is_string  
 
 
 
fits_is_integer_scalar


 fits_is_integer_scalar  
 
SEE fits_is_integer_scalar  
 
 
 
fits_is_real_scalar


 fits_is_real_scalar  
 
SEE fits_is_integer_scalar  
 
 
 
fits_is_real_scalar


 fits_is_real_scalar  
 
SEE fits_is_integer_scalar  
 
 
 
fits_is_string_scalar


 fits_is_string_scalar  
 
SEE fits_is_integer_scalar  
 
 
 
fits_is_string_scalar


 fits_is_string_scalar  
 
SEE fits_is_integer_scalar  
 
 
 
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_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).  
     "HIERARCH"  cards  are  supported.   The  '#' special  character  is  not  
     supported on them, though.  
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.  
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).   Second  
     argument LIST can be specified to select or re-order some fields: LIST is  
     a vector of indices of selected and re-ordered fields, the result will be  
     as  if PTR(LIST) was  given as  unique argument.   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_parse


             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  
     Trailing spaces  (which are irrelevant according  to FITS specifications)  
     get  discarded  from the  returned  value  for  string-valued cards  (not  
     commentary cards).  
     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_read


                       a = 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).  If data get  read from the primary  HDU or a  
     FITS image extension, the result  returned by the function fits_read() is  
     a  numerical array (see  fits_read_array); if  the data  get read  from a  
     binary  table  extension,  the  result  is  a  vector  of  pointers  (see  
     fits_read_bintable).  
     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 (n-th  field of  the  table is  
     pointed  by   n-th  pointer  element).   Empty  fields   and  fields  for  
     unsupported data types (bit array)  yield a null pointer value (&[]).  If  
     TDIMn  keyword  is  present,  then  the  dimensions  of  n-th  field  are  
     (NROWS,i,j,k,...)   where ROWS is  the number  of rows  in the  table and  
     '(i,j,k,...)' is  the value  of the TDIMn  keyword.  Otherwise,  the n-th  
     field is a NROWS-by-NCOLS(n) array  where NCOLS(n) is the repeat count of  
     the n-th  field in  the table (see  fits_write_bintable).  If  the repeat  
     count is 1 and  TDIMn is not set, the n-th field  is a NROWS vector; that  
     is, not a NROWS-by-1 array.  
     An empty table  (number of rows or number of fileds  less than one) yield  
     an empty result.  
     Keyword SELECT  can be used to retain  only some fields of  the table (or  
     re-order them).  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, for  instance: 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 NROWS vector 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  
 
SEE fits_ignore_short_file  
 
 
 
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_rewind


             fits_rewind(fh)  
 
     Move FITS handle FH to primary Header Data Unit and parse the header part  
     of the unit.  FH is returned when called as a function.  
SEE ALSO: fits,   fits_read_header,   fits_next_hdu  
 
 
 
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_strcmp


             fits_strcmp(a, b)  
 
     Returns non-zero  where (array of) strings A  and B are the  same in FITS  
     sense, i.e.,  ignore case and  trailing ordinary spaces (code  0x20). For  
     instance, "Hello" and "HELLO " are the same strings.  
SEE ALSO: fits,   strcase,   fits_toupper,   fits_trimright  
 
 
 
fits_tolower


 fits_tolower  
 
SEE fits_toupper  
 
 
 
fits_tolower


 fits_tolower  
 
SEE fits_toupper  
 
 
 
fits_toupper


 fits_toupper  
 
SEE fits_toupper  
 
 
 
fits_toupper


             fits_tolower(s);  
          or fits_toupper(s);  
 
     Converts a string or an array of strings S to lower/upper case letters.  
SEE ALSO: fits,   strcase,   fits_trimright  
 
 
 
fits_trimright


             fits_trimright(s)  
 
     Removes trailing  ordinary spaces (character  0x20) from string  array S.  
     Note that trailing spaces are usually not significant in FITS.  
SEE ALSO: fits,   fits_tolower,   fits_toupper,   strpart,  
strword  
 
 
 
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  
     If FITS cards "TFORM#" (with #  equal to the field number) already exists  
     in the current header,  fits_write_bintable checks the consistency of the  
     corresponding data  field in PTR (and performs  any required conversion);  
     otherwise, the format is automatically guessed and set accordingly 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.  
     If keyword FIXDIMS  is true (non nil and non-zero)  then the repeat count  
     in "TFORMn"  cards and  the dimension list  in the "TDIMn"  cards already  
     present  in the  header of  the current  HDU are  corrected to  match the  
     actual dimensions of the n-th columnin PTR.  
     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  
 
 
 
fitsMakeOldHeader


 fitsMakeOldHeader  
 
SEE fitsOldHeaderMembers  
 
 
 
fitsObsolete


 fitsObsolete  
 
SEE fitsHeader  
 
 
 
fitsOldHeaderKeywords


 fitsOldHeaderKeywords  
 
SEE fitsOldHeaderMembers  
 
 
 
fitsOldHeaderMembers


             fitsMakeOldHeader(fh)  
 
     Convert header information in FITS handle FH into the obsolete FitsHeader  
     structure.  
SEE ALSO: fits,   FitsHeader