CCfits  2.6
HDU.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 HDU_H
10 #define HDU_H 1
11 #include <map>
12 
13 // vector
14 #include <vector>
15 #include <list>
16 // CCfitsHeader
17 #include "CCfits.h"
18 // Keyword
19 #include "Keyword.h"
20 // NewKeyword
21 #include "NewKeyword.h"
22 // FitsError
23 #include "FitsError.h"
24 // FITSUtil
25 #include "FITSUtil.h"
26 
27 namespace CCfits {
28  class FITS;
29 
30 } // namespace CCfits
31 namespace CCfits {
32  class HDUCreator; // Needed for friend declaration
33 }
34 
35 #ifdef _MSC_VER
36 #include "MSconfig.h" // for truncation warning
37 #endif
38 #include "KeywordT.h"
39 
40 
41 namespace CCfits {
42 
673  class HDU
674  {
675 
676  public:
677 
678 
679  class InvalidImageDataType : public FitsException //## Inherits: <unnamed>%394FBA12005C
680  {
681  public:
682  InvalidImageDataType (const string& diag, bool silent = true);
683 
684  protected:
685  private:
686  private: //## implementation
687  };
688 
689 
690  class InvalidExtensionType : public FitsException //## Inherits: <unnamed>%3964C1D00352
691  {
692  public:
693  InvalidExtensionType (const string& diag, bool silent = true);
694 
695  protected:
696  private:
697  private: //## implementation
698  };
699 
700 
701  class NoSuchKeyword : public FitsException //## Inherits: <unnamed>%398865D10264
702  {
703  public:
704  NoSuchKeyword (const string& diag, bool silent = true);
705 
706  protected:
707  private:
708  private: //## implementation
709  };
710 
711 
712  class NoNullValue : public FitsException //## Inherits: <unnamed>%3B0D58CE0306
713  {
714  public:
715  NoNullValue (const string& diag, bool silent = true);
716 
717  protected:
718  private:
719  private: //## implementation
720  };
721 
722 
723  HDU(const HDU &right);
724  bool operator==(const HDU &right) const;
725 
726  bool operator!=(const HDU &right) const;
727 
728  virtual HDU * clone (FITS* p) const = 0;
729  fitsfile* fitsPointer () const;
730  FITS* parent () const;
731  // By all means necessary, set the fitsfile pointer so that
732  // this HDU is the current HDU.
733  //
734  // This would appear to be a good candidate for the public
735  // interface.
736  virtual void makeThisCurrent () const;
737  const String& getComments ();
738  const string& comment () const;
739  // Write a comment string. A default value for the string is given
740  // "GenericComment" so users can put a placeholder call
741  // to this function in their code before knowing quite what should go in it.
742  void writeComment (const String& comment = "Generic Comment");
743  const String& getHistory ();
744  const string& history () const;
745  // Write a history string. A default value for the string is given
746  // "Generic History String" so users can put a placeholder call
747  // to this function in their code before knowing quite what should go in it.
748  void writeHistory (const String& history = "Generic History String");
749  // Write a date card.
750  void writeDate ();
751  friend std::ostream& operator << (std::ostream& s, const CCfits::HDU& right);
752  long axes () const;
753  long axis (size_t index) const;
754  void index (int value);
755  int index () const;
756  long bitpix () const;
757  virtual double scale () const;
758  virtual void scale (double value);
759  virtual double zero () const;
760  virtual void zero (double value);
761  virtual void resetImageRead ();
762  virtual void suppressScaling (bool toggle = true);
763  void writeChecksum ();
764  void updateChecksum ();
765  std::pair<int,int> verifyChecksum () const;
766  std::pair<unsigned long,unsigned long> getChecksum () const;
767  void deleteKey (const String& doomed);
768  void readAllKeys (const std::vector<int> & keyCategories = std::vector<int>());
769  void copyAllKeys (const HDU* inHdu, const std::vector<int> & keyCategories = std::vector<int>());
770  std::map<String, Keyword*>& keyWord ();
771  Keyword& keyWord (const String& keyName);
772  static std::vector<int> keywordCategories ();
773  const std::map<string,Keyword*>& keyWord () const;
774  const Keyword& keyWord (const string& keyname) const;
775  Keyword& readNextKey(const std::vector<String>& incList,
776  const std::vector<String>& excList,
777  bool searchFromBeginning = false);
778 
779 
780  public:
781  // Additional Public Declarations
782 
783  template <typename T>
784  void readKey(const String& keyName, T& val);
785 
786  template <typename T>
787  void readKeys(std::vector<String>& keyNames, std::vector<T>& vals);
788 
789  template <typename T>
790  Keyword& addKey(const String& name, T val, const String& comment, bool isLongStr = false);
791 
792  // This non-template function could be entered with Rose, but
793  // it's instead placed with the other addKey function to
794  // simplify the Doxygen generated doc file output.
795  Keyword* addKey(const Keyword* inKeyword);
796 
797  Keyword& addKey(const String& name, const char* charString, const String& comment, bool isLongStr = false);
798 
799 #ifdef TEMPLATE_AMBIG_DEFECT
800  inline void readKeyMS(const String& keyName, int & val);
801  inline void readKeys(std::vector<String>& keyNames, std::vector<String>& vals);
802 
803 #endif
804 
805 
806  protected:
807 
808  // Functions as the default constructor, which is required for
809  // the map container class.
810  HDU (FITS* p = 0);
811  HDU (FITS* p, int bitpix, int naxis, const std::vector<long>& axes);
812  virtual ~HDU();
813 
814  Keyword& readKeyword (const String &keyname);
815  void readKeywords (std::list<String>& keynames);
816  virtual std::ostream & put (std::ostream &s) const = 0;
817  void bitpix (long value);
818  bool checkImgDataTypeChange (double zero, double scale) const;
819  long& naxis ();
820  void naxis (const long& value);
821  // Flags whether there were any null values found in the
822  // last read operation.
823  bool& anynul ();
824  void anynul (const bool& value);
825  FITS*& parent ();
826 
827  std::vector< long >& naxes ();
828  long& naxes (size_t index);
829  void naxes (size_t index, const long& value);
830 
831  // Additional Protected Declarations
832 
833 
834  private:
835 
836  // clear the FITS Keyword map. To be called by
837  // the dtor and the copy/assignment operations.
838  void clearKeys ();
839  virtual void initRead () = 0;
840  void readHduInfo ();
841  Keyword* addKeyword (Keyword* newKey);
842  virtual bool compare (const HDU &right) const;
843  // clear the FITS Keyword map. To be called by
844  // the dtor and the copy/assignment operations.
845  void copyKeys (const HDU& right);
846  String getNamedLines (const String& name);
847  // save keyword found by read all keys into the array of keywords that have been read.
848  // Similar to addKeyword except there's no write and no returned value. For use by readAllKeys()
849  void saveReadKeyword (Keyword* newKey);
850  void zeroInit (double value);
851  void scaleInit (double value);
852 
853  // Additional Private Declarations
854 
855 
856  private: //## implementation
857  // Data Members for Class Attributes
858  long m_naxis;
859  long m_bitpix;
860  int m_index;
861  bool m_anynul;
862  string m_history;
863  string m_comment;
864  double m_zero;
865  // Floating point scale factor for image data that takes
866  // the value of the BSCALE parameter.
867  double m_scale;
868 
869  // Data Members for Associations
870  std::map<string,Keyword*> m_keyWord;
871  FITS* m_parent;
872  std::vector< long > m_naxes;
873 
874  // Additional Implementation Declarations
875  static const size_t s_nCategories;
876  static const int s_iKeywordCategories[];
877 
878  friend class HDUCreator;
879  friend Keyword* KeywordCreator::getKeyword(const String& keyname, HDU* p);
880  friend Keyword* KeywordCreator::getKeyword(const String& keyname, ValueType keyType, HDU* p);
881 
882  };
883 
884 
885  template <typename T>
886  Keyword& HDU::addKey(const String& name, T value, const String& comment, bool isLongStr)
887  {
888  makeThisCurrent();
889  NewKeyword<T> keyCreator(this,value);
890  Keyword& newKey = *(addKeyword(keyCreator.createKeyword(name,comment,isLongStr)));
891  return newKey;
892  }
893 
894  template <typename T>
895  void HDU::readKey(const String& keyName, T& val)
896  {
897  makeThisCurrent();
898  Keyword& key = readKeyword(keyName);
899  key.value(val);
900  }
901 
902  template <typename T>
903  void HDU::readKeys(std::vector<String>& keyNames, std::vector<T>& vals)
904  {
905  size_t nRead = keyNames.size();
906 
907  std::list<String> valKeys;
908  std::list<T> valList;
909  for (size_t i = 0; i < nRead; i++) valKeys.push_back(keyNames[i]);
910  // read all the keys requested, rejecting those that don't exist.
911 
912  readKeywords(valKeys);
913 
914  // get the values of all of the requested keys, rejecting those of the
915  // wrong type.
916 
917  T current;
918  std::list<String>::iterator it = valKeys.begin();
919  while (it != valKeys.end())
920  {
921  try
922  {
923  m_keyWord[*it]->value(current);
924  valList.push_back(current);
925  ++it;
926  }
927  catch ( Keyword::WrongKeywordValueType )
928  {
929  it = valKeys.erase(it);
930  }
931  }
932 
933  keyNames.erase(keyNames.begin(),keyNames.end());
934 
935  if (!valList.empty())
936  {
937  if (valList.size() != vals.size()) vals.resize(valList.size());
938 
939  size_t i=0;
940  for (typename std::list<T>::const_iterator it1
941  = valList.begin(); it1 != valList.end(); ++it1,++i)
942  {
943  vals[i] = *it1;
944  }
945  for (std::list<String>::const_iterator it1= valKeys.begin(); it1 != valKeys.end(); ++it1)
946  {
947  keyNames.push_back(*it1);
948  }
949  }
950 
951  }
952 
953  // Class CCfits::HDU::InvalidImageDataType
954 
955  // Class CCfits::HDU::InvalidExtensionType
956 
957  // Class CCfits::HDU::NoSuchKeyword
958 
959  // Class CCfits::HDU::NoNullValue
960 
961  // Class CCfits::HDU
962 
963  inline const string& HDU::comment () const
964  {
965  return m_comment;
966  }
967 
968  inline const string& HDU::history () const
969  {
970  return m_history;
971  }
972 
973  inline std::ostream& operator << (std::ostream& s, const CCfits::HDU& right)
974  {
975  return right.put(s);
976  }
977 
978  inline long HDU::axes () const
979  {
980  return m_naxis;
981  }
982 
983  inline long HDU::axis (size_t index) const
984  {
985  return m_naxes[index];
986  }
987 
988  inline void HDU::index (int value)
989  {
990  m_index = value;
991  }
992 
993  inline int HDU::index () const
994  {
995  return m_index;
996  }
997 
998  inline long HDU::bitpix () const
999  {
1000  return m_bitpix;
1001  }
1002 
1003  inline void HDU::bitpix (long value)
1004  {
1005  m_bitpix = value;
1006  }
1007 
1008  inline double HDU::scale () const
1009  {
1010  return m_scale;
1011  }
1012 
1013  inline void HDU::scale (double value)
1014  {
1015  m_scale = value;
1016  }
1017 
1018  inline double HDU::zero () const
1019  {
1020  return m_zero;
1021  }
1022 
1023  inline void HDU::zero (double value)
1024  {
1025  m_zero = value;
1026  }
1027 
1028  inline void HDU::resetImageRead ()
1029  {
1030  }
1031 
1032  inline void HDU::saveReadKeyword (Keyword* newKey)
1033  {
1034  m_keyWord.insert(std::map<String,Keyword*>::value_type(newKey->name(),newKey->clone()));
1035  }
1036 
1037  inline std::map<String, Keyword*>& HDU::keyWord ()
1038  {
1039  return m_keyWord;
1040  }
1041 
1042  inline Keyword& HDU::keyWord (const String& keyName)
1043  {
1044  std::map<String,Keyword*>::iterator key = m_keyWord.find(keyName);
1045  if (key == m_keyWord.end()) throw HDU::NoSuchKeyword(keyName);
1046  return *((*key).second);
1047  }
1048 
1049  inline long& HDU::naxis ()
1050  {
1051  return m_naxis;
1052  }
1053 
1054  inline void HDU::naxis (const long& value)
1055  {
1056  m_naxis = value;
1057  }
1058 
1059  inline bool& HDU::anynul ()
1060  {
1061  return m_anynul;
1062  }
1063 
1064  inline void HDU::anynul (const bool& value)
1065  {
1066  m_anynul = value;
1067  }
1068 
1069  inline const std::map<string,Keyword*>& HDU::keyWord () const
1070  {
1071  return m_keyWord;
1072  }
1073 
1074  inline const Keyword& HDU::keyWord (const string& keyname) const
1075  {
1076  std::map<String,Keyword*>::const_iterator key = m_keyWord.find(keyname);
1077  if (key == m_keyWord.end()) throw HDU::NoSuchKeyword(keyname);
1078  return *((*key).second);
1079  }
1080 
1081  inline FITS*& HDU::parent ()
1082  {
1083  return m_parent;
1084  }
1085 
1086  inline std::vector< long >& HDU::naxes ()
1087  {
1088  return m_naxes;
1089  }
1090 
1091  inline long& HDU::naxes (size_t index)
1092  {
1093  return m_naxes[index];
1094  }
1095 
1096  inline void HDU::naxes (size_t index, const long& value)
1097  {
1098  m_naxes[index] = value;
1099  }
1100 
1101 } // namespace CCfits
1102 
1103 #ifdef SPEC_TEMPLATE_IMP_DEFECT
1104 namespace CCfits {
1105 
1106  inline void HDU::readKeyMS(const String& keyName, int & val)
1107  {
1108  makeThisCurrent();
1109  Keyword& key = readKeyword(keyName);
1110  key.value(val);
1111  }
1112 
1113  inline void HDU::readKeys(std::vector<String>& keyNames, std::vector<String>& vals)
1114  {
1115  size_t nRead = keyNames.size();
1116 
1117  std::list<String> valKeys;
1118  std::list<String> valList;
1119  for (size_t i = 0; i < nRead; i++) valKeys.push_back(keyNames[i]);
1120  // read all the keys requested, rejecting those that don't exist.
1121 
1122  readKeywords(valKeys);
1123 
1124  // get the values of all of the requested keys, rejecting those of the
1125  // wrong type.
1126 
1127  String current;
1128  std::list<String>::iterator it = valKeys.begin();
1129  while (it != valKeys.end())
1130  {
1131  try
1132  {
1133  m_keyWord[*it]->value(current);
1134  valList.push_back(current);
1135  ++it;
1136  }
1137  catch ( Keyword::WrongKeywordValueType )
1138  {
1139  it = valKeys.erase(it);
1140  }
1141  }
1142 
1143  keyNames.erase(keyNames.begin(),keyNames.end());
1144 
1145  if (!valList.empty())
1146  {
1147  if (valList.size() != vals.size()) vals.resize(valList.size());
1148 
1149  size_t i=0;
1150  std::list<String>::const_iterator it1 = valList.begin();
1151  for ( ; it1 != valList.end(); ++it1,++i)
1152  {
1153  vals[i] = *it1;
1154  }
1155  for ( it1= valKeys.begin(); it1 != valKeys.end(); ++it1)
1156  {
1157  keyNames.push_back(*it1);
1158  }
1159  }
1160 
1161  }
1162 }
1163  #endif
1164 
1165 
1166 #endif
std::pair< unsigned long, unsigned long > getChecksum() const
compute and return the checksum values for the HDU without creating or modifying the CHECKSUM/DATASUM...
Definition: HDU.cxx:532
void writeChecksum()
compute and write the DATASUM and CHECKSUM keyword values
Definition: HDU.cxx:500
static std::vector< int > keywordCategories()
Return the default enumerated keyword categories used by copyAllKeys()
Definition: HDU.cxx:660
void writeDate()
write a date string to *this.
Definition: HDU.cxx:460
exception to be thrown on seek errors for keywords.
Definition: HDU.h:701
void writeComment(const String &comment="Generic Comment")
write a comment string.
Definition: HDU.cxx:403
FITS * parent() const
return reference to the pointer representing the FITS object containing the HDU
Definition: HDU.cxx:313
virtual Keyword * clone() const =0
virtual copy constructor
long axis(size_t index) const
return the size of axis numbered index [zero based].
Definition: HDU.h:983
bool operator!=(const HDU &right) const
inequality operator
Definition: HDU.cxx:150
NoNullValue(const string &diag, bool silent=true)
Exception ctor, prefixes the string &quot;Fits Error: No Null Pixel Value specified for Image &quot; before the...
Definition: HDU.cxx:76
long bitpix() const
return the data type keyword.
Definition: HDU.h:998
void deleteKey(const String &doomed)
delete a keyword from the header
Definition: HDU.cxx:543
virtual HDU * clone(FITS *p) const =0
virtual copy constructor, to be implemented in subclasses.
fitsfile * fitsPointer() const
return the fitsfile pointer for the FITS object containing the HDU
Definition: HDU.cxx:308
const String & name() const
return the name of a keyword
Definition: Keyword.h:320
std::pair< int, int > verifyChecksum() const
verify the HDU by computing the checksums and comparing them with the CHECKSUM/DATASUM keywords ...
Definition: HDU.cxx:518
exception to be thrown on seek errors for keywords.
Definition: HDU.h:712
Abstract base class defining the interface for Keyword objects.
Definition: Keyword.h:198
Base class for all HDU [Header-Data Unit] objects.
Definition: HDU.h:673
std::map< String, Keyword * > & keyWord()
return the associative array containing the HDU keywords so far read.
Definition: HDU.h:1037
virtual void resetImageRead()
force next image reading operation to read from file instead of object cache.
Definition: HDU.h:1028
Keyword & readNextKey(const std::vector< String > &incList, const std::vector< String > &excList, bool searchFromBeginning=false)
Read the next key in the HDU which matches a string in incList, and does not match string in excList...
Definition: HDU.cxx:783
const String & getHistory()
read the history information from the HDU and add it to the FITS object.
Definition: HDU.cxx:425
InvalidExtensionType(const string &diag, bool silent=true)
Exception ctor, prefixes the string &quot;Fits Error: Extension Type: &quot; before the specific message...
Definition: HDU.cxx:54
Memory object representation of a disk FITS file.
Definition: FITS.h:628
FitsException is the base class for all exceptions thrown by this library.
Definition: FitsError.h:93
void readKey(const String &keyName, T &val)
read a keyword of specified type from the header of a disk FITS file and return its value...
Definition: HDU.h:895
ValueType
CCfits value types and their CFITSIO equivalents (in caps)
Definition: CCfits.h:81
int index() const
return the HDU number
Definition: HDU.h:993
virtual void makeThisCurrent() const
move the fitsfile pointer to this current HDU.
Definition: HDU.cxx:318
HDU(const HDU &right)
copy constructor
Definition: HDU.cxx:86
void readAllKeys(const std::vector< int > &keyCategories=std::vector< int >())
read all of the keys in the header
Definition: HDU.cxx:553
std::ostream & operator<<(std::ostream &s, const Column &right)
output operator for Column objects.
Definition: Column.h:1337
void writeHistory(const String &history="Generic History String")
write a history string.
Definition: HDU.cxx:438
T & value(T &val) const
get the keyword value
Definition: KeywordT.h:29
long axes() const
return the number of axes in the HDU data section (always 2 for tables).
Definition: HDU.h:978
virtual ~HDU()
destructor
Definition: HDU.cxx:138
NoSuchKeyword(const string &diag, bool silent=true)
Exception ctor, prefixes the string &quot;Fits Error: Keyword not found: &quot; before the specific message...
Definition: HDU.cxx:66
void copyAllKeys(const HDU *inHdu, const std::vector< int > &keyCategories=std::vector< int >())
copy all keys from another header
Definition: HDU.cxx:617
const String & getComments()
read the comments from the HDU and add it to the FITS object.
Definition: HDU.cxx:391
exception to be thrown if user requests extension type that can not be understood as ImageExt...
Definition: HDU.h:690
bool operator==(const HDU &right) const
equality operator
Definition: HDU.cxx:145
std::vector< long > & naxes()
return the HDU data axis array.
Definition: HDU.h:1086
const string & history() const
return the history string previously read by getHistory()
Definition: HDU.h:968
virtual double scale() const
return the BSCALE keyword value
Definition: HDU.h:1008
virtual double zero() const
return the BZERO keyword value
Definition: HDU.h:1018
void updateChecksum()
update the CHECKSUM keyword value, assuming DATASUM exists and is correct
Definition: HDU.cxx:509
InvalidImageDataType(const string &diag, bool silent=true)
Exception ctor, prefixes the string &quot;Fits Error: Invalid Data Type for Image &quot; before the specific me...
Definition: HDU.cxx:44
const string & comment() const
return the comment string previously read by getComment()
Definition: HDU.h:963
void readKeys(std::vector< String > &keyNames, std::vector< T > &vals)
read a set of specified keywords of the same data type from the header of a disk FITS file and return...
Definition: HDU.h:903
Keyword & addKey(const String &name, T val, const String &comment, bool isLongStr=false)
create a new keyword in the HDU with specified value and comment fields
Definition: HDU.h:886
virtual void suppressScaling(bool toggle=true)
turn off image scaling regardless of the BSCALE and BZERO keyword values
Definition: HDU.cxx:483
exception to be thrown if user requests creation of an image of type not supported by cfitsio...
Definition: HDU.h:679