CCfits  2.5
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
CCfits::FITS::getNoiseBits
int getNoiseBits() const
Get the cfitsio noisebits parameter used when compressing floating-point images.
Definition: FITS.cxx:1451
CCfits::FITS::addImage
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:947
CCfits::FITS::NoSuchHDU
exception thrown by HDU retrieval methods.
Definition: FITS.h:675
CCfits::FITS::flush
void flush()
flush buffer contents to disk
Definition: FITS.cxx:1001
CCfits::FITS
Memory object representation of a disk FITS file.
Definition: FITS.h:668
CCfits::FITS::verboseMode
static bool verboseMode()
return verbose setting for library
Definition: FITS.h:891
CCfits::FITS::clearErrors
static void clearErrors()
clear the error stack and set status to zero.
Definition: FITS.cxx:388
CCfits::FITS::extension
const ExtMap & extension() const
return const reference to the extension container
Definition: FITS.cxx:1030
CCfits::FITS::deleteExtension
void deleteExtension(const String &doomed, int version=1)
Delete extension specified by name and version number.
Definition: FITS.cxx:393
CCfits::FITS::NoSuchHDU::NoSuchHDU
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:46
CCfits::FITS::FITS
FITS(const String &name, RWmode mode=Read, bool readDataFlag=false, const std::vector< String > &primaryKeys=std::vector< String >())
basic constructor
Definition: FITS.cxx:88
CCfits::Table
Definition: Table.h:271
CCfits::FITS::addTable
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:917
CCfits::FITS::CantOpen::CantOpen
CantOpen(const String &diag, bool silent=true)
Exception ctor prefixes the string: "FITS Error: Cannot create file " before specific message.
Definition: FITS.cxx:67
CCfits::HDU
Base class for all HDU [Header-Data Unit] objects.
Definition: HDU.h:571
CCfits::FITS::setNoiseBits
void setNoiseBits(int noiseBits)
Set the cfitsio noisebits parameter used when compressing floating-point images.
Definition: FITS.cxx:1413
CCfits::FITS::currentExtension
ExtHDU & currentExtension()
return a non-const reference to whichever is the current extension.
Definition: FITS.cxx:1250
CCfits::PHDU
class representing the primary HDU for a FITS file.
Definition: PHDU.h:267
CCfits::FITS::setCompressionType
void setCompressionType(int compType)
set the compression algorithm to be used when adding image extensions to the FITS object.
Definition: FITS.cxx:1391
CCfits::FITS::CantCreate::CantCreate
CantCreate(const String &diag, bool silent=false)
Exception ctor prefixes the string: "FITS Error: Cannot create file " before specific message.
Definition: FITS.cxx:77
CCfits::FITS::CantOpen
thrown on failure to open existing file
Definition: FITS.h:699
CCfits::FITS::OperationNotSupported
thrown for unsupported operations, such as attempted to select rows from an image extension.
Definition: FITS.h:687
CCfits::FITS::getCompressionType
int getCompressionType() const
Get the int specifying the compression algorithm to be used when adding an image extension.
Definition: FITS.cxx:1422
CCfits::FITS::setVerboseMode
static void setVerboseMode(bool value)
set verbose setting for library
Definition: FITS.h:896
CCfits::FITS::pHDU
const PHDU & pHDU() const
return a reference to the primary HDU.
Definition: FITS.cxx:831
CCfits::FITS::name
const String & name() const
return filename of file corresponding to FITS object
Definition: FITS.cxx:1048
CCfits::FITS::OperationNotSupported::OperationNotSupported
OperationNotSupported(const String &msg, bool silent=true)
Exception ctor, prefixes the string "FITS Error: Operation not supported:" before the specific messag...
Definition: FITS.cxx:57
CCfits::FITS::~FITS
~FITS()
destructor
Definition: FITS.cxx:353
CCfits::FITS::CantCreate
thrown on failure to create new file
Definition: FITS.h:711
CCfits::FITS::currentExtensionName
const String & currentExtensionName() const
return the name of the extension that the fitsfile is currently addressing.
Definition: FITS.cxx:1007
CCfits::FITS::read
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:443
CCfits::FITS::copy
void copy(const HDU &source)
copy the HDU source into the FITS object.
Definition: FITS.cxx:1054
CCfits::FITS::filter
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:1118
CCfits
Namespace enclosing all CCfits classes and globals definitions.
Definition: AsciiTable.cxx:26
CCfits::FITS::fitsPointer
fitsfile * fitsPointer() const
return the CFITSIO fitsfile pointer for this FITS object
Definition: FITS.cxx:793
CCfits::FitsException
FitsException is the base class for all exceptions thrown by this library.
Definition: FitsError.h:93
CCfits::FITS::setTileDimensions
void setTileDimensions(const std::vector< long > &tileSizes)
Set the dimensions of the tiles into which the image is divided during compression.
Definition: FITS.cxx:1400
CCfits::FITS::getTileDimensions
void getTileDimensions(std::vector< long > &tileSizes) const
Get the current settings of dimension sizes for tiles used in image compression.
Definition: FITS.cxx:1433
CCfits::FITS::destroy
void destroy()
Erase FITS object and close corresponding file.
Definition: FITS.cxx:984
CCfits::FITS::resetPosition
void resetPosition()
explicit call to set the fits file pointer to the primary.
Definition: FITS.cxx:1036
CCfits::ExtHDU
base class for all FITS extension HDUs, i.e. Image Extensions and Tables.
Definition: ExtHDU.h:438