CCfits  2.6
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 PHDU;
27  class Table;
28  class GroupTable;
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 {
624  // ! The FITS object class. Contains a primary HDU and Extensions indexed by name.
625 
626 
627 
628  class FITS
629  {
630 
631  public:
632 
633 
634  class NoSuchHDU : public FitsException //## Inherits: <unnamed>%396C90CB0236
635  {
636  public:
637  NoSuchHDU (const String& diag, bool silent = true);
638 
639  protected:
640  private:
641  private: //## implementation
642  };
643 
644 
645  class OperationNotSupported : public FitsException //## Inherits: <unnamed>%39806C7600D5
646  {
647  public:
648  OperationNotSupported (const String& msg, bool silent = true);
649 
650  protected:
651  private:
652  private: //## implementation
653  };
654 
655 
656  class CantOpen : public FitsException //## Inherits: <unnamed>%39C8EB1D02C0
657  {
658  public:
659  CantOpen (const String& diag, bool silent = true);
660 
661  protected:
662  private:
663  private: //## implementation
664  };
665 
666 
667  struct CantCreate : public FitsException //## Inherits: <unnamed>%39C8EB10020B
668  {
669  CantCreate (const String& diag, bool silent = false);
670 
671  public:
672  protected:
673  private:
674  private: //## implementation
675  };
676 
677  FITS (const String &name, RWmode rwmode = Read, bool readDataFlag = false, const std::vector<String>& primaryKeys = std::vector<String>());
678  // Open a file and read a specified HDU.
679  //
680  // Optional parameter allows the reading of specified primary HDU keys.
681  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);
682  // Read data from a set of specified HDUs. keywords can only be specified for the primary here.
683  // The code will call a different constructor for the case where keywords are required for
684  // the extensions.
685  FITS (const String &name, RWmode rwmode, const std::vector<String>& hduNames, bool readDataFlag = false, const std::vector<String>& primaryKey = std::vector<String>());
686  // Initialize a new FITS file object with the primary from a
687  // different file.
688  FITS (const String& fileName, const FITS& source);
689  // Fully general FITS HDU reader. May read any part of fits file by
690  // supplying HDU names and version numbers, and optionally
691  // the data read flag.
692  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>());
693  // Writing constructor. Takes a name and information to create an empty
694  // Primary HDU which can then be filled with calls to HDU methods.
695  FITS (const String& name, int bitpix, int naxis, long *naxes);
696  // Open a file and read a specified HDU.
697  //
698  // Optional parameter allows the reading of specified primary HDU keys.
699  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>());
700  // Open a file and read a HDU that contains specified
701  // search keywords with [optional] specified values
702  // (sometimes one just wants to know that the keyword is present).
703  //
704  // Optional parameters allows the reading of specified primary HDU keys and specified keywords in
705  // the HDU of interest.
706  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);
707  ~FITS();
708 
709  static void clearErrors ();
710  void deleteExtension (const String& doomed, int version = 1);
711 
712  // Read keys and data from a single ExtHDU in the file.
713  void read (const String &hduName, bool readDataFlag = false, const std::vector<String> &keys = std::vector<String>(), int version = 1);
714  // Read multiple ExtHDUs. If the version number needs to be specified
715  // then one must call a different method.
716  void read (const std::vector<String> &hduNames, bool readDataFlag = false);
717  // Read selected data from multiple ExtHDUs
718  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>());
719  // Read keys and data from a single ExtHDU in the file.
720  // Construct and Read HDU specified by number. One can add further HDUs by number using the HDUCreator factory.
721  void read (int hduIndex, bool readDataFlag = false, const std::vector<String> &keys = std::vector<String>());
722  // Open a file and read a HDU that contains specified
723  // search keywords with [optional] specified values
724  // (sometimes one just wants to know that the keyword is present).
725  //
726  // Optional parameters allows the reading of specified primary HDU keys and specified keywords in
727  // the HDU of interest.
728  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);
730  ExtHDU& extension (int i);
731  const ExtHDU& extension (int i) const;
732  ExtHDU& extension (const String& hduName, int version = 1);
733  const ExtHDU& extension (const String& hduName, int version = 1) const;
734  fitsfile* fitsPointer () const;
735  PHDU& pHDU ();
736  const PHDU& pHDU () const;
737  friend std::ostream& operator << (std::ostream& s, const FITS& right);
738  // ! add a new Table extension to a FITS object
739  Table* addTable (const String& hduName, int rows, // ! Number of rows in new table. Mandatory
740  const std::vector<String>& columnName = std::vector<String>(), // ! Optional set of column names for new table
741  const std::vector<String>& columnFmt = std::vector<String>(), // ! Column formats for column units. Mandatory if columnName is specified
742  const std::vector<String>& columnUnit = std::vector<String>(), // ! Column formats for column units. Optional
743  HduType type = BinaryTbl, int version = 1);
744  // ! add a new Group Table to the FITS object
745  Table * addGroupTable(const String & groupName, int groupID);
746  //GroupTable * addGroupTable(const String & groupName, int groupID);
747  // ! add a new ImageExt (image extension) to the FITS object. A "writing" method.
748  ExtHDU* addImage (const String& hduName, int bpix, std::vector<long>& naxes, int version = 1);
749  // Force destruction of the FITS object. Essentially
750  // is a manual destructor call.
751  void destroy () throw ();
752  void flush ();
753  void resetPosition ();
754  const ExtMap& extension () const;
755  void deleteExtension (int doomed);
756  const String& currentExtensionName () const;
757  void currentExtensionName (const String& extName);
758  const String& name () const;
759  void copy (const HDU& source);
760  Table& filter (const String& expression, ExtHDU& inputTable, bool overwrite = true, bool readData = false);
761  void setCompressionType (int compType);
762  void setTileDimensions (const std::vector<long>& tileSizes);
763  void setNoiseBits (int noiseBits);
764  int getCompressionType () const;
765  void getTileDimensions (std::vector<long>& tileSizes) const;
766  int getNoiseBits () const;
767  static bool verboseMode ();
768  static void setVerboseMode (bool value);
769 
770  public:
771  // Additional Public Declarations
772 
773  protected:
774  // Additional Protected Declarations
775 
776  private:
777  FITS(const FITS &right);
778  FITS & operator=(const FITS &right);
779 
780  void unmapExtension (ExtHDU& doomed);
781  int nextVersionNumber (const String& inputName) const;
782  // read the primary HDU. Read the image if
783  // readDataFlag is true.
784  void read (bool readDataFlag = false, const std::vector<String>& keys = std::vector<String>());
785  // Returns index of current HDU where primary = 0. (Extended file syntax may cause a shift to an
786  // extension.)
787  int open (RWmode rwmode = Read);
788  // Create returns true if a new file was created or an
789  // existing file overwritten, false if appending.
790  //
791  // It throws exception CantCreate or CantOpen if either fails.
792  bool create ();
793  // Close the fits file.
794  //
795  // Called in destructors so must not throw.
796  int close () throw ();
797  std::ostream & put (std::ostream &s) const;
798  ExtHDU& extbyVersion (const String& hduName, int version) const;
799  void pHDU (PHDU* value);
800  void readExtensions (bool readDataFlag = false);
801  ExtHDU* addExtension (ExtHDU* ext);
802  String nameOfUnmapped (int hduNum) const;
803  void cloneHeader (const ExtHDU& source);
804 
805  // Check if caller is requesting an already read ExtHDU (ie. one
806  // that's already been added to ExtMap). If hduIdx=0, check by
807  // matching name and optional version. Otherwise check by matching
808  // hduIdx. If found, returns pointer to the ExtHDU. Otherwise
809  // returns 0. This will not throw.
810  ExtHDU* checkAlreadyRead(const int hduIdx,
811  const String& hduName = string(""), const int version=1) const throw();
812 
813  // Additional Private Declarations
814 
815  void destroyPrimary ();
816  void destroyExtensions ();
817  int currentCompressionTileDim () const;
818  void currentCompressionTileDim (int value);
819 
820 
821  private: //## implementation
822  // Data Members for Class Attributes
823  static bool s_verboseMode;
824  int m_currentCompressionTileDim;
825 
826  // Data Members for Associations
827  RWmode m_mode;
828  std::string m_currentExtensionName;
829  std::string m_filename;
830  PHDU* m_pHDU;
831  ExtMap m_extension;
832  fitsfile* m_fptr;
833 
834 
835  // ## Additional Implementation Declarations
836  friend void HDU::makeThisCurrent() const;
837  // MakeImage needs to access the m_pHDU pointer
838  friend PHDU * HDUCreator::MakeImage (int bpix, int naxis, const std::vector<long>& naxes);
839 
840  };
841 
842  // Class CCfits::FITS::NoSuchHDU
843 
844  // Class CCfits::FITS::OperationNotSupported
845 
846  // Class CCfits::FITS::CantOpen
847 
848  // Class CCfits::FITS::CantCreate
849 
850  // Class CCfits::FITS
851 
852  inline ExtHDU& FITS::extension (const String& hduName, int version)
853  {
854  return extbyVersion(hduName,version);
855  }
856 
857  inline std::ostream& operator << (std::ostream& s, const FITS& right)
858  {
859  return right.put(s);
860  }
861 
862  inline bool FITS::verboseMode ()
863  {
864  return s_verboseMode;
865  }
866 
867  inline void FITS::setVerboseMode (bool value)
868  {
869  s_verboseMode = value;
870  }
871 
872  inline int FITS::currentCompressionTileDim () const
873  {
874  return m_currentCompressionTileDim;
875  }
876 
877  inline void FITS::currentCompressionTileDim (int value)
878  {
879  m_currentCompressionTileDim = value;
880  }
881 
882  inline const String& FITS::currentExtensionName () const
883  {
884  return m_currentExtensionName;
885  }
886 
887  inline void FITS::currentExtensionName (const String& extName)
888  {
889  m_currentExtensionName = extName;
890  }
891 
892  inline const String& FITS::name () const
893  {
894  return m_filename;
895  }
896 
897  inline void FITS::pHDU (PHDU* value)
898  {
899  m_pHDU = value;
900  }
901 
902  inline const PHDU& FITS::pHDU () const
903  {
904  return *m_pHDU;
905  }
906 
907  inline PHDU& FITS::pHDU ()
908  {
909  return *m_pHDU;
910  }
911 
912  inline const ExtMap& FITS::extension () const
913  {
914  return m_extension;
915  }
916 
917  inline fitsfile* FITS::fitsPointer () const
918  {
919  return m_fptr;
920  }
921 
922 } // namespace CCfits
923 
924 
925 #endif
base class for all FITS extension HDUs, i.e. Image Extensions and Tables.
Definition: ExtHDU.h:439
thrown on failure to open existing file
Definition: FITS.h:657
CantOpen(const String &diag, bool silent=true)
Exception ctor prefixes the string: "FITS Error: Cannot create file " before specific message.
Definition: FITS.cxx:70
exception thrown by HDU retrieval methods.
Definition: FITS.h:635
NoSuchHDU(const String &diag, bool silent=true)
Exception ctor, prefixes the string "FITS Error: Cannot read HDU in FITS file:" before the specific m...
Definition: FITS.cxx:49
thrown for unsupported operations, such as attempted to select rows from an image extension.
Definition: FITS.h:646
OperationNotSupported(const String &msg, bool silent=true)
Exception ctor, prefixes the string "FITS Error: Operation not supported:" before the specific messag...
Definition: FITS.cxx:60
Memory object representation of a disk FITS file.
Definition: FITS.h:629
int getCompressionType() const
Get the int specifying the compression algorithm to be used when adding an image extension.
Definition: FITS.cxx:1439
void setNoiseBits(int noiseBits)
Set the cfitsio noisebits parameter used when compressing floating-point images.
Definition: FITS.cxx:1430
void flush()
flush buffer contents to disk
Definition: FITS.cxx:1054
const String & currentExtensionName() const
return the name of the extension that the fitsfile is currently addressing.
Definition: FITS.h:882
void read(const String &hduName, bool readDataFlag=false, const std::vector< String > &keys=std::vector< String >(), int version=1)
get data from single HDU from disk file.
Definition: FITS.cxx:421
~FITS()
destructor
Definition: FITS.cxx:332
PHDU & pHDU()
return a reference to the primary HDU.
Definition: FITS.h:907
static void clearErrors()
clear the error stack and set status to zero.
Definition: FITS.cxx:366
ExtHDU & currentExtension()
return a non-const reference to whichever is the current extension.
Definition: FITS.cxx:1269
void copy(const HDU &source)
copy the HDU source into the FITS object.
Definition: FITS.cxx:1079
fitsfile * fitsPointer() const
return the CFITSIO fitsfile pointer for this FITS object
Definition: FITS.h:917
Table * addTable(const String &hduName, int rows, const std::vector< String > &columnName=std::vector< String >(), const std::vector< String > &columnFmt=std::vector< String >(), const std::vector< String > &columnUnit=std::vector< String >(), HduType type=BinaryTbl, int version=1)
Add a table extension to an existing FITS object. Add extension to FITS object for file with w or rw ...
Definition: FITS.cxx:870
void resetPosition()
explicit call to set the fits file pointer to the primary.
Definition: FITS.cxx:1072
void setTileDimensions(const std::vector< long > &tileSizes)
Set the dimensions of the tiles into which the image is divided during compression.
Definition: FITS.cxx:1417
void deleteExtension(const String &doomed, int version=1)
Delete extension specified by name and version number.
Definition: FITS.cxx:371
static void setVerboseMode(bool value)
set verbose setting for library
Definition: FITS.h:867
void getTileDimensions(std::vector< long > &tileSizes) const
Get the current settings of dimension sizes for tiles used in image compression.
Definition: FITS.cxx:1450
const String & name() const
return filename of file corresponding to FITS object
Definition: FITS.h:892
static bool verboseMode()
return verbose setting for library
Definition: FITS.h:862
int getNoiseBits() const
Get the cfitsio noisebits parameter used when compressing floating-point images.
Definition: FITS.cxx:1468
void setCompressionType(int compType)
set the compression algorithm to be used when adding image extensions to the FITS object.
Definition: FITS.cxx:1408
Table & filter(const String &expression, ExtHDU &inputTable, bool overwrite=true, bool readData=false)
Filter the rows of the inputTable with the condition expression, and return a reference to the result...
Definition: FITS.cxx:1143
const ExtMap & extension() const
return const reference to the extension container
Definition: FITS.h:912
FITS(const String &name, RWmode rwmode=Read, bool readDataFlag=false, const std::vector< String > &primaryKeys=std::vector< String >())
basic constructor
Definition: FITS.cxx:91
void destroy()
Erase FITS object and close corresponding file.
Definition: FITS.cxx:1016
ExtHDU * addImage(const String &hduName, int bpix, std::vector< long > &naxes, int version=1)
Add an image extension to an existing FITS object. (File with w or rw access).
Definition: FITS.cxx:979
FitsException is the base class for all exceptions thrown by this library.
Definition: FitsError.h:94
Base class for all HDU [Header-Data Unit] objects.
Definition: HDU.h:674
class representing the primary HDU for a FITS file.
Definition: PHDU.h:268
Definition: Table.h:283
Namespace enclosing all CCfits classes and globals definitions.
Definition: AsciiTable.cxx:26
thrown on failure to create new file
Definition: FITS.h:668
CantCreate(const String &diag, bool silent=false)
Exception ctor prefixes the string: "FITS Error: Cannot create file " before specific message.
Definition: FITS.cxx:80