
FITS(1.0)         MISC. REFERENCE MANUAL PAGES          FITS(1.0)

NAME
     _F_I_T_S _H_E_A_D_E_R _r_o_u_t_i_n_e_s:  fits_read_header, fits_write_header,
     fits_header_field,  fits_scan, fits_print, fits_copy_header,
     fits_create_header, fits_free_header.

     _F_I_T_S _M_A_T_R_I_X _r_o_u_t_i_n_e_s:  fits_read_matrix, fits_write_matrix,
     fits_get_matrix_value, fits_set_matrix_value,
     fits_create_matrix, fits_free_matrix, fits_insert_array

SYNOPSIS
     (compile with -lFITS)
     # include <fitsio.h>

      _F_I_T_S _H_e_a_d_e_r _R_o_u_t_i_n_e_s
          int   fits_read_header (filename, header)
          char      *filename;
          Header    *header;

          int   fits_write_header (filename, header)
          char      *filename;
          Header    *header;

          char *fits_header_field (header, field, N)
          Header    *header;
          char      *field;
          int        N;

          int   fits_scan   (header, field, mode, value, N)
          int   fits_print  (header, field, mode, value, N)
          int   fits_modify (header, field, mode, value, N)
          Header    *header;
          char      *field, *mode, *value;
          int        N;

          int   fits_create_header (header)
          Header    *header;

          int   fits_copy_header (header1, header2)
          Header    *header1;
          Header    *header2;

          int   fits_free_header (header)
          Header    *header;

      _F_I_T_S _M_a_t_r_i_x _R_o_u_t_i_n_e_s
          int   fits_read_matrix (filename, matrix)
          char      *filename;
          Matrix    *matrix;

          int   fits_write_matrix (filename, matrix)

Version 1.0        Last change: Sept 18, 1992                   1

FITS(1.0)         MISC. REFERENCE MANUAL PAGES          FITS(1.0)

          char      *filename;
          Matrix    *matrix;

          int   fits_get_matrix_value (matrix, x, y)
          Matrix    *matrix;
          int        x, y;

          void  fits_set_matrix_value (matrix, x, y, value)
          Matrix    *matrix;
          int        x, y;
          double     value;

          int   fits_create_matrix (header, matrix)
          Header    *header;
          Matrix    *matrix;

          int   fits_insert_array (matrix, array, x, y)
          Matrix    *matrix;
          Matrix    *array;
          int        x, y;

          int   fits_free_matrix (matrix)
          Matrix    *matrix;

DESCRIPTION
     These functions allow for FITS I/O in a general C-like way.
     There are several relavant structures defined in _f_i_t_s_i_o._h
     (see STRUCTURES below).

      _F_I_T_S _H_e_a_d_e_r _R_o_u_t_i_n_e_s

          _f_i_t_s__r_e_a_d__h_e_a_d_e_r opens a file and reads the FITS header
          into a Header structure.  No error checking, except
          file existence is currently provided.

          _f_i_t_s__w_r_i_t_e__h_e_a_d_e_r opens a file and write the Header
          structure into the file in FITS format.  It also puts a
          RETURN character (0x0a) into the N*80 bytes (the end of
          every header line).  This is not FITS standard, but it
          makes the header more readable.

          _f_i_t_s__h_e_a_d_e_r__f_i_e_l_d returns a pointer to the start of the
          Nth header line with the given keyword "field".  No
          error check is provided, except to note the lack of
          such a field (returns a NULL value).

          _f_i_t_s__s_c_a_n, _f_i_t_s__p_r_i_n_t and _f_i_t_s__m_o_d_i_f_y are modeled on
          _f_s_c_a_n_f and _f_p_r_i_n_t_f but act on a FITS header instead of
          a stream.  _f_i_t_s__p_r_i_n_t write a new entry, while
          _f_i_t_s__m_o_d_i_f_y alters the value of an existing entry

Version 1.0        Last change: Sept 18, 1992                   2

FITS(1.0)         MISC. REFERENCE MANUAL PAGES          FITS(1.0)

          (wiping out the comment line).  The following modes are
          supported:

               %d   A signed decimal integer is expected.
               %u   An unsigned decimal integer is expected.
               %ld  A long decimal integer is expected.
               %hd  A short decimal integer is expected.
               %f   A float is expected.
               %lf  A double is expected.
               %t   A boolean is expected.  The pointer should be
                    of type _b_o_o_l.
               %s   A string is expected.  The pointer should be
                    of type _c_h_a_r.
                    should be of type _c_h_a_r.
               %S A comment line string is expected.  The pointer

          _f_i_t_s__c_r_e_a_t_e__h_e_a_d_e_r creates a Header structure based on
          a partially filled Header structure.  The mandatory
          structure values (simple, bitpix, Naxes, Naxis[N],
          extend, unsign) must be set.  The buffer will be filled
          in according to these values.

          _f_i_t_s__c_o_p_y__h_e_a_d_e_r copies the header1 to header2;

          _f_i_t_s__f_r_e_e__h_e_a_d_e_r frees the allocated pointers
          associated with the header.

      _F_I_T_S _M_a_t_r_i_x _R_o_u_t_i_n_e_s

          _f_i_t_s__r_e_a_d__m_a_t_r_i_x opens the given file and reads the
          matrix structure.  There is, of course, no decent error
          checking.

          _f_i_t_s__w_r_i_t_e__m_a_t_r_i_x opens the given file and writes the
          matrix structure.  The matrix is written to the end of
          the file, in the assumption that there is already a
          Header written to the file. There is, of course, no
          decent error checking.

          _f_i_t_s__g_e_t__m_a_t_r_i_x__v_a_l_u_e returns the value of the pixel at
          the given (2-D) coordinates.

          _f_i_t_s__s_e_t__m_a_t_r_i_x__v_a_l_u_e sets the value of the pixel at
          the given (2-D) coordinates.

          _f_i_t_s__c_r_e_a_t_e__m_a_t_r_i_x creates a matrix which corresponds
          to the format described in the Header structure.

          _f_i_t_s__c_o_p_y__m_a_t_r_i_x makes a duplicate copy of header1 in
          header2.

          _f_i_t_s__f_r_e_e__m_a_t_r_i_x frees the allocated pointers

Version 1.0        Last change: Sept 18, 1992                   3

FITS(1.0)         MISC. REFERENCE MANUAL PAGES          FITS(1.0)

          associated with the Matrix.

          _f_i_t_s__i_n_s_e_r_t__a_r_r_a_y set the values of the Matrix to those
          of the array (a small Matrix), using the x,y values as
          a relative offset.

STRUCTURES
     There are several important structures defined in _f_i_t_s_i_o._h
     which are described here.

     # define bool char

     # typedef struct {
       bool                    simple;
       bool                    unsign;
       bool                    extend;
       int                     bitpix;
       int                     Naxes;
       int                     Naxis[FT_MAX_NAXES];
       int                     size;
       double                  bzero, bscale;
       char                   *buffer;
      } Header;

     typedef struct {
       int                     Naxes;
       int                     Naxis[FT_MAX_NAXES];
       int                     bitpix;
       bool                    unsign;
       double                  bzero, bscale;
       char                   *buffer;
       int                     size;
      } Matrix;

     REMINDER: data = (byte value) * bscale + bzero

     _b_o_o_l is defined to be a char.

     _H_e_a_d_e_r is a structure for holding all header information.
     It consists of values of the basic header fields required
     for a FITS file (SIMPLE, EXTEND, BITPIX, NAXIS, NAXIS1,
     NAXIS2...) as well as a pointer to the header data itself
     (_b_u_f_f_e_r) and the number of bytes in the header buffer
     (_s_i_z_e).

     _M_a_t_r_i_x is a structure for holding the image matrix data.  It
     consists of the _N_a_x_e_s, and _N_a_x_i_s[_1_0] entries as well as the
     _b_u_f_f_e_r and the _s_i_z_e entries.

COPYRIGHT
     Copyright 1991 Eugene Magnier

Version 1.0        Last change: Sept 18, 1992                   4

FITS(1.0)         MISC. REFERENCE MANUAL PAGES          FITS(1.0)

     Permission to use, copy, modify, distribute, and sell this
     software and its documentation for any purpose is hereby
     granted without fee, provided that the above copyright
     notice appear in all copies and that both that copyright
     notice and this permission notice appear in supporting
     documentation, and that the name of MIT not be used in
     advertising or publicity pertaining to distribution of the
     software without specific, written prior permission.  MIT
     and the authors make no representations about the
     suitability of this software for any purpose.  It is
     provided "as is" without express or implied warranty.
     MIT and the authors disclaim all warranties with regard to
     this software, including all implied warranties of
     merchantability and fitness, in no event shall MIT or the
     authors be liable for any special, indirect or consequential
     damages or any damages whatsoever resulting from loss of
     use, data or profits, whether in an action of contract,
     negligence or other tortious action, arising out of or in
     connection with the use or performance of this software.
ACKNOWLEDGEMENTS
     Walter H.G. Lewin for inspiration
     NASA for lots of money
AUTHOR
     Eugene Magnier.  MIT - CSR

Version 1.0        Last change: Sept 18, 1992                   5

