CCfits  2.5
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  class FITSBase;
30 
31 } // namespace CCfits
32 namespace CCfits {
33  class HDUCreator; // Needed for friend declaration
34 }
35 
36 #ifdef _MSC_VER
37 #include "MSconfig.h" // for truncation warning
38 #endif
39 #include "KeywordT.h"
40 
41 
42 namespace CCfits {
571  class HDU
572  {
573 
574  public:
575 
576 
577 
578  class InvalidImageDataType : public FitsException //## Inherits: <unnamed>%394FBA12005C
579  {
580  public:
581  InvalidImageDataType (const string& diag, bool silent = true);
582 
583  protected:
584  private:
585  private: //## implementation
586  };
587 
588 
589 
590  class InvalidExtensionType : public FitsException //## Inherits: <unnamed>%3964C1D00352
591  {
592  public:
593  InvalidExtensionType (const string& diag, bool silent = true);
594 
595  protected:
596  private:
597  private: //## implementation
598  };
599 
600 
601 
602  class NoSuchKeyword : public FitsException //## Inherits: <unnamed>%398865D10264
603  {
604  public:
605  NoSuchKeyword (const string& diag, bool silent = true);
606 
607  protected:
608  private:
609  private: //## implementation
610  };
611 
612 
613 
614  class NoNullValue : public FitsException //## Inherits: <unnamed>%3B0D58CE0306
615  {
616  public:
617  NoNullValue (const string& diag, bool silent = true);
618 
619  protected:
620  private:
621  private: //## implementation
622  };
623  HDU(const HDU &right);
624  bool operator==(const HDU &right) const;
625 
626  bool operator!=(const HDU &right) const;
627 
628  virtual HDU * clone (FITSBase* p) const = 0;
629  fitsfile* fitsPointer () const;
630  FITSBase* parent () const;
631  // By all means necessary, set the fitsfile pointer so that
632  // this HDU is the current HDU.
633  //
634  // This would appear to be a good candidate for the public
635  // interface.
636  virtual void makeThisCurrent () const;
637  const String& getComments ();
638  const string& comment () const;
639  // Write a history string. A default value for the string is given
640  // "GenericComment" so users can put a placeholder call
641  // to this function in their code before knowing quite what should go in it.
642  void writeComment (const String& comment = "Generic Comment");
643  const String& getHistory ();
644  const string& history () const;
645  // Write a history string. A default value for the string is given
646  // "Generic History String" so users can put a placeholder call
647  // to this function in their code before knowing quite what should go in it.
648  void writeHistory (const String& history = "Generic History String");
649  // Write a date card.
650  void writeDate ();
651  friend std::ostream& operator << (std::ostream& s, const CCfits::HDU& right);
652  long axes () const;
653  long axis (size_t index) const;
654  void index (int value);
655  int index () const;
656  long bitpix () const;
657  virtual double scale () const;
658  virtual void scale (double value);
659  virtual double zero () const;
660  virtual void zero (double value);
661  virtual void resetImageRead ();
662  virtual void suppressScaling (bool toggle = true);
663  void writeChecksum ();
664  void updateChecksum ();
665  std::pair<int,int> verifyChecksum () const;
666  std::pair<unsigned long,unsigned long> getChecksum () const;
667  void deleteKey (const String& doomed);
668  void readAllKeys ();
669  void copyAllKeys (const HDU* inHdu);
670  std::map<String, Keyword*>& keyWord ();
671  Keyword& keyWord (const String& keyName);
672  static std::vector<int> keywordCategories ();
673  const std::map<string,Keyword*>& keyWord () const;
674  const Keyword& keyWord (const string& keyname) const;
675  Keyword& readNextKey(const std::vector<String>& incList,
676  const std::vector<String>& excList,
677  bool searchFromBeginning = false);
678 
679  public:
680  // Additional Public Declarations
681  template <typename T>
682  void readKey(const String& keyName, T& val);
683 
684  template <typename T>
685  void readKeys(std::vector<String>& keyNames, std::vector<T>& vals);
686 
687  template <typename T>
688  Keyword& addKey(const String& name, T val, const String& comment);
689 
690  // This non-template function could be entered with Rose, but
691  // it's instead placed with the other addKey function to
692  // simplify the Doxygen generated doc file output.
693  Keyword* addKey(const Keyword* inKeyword);
694 
695  Keyword& addKey(const String& name, const char* charString, const String& comment);
696 
697 #ifdef TEMPLATE_AMBIG_DEFECT
698  inline void readKeyMS(const String& keyName, int & val);
699  inline void readKeys(std::vector<String>& keyNames, std::vector<String>& vals);
700 
701 #endif
702  protected:
703  // Functions as the default constructor, which is required for
704  // the map container class.
705  HDU (FITSBase* p = 0);
706  HDU (FITSBase* p, int bitpix, int naxis, const std::vector<long>& axes);
707  virtual ~HDU();
708 
709  Keyword& readKeyword (const String &keyname);
710  void readKeywords (std::list<String>& keynames);
711  virtual std::ostream & put (std::ostream &s) const = 0;
712  void bitpix (long value);
713  bool checkImgDataTypeChange (double zero, double scale) const;
714  long& naxis ();
715  void naxis (const long& value);
716  // Flags whether there were any null values found in the
717  // last read operation.
718  bool& anynul ();
719  void anynul (const bool& value);
720  FITSBase*& parent ();
721  std::vector< long >& naxes ();
722  long& naxes (size_t index);
723  void naxes (size_t index, const long& value);
724 
725  // Additional Protected Declarations
726 
727  private:
728  // clear the FITS Keyword map. To be called by
729  // the dtor and the copy/assignment operations.
730  void clearKeys ();
731  virtual void initRead () = 0;
732  void readHduInfo ();
733  Keyword* addKeyword (Keyword* newKey);
734  virtual bool compare (const HDU &right) const;
735  // clear the FITS Keyword map. To be called by
736  // the dtor and the copy/assignment operations.
737  void copyKeys (const HDU& right);
738  String getNamedLines (const String& name);
739  // save keyword found by read all keys into the array of keywords that have been read.
740  // Similar to addKeyword except there's no write and no returned value. For use by readAllKeys()
741  void saveReadKeyword (Keyword* newKey);
742  void zeroInit (double value);
743  void scaleInit (double value);
744 
745  // Additional Private Declarations
746 
747  private: //## implementation
748  // Data Members for Class Attributes
749  long m_naxis;
750  long m_bitpix;
751  int m_index;
752  bool m_anynul;
753  string m_history;
754  string m_comment;
755  double m_zero;
756  // Floating point scale factor for image data that takes
757  // the value of the BSCALE parameter.
758  double m_scale;
759 
760  // Data Members for Associations
761  std::map<string,Keyword*> m_keyWord;
762  FITSBase* m_parent;
763  std::vector< long > m_naxes;
764 
765  // Additional Implementation Declarations
766  static const size_t s_nCategories;
767  static const int s_iKeywordCategories[];
768 
769  friend class HDUCreator;
770  friend Keyword* KeywordCreator::getKeyword(const String& keyname, HDU* p);
771  friend Keyword* KeywordCreator::getKeyword(const String& keyname, ValueType keyType, HDU* p);
772  };
773  template <typename T>
774  Keyword& HDU::addKey(const String& name, T value, const String& comment)
775  {
776  makeThisCurrent();
777  NewKeyword<T> keyCreator(this,value);
778  Keyword& newKey = *(addKeyword(keyCreator.createKeyword(name,comment)));
779  return newKey;
780  }
781 
782  template <typename T>
783  void HDU::readKey(const String& keyName, T& val)
784  {
785  makeThisCurrent();
786  Keyword& key = readKeyword(keyName);
787  key.value(val);
788  }
789 
790 
791  template <typename T>
792  void HDU::readKeys(std::vector<String>& keyNames, std::vector<T>& vals)
793  {
794  size_t nRead = keyNames.size();
795 
796  std::list<String> valKeys;
797  std::list<T> valList;
798  for (size_t i = 0; i < nRead; i++) valKeys.push_back(keyNames[i]);
799  // read all the keys requested, rejecting those that don't exist.
800 
801  readKeywords(valKeys);
802 
803  // get the values of all of the requested keys, rejecting those of the
804  // wrong type.
805 
806  T current;
807  std::list<String>::iterator it = valKeys.begin();
808  while (it != valKeys.end())
809  {
810  try
811  {
812  m_keyWord[*it]->value(current);
813  valList.push_back(current);
814  ++it;
815  }
816  catch ( Keyword::WrongKeywordValueType )
817  {
818  it = valKeys.erase(it);
819  }
820  }
821 
822  keyNames.erase(keyNames.begin(),keyNames.end());
823 
824  if (!valList.empty())
825  {
826  if (valList.size() != vals.size()) vals.resize(valList.size());
827 
828  size_t i=0;
829  for (typename std::list<T>::const_iterator it1
830  = valList.begin(); it1 != valList.end(); ++it1,++i)
831  {
832  vals[i] = *it1;
833  }
834  for (std::list<String>::const_iterator it1= valKeys.begin(); it1 != valKeys.end(); ++it1)
835  {
836  keyNames.push_back(*it1);
837  }
838  }
839 
840  }
841 
842  // Class CCfits::HDU::InvalidImageDataType
843 
844  // Class CCfits::HDU::InvalidExtensionType
845 
846  // Class CCfits::HDU::NoSuchKeyword
847 
848  // Class CCfits::HDU::NoNullValue
849 
850  // Class CCfits::HDU
851 
852  inline const string& HDU::comment () const
853  {
854  return m_comment;
855  }
856 
857  inline const string& HDU::history () const
858  {
859  return m_history;
860  }
861 
862  inline std::ostream& operator << (std::ostream& s, const CCfits::HDU& right)
863  {
864  return right.put(s);
865  }
866 
867  inline long HDU::axes () const
868  {
869 
870  return m_naxis;
871  }
872 
873  inline long HDU::axis (size_t index) const
874  {
875 
876  return m_naxes[index];
877  }
878 
879  inline void HDU::index (int value)
880  {
881 
882  m_index = value;
883  }
884 
885  inline int HDU::index () const
886  {
887  return m_index;
888  }
889 
890  inline long HDU::bitpix () const
891  {
892  return m_bitpix;
893  }
894 
895  inline void HDU::bitpix (long value)
896  {
897  m_bitpix = value;
898  }
899 
900  inline double HDU::scale () const
901  {
902  return m_scale;
903  }
904 
905  inline void HDU::scale (double value)
906  {
907  m_scale = value;
908  }
909 
910  inline double HDU::zero () const
911  {
912  return m_zero;
913  }
914 
915  inline void HDU::zero (double value)
916  {
917  m_zero = value;
918  }
919 
920  inline void HDU::resetImageRead ()
921  {
922  }
923 
924  inline void HDU::saveReadKeyword (Keyword* newKey)
925  {
926  m_keyWord.insert(std::map<String,Keyword*>::value_type(newKey->name(),newKey->clone()));
927  }
928 
929  inline std::map<String, Keyword*>& HDU::keyWord ()
930  {
931 
932  return m_keyWord;
933  }
934 
935  inline Keyword& HDU::keyWord (const String& keyName)
936  {
937  std::map<String,Keyword*>::iterator key = m_keyWord.find(keyName);
938  if (key == m_keyWord.end()) throw HDU::NoSuchKeyword(keyName);
939  return *((*key).second);
940  }
941 
942  inline long& HDU::naxis ()
943  {
944  return m_naxis;
945  }
946 
947  inline void HDU::naxis (const long& value)
948  {
949  m_naxis = value;
950  }
951 
952  inline bool& HDU::anynul ()
953  {
954  return m_anynul;
955  }
956 
957  inline void HDU::anynul (const bool& value)
958  {
959  m_anynul = value;
960  }
961 
962  inline const std::map<string,Keyword*>& HDU::keyWord () const
963  {
964  return m_keyWord;
965  }
966 
967  inline const Keyword& HDU::keyWord (const string& keyname) const
968  {
969  std::map<String,Keyword*>::const_iterator key = m_keyWord.find(keyname);
970  if (key == m_keyWord.end()) throw HDU::NoSuchKeyword(keyname);
971  return *((*key).second);
972  }
973 
974  inline FITSBase*& HDU::parent ()
975  {
976  return m_parent;
977  }
978 
979  inline std::vector< long >& HDU::naxes ()
980  {
981  return m_naxes;
982  }
983 
984  inline long& HDU::naxes (size_t index)
985  {
986  return m_naxes[index];
987  }
988 
989  inline void HDU::naxes (size_t index, const long& value)
990  {
991  m_naxes[index] = value;
992  }
993 
994 } // namespace CCfits
995 #ifdef SPEC_TEMPLATE_IMP_DEFECT
996 namespace CCfits {
997 
998  inline void HDU::readKeyMS(const String& keyName, int & val)
999  {
1000  makeThisCurrent();
1001  Keyword& key = readKeyword(keyName);
1002  key.value(val);
1003  }
1004 
1005  inline void HDU::readKeys(std::vector<String>& keyNames, std::vector<String>& vals)
1006  {
1007  size_t nRead = keyNames.size();
1008 
1009  std::list<String> valKeys;
1010  std::list<String> valList;
1011  for (size_t i = 0; i < nRead; i++) valKeys.push_back(keyNames[i]);
1012  // read all the keys requested, rejecting those that don't exist.
1013 
1014  readKeywords(valKeys);
1015 
1016  // get the values of all of the requested keys, rejecting those of the
1017  // wrong type.
1018 
1019  String current;
1020  std::list<String>::iterator it = valKeys.begin();
1021  while (it != valKeys.end())
1022  {
1023  try
1024  {
1025  m_keyWord[*it]->value(current);
1026  valList.push_back(current);
1027  ++it;
1028  }
1029  catch ( Keyword::WrongKeywordValueType )
1030  {
1031  it = valKeys.erase(it);
1032  }
1033  }
1034 
1035  keyNames.erase(keyNames.begin(),keyNames.end());
1036 
1037  if (!valList.empty())
1038  {
1039  if (valList.size() != vals.size()) vals.resize(valList.size());
1040 
1041  size_t i=0;
1042  std::list<String>::const_iterator it1 = valList.begin();
1043  for ( ; it1 != valList.end(); ++it1,++i)
1044  {
1045  vals[i] = *it1;
1046  }
1047  for ( it1= valKeys.begin(); it1 != valKeys.end(); ++it1)
1048  {
1049  keyNames.push_back(*it1);
1050  }
1051  }
1052 
1053  }
1054 }
1055  #endif
1056 
1057 
1058 #endif
virtual double zero() const
return the BZERO keyword value
Definition: HDU.h:910
void writeChecksum()
compute and write the DATASUM and CHECKSUM keyword values
Definition: HDU.cxx:479
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:511
T & value(T &val) const
get the keyword value
Definition: KeywordT.h:29
fitsfile * fitsPointer() const
return the fitsfile pointer for the FITS object containing the HDU
Definition: HDU.cxx:310
static std::vector< int > keywordCategories()
return the enumerated keyword categories used by readAllKeys() and copyAllKeys()
Definition: HDU.cxx:600
const string & history() const
return the history string previously read by getHistory()
Definition: HDU.h:857
void writeDate()
write a date string to *this.
Definition: HDU.cxx:439
exception to be thrown on seek errors for keywords.
Definition: HDU.h:602
void writeComment(const String &comment="Generic Comment")
write a comment string.
Definition: HDU.cxx:407
virtual Keyword * clone() const =0
virtual copy constructor
virtual double scale() const
return the BSCALE keyword value
Definition: HDU.h:900
void deleteKey(const String &doomed)
delete a keyword from the header
Definition: HDU.cxx:522
void copyAllKeys(const HDU *inHdu)
copy all keys from another header
Definition: HDU.cxx:573
exception to be thrown on seek errors for keywords.
Definition: HDU.h:614
Abstract base class defining the interface for Keyword objects.
Definition: Keyword.h:198
const string & comment() const
return the comment string previously read by getComment()
Definition: HDU.h:852
bool operator!=(const HDU &right) const
inequality operator
Definition: HDU.cxx:152
Base class for all HDU [Header-Data Unit] objects.
Definition: HDU.h:571
int index() const
return the HDU number
Definition: HDU.h:885
long axes() const
return the number of axes in the HDU data section (always 2 for tables).
Definition: HDU.h:867
std::map< String, Keyword * > & keyWord()
return the associative array containing the HDU keywords so far read.
Definition: HDU.h:929
Keyword & addKey(const String &name, T val, const String &comment)
create a new keyword in the HDU with specified value and comment fields
Definition: HDU.h:774
virtual void resetImageRead()
force next image reading operation to read from file instead of object cache.
Definition: HDU.h:920
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:723
virtual HDU * clone(FITSBase *p) const =0
virtual copy constructor, to be implemented in subclasses.
const String & name() const
return the name of a keyword
Definition: Keyword.h:314
const String & getHistory()
read the history information from the HDU and add it to the FITS object.
Definition: HDU.cxx:417
FitsException is the base class for all exceptions thrown by this library.
Definition: FitsError.h:93
Namespace enclosing all CCfits classes and globals definitions.
Definition: AsciiTable.cxx:26
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:783
long axis(size_t index) const
return the size of axis numbered index [zero based].
Definition: HDU.h:873
ValueType
CCfits value types and their CFITSIO equivalents (in caps)
Definition: CCfits.h:81
HDU(const HDU &right)
copy constructor
Definition: HDU.cxx:88
void readAllKeys()
read all of the keys in the header
Definition: HDU.cxx:532
void writeHistory(const String &history="Generic History String")
write a history string.
Definition: HDU.cxx:430
long bitpix() const
return the data type keyword.
Definition: HDU.h:890
virtual ~HDU()
destructor
Definition: HDU.cxx:140
const String & getComments()
read the comments from the HDU and add it to the FITS object.
Definition: HDU.cxx:395
virtual void makeThisCurrent() const
move the fitsfile pointer to this current HDU.
Definition: HDU.cxx:322
bool operator==(const HDU &right) const
equality operator
Definition: HDU.cxx:147
exception to be thrown if user requests extension type that can not be understood as ImageExt...
Definition: HDU.h:590
std::pair< int, int > verifyChecksum() const
verify the HDU by computing the checksums and comparing them with the CHECKSUM/DATASUM keywords ...
Definition: HDU.cxx:497
std::vector< long > & naxes()
return the HDU data axis array.
Definition: HDU.h:979
FITSBase * parent() const
return reference to the pointer representing the FITSBase object containing the HDU ...
Definition: HDU.cxx:316
void updateChecksum()
update the CHECKSUM keyword value, assuming DATASUM exists and is correct
Definition: HDU.cxx:488
InvalidImageDataType(const string &diag, bool silent=true)
Exception ctor, prefixes the string "Fits Error: Invalid Data Type for Image " before the specific me...
Definition: HDU.cxx:46
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:792
virtual void suppressScaling(bool toggle=true)
turn off image scaling regardless of the BSCALE and BZERO keyword values
Definition: HDU.cxx:462
exception to be thrown if user requests creation of an image of type not supported by cfitsio...
Definition: HDU.h:578