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