CCfits  2.6
Classes | Public Member Functions | Static Public Member Functions | Protected Member Functions | List of all members
CCfits::HDU Class Referenceabstract

Base class for all HDU [Header-Data Unit] objects. More...

#include <HDU.h>

Inheritance diagram for CCfits::HDU:
Inheritance diagram CCfits::ExtHDU CCfits::PHDU CCfits::Table CCfits::AsciiTable CCfits::BinTable CCfits::GroupTable

Classes

class  InvalidExtensionType
 exception to be thrown if user requests extension type that can not be understood as ImageExt, AsciiTable or BinTable. More...
 
class  InvalidImageDataType
 exception to be thrown if user requests creation of an image of type not supported by cfitsio. More...
 
class  NoNullValue
 exception to be thrown on seek errors for keywords. More...
 
class  NoSuchKeyword
 exception to be thrown on seek errors for keywords. More...
 

Public Member Functions

 HDU (const HDU &right)
 copy constructor
 
template<typename T >
KeywordaddKey (const String &name, T val, const String &comment, bool isLongStr=false)
 create a new keyword in the HDU with specified value and comment fields More...
 
KeywordaddKey (const Keyword *inKeyword)
 create a copy of an existing Keyword and add to HDU More...
 
long axes () const
 return the number of axes in the HDU data section (always 2 for tables).
 
long axis (size_t index) const
 return the size of axis numbered index [zero based]. More...
 
long bitpix () const
 return the data type keyword. More...
 
virtual HDUclone (FITS *p) const =0
 virtual copy constructor, to be implemented in subclasses.
 
const string & comment () const
 return the comment string previously read by getComment()
 
void copyAllKeys (const HDU *inHdu, const std::vector< int > &keyCategories=std::vector< int >())
 copy all keys from another header More...
 
void deleteKey (const String &doomed)
 delete a keyword from the header More...
 
fitsfile * fitsPointer () const
 return the fitsfile pointer for the FITS object containing the HDU
 
std::pair< unsigned long,
unsigned long > 
getChecksum () const
 compute and return the checksum values for the HDU without creating or modifying the CHECKSUM/DATASUM keywords. More...
 
const String & getComments ()
 read the comments from the HDU and add it to the FITS object. More...
 
const String & getHistory ()
 read the history information from the HDU and add it to the FITS object. More...
 
const string & history () const
 return the history string previously read by getHistory()
 
void index (int value)
 set the HDU number
 
int index () const
 return the HDU number
 
std::map< String, Keyword * > & keyWord ()
 return the associative array containing the HDU keywords so far read.
 
KeywordkeyWord (const String &keyName)
 return a (previously read) keyword from the HDU object.
 
const std::map< string,
Keyword * > & 
keyWord () const
 return the associative array containing the HDU Keywords that have been read so far.
 
const KeywordkeyWord (const string &keyname) const
 return a (previously read) keyword from the HDU object. const version
 
virtual void makeThisCurrent () const
 move the fitsfile pointer to this current HDU. More...
 
bool operator!= (const HDU &right) const
 inequality operator
 
bool operator== (const HDU &right) const
 equality operator
 
FITSparent () const
 return reference to the pointer representing the FITS object containing the HDU
 
void readAllKeys (const std::vector< int > &keyCategories=std::vector< int >())
 read all of the keys in the header More...
 
template<typename T >
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. More...
 
template<typename T >
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 their values More...
 
KeywordreadNextKey (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. More...
 
virtual void resetImageRead ()
 force next image reading operation to read from file instead of object cache. More...
 
virtual double scale () const
 return the BSCALE keyword value
 
virtual void scale (double value)
 set the BSCALE keyword value for images (see warning for images of int type) More...
 
virtual void suppressScaling (bool toggle=true)
 turn off image scaling regardless of the BSCALE and BZERO keyword values More...
 
void updateChecksum ()
 update the CHECKSUM keyword value, assuming DATASUM exists and is correct More...
 
std::pair< int, int > verifyChecksum () const
 verify the HDU by computing the checksums and comparing them with the CHECKSUM/DATASUM keywords More...
 
void writeChecksum ()
 compute and write the DATASUM and CHECKSUM keyword values More...
 
void writeComment (const String &comment="Generic Comment")
 write a comment string. More...
 
void writeDate ()
 write a date string to *this.
 
void writeHistory (const String &history="Generic History String")
 write a history string. More...
 
virtual double zero () const
 return the BZERO keyword value
 
virtual void zero (double value)
 set the BZERO keyword value for images (see warning for images of int type) More...
 

Static Public Member Functions

static std::vector< int > keywordCategories ()
 Return the default enumerated keyword categories used by copyAllKeys() More...
 

Protected Member Functions

 HDU (FITS *p=0)
 default constructor, called by HDU subclasses that read from FITS files.
 
 HDU (FITS *p, int bitpix, int naxis, const std::vector< long > &axes)
 constructor for creating new HDU objects, called by HDU subclasses writing to FITS files.
 
virtual ~HDU ()
 destructor
 
std::vector< long > & naxes ()
 return the HDU data axis array.
 

Detailed Description

Base class for all HDU [Header-Data Unit] objects.

HDU objects in CCfits are either PHDU (Primary HDU objects) or ExtHDU (Extension HDU) objects. ExtHDUs are further subclassed into ImageExt or Table objects, which are finally AsciiTable or BinTable objects.

HDU's public interface gives access to properties that are common to all HDUs, largely required keywords, and functions that are common to all HDUs, principally the manipulation of keywords and their values.

HDUs must be constructed by HDUCreator objects which are called by FITS methods. Each HDU has an embedded pointer to its parent FITS object.

Member Function Documentation

template<typename T >
Keyword & CCfits::HDU::addKey ( const String &  name,
value,
const String &  comment,
bool  isLongStr = false 
)

create a new keyword in the HDU with specified value and comment fields

The function returns a reference to keyword object just created. If a keyword with this name already exists, it will be overwritten. Note that this is mostly intended for adding user-defined keywords. It should not be used to add keywords for which there are already specific HDU functions, such as scaling or checksum. Nor should it be used for image or column structural keywords, such as BITPIX, NAXIS, TFORMn, etc. As a general rule, it is best to use this for keywords belonging to the same categories listed in the keywordCategories() function.

Parameters
name(String) The keyword name
value(Recommended T = String, double, std::complex<float>, int, or bool) The keyword value
comment(String) The keyword comment
isLongStr(Bool, default=false) Is the keyword long (greater than 68 characters)

It is possible to create a keyword with a value of any of the allowed data types in fitsio (see the cfitsio manual section 4.3). However one should be aware that if this keyword value is read in from the file at a later time, it will be stored in a templated Keyword subclass (KeyData<T>) where T will be one of the recommended types listed above. Also see Keyword::value (T& val) for more details.

If the keyword is long (isLong=true), the keyword is written using the Long String Keyword convention, as described in the "Local FITS Conventions" section of the cfitsio documentation.

Keyword * CCfits::HDU::addKey ( const Keyword inKeyword)

create a copy of an existing Keyword and add to HDU

This is particularly useful for copying Keywords from one HDU to another. For example the inKeyword pointer might come from a different HDU's std::map<string,Keyword*>. If a keyword with this name already exists, it will be overwritten. The return value is a pointer to the newly created Keyword inserted into this HDU. Also see copyAllKeys().

long CCfits::HDU::axis ( size_t  index) const
inline

return the size of axis numbered index [zero based].

return the length of HDU data axis i.

long CCfits::HDU::bitpix ( ) const
inline

return the data type keyword.

Takes values denoting the image data type for images, and takes the fixed value 8 for tables.

void CCfits::HDU::copyAllKeys ( const HDU inHdu,
const std::vector< int > &  keyCategories = std::vector<int>() 
)

copy all keys from another header

Parameters
inHduAn existing HDU whose keys will be copied into the current object.
keyCategories(optional) A user-defined list of keyword categories to copy into current object

This will copy all keys that exist in the keyWord map of inHDU, and which belong to one of the desired keyword classes: either the default classes returned by the keywordCategories() function, or those given by the user-supplied vector of categories. The keywordMap can be populated with readAllKeys(). Only those keys in the map that match the desired category are copied.

Keywords are written in alphabetical order.

History and comment keys are copied to the current HDU from the input HDU, using the getComments()/getHistory() and writeComment()/writeHistory() methods.

All of the input comments and history are merged into one block, not spaced as they were in the input file.

It is highly recommended to use the default keyword categories, and not to pass in a user-defined list of categories, unless the user is very careful. Using the wrong categories can lead to incorrect keywords in files. For example, if the user passed in the TYP_CKSUM_KEY category to copyAllKeys(), then the CHECKSUM keyword would be copied from the old file to the new file. Similar care must be taken with metadata keywords for columns. This is more important for copyAllKeys() than for readAllKeys() because copyAllKeys() is the method that is actually inserting the keywords into the new file, while readAllKeys() is only reading in the source file's keywords.

void CCfits::HDU::deleteKey ( const String &  doomed)

delete a keyword from the header

removes doomed from the FITS file and from the FITS object

std::pair< unsigned long, unsigned long > CCfits::HDU::getChecksum ( ) const

compute and return the checksum values for the HDU without creating or modifying the CHECKSUM/DATASUM keywords.

Wrapper for the CFITSIO function fits_get_chksum: This returns a std::pair<unsigned long, unsigned long> where the pair's first data member holds the datasum value and second holds the hdusum value.

const String & CCfits::HDU::getComments ( )

read the comments from the HDU and add it to the FITS object.

The comment string found in the header is concatenated and returned to the calling function

const String & CCfits::HDU::getHistory ( )

read the history information from the HDU and add it to the FITS object.

The history string found in the header is concatenated and returned to the calling function

static std::vector< int > CCfits::HDU::keywordCategories ( )
static

Return the default enumerated keyword categories used by copyAllKeys()

This returns a vector of integers indicating which categories of keywords are the default for the copyAllKeys functions. The list of categories currently hardcoded is: TYP_REFSYS_KEY (120) and TYP_USER_KEY (150).

For the list of all possible keyword categories, see the CFITSIO documentation for the fits_get_keyclass function.

void CCfits::HDU::makeThisCurrent ( ) const
virtual

move the fitsfile pointer to this current HDU.

This function should never need to be called by the user since it is called internally whenever required.

Reimplemented in CCfits::ExtHDU.

void CCfits::HDU::readAllKeys ( const std::vector< int > &  keyCategories = std::vector<int>())

read all of the keys in the header

Parameters
keyCategories(optional) A user-defined list of keyword categories to read

This member function reads and stores keys from the current object that are one of the desired keyword categories: either the default categories or those given by the user-supplied vector of categories. The default categories are: TYP_CMPRS_KEY (20), TYP_CKSUM_KEY (100), TYP_WCS_KEY (110), TYP_REFSYS_KEY (120), and TYP_USER_KEY (150).

History and comment keys are also read from the current HDU.

Note that readAllKeys can only construct keys of type string, double, complex<float>, integer, and bool because the FITS header records do not encode exact type information.

template<typename T >
void CCfits::HDU::readKey ( const String &  keyName,
T &  val 
)

read a keyword of specified type from the header of a disk FITS file and return its value.

T is one of the types String, double, float, int, std::complex<float>, and bool. If a Keyword object with the name keyName already exists in this HDU due to a previous read call, then this will re-read from the file and create a new Keyword object to replace the existing one.

template<typename T >
void CCfits::HDU::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 their values

T is one of the types String, double, float, int, std::complex<float>, and bool.

Keyword & CCfits::HDU::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.

Parameters
incListVector of strings specifying keyword names to search.
excListVector of strings specifying names to exclude from search. This may be left empty.
searchFromBeginningIf 'true', search will be conducted from the start of the HDU. Otherwise it starts from the current position.

This is a wrapper around the CFITSIO fits_find_nextkey function. It reads in and returns the next keyword whose name matches matches one of the strings in incList, which may contain wild card characters (*,?, and #). It will exclude keywords whose name matches a string in excList. If no keyword is found, a FitError is thrown.

By default the search is conducted from the current keyword position in the HDU. If searchFromBeginning is set to 'true', search will start from the beginning of the HDU. If HDU is not the currently open extension, this will make it so and start the keyword search from the beginning.

void CCfits::HDU::resetImageRead ( )
inlinevirtual

force next image reading operation to read from file instead of object cache.

[Note: It is not necessary to call this function for normal image reading operations.] For primary HDUs and image extensions, this forces the next read operation to retrieve data from the file regardless of whether the data has already been read and stored in the HDU's internal arrays. This does nothing if the HDU does not contain an image.

void CCfits::HDU::scale ( double  value)
inlinevirtual

set the BSCALE keyword value for images (see warning for images of int type)

For primary HDUs and image extensions, this will add (or update) the BSCALE keyword in the header. The new setting will affect future image array read/writes as described in section 4.7 Data Scaling of the CFITSIO manual. For table extensions this function does nothing.

WARNING: If the image contains integer-type data (as indicated by the bitpix() return value), the new scale and zero value combination must not be such that the scaled data would require a floating-point type (this uses the CFITSIO function fits_get_img_equivtype to make the determination). If this situation occurs, the function will throw a FitsException.

Reimplemented in CCfits::PHDU.

void CCfits::HDU::suppressScaling ( bool  toggle = true)
virtual

turn off image scaling regardless of the BSCALE and BZERO keyword values

For toggle = true, this turns off image scaling for future read/writes by resetting the scale and zero to 1.0 and 0.0 respectively. It does NOT modify the BSCALE and BZERO keywords. If toggle = false, the scale and zero values will be restored to the keyword values.

void CCfits::HDU::updateChecksum ( )

update the CHECKSUM keyword value, assuming DATASUM exists and is correct

Wrapper for the CFITSIO function fits_update_chksum: This recomputes and writes the CHECKSUM value with the assumption that the DATASUM value is correct. If the DATASUM keyword doesn't yet exist or is not up-to-date, use the HDU::writeChecksum function instead. This will throw a FitsError exception if called when there is no DATASUM keyword in the header.

std::pair< int, int > CCfits::HDU::verifyChecksum ( ) const

verify the HDU by computing the checksums and comparing them with the CHECKSUM/DATASUM keywords

Wrapper for the CFITSIO function fits_verify_chksum: The data unit is verified correctly if the computed checksum equals the DATASUM keyword value, and the HDU is verified if the entire checksum equals zero (see the CFITSIO manual for further details).

This returns a std::pair<int,int> where the pair's first data member = DATAOK and second = HDUOK. DATAOK and HDUOK values will be = 1 if verified correctly, 0 if the keyword is missing, and -1 if the computed checksum is not correct.

void CCfits::HDU::writeChecksum ( )

compute and write the DATASUM and CHECKSUM keyword values

Wrapper for the CFITSIO function fits_write_chksum: This performs the datasum and checksum calculations for this HDU, as described in the CFITSIO manual. If either the DATASUM or CHECKSUM keywords already exist, their values will be updated.

void CCfits::HDU::writeComment ( const String &  comment = "Generic Comment")

write a comment string.

A default value for the string is given ("Generic Comment String") so users can put a placeholder call to this function in their code.

void CCfits::HDU::writeHistory ( const String &  history = "Generic History String")

write a history string.

A default value for the string is given ("Generic History String") so users can put a placeholder call to this function in their code.

void CCfits::HDU::zero ( double  value)
inlinevirtual

set the BZERO keyword value for images (see warning for images of int type)

For primary HDUs and image extensions, this will add (or update) the BZERO keyword in the header. The new setting will affect future image array read/writes as described in section 4.7 Data Scaling of the CFITSIO manual. For table extensions this function does nothing.

WARNING: If the image contains integer-type data (as indicated by the bitpix() return value), the new scale and zero value combination must not be such that the scaled data would require a floating-point type (this uses the CFITSIO function fits_get_img_equivtype to make the determination). If this situation occurs, the function will throw a FitsException.

Reimplemented in CCfits::PHDU.


The documentation for this class was generated from the following files: