kstars/kstars/indi/fitsrw.h

   1 /******************************************************************************/
   2 /*                      Peter Kirchgessner                                    */
   3 /*                      e-mail: pkirchg@aol.com                               */
   4 /*                      WWW   : http://members.aol.com/pkirchg                */
   5 /******************************************************************************/
   6 /*  #BEG-HDR                                                                  */
   7 /*                                                                            */
   8 /*  Package       : FITS reading/writing library                              */
   9 /*  Modul-Name    : fitsrw.h                                                  */
  10 /*  Description   : Include file for FITS-r/w-library                         */
  11 /*  Function(s)   :                                                           */
  12 /*  Author        : P. Kirchgessner                                           */
  13 /*  Date of Gen.  : 12-Apr-97                                                 */
  14 /*  Last modified : 17-May-97                                                 */
  15 /*  Version       : 0.10                                                      */
  16 /*  Compiler Opt. :                                                           */
  17 /*  Changes       :                                                           */
  18 /*                                                                            */
  19 /*  #END-HDR                                                                  */
  20 /******************************************************************************/
  21
  22 /** \file fitsrw.h
  23     \brief FITS reading/writing library.
  24     \author Peter Kirchgessner
  25 */
  26
  27 #ifndef FITS_MAX_AXIS
  28
  29 #include <stdio.h>
  30
  31 #define FITS_CARD_SIZE      80
  32 #define FITS_RECORD_SIZE  2880
  33 #define FITS_MAX_AXIS      999
  34
  35 #define FITS_NADD_CARDS    128
  36
  37 #ifdef __cplusplus
  38 extern "C" {
  39 #endif
  40
  41 /* Data representations */
  42 /** \typedef FITS_BITPIX8
  43     \brief One byte declared as unsigned char.
  44 */
  45 typedef unsigned char FITS_BITPIX8;
  46
  47 /** \typedef FITS_BITPIX16
  48     \brief Two bytes declared as short.
  49 */
  50 typedef short         FITS_BITPIX16;
  51
  52 /** \typedef FITS_BITPIX32
  53     \brief Four bytes declared as long.
  54 */
  55 typedef long          FITS_BITPIX32;
  56
  57 /** \typedef FITS_BITPIXM32
  58     \brief IEEE -32 FITS format declared as 4-byte float.
  59 */
  60 typedef float         FITS_BITPIXM32;
  61
  62 /** \typedef FITS_BITPIXM64
  63     \brief IEEE -64 FITS format declared as 8-byte double.
  64 */
  65 typedef double        FITS_BITPIXM64;
  66
  67 typedef int           FITS_BOOL;
  68 typedef long          FITS_LONG;
  69 typedef double        FITS_DOUBLE;
  70 typedef char          FITS_STRING[FITS_CARD_SIZE];
  71
  72 typedef enum {
  73  typ_bitpix8, typ_bitpix16, typ_bitpix32, typ_bitpixm32, typ_bitpixm64,
  74  typ_fbool, typ_flong, typ_fdouble, typ_fstring
  75 } FITS_DATA_TYPES;
  76
  77 /** \struct FITS_PIX_TRANSFORM
  78     \brief A struct that describes how to transform FITS pixel values.
  79 *
  80 * The pixel values represent the lower and upper boundaries of the pixel data from the FITS file. The data values represent the range of the final pixel values. For example, to transform FITS pixel values to grey scale, the data min is 0 and data max is 255. The transformation is linear.
  81 */
  82 typedef struct {
  83  double pixmin, pixmax;    /** The pixel values [pixmin,pixmax] that should be mapped */
  84  double datamin, datamax;  /** The data values [datamin,datamax] that the pixel values should be mapped to*/
  85  double replacement;       /** datavalue to use for blank or NaN pixels */
  86  char dsttyp;              /** Destination typ ('c' = char) */
  87 } FITS_PIX_TRANSFORM;
  88
  89 typedef union {
  90  FITS_BITPIX8   bitpix8;
  91  FITS_BITPIX16  bitpix16;
  92  FITS_BITPIX32  bitpix32;
  93  FITS_BITPIXM32 bitpixm32;
  94  FITS_BITPIXM64 bitpixm64;
  95
  96  FITS_BOOL   fbool;
  97  FITS_LONG   flong;
  98  FITS_DOUBLE fdouble;
  99  FITS_STRING fstring;
 100 } FITS_DATA;
 101
 102 /** \struct FITS_RECORD_LIST
 103     \brief Record list.
 104 */
 105 typedef struct fits_record_list {
 106  unsigned char data[FITS_RECORD_SIZE];
 107  struct fits_record_list *next_record;
 108 } FITS_RECORD_LIST;
 109
 110 /** \struct FITS_HDU_LIST
 111     \brief Header and Data Unit List.
 112
 113 * The structure hold header and data unit lists. The \p used struct contains flags specifying if some cards are used.
 114 */
 115 typedef struct fits_hdu_list {
 116  long header_offset;              /** Offset of header in the file */
 117  long data_offset;                /** Offset of data in the file */
 118  long data_size;                  /** Size of data in the HDU (including pad)*/
 119  long udata_size;                 /** Size of used data in the HDU (excl. pad) */
 120  int  bpp;                        /** Bytes per pixel */
 121  int numpic;                      /** Number of interpretable images in HDU */
 122  int naddcards;                   /** Number of additional cards */
 123  char addcards[FITS_NADD_CARDS][FITS_CARD_SIZE];
 124  struct {
 125    char nan_value;                /** NaN's found in data ? */
 126    char blank_value;              /** Blanks found in data ? */
 127
 128    char blank;
 129    char datamin;
 130    char datamax;
 131    char simple;                   /** This indicates a simple HDU */
 132    char xtension;                 /** This indicates an extension */
 133    char gcount;
 134    char pcount;
 135    char bzero;
 136    char bscale;
 137    char groups;
 138    char extend;
 139  } used;
 140  double pixmin, pixmax;           /** Minimum/Maximum pixel values */
 141                                   /* Some decoded data of the HDU: */
 142  int naxis;                       /** Number of axes */
 143  int naxisn[FITS_MAX_AXIS];       /** Sizes of axes (NAXIS1 --> naxisn[0]) */
 144  int bitpix;                      /** Data representation (8,16,32,-16,-32) */
 145                                   /* When using the following data, */
 146                                   /* the used-flags must be checked before. */
 147  long blank;                      /** Blank value. Check the \p used struct to verify if this is a valid value*/
 148  double datamin, datamax;         /** Minimum/Maximum physical data values. Check the \p used struct to verify if this is a valid value*/
 149  char xtension[FITS_CARD_SIZE];   /** Type of extension. Check the \p used struct to verify if this is a valid value*/
 150  long gcount, pcount;             /** Used by XTENSION. Check the \p used struct to verify if this is a valid value*/
 151  double bzero, bscale;            /** Transformation values. Check the \p used struct to verify if this is a valid value*/
 152  int groups;                      /** Random groups indicator. Check the \p used struct to verify if this is a valid value*/
 153  int extend;                      /** Extend flag. Check the \p used struct to verify if this is a valid value*/
 154
 155  FITS_RECORD_LIST *header_record_list; /** Header records read in */
 156  struct fits_hdu_list *next_hdu;
 157 } FITS_HDU_LIST;
 158
 159 /** \struct FITS_FILE
 160     \brief Structure to hold FITS file information and pointers.
 161 */
 162 typedef struct {
 163  FILE *fp;                    /** File pointer to fits file */
 164  char openmode;               /** Mode the file was opened (0, 'r', 'w') */
 165
 166  int n_hdu;                   /** Number of HDUs in file */
 167  int n_pic;                   /** Total number of interpretable pictures */
 168  int nan_used;                /** NaN's used in the file ? */
 169  int blank_used;              /** Blank's used in the file ? */
 170
 171  FITS_HDU_LIST *hdu_list;     /** Header and Data Unit List */
 172 } FITS_FILE;
 173
 174
 175 /* User callable functions of the FITS-library */
 176 /**
 177  * \defgroup fitsFunctions User callable functions of the FITS-library.
 178  */
 179 /*@{*/
 180
 181 /** \brief open a FITS file.
 182     \param filename name of file to open
 183     \param openmode mode to open the file ("r", "w")
 184     \return On success, a FITS_FILE-pointer is returned. On failure, a NULL-pointer is returned. The functions scans through the file loading each header and analyzing them.
 185 */
 186 FITS_FILE     *fits_open (const char *filename, const char *openmode);
 187
 188 /** \brief close a FITS file.
 189     \param ff FITS file pointer.
 190 */
 191 void           fits_close (FITS_FILE *ff);
 192
 193 /** \brief add a HDU to the file.
 194     \param ff FITS file pointer.
 195     \return Adds a new HDU to the list kept in ff. A pointer to the new HDU is returned. On failure, a NULL-pointer is returned.
 196 */
 197 FITS_HDU_LIST *fits_add_hdu (FITS_FILE *ff);
 198
 199 /** \brief add a card to the HDU.
 200     The card must follow the standards of FITS. The card must not use a
 201     keyword that is written using *hdulist itself.
 202     \param hdulist HDU listr.
 203     \param card card to add.
 204     \return On success 0 is returned. On failure -1 is returned.
 205 */
 206 int            fits_add_card (FITS_HDU_LIST *hdulist, char *card);
 207
 208 /** \brief print the internal representation of a single header.
 209     \param hdr pointer to the header
 210 */
 211 void           fits_print_header (FITS_HDU_LIST *hdr);
 212
 213 /** \brief write a FITS header to the file.
 214     \param ff FITS-file pointer.
 215     \param hdulist pointer to header.
 216     \return On success, 0 is returned. On failure, -1 is returned.
 217 */
 218 int            fits_write_header (FITS_FILE *ff, FITS_HDU_LIST *hdulist);
 219
 220 /** \brief get information about an image.
 221     \param ff FITS-file pointer.
 222     \param picind Index of picture in file (1,2,...)
 223     \param hdupicind Index of picture in HDU (1,2,...)
 224     \return The function returns on success a pointer to a FITS_HDU_LIST. hdupicind then gives the index of the image within the HDU. On failure, NULL is returned.
 225 */
 226 FITS_HDU_LIST *fits_image_info (FITS_FILE *ff, int picind, int *hdupicind);
 227
 228 /** \brief position to a specific image.
 229     The function positions the file pointer to a specified image.
 230     \param ff FITS-file pointer.
 231     \param picind Index of picture to seek (1,2,...)
 232     \return The function returns on success a pointer to a FITS_HDU_LIST. This pointer must also be used when reading data from the image. On failure, NULL is returned.
 233 */
 234 FITS_HDU_LIST *fits_seek_image (FITS_FILE *ff, int picind);
 235
 236 /** \brief decode a card
 237     Decodes a card and returns a pointer to the union, keeping the data.
 238     \param card pointer to card image.
 239     \param data_type datatype to decode.
 240     \return If card is NULL or on failure, a NULL-pointer is returned. If the card does not have the value indicator, an error is generated, but its tried to decode the card. The data is only valid up to the next call of the function.
 241 */
 242 FITS_DATA     *fits_decode_card (const char *card, FITS_DATA_TYPES data_type);
 243
 244 /** \brief search a card in the record list.
 245     A card is searched in the reord list. Only the first eight characters of keyword are significant. If keyword is less than 8 characters, its filled with blanks.
 246     \param rl record list to search.
 247     \param keyword keyword identifying the card.
 248     \return If the card is found, a pointer to the card is returned. The pointer does not point to a null-terminated string. Only the next 80 bytes are allowed to be read. On failure a NULL-pointer is returned.
 249 */
 250 char          *fits_search_card (FITS_RECORD_LIST *rl, const char *keyword);
 251
 252 /** \brief read pixel values from a file
 253     The function reads npix pixel values from the file, transforms them checking for blank/NaN pixels and stores the transformed values in buf. hdulist must be a pointer returned by fits_seek_image(). Before starting to read an image, fits_seek_image() must be called. Even for successive images.
 254     \param ff FITS file structure.
 255     \param hdulist pointer to hdulist that describes image.
 256     \param npix number of pixel values to read.
 257     \param trans pixel transformation.
 258     \param buf buffer where to place transformed pixels.
 259     \return The number of transformed pixels is returned. If the returned value is less than npix (or even -1), an error has occured.
 260 */
 261 int            fits_read_pixel (FITS_FILE *ff, FITS_HDU_LIST *hdulist,
 262                                 int npix, FITS_PIX_TRANSFORM *trans, void *buf);
 263
 264 /** \brief get an error message.
 265     \return If an error message has been set, a pointer to the message is returned. Otherwise a NULL pointer is returned. An inquired error message is removed from the error FIFO.
 266 */
 267 char           *fits_get_error (void);
 268
 269 /*@}*/
 270
 271 int            fits_nan_32 (unsigned char *v);
 272 int            fits_nan_64 (unsigned char *v);
 273
 274 /* Demo functions */
 275 #define FITS_NO_DEMO
 276 int fits_to_pgmraw (char *fitsfile, char *pgmfile);
 277 int pgmraw_to_fits (char *pgmfile, char *fitsfile);
 278
 279 #ifdef __cplusplus
 280 }
 281 #endif
 282
 283 #endif