FITS.h
// Astrophysics Science Division,
// NASA/ Goddard Space Flight Center
// HEASARC
// http://heasarc.gsfc.nasa.gov
// e-mail: ccfits@legacy.gsfc.nasa.gov
//
// Original author: Ben Dorman
#ifndef FITS_H
#define FITS_H 1
// exception
#include <exception>
// string
#include <string>
// map
#include <map>
// ExtHDU
#include "ExtHDU.h"
// HDUCreator
#include "HDUCreator.h"
// FitsError
#include "FitsError.h"
namespace CCfits {
class PHDU;
class Table;
class GroupTable;
} // namespace CCfits
//class PHDU;
extern "C"
{
# include <sys/stat.h>
}
#include <memory>
namespace CCfits {
// ! The FITS object class. Contains a primary HDU and Extensions indexed by name.
class FITS
{
public:
class NoSuchHDU : public FitsException //## Inherits: <unnamed>%396C90CB0236
{
public:
NoSuchHDU (const String& diag, bool silent = true);
protected:
private:
private: //## implementation
};
class OperationNotSupported : public FitsException //## Inherits: <unnamed>%39806C7600D5
{
public:
OperationNotSupported (const String& msg, bool silent = true);
protected:
private:
private: //## implementation
};
class CantOpen : public FitsException //## Inherits: <unnamed>%39C8EB1D02C0
{
public:
CantOpen (const String& diag, bool silent = true);
protected:
private:
private: //## implementation
};
struct CantCreate : public FitsException //## Inherits: <unnamed>%39C8EB10020B
{
CantCreate (const String& diag, bool silent = false);
public:
protected:
private:
private: //## implementation
};
FITS (const String &name, RWmode rwmode = Read, bool readDataFlag = false, const std::vector<String>& primaryKeys = std::vector<String>());
// Open a file and read a specified HDU.
//
// Optional parameter allows the reading of specified primary HDU keys.
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);
// Read data from a set of specified HDUs. keywords can only be specified for the primary here.
// The code will call a different constructor for the case where keywords are required for
// the extensions.
FITS (const String &name, RWmode rwmode, const std::vector<String>& hduNames, bool readDataFlag = false, const std::vector<String>& primaryKey = std::vector<String>());
// Initialize a new FITS file object with the primary from a
// different file.
FITS (const String& fileName, const FITS& source);
// Fully general FITS HDU reader. May read any part of fits file by
// supplying HDU names and version numbers, and optionally
// the data read flag.
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>());
// Writing constructor. Takes a name and information to create an empty
// Primary HDU which can then be filled with calls to HDU methods.
FITS (const String& name, int bitpix, int naxis, long *naxes);
// Open a file and read a specified HDU.
//
// Optional parameter allows the reading of specified primary HDU keys.
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>());
// Open a file and read a HDU that contains specified
// search keywords with [optional] specified values
// (sometimes one just wants to know that the keyword is present).
//
// Optional parameters allows the reading of specified primary HDU keys and specified keywords in
// the HDU of interest.
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);
~FITS();
static void clearErrors ();
void deleteExtension (const String& doomed, int version = 1);
// Read keys and data from a single ExtHDU in the file.
void read (const String &hduName, bool readDataFlag = false, const std::vector<String> &keys = std::vector<String>(), int version = 1);
// Read multiple ExtHDUs. If the version number needs to be specified
// then one must call a different method.
void read (const std::vector<String> &hduNames, bool readDataFlag = false);
// Read selected data from multiple ExtHDUs
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>());
// Read keys and data from a single ExtHDU in the file.
// Construct and Read HDU specified by number. One can add further HDUs by number using the HDUCreator factory.
void read (int hduIndex, bool readDataFlag = false, const std::vector<String> &keys = std::vector<String>());
// Open a file and read a HDU that contains specified
// search keywords with [optional] specified values
// (sometimes one just wants to know that the keyword is present).
//
// Optional parameters allows the reading of specified primary HDU keys and specified keywords in
// the HDU of interest.
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);
ExtHDU& currentExtension ();
ExtHDU& extension (int i);
const ExtHDU& extension (int i) const;
ExtHDU& extension (const String& hduName, int version = 1);
const ExtHDU& extension (const String& hduName, int version = 1) const;
fitsfile* fitsPointer () const;
PHDU& pHDU ();
const PHDU& pHDU () const;
friend std::ostream& operator << (std::ostream& s, const FITS& right);
// ! add a new Table extension to a FITS object
Table* addTable (const String& hduName, int rows, // ! Number of rows in new table. Mandatory
const std::vector<String>& columnName = std::vector<String>(), // ! Optional set of column names for new table
const std::vector<String>& columnFmt = std::vector<String>(), // ! Column formats for column units. Mandatory if columnName is specified
const std::vector<String>& columnUnit = std::vector<String>(), // ! Column formats for column units. Optional
HduType type = BinaryTbl, int version = 1);
// ! add a new Group Table to the FITS object
Table * addGroupTable(const String & groupName, int groupID);
//GroupTable * addGroupTable(const String & groupName, int groupID);
// ! add a new ImageExt (image extension) to the FITS object. A "writing" method.
ExtHDU* addImage (const String& hduName, int bpix, std::vector<long>& naxes, int version = 1);
// Force destruction of the FITS object. Essentially
// is a manual destructor call.
void destroy () throw ();
void flush ();
void resetPosition ();
const ExtMap& extension () const;
void deleteExtension (int doomed);
const String& currentExtensionName () const;
void currentExtensionName (const String& extName);
const String& name () const;
void copy (const HDU& source);
Table& filter (const String& expression, ExtHDU& inputTable, bool overwrite = true, bool readData = false);
void setCompressionType (int compType);
void setTileDimensions (const std::vector<long>& tileSizes);
void setNoiseBits (int noiseBits);
int getCompressionType () const;
void getTileDimensions (std::vector<long>& tileSizes) const;
int getNoiseBits () const;
static bool verboseMode ();
static void setVerboseMode (bool value);
public:
// Additional Public Declarations
protected:
// Additional Protected Declarations
private:
FITS(const FITS &right);
FITS & operator=(const FITS &right);
void unmapExtension (ExtHDU& doomed);
int nextVersionNumber (const String& inputName) const;
// read the primary HDU. Read the image if
// readDataFlag is true.
void read (bool readDataFlag = false, const std::vector<String>& keys = std::vector<String>());
// Returns index of current HDU where primary = 0. (Extended file syntax may cause a shift to an
// extension.)
int open (RWmode rwmode = Read);
// Create returns true if a new file was created or an
// existing file overwritten, false if appending.
//
// It throws exception CantCreate or CantOpen if either fails.
bool create ();
// Close the fits file.
//
// Called in destructors so must not throw.
int close () throw ();
std::ostream & put (std::ostream &s) const;
ExtHDU& extbyVersion (const String& hduName, int version) const;
void pHDU (PHDU* value);
void readExtensions (bool readDataFlag = false);
ExtHDU* addExtension (ExtHDU* ext);
String nameOfUnmapped (int hduNum) const;
void cloneHeader (const ExtHDU& source);
// Check if caller is requesting an already read ExtHDU (ie. one
// that's already been added to ExtMap). If hduIdx=0, check by
// matching name and optional version. Otherwise check by matching
// hduIdx. If found, returns pointer to the ExtHDU. Otherwise
// returns 0. This will not throw.
ExtHDU* checkAlreadyRead(const int hduIdx,
const String& hduName = string(""), const int version=1) const throw();
// Additional Private Declarations
void destroyPrimary ();
void destroyExtensions ();
int currentCompressionTileDim () const;
void currentCompressionTileDim (int value);
private: //## implementation
// Data Members for Class Attributes
static bool s_verboseMode;
int m_currentCompressionTileDim;
// Data Members for Associations
RWmode m_mode;
std::string m_currentExtensionName;
std::string m_filename;
PHDU* m_pHDU;
ExtMap m_extension;
fitsfile* m_fptr;
// ## Additional Implementation Declarations
friend void HDU::makeThisCurrent() const;
// MakeImage needs to access the m_pHDU pointer
friend PHDU * HDUCreator::MakeImage (int bpix, int naxis, const std::vector<long>& naxes);
};
// Class CCfits::FITS::NoSuchHDU
// Class CCfits::FITS::OperationNotSupported
// Class CCfits::FITS::CantOpen
// Class CCfits::FITS::CantCreate
// Class CCfits::FITS
inline ExtHDU& FITS::extension (const String& hduName, int version)
{
return extbyVersion(hduName,version);
}
inline std::ostream& operator << (std::ostream& s, const FITS& right)
{
return right.put(s);
}
inline bool FITS::verboseMode ()
{
return s_verboseMode;
}
inline void FITS::setVerboseMode (bool value)
{
s_verboseMode = value;
}
inline int FITS::currentCompressionTileDim () const
{
return m_currentCompressionTileDim;
}
inline void FITS::currentCompressionTileDim (int value)
{
m_currentCompressionTileDim = value;
}
inline const String& FITS::currentExtensionName () const
{
return m_currentExtensionName;
}
inline void FITS::currentExtensionName (const String& extName)
{
m_currentExtensionName = extName;
}
inline const String& FITS::name () const
{
return m_filename;
}
inline void FITS::pHDU (PHDU* value)
{
m_pHDU = value;
}
inline const PHDU& FITS::pHDU () const
{
return *m_pHDU;
}
inline PHDU& FITS::pHDU ()
{
return *m_pHDU;
}
inline const ExtMap& FITS::extension () const
{
return m_extension;
}
inline fitsfile* FITS::fitsPointer () const
{
return m_fptr;
}
} // namespace CCfits
#endif
CCfits::FITS::fitsPointer
fitsfile * fitsPointer() const
return the CFITSIO fitsfile pointer for this FITS object
Definition: FITS.h:917
CCfits::FITS::CantOpen::CantOpen
CantOpen(const String &diag, bool silent=true)
Exception ctor prefixes the string: &quot;FITS Error: Cannot create file &quot; before specific message...
Definition: FITS.cxx:70
CCfits::FITS::getCompressionType
int getCompressionType() const
Get the int specifying the compression algorithm to be used when adding an image extension.
Definition: FITS.cxx:1439
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:1408
CCfits::FITS::extension
const ExtMap & extension() const
return const reference to the extension container
Definition: FITS.h:912
CCfits::FITS::CantOpen
thrown on failure to open existing file
Definition: FITS.h:656
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:870
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:1450
CCfits::FITS::resetPosition
void resetPosition()
explicit call to set the fits file pointer to the primary.
Definition: FITS.cxx:1072
CCfits::FITS::setNoiseBits
void setNoiseBits(int noiseBits)
Set the cfitsio noisebits parameter used when compressing floating-point images.
Definition: FITS.cxx:1430
CCfits::FITS::OperationNotSupported::OperationNotSupported
OperationNotSupported(const String &msg, bool silent=true)
Exception ctor, prefixes the string &quot;FITS Error: Operation not supported:&quot; before the specific messag...
Definition: FITS.cxx:60
CCfits::FITS::name
const String & name() const
return filename of file corresponding to FITS object
Definition: FITS.h:892
CCfits::FITS::pHDU
PHDU & pHDU()
return a reference to the primary HDU.
Definition: FITS.h:907
CCfits::FITS::currentExtension
ExtHDU & currentExtension()
return a non-const reference to whichever is the current extension.
Definition: FITS.cxx:1269
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:979
CCfits::FITS::destroy
void destroy()
Erase FITS object and close corresponding file.
Definition: FITS.cxx:1016
CCfits::FITS::verboseMode
static bool verboseMode()
return verbose setting for library
Definition: FITS.h:862
CCfits::HDU
Base class for all HDU [Header-Data Unit] objects.
Definition: HDU.h:673
CCfits::FITS::OperationNotSupported
thrown for unsupported operations, such as attempted to select rows from an image extension...
Definition: FITS.h:645
CCfits::FITS::CantCreate::CantCreate
CantCreate(const String &diag, bool silent=false)
Exception ctor prefixes the string: &quot;FITS Error: Cannot create file &quot; before specific message...
Definition: FITS.cxx:80
CCfits::FITS::clearErrors
static void clearErrors()
clear the error stack and set status to zero.
Definition: FITS.cxx:366
CCfits::FITS::FITS
FITS(const String &name, RWmode rwmode=Read, bool readDataFlag=false, const std::vector< String > &primaryKeys=std::vector< String >())
basic constructor
Definition: FITS.cxx:91
CCfits::FITS
Memory object representation of a disk FITS file.
Definition: FITS.h:628
CCfits::FitsException
FitsException is the base class for all exceptions thrown by this library.
Definition: FitsError.h:93
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:1143
CCfits::ExtHDU
base class for all FITS extension HDUs, i.e. Image Extensions and Tables.
Definition: ExtHDU.h:438
CCfits::FITS::setVerboseMode
static void setVerboseMode(bool value)
set verbose setting for library
Definition: FITS.h:867
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:421
CCfits::FITS::CantCreate
thrown on failure to create new file
Definition: FITS.h:667
CCfits::FITS::NoSuchHDU::NoSuchHDU
NoSuchHDU(const String &diag, bool silent=true)
Exception ctor, prefixes the string &quot;FITS Error: Cannot read HDU in FITS file:&quot; before the specific m...
Definition: FITS.cxx:49
CCfits::Table
Definition: Table.h:282
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:1417
CCfits::FITS::flush
void flush()
flush buffer contents to disk
Definition: FITS.cxx:1054
CCfits::PHDU
class representing the primary HDU for a FITS file.
Definition: PHDU.h:267
CCfits::FITS::deleteExtension
void deleteExtension(const String &doomed, int version=1)
Delete extension specified by name and version number.
Definition: FITS.cxx:371
CCfits::FITS::~FITS
~FITS()
destructor
Definition: FITS.cxx:332
CCfits::FITS::currentExtensionName
const String & currentExtensionName() const
return the name of the extension that the fitsfile is currently addressing.
Definition: FITS.h:882
CCfits::FITS::NoSuchHDU
exception thrown by HDU retrieval methods.
Definition: FITS.h:634
CCfits::FITS::copy
void copy(const HDU &source)
copy the HDU source into the FITS object.
Definition: FITS.cxx:1079
CCfits::FITS::getNoiseBits
int getNoiseBits() const
Get the cfitsio noisebits parameter used when compressing floating-point images.
Definition: FITS.cxx:1468