CCfits  2.4
FITS.h
1 // Astrophysics Science Division,
2 // NASA/ Goddard Space Flight Center
3 // HEASARC
4 // http://heasarc.gsfc.nasa.gov
5 // e-mail: ccfits@legacy.gsfc.nasa.gov
6 //
7 // Original author: Ben Dorman
8 
9 #ifndef FITS_H
10 #define FITS_H 1
11 
12 // exception
13 #include <exception>
14 // string
15 #include <string>
16 // map
17 #include <map>
18 // ExtHDU
19 #include "ExtHDU.h"
20 // HDUCreator
21 #include "HDUCreator.h"
22 // FitsError
23 #include "FitsError.h"
24 
25 namespace CCfits {
26  class FITSBase;
27  class PHDU;
28  class Table;
29 
30 } // namespace CCfits
31 //class PHDU;
32 extern "C"
33 {
34 # include <sys/stat.h>
35 }
36 #include <memory>
37 
38 
39 namespace CCfits {
664  // ! The FITS object class. Contains a primary HDU and Extensions indexed by name.
665 
666 
667 
668  class FITS
669  {
670 
671  public:
672 
673 
674 
675  class NoSuchHDU : public FitsException //## Inherits: <unnamed>%396C90CB0236
676  {
677  public:
678  NoSuchHDU (const String& diag, bool silent = true);
679 
680  protected:
681  private:
682  private: //## implementation
683  };
684 
685 
686 
687  class OperationNotSupported : public FitsException //## Inherits: <unnamed>%39806C7600D5
688  {
689  public:
690  OperationNotSupported (const String& msg, bool silent = true);
691 
692  protected:
693  private:
694  private: //## implementation
695  };
696 
697 
698 
699  class CantOpen : public FitsException //## Inherits: <unnamed>%39C8EB1D02C0
700  {
701  public:
702  CantOpen (const String& diag, bool silent = true);
703 
704  protected:
705  private:
706  private: //## implementation
707  };
708 
709 
710 
711  struct CantCreate : public FitsException //## Inherits: <unnamed>%39C8EB10020B
712  {
713  CantCreate (const String& diag, bool silent = false);
714 
715  public:
716  protected:
717  private:
718  private: //## implementation
719  };
720  FITS (const String &name, RWmode mode = Read, bool readDataFlag = false, const std::vector<String>& primaryKeys = std::vector<String>());
721  // Open a file and read a specified HDU.
722  //
723  // Optional parameter allows the reading of specified primary HDU keys.
724  FITS (const String &name, RWmode mode, 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);
725  // Read data from a set of specified HDUs. keywords can only be specified for the primary here.
726  // The code will call a different constructor for the case where keywords are required for
727  // the extensions.
728  FITS (const String &name, RWmode mode, const std::vector<String>& hduNames, bool readDataFlag = false, const std::vector<String>& primaryKey = std::vector<String>());
729  // Initialize a new FITS file object with the primary from a
730  // different file.
731  FITS (const String& fileName, const FITS& source);
732  // Fully general FITS HDU reader. May read any part of fits file by
733  // supplying HDU names and version numbers, and optionally
734  // the data read flag.
735  FITS (const String &name, RWmode mode, 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>());
736  // Writing constructor. Takes a name and information to create an empty
737  // Primary HDU which can then be filled with calls to HDU methods.
738  FITS (const String& name, int bitpix, int naxis, long *naxes);
739  // Open a file and read a specified HDU.
740  //
741  // Optional parameter allows the reading of specified primary HDU keys.
742  FITS (const string &name, RWmode mode, int hduIndex, bool readDataFlag = false, const std::vector<String>& hduKeys = std::vector<String>(), const std::vector<String>& primaryKey = std::vector<String>());
743  // Open a file and read a HDU that contains specified
744  // search keywords with [optional] specified values
745  // (sometimes one just wants to know that the keyword is present).
746  //
747  // Optional parameters allows the reading of specified primary HDU keys and specified keywords in
748  // the HDU of interest.
749  FITS (const String &name, RWmode mode, 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);
750  ~FITS();
751 
752  static void clearErrors ();
753  void deleteExtension (const String& doomed, int version = 1);
754  // Read keys and data from a single ExtHDU in the file.
755  void read (const String &hduName, bool readDataFlag = false, const std::vector<String> &keys = std::vector<String>(), int version = 1);
756  // Read multiple ExtHDUs. If the version number needs to be specified then one must call a
757  // different method.
758  void read (const std::vector<String> &hduNames, bool readDataFlag = false);
759  // Read selected data from multiple ExtHDUs
760  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>());
761  // Read keys and data from a single ExtHDU in the file.
762  void read (int hduIndex, // Construct and Read HDU specified by number. One can add further HDUs by number using
763  // the HDUCreator factory.
764  bool readDataFlag = false, const std::vector<String> &keys = std::vector<String>());
765  // Open a file and read a HDU that contains specified
766  // search keywords with [optional] specified values
767  // (sometimes one just wants to know that the keyword is present).
768  //
769  // Optional parameters allows the reading of specified primary HDU keys and specified keywords in
770  // the HDU of interest.
771  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);
772  const ExtHDU& extension (int i) const;
773  fitsfile* fitsPointer () const;
774  ExtHDU& extension (int i);
775  const ExtHDU& extension (const String& hduName, int version = 1) const;
776  const PHDU& pHDU () const;
777  PHDU& pHDU ();
778  ExtHDU& extension (const String& hduName, int version = 1);
779  friend std::ostream& operator << (std::ostream& s, const FITS& right);
780  // ! add a new Table extension to a FITS object
781  Table* addTable (const String& hduName, int rows, // ! Number of rows in new table. Mandatory
782  const std::vector<String>& columnName = std::vector<String>(), // ! Optional set of column names for new table
783  const std::vector<String>& columnFmt = std::vector<String>(), // ! Column formats for column units. Mandatory if columnName is specified
784  const std::vector<String>& columnUnit = std::vector<String>(), // ! Column formats for column units. Optional
785  HduType type = BinaryTbl, int version = 1);
786  // ! add a new ImageExt (image extension) to the FITS object. A "writing" method.
787  ExtHDU* addImage (const String& hduName, int bpix, std::vector<long>& naxes, int version = 1);
788  // Force destruction of the FITS object. Essentially
789  // is a manual destructor call.
790  void destroy () throw ();
791  void flush ();
792  const String& currentExtensionName () const;
793  const ExtMap& extension () const;
794  void resetPosition ();
795  void currentExtensionName (const String& extName);
796  const String& name () const;
797  void copy (const HDU& source);
798  Table& filter (const String& expression, ExtHDU& inputTable, bool overwrite = true, bool readData = false);
800  void deleteExtension (int doomed);
801  void setCompressionType (int compType);
802  void setTileDimensions (const std::vector<long>& tileSizes);
803  void setNoiseBits (int noiseBits);
804  int getCompressionType () const;
805  void getTileDimensions (std::vector<long>& tileSizes) const;
806  int getNoiseBits () const;
807  static bool verboseMode ();
808  static void setVerboseMode (bool value);
809 
810  public:
811  // Additional Public Declarations
812 
813  protected:
814  // Additional Protected Declarations
815 
816  private:
817  FITS(const FITS &right);
818  FITS & operator=(const FITS &right);
819 
820  void unmapExtension (ExtHDU& doomed);
821  int nextVersionNumber (const String& inputName) const;
822  // read the primary HDU. Read the image if
823  // readDataFlag is true.
824  void read (bool readDataFlag = false, const std::vector<String>& keys = std::vector<String>());
825  // Returns index of current HDU where primary = 0. (Extended file syntax may cause a shift to an
826  // extension.)
827  int open (RWmode mode = Read);
828  // Create returns true if a new file was created or an
829  // existing file overwritten, false if appending.
830  //
831  //
832  // It throws exception CantCreate or CantOpen if either fails.
833  bool create ();
834  // Close the fits file.
835  //
836  // Called in destructors so must not throw.
837  int close () throw ();
838  std::ostream & put (std::ostream &s) const;
839  ExtHDU& extbyVersion (const String& hduName, int version) const;
840  void pHDU (PHDU* value);
841  void readExtensions (bool readDataFlag = false);
842  ExtHDU* addExtension (ExtHDU* ext);
843  void swap (FITS& right);
844  ExtMap& extensionMap ();
845  String nameOfUnmapped (int hduNum) const;
846  void cloneHeader (const ExtHDU& source);
847 
848  // Check if caller is requesting an already read ExtHDU (ie. one
849  // that's already been added to ExtMap). If hduIdx=0, check by
850  // matching name and optional version. Otherwise check by matching
851  // hduIdx. If found, returns pointer to the ExtHDU. Otherwise
852  // returns 0. This will not throw.
853  ExtHDU* checkAlreadyRead(const int hduIdx,
854  const String& hduName = string(""), const int version=1) const throw();
855 
856  // Additional Private Declarations
857 
858  private: //## implementation
859  // Data Members for Class Attributes
860  static bool s_verboseMode;
861 
862  // Data Members for Associations
863  FITSBase* m_FITSImpl;
864 
865  // Additional Implementation Declarations
866  friend void HDU::makeThisCurrent() const;
867  };
868 
869  // Class CCfits::FITS::NoSuchHDU
870 
871  // Class CCfits::FITS::OperationNotSupported
872 
873  // Class CCfits::FITS::CantOpen
874 
875  // Class CCfits::FITS::CantCreate
876 
877  // Class CCfits::FITS
878 
879  inline ExtHDU& FITS::extension (const String& hduName, int version)
880  {
881 
882  return extbyVersion(hduName,version);
883  }
884 
885  inline std::ostream& operator << (std::ostream& s, const FITS& right)
886  {
887 
888  return right.put(s);
889  }
890 
891  inline bool FITS::verboseMode ()
892  {
893  return s_verboseMode;
894  }
895 
896  inline void FITS::setVerboseMode (bool value)
897  {
898  s_verboseMode = value;
899  }
900 
901 } // namespace CCfits
902 
903 
904 #endif