CCfits  2.7
FITS.h
00001 //  Astrophysics Science Division,
00002 //  NASA/ Goddard Space Flight Center
00003 //  HEASARC
00004 //  http://heasarc.gsfc.nasa.gov
00005 //  e-mail: ccfits@legacy.gsfc.nasa.gov
00006 //
00007 //  Original author: Ben Dorman
00008 
00009 #ifndef FITS_H
00010 #define FITS_H 1
00011 
00012 // exception
00013 #include <exception>
00014 // string
00015 #include <string>
00016 // map
00017 #include <map>
00018 // ExtHDU
00019 #include "ExtHDU.h"
00020 // HDUCreator
00021 #include "HDUCreator.h"
00022 // FitsError
00023 #include "FitsError.h"
00024 
00025 namespace CCfits {
00026   class PHDU;
00027   class Table;
00028   class GroupTable;
00029 
00030 } // namespace CCfits
00031 //class PHDU;
00032 extern "C"
00033 {
00034 #       include <sys/stat.h>
00035 }           
00036 #include <memory>
00037 
00038 
00039 namespace CCfits {
00624   //  ! The FITS object class. Contains a primary HDU and Extensions indexed by name.
00625 
00626 
00627 
00628   class FITS 
00629   {
00630 
00631     public:
00632 
00633 
00634       class NoSuchHDU : public FitsException  //## Inherits: <unnamed>%396C90CB0236
00635       {
00636         public:
00637             NoSuchHDU (const String& diag, bool silent = true);
00638 
00639         protected:
00640         private:
00641         private: //## implementation
00642       };
00643 
00644 
00645       class OperationNotSupported : public FitsException  //## Inherits: <unnamed>%39806C7600D5
00646       {
00647         public:
00648             OperationNotSupported (const String& msg, bool silent = true);
00649 
00650         protected:
00651         private:
00652         private: //## implementation
00653       };
00654 
00655 
00656       class CantOpen : public FitsException  //## Inherits: <unnamed>%39C8EB1D02C0
00657       {
00658         public:
00659             CantOpen (const String& diag, bool silent = true);
00660 
00661         protected:
00662         private:
00663         private: //## implementation
00664       };
00665 
00666 
00667       struct CantCreate : public FitsException  //## Inherits: <unnamed>%39C8EB10020B
00668       {
00669             CantCreate (const String& diag, bool silent = false);
00670 
00671         public:
00672         protected:
00673         private:
00674         private: //## implementation
00675       };
00676       
00677         FITS (const String &name, RWmode rwmode = Read, bool readDataFlag = false, const std::vector<String>& primaryKeys = std::vector<String>());
00678         //  Open a file and read a specified HDU.
00679         //
00680         //  Optional parameter allows the reading of specified primary HDU keys.
00681         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);
00682         //  Read data from a set of specified HDUs. keywords can only be specified for the primary here.
00683         //  The code will call a different constructor for the case where keywords are required for
00684         //  the extensions.
00685         FITS (const String &name, RWmode rwmode, const std::vector<String>& hduNames, bool readDataFlag = false, const std::vector<String>& primaryKey = std::vector<String>());
00686         //  Initialize a new FITS file object with the primary from a
00687         //  different file.
00688         FITS (const String& fileName, const FITS& source);
00689         //  Fully general FITS HDU reader. May read any part of fits file by
00690         //  supplying HDU names and version numbers, and optionally
00691         //  the data read flag.
00692         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>());
00693         //  Writing constructor. Takes a name and information to create an empty
00694         //  Primary HDU which can then be filled with calls to HDU methods.
00695         FITS (const String& name, int bitpix, int naxis, long *naxes);
00696         //  Open a file and read a specified HDU.
00697         //
00698         //  Optional parameter allows the reading of specified primary HDU keys.
00699         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>());
00700         //  Open a file and read a HDU that contains  specified
00701         //  search keywords with [optional] specified values
00702         //  (sometimes one just wants to know that the keyword is present).
00703         //
00704         //  Optional parameters allows the reading of specified primary HDU keys and specified keywords in
00705         //  the HDU of interest.
00706         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);
00707         ~FITS();
00708 
00709         static void clearErrors ();
00710         void deleteExtension (const String& doomed, int version = 1);
00711         
00712         //  Read keys and data from a single ExtHDU in the file.
00713         void read (const String &hduName, bool readDataFlag = false, const std::vector<String> &keys = std::vector<String>(), int version = 1);
00714         //  Read multiple ExtHDUs. If the version number needs to be specified
00715         //  then one must call a different method.
00716         void read (const std::vector<String> &hduNames, bool readDataFlag = false);
00717         //  Read selected data from multiple ExtHDUs
00718         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>());
00719         //  Read keys and data from a single ExtHDU in the file.
00720         //  Construct and Read HDU specified by number. One can add further HDUs by number using the HDUCreator factory.
00721         void read (int hduIndex, bool readDataFlag = false, const std::vector<String> &keys = std::vector<String>());
00722         //  Open a file and read a HDU that contains  specified
00723         //  search keywords with [optional] specified values
00724         //  (sometimes one just wants to know that the keyword is present).
00725         //
00726         //  Optional parameters allows the reading of specified primary HDU keys and specified keywords in
00727         //  the HDU of interest.
00728         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);
00729         ExtHDU& currentExtension ();
00730         ExtHDU& extension (int i);
00731         const ExtHDU& extension (int i) const;
00732         ExtHDU& extension (const String& hduName, int version = 1);
00733         const ExtHDU& extension (const String& hduName, int version = 1) const;
00734         fitsfile* fitsPointer () const;
00735         PHDU& pHDU ();
00736         const PHDU& pHDU () const;
00737         friend std::ostream& operator << (std::ostream& s, const FITS& right);
00738         //  ! add a new Table extension to a FITS object
00739         Table* addTable (const String& hduName, int rows,                   // ! Number of rows in new table. Mandatory
00740           const std::vector<String>& columnName = std::vector<String>(),    // ! Optional set of column names for new table
00741           const std::vector<String>& columnFmt = std::vector<String>(),     // ! Column formats for column units. Mandatory if columnName is specified
00742           const std::vector<String>& columnUnit = std::vector<String>(),    // ! Column formats for column units. Optional
00743           HduType type = BinaryTbl, int version = 1);
00744         // ! add a new Group Table to the FITS object
00745         Table * addGroupTable(const String & groupName, int groupID);
00746         //GroupTable * addGroupTable(const String & groupName, int groupID);
00747         //  ! add a new ImageExt (image extension) to the FITS object. A "writing" method.
00748         ExtHDU* addImage (const String& hduName, int bpix, std::vector<long>& naxes, int version = 1);
00749         // Force destruction of the FITS object. Essentially
00750         // is a manual destructor call.
00751         void destroy () throw ();
00752         void flush ();
00753         void resetPosition ();
00754         const ExtMap& extension () const;
00755         void deleteExtension (int doomed);
00756         const String& currentExtensionName () const;
00757         void currentExtensionName (const String& extName);
00758         const String& name () const;
00759         void copy (const HDU& source);
00760         Table& filter (const String& expression, ExtHDU& inputTable, bool overwrite = true, bool readData = false);
00761         void setCompressionType (int compType);
00762         void setTileDimensions (const std::vector<long>& tileSizes);
00763         void setNoiseBits (int noiseBits);
00764         int getCompressionType () const;
00765         void getTileDimensions (std::vector<long>& tileSizes) const;
00766         int getNoiseBits () const;
00767         static bool verboseMode ();
00768         static void setVerboseMode (bool value);
00769 
00770     public:
00771       // Additional Public Declarations
00772 
00773     protected:
00774       // Additional Protected Declarations
00775 
00776     private:
00777         FITS(const FITS &right);
00778         FITS & operator=(const FITS &right);
00779 
00780         void unmapExtension (ExtHDU& doomed);
00781         int nextVersionNumber (const String& inputName) const;
00782         //  read the primary HDU. Read the image if
00783         //  readDataFlag is true.
00784         void read (bool readDataFlag = false, const std::vector<String>& keys = std::vector<String>());
00785         //  Returns index of current HDU where primary = 0.  (Extended file syntax may cause a shift to an
00786         //  extension.)
00787         int open (RWmode rwmode = Read);
00788         //  Create returns true if a new file was created or an
00789         //  existing file overwritten, false if appending.
00790         //
00791         //  It throws exception CantCreate or CantOpen if either fails.
00792         bool create ();
00793         //  Close the fits file.
00794         //
00795         //  Called in destructors so must not throw.
00796         int close () throw ();
00797         std::ostream & put (std::ostream &s) const;
00798         ExtHDU& extbyVersion (const String& hduName, int version) const;
00799         void pHDU (PHDU* value);
00800         void readExtensions (bool readDataFlag = false);
00801         ExtHDU* addExtension (ExtHDU* ext);
00802         String nameOfUnmapped (int hduNum) const;
00803         void cloneHeader (const ExtHDU& source);
00804 
00805         // Check if caller is requesting an already read ExtHDU (ie. one
00806         // that's already been added to ExtMap).  If hduIdx=0, check by
00807         // matching name and optional version.  Otherwise check by matching
00808         // hduIdx.  If found, returns pointer to the ExtHDU.  Otherwise
00809         // returns 0.  This will not throw.
00810         ExtHDU* checkAlreadyRead(const int hduIdx, 
00811                     const String& hduName = string(""), const int version=1) const throw();
00812 
00813       // Additional Private Declarations
00814         
00815         void destroyPrimary ();
00816         void destroyExtensions ();
00817         int currentCompressionTileDim () const;
00818         void currentCompressionTileDim (int value);
00819         
00820 
00821     private: //## implementation
00822       // Data Members for Class Attributes
00823         static bool s_verboseMode;
00824         int m_currentCompressionTileDim;
00825 
00826       // Data Members for Associations
00827         RWmode m_mode;
00828         std::string m_currentExtensionName;
00829         std::string m_filename;
00830         PHDU* m_pHDU;
00831         ExtMap m_extension;
00832         fitsfile* m_fptr;
00833         
00834 
00835       // ## Additional Implementation Declarations
00836       friend void HDU::makeThisCurrent() const; 
00837       // MakeImage needs to access the m_pHDU pointer
00838       friend PHDU * HDUCreator::MakeImage (int bpix, int naxis, const std::vector<long>& naxes); 
00839       
00840   };
00841 
00842   // Class CCfits::FITS::NoSuchHDU 
00843 
00844   // Class CCfits::FITS::OperationNotSupported 
00845 
00846   // Class CCfits::FITS::CantOpen 
00847 
00848   // Class CCfits::FITS::CantCreate 
00849 
00850   // Class CCfits::FITS 
00851 
00852   inline ExtHDU& FITS::extension (const String& hduName, int version)
00853   {
00854     return extbyVersion(hduName,version);
00855   }
00856 
00857   inline std::ostream& operator << (std::ostream& s, const FITS& right)
00858   {
00859     return right.put(s);
00860   }
00861 
00862   inline bool FITS::verboseMode ()
00863   {
00864     return s_verboseMode;
00865   }
00866 
00867   inline void FITS::setVerboseMode (bool value)
00868   {
00869     s_verboseMode = value;
00870   }
00871   
00872   inline int FITS::currentCompressionTileDim () const
00873   {
00874     return m_currentCompressionTileDim;
00875   }
00876 
00877   inline void FITS::currentCompressionTileDim (int value)
00878   {
00879     m_currentCompressionTileDim = value;
00880   }
00881 
00882   inline const String& FITS::currentExtensionName () const
00883   {
00884     return m_currentExtensionName;
00885   }
00886 
00887   inline void FITS::currentExtensionName (const String& extName)
00888   {
00889     m_currentExtensionName = extName;
00890   }
00891 
00892   inline const String& FITS::name () const
00893   {
00894     return m_filename;
00895   }
00896 
00897   inline void FITS::pHDU (PHDU* value)
00898   {
00899     m_pHDU = value;
00900   }
00901 
00902   inline const PHDU& FITS::pHDU () const
00903   {
00904     return *m_pHDU;
00905   }
00906 
00907   inline PHDU& FITS::pHDU ()
00908   {
00909     return *m_pHDU;
00910   }
00911 
00912   inline const ExtMap& FITS::extension () const
00913   {
00914      return m_extension;
00915   }
00916 
00917   inline fitsfile* FITS::fitsPointer () const
00918   {
00919     return m_fptr;
00920   }
00921 
00922 } // namespace CCfits
00923 
00924 
00925 #endif