FITS.h

//  Astrophysics Science Division,
//  NASA/ Goddard Space Flight Center
//  HEASARC
//  http://heasarc.gsfc.nasa.gov
//  e-mail: ccfits@legacy.gsfc.nasa.gov
//
//  Original author: Ben Dorman
 
#ifndef FITS_H
#define FITS_H 1
 
// exception
#include <exception>
// string
#include <string>
// map
#include <map>
// ExtHDU
#include "ExtHDU.h"
// HDUCreator
#include "HDUCreator.h"
// FitsError
#include "FitsError.h"
 
namespace CCfits {
  class PHDU;
  class Table;
  class GroupTable;
 
} // namespace CCfits
//class PHDU;
extern "C"
{
#       include <sys/stat.h>
}           
#include <memory>
 
 
namespace CCfits {
  //  ! The FITS object class. Contains a primary HDU and Extensions indexed by name.
 
 
 
  class FITS 
  {
 
    public:
 
 
      class NoSuchHDU : public FitsException  //## Inherits: <unnamed>%396C90CB0236
      {
        public:
            NoSuchHDU (const String& diag, bool silent = true);
 
        protected:
        private:
        private: //## implementation
      };
 
 
      class OperationNotSupported : public FitsException  //## Inherits: <unnamed>%39806C7600D5
      {
        public:
            OperationNotSupported (const String& msg, bool silent = true);
 
        protected:
        private:
        private: //## implementation
      };
 
 
      class CantOpen : public FitsException  //## Inherits: <unnamed>%39C8EB1D02C0
      {
        public:
            CantOpen (const String& diag, bool silent = true);
 
        protected:
        private:
        private: //## implementation
      };
 
 
      struct CantCreate : public FitsException  //## Inherits: <unnamed>%39C8EB10020B
      {
            CantCreate (const String& diag, bool silent = false);
 
        public:
        protected:
        private:
        private: //## implementation
      };
      
        FITS (const String &name, RWmode rwmode = Read, bool readDataFlag = false, const std::vector<String>& primaryKeys = std::vector<String>());
        //  Open a file and read a specified HDU.
        //
        //  Optional parameter allows the reading of specified primary HDU keys.
        FITS (const String &name, RWmode rwmode, const string &hduName, bool readDataFlag = false, const std::vector<String>& hduKeys = std::vector<String>(), const std::vector<String>& primaryKey = std::vector<String>(), int version = 1);
        //  Read data from a set of specified HDUs. keywords can only be specified for the primary here.
        //  The code will call a different constructor for the case where keywords are required for
        //  the extensions.
        FITS (const String &name, RWmode rwmode, const std::vector<String>& hduNames, bool readDataFlag = false, const std::vector<String>& primaryKey = std::vector<String>());
        //  Initialize a new FITS file object with the primary from a
        //  different file.
        FITS (const String& fileName, const FITS& source);
        //  Fully general FITS HDU reader. May read any part of fits file by
        //  supplying HDU names and version numbers, and optionally
        //  the data read flag.
        FITS (const String &name, RWmode rwmode, const std::vector<String>& hduNames, const std::vector<std::vector<String> >& hduKeys, bool readDataFlag = false, const std::vector<String>& primaryKeys = std::vector<String>(), const std::vector<int>& hduVersions = std::vector<int>());
        //  Writing constructor. Takes a name and information to create an empty
        //  Primary HDU which can then be filled with calls to HDU methods.
        FITS (const String& name, int bitpix, int naxis, long *naxes);
        //  Open a file and read a specified HDU.
        //
        //  Optional parameter allows the reading of specified primary HDU keys.
        FITS (const string &name, RWmode rwmode, int hduIndex, bool readDataFlag = false, const std::vector<String>& hduKeys = std::vector<String>(), const std::vector<String>& primaryKey = std::vector<String>());
        //  Open a file and read a HDU that contains  specified
        //  search keywords with [optional] specified values
        //  (sometimes one just wants to know that the keyword is present).
        //
        //  Optional parameters allows the reading of specified primary HDU keys and specified keywords in
        //  the HDU of interest.
        FITS (const String &name, RWmode rwmode, const std::vector<String>& searchKeys, const std::vector<String> &searchValues, bool readDataFlag = false, const std::vector<String>& hduKeys = std::vector<String>(), const std::vector<String>& primaryKey = std::vector<string>(), int version = 1);
        ~FITS();
 
        static void clearErrors ();
        void deleteExtension (const String& doomed, int version = 1);
        
        //  Read keys and data from a single ExtHDU in the file.
        void read (const String &hduName, bool readDataFlag = false, const std::vector<String> &keys = std::vector<String>(), int version = 1);
        //  Read multiple ExtHDUs. If the version number needs to be specified
        //  then one must call a different method.
        void read (const std::vector<String> &hduNames, bool readDataFlag = false);
        //  Read selected data from multiple ExtHDUs
        void read (const std::vector<String> &hduNames, const std::vector<std::vector<String> > &keys, bool readDataFlag = false, const std::vector<int>& hduVersions = std::vector<int>());
        //  Read keys and data from a single ExtHDU in the file.
        //  Construct and Read HDU specified by number. One can add further HDUs by number using the HDUCreator factory.
        void read (int hduIndex, bool readDataFlag = false, const std::vector<String> &keys = std::vector<String>());
        //  Open a file and read a HDU that contains  specified
        //  search keywords with [optional] specified values
        //  (sometimes one just wants to know that the keyword is present).
        //
        //  Optional parameters allows the reading of specified primary HDU keys and specified keywords in
        //  the HDU of interest.
        void read (const std::vector<String>& searchKeys, const std::vector<String> &searchValues, bool readDataFlag = false, const std::vector<String>& hduKeys = std::vector<String>(), int version = 1);
        ExtHDU& currentExtension ();
        ExtHDU& extension (int i);
        const ExtHDU& extension (int i) const;
        ExtHDU& extension (const String& hduName, int version = 1);
        const ExtHDU& extension (const String& hduName, int version = 1) const;
        fitsfile* fitsPointer () const;
        PHDU& pHDU ();
        const PHDU& pHDU () const;
        friend std::ostream& operator << (std::ostream& s, const FITS& right);
        //  ! add a new Table extension to a FITS object
        Table* addTable (const String& hduName, int rows,                   // ! Number of rows in new table. Mandatory
          const std::vector<String>& columnName = std::vector<String>(),    // ! Optional set of column names for new table
          const std::vector<String>& columnFmt = std::vector<String>(),     // ! Column formats for column units. Mandatory if columnName is specified
          const std::vector<String>& columnUnit = std::vector<String>(),    // ! Column formats for column units. Optional
          HduType type = BinaryTbl, int version = 1);
        // ! add a new Group Table to the FITS object
        Table * addGroupTable(const String & groupName, int groupID);
        //GroupTable * addGroupTable(const String & groupName, int groupID);
        //  ! add a new ImageExt (image extension) to the FITS object. A "writing" method.
        ExtHDU* addImage (const String& hduName, int bpix, std::vector<long>& naxes, int version = 1);
        // Force destruction of the FITS object. Essentially
        // is a manual destructor call.
        void destroy () throw ();
        void flush ();
        void resetPosition ();
        const ExtMap& extension () const;
        void deleteExtension (int doomed);
        const String& currentExtensionName () const;
        void currentExtensionName (const String& extName);
        const String& name () const;
        void copy (const HDU& source);
        Table& filter (const String& expression, ExtHDU& inputTable, bool overwrite = true, bool readData = false);
        void setCompressionType (int compType);
        void setTileDimensions (const std::vector<long>& tileSizes);
        void setNoiseBits (int noiseBits);
        int getCompressionType () const;
        void getTileDimensions (std::vector<long>& tileSizes) const;
        int getNoiseBits () const;
        static bool verboseMode ();
        static void setVerboseMode (bool value);
 
    public:
      // Additional Public Declarations
 
    protected:
      // Additional Protected Declarations
 
    private:
        FITS(const FITS &right);
        FITS & operator=(const FITS &right);
 
        void unmapExtension (ExtHDU& doomed);
        int nextVersionNumber (const String& inputName) const;
        //  read the primary HDU. Read the image if
        //  readDataFlag is true.
        void read (bool readDataFlag = false, const std::vector<String>& keys = std::vector<String>());
        //  Returns index of current HDU where primary = 0.  (Extended file syntax may cause a shift to an
        //  extension.)
        int open (RWmode rwmode = Read);
        //  Create returns true if a new file was created or an
        //  existing file overwritten, false if appending.
        //
        //  It throws exception CantCreate or CantOpen if either fails.
        bool create ();
        //  Close the fits file.
        //
        //  Called in destructors so must not throw.
        int close () throw ();
        std::ostream & put (std::ostream &s) const;
        ExtHDU& extbyVersion (const String& hduName, int version) const;
        void pHDU (PHDU* value);
        void readExtensions (bool readDataFlag = false);
        ExtHDU* addExtension (ExtHDU* ext);
        String nameOfUnmapped (int hduNum) const;
        void cloneHeader (const ExtHDU& source);
 
        // Check if caller is requesting an already read ExtHDU (ie. one
        // that's already been added to ExtMap).  If hduIdx=0, check by
        // matching name and optional version.  Otherwise check by matching
        // hduIdx.  If found, returns pointer to the ExtHDU.  Otherwise
        // returns 0.  This will not throw.
        ExtHDU* checkAlreadyRead(const int hduIdx, 
                    const String& hduName = string(""), const int version=1) const throw();
 
      // Additional Private Declarations
        
        void destroyPrimary ();
        void destroyExtensions ();
        int currentCompressionTileDim () const;
        void currentCompressionTileDim (int value);
        
 
    private: //## implementation
      // Data Members for Class Attributes
        static bool s_verboseMode;
        int m_currentCompressionTileDim;
 
      // Data Members for Associations
        RWmode m_mode;
        std::string m_currentExtensionName;
        std::string m_filename;
        PHDU* m_pHDU;
        ExtMap m_extension;
        fitsfile* m_fptr;
        
 
      // ## Additional Implementation Declarations
      friend void HDU::makeThisCurrent() const; 
      // MakeImage needs to access the m_pHDU pointer
      friend PHDU * HDUCreator::MakeImage (int bpix, int naxis, const std::vector<long>& naxes); 
      
  };
 
  // Class CCfits::FITS::NoSuchHDU 
 
  // Class CCfits::FITS::OperationNotSupported 
 
  // Class CCfits::FITS::CantOpen 
 
  // Class CCfits::FITS::CantCreate 
 
  // Class CCfits::FITS 
 
  inline ExtHDU& FITS::extension (const String& hduName, int version)
  {
    return extbyVersion(hduName,version);
  }
 
  inline std::ostream& operator << (std::ostream& s, const FITS& right)
  {
    return right.put(s);
  }
 
  inline bool FITS::verboseMode ()
  {
    return s_verboseMode;
  }
 
  inline void FITS::setVerboseMode (bool value)
  {
    s_verboseMode = value;
  }
  
  inline int FITS::currentCompressionTileDim () const
  {
    return m_currentCompressionTileDim;
  }
 
  inline void FITS::currentCompressionTileDim (int value)
  {
    m_currentCompressionTileDim = value;
  }
 
  inline const String& FITS::currentExtensionName () const
  {
    return m_currentExtensionName;
  }
 
  inline void FITS::currentExtensionName (const String& extName)
  {
    m_currentExtensionName = extName;
  }
 
  inline const String& FITS::name () const
  {
    return m_filename;
  }
 
  inline void FITS::pHDU (PHDU* value)
  {
    m_pHDU = value;
  }
 
  inline const PHDU& FITS::pHDU () const
  {
    return *m_pHDU;
  }
 
  inline PHDU& FITS::pHDU ()
  {
    return *m_pHDU;
  }
 
  inline const ExtMap& FITS::extension () const
  {
     return m_extension;
  }
 
  inline fitsfile* FITS::fitsPointer () const
  {
    return m_fptr;
  }
 
} // namespace CCfits
 
 
#endif