Memory object representation of a disk FITS file. More...

#include <FITS.h>

Classes
class	CantCreate
	thrown on failure to create new file More...

class	CantOpen
	thrown on failure to open existing file More...

class	NoSuchHDU
	exception thrown by HDU retrieval methods. More...

class	OperationNotSupported
	thrown for unsupported operations, such as attempted to select rows from an image extension. More...

Public Member Functions
	FITS (const String &fileName, const FITS &source)
	Create a new FITS object and corresponding file with a copy of the primary header of the source. If the filename corresponds to an existing file and does not start with the '!' character, the construction will fail with a CantCreate exception. More...

	FITS (const String &name, int bitpix, int naxis, long *naxes)
	Constructor for creating new FITS objects containing images. More...

	FITS (const String &name, RWmode rwmode, const std::vector< String > &hduNames, bool readDataFlag=false, const std::vector< String > &primaryKey=std::vector< String >())

	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 >())
	FITS read constructor in full generality. More...

	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)
	open fits file and read HDU which contains supplied keywords with [optional] specified values (sometimes one just wants to know that the keyword is present). More...

	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)
	Open a FITS file and read a single specified HDU. More...

	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 >())
	read a single numbered HDU. More...

	FITS (const String &name, RWmode rwmode=Read, bool readDataFlag=false, const std::vector< String > &primaryKeys=std::vector< String >())
	basic constructor More...

	~FITS ()
	destructor

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). More...

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 access. More...

void	copy (const HDU &source)
	copy the HDU source into the FITS object. More...

ExtHDU &	currentExtension ()
	return a non-const reference to whichever is the current extension.

const String &	currentExtensionName () const
	return the name of the extension that the fitsfile is currently addressing. More...

void	deleteExtension (const String &doomed, int version=1)
	Delete extension specified by name and version number. More...

void	deleteExtension (int doomed)
	Delete extension specified by extension number. More...

void	destroy () throw ()
	Erase FITS object and close corresponding file. More...

const ExtMap &	extension () const
	return const reference to the extension container More...

ExtHDU &	extension (const String &hduName, int version=1)
	return FITS extension by name and (optionally) version number.

const ExtHDU &	extension (const String &hduName, int version=1) const
	return FITS extension by name and (optionally) version number.

ExtHDU &	extension (int i)
	return FITS extension by index number. non-const version. see const version for details.

const ExtHDU &	extension (int i) const
	return FITS extension by index number. N.B. The input index number is currently defined as enumerating extensions, so the extension(1) returns HDU number 2.

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 resulting Table. More...

fitsfile *	fitsPointer () const
	return the CFITSIO fitsfile pointer for this FITS object

void	flush ()
	flush buffer contents to disk More...

int	getCompressionType () const
	Get the int specifying the compression algorithm to be used when adding an image extension.

int	getNoiseBits () const
	Get the cfitsio noisebits parameter used when compressing floating-point images.

void	getTileDimensions (std::vector< long > &tileSizes) const
	Get the current settings of dimension sizes for tiles used in image compression. More...

const String &	name () const
	return filename of file corresponding to FITS object

PHDU &	pHDU ()
	return a reference to the primary HDU.

const PHDU &	pHDU () const
	return a const reference to the primary HDU.

void	read (const std::vector< String > &hduNames, bool readDataFlag=false)
	get data from a set of HDUs from disk file. More...

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 >())
	get data from a set of HDUs from disk file, specifying keys and version numbers. More...

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)
	read method for read header or HDU that contains specified keywords. More...

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. More...

void	read (int hduIndex, bool readDataFlag=false, const std::vector< String > &keys=std::vector< String >())
	read an HDU specified by index number. More...

void	resetPosition ()
	explicit call to set the fits file pointer to the primary.

void	setCompressionType (int compType)
	set the compression algorithm to be used when adding image extensions to the FITS object. More...

void	setNoiseBits (int noiseBits)
	Set the cfitsio noisebits parameter used when compressing floating-point images. More...

void	setTileDimensions (const std::vector< long > &tileSizes)
	Set the dimensions of the tiles into which the image is divided during compression. More...

Static Public Member Functions
static void	clearErrors ()
	clear the error stack and set status to zero.

static void	setVerboseMode (bool value)
	set verbose setting for library

static bool	verboseMode ()
	return verbose setting for library More...

Detailed Description

Memory object representation of a disk FITS file.

Constructors are provided to get FITS data from an existing file or to create new FITS data sets. Overloaded versions allow the user to:

(a) read from one or more specified extensions, specified by EXTNAME and VERSION or by HDU number. (b) read either just header information or data on construction (c) specify scalar keyword values to be read on construction (d) open and read an extension that has specified keyword values (e) create a new FITS object and corresponding file, including an empty primary header.

The memory fits object as constructed is always an image of a valid FITS object, i.e. a primary HDU is created on construction.

Calling the destructor closes the disk file, so that FITS files are automatically deleted at the end of scope unless other arrangements are made

Constructor & Destructor Documentation

◆ FITS() [1/8]

CCfits::FITS::FITS	(	const String &	name,
		RWmode	rwmode = `Read`,
		bool	readDataFlag = `false`,
		const std::vector< String > &	primaryKeys = `std::vector<String>()`
	)

basic constructor

This basic constructor makes a FITS object from the given filename. The file name is the only required argument. The file name string is passed directly to the cfitsio library: thus the extended file name syntax described in the cfitsio manual should work as documented. (Though the extended file name feature which allows the opening of a particular image located in the row of a table is currently unsupported.)

If the rwmode is Read [default]: It will read all of the headers in the file, and all of the data if the readDataFlag is supplied as true. It will also read optional primary keys. Upon completion, the the last header in the file will become the current extension. (However if the file name includes extended syntax selecting a particular extension, that extension will be the current one.)

If the rwmode is Write and the file already exists: The file is opened in read-write mode, all of the headers of the file are read, and all of the data if the readDataFlag is supplied as true. It will also read optional primary keys. For backwards compatibility with older versions of CCfits (which only read the primary when in Write mode for pre-existing files), the primary will become the current extension.

If the rwmode is Write and the file does NOT exist (or is overwritten using '!' syntax): A default primary HDU will be created in the file with BITPIX=8 and NAXIS=0. However if you wish to create a new file with image data in the primary, the version of the FITS constructor that specifies the data type and number of axes should be used instead.

Parameters

name	The name of the FITS file to be read/written
rwmode	The read/write mode: must be Read or Write
readDataFlag	boolean: read data on construction if true
primaryKeys	Allows optional reading of primary header keys on construction

Exceptions

NoSuchHDU	thrown on HDU seek error either by index or {name,version}
FitsError	thrown on non-zero status code from cfitsio when not overriden by FitsException error to produce more illuminating message.

◆ FITS() [2/8]

CCfits::FITS::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`
	)

Open a FITS file and read a single specified HDU.

This and similar constructor variants support reading table data.

Optional arguments allow the reading of primary header keys and specified data from hduName, the HDU to be read. An object representing the primary HDU is always created: if it contains an image, that image may be read by subsequent calls.

If extended file name syntax is used and selects an extension other than hduName, a FITS::OperationNotSupported exception will be thrown.

Parameters

name	The name of the FITS file to be read
rwmode	The read/write mode: takes values Read or Write
hduName	The name of the HDU to be read.
hduKeys	Optional array of keywords to be read from the HDU
version	Optional version number. If not supplied the first HDU with name hduName is read see above for other parameter definitions

◆ FITS() [3/8]

CCfits::FITS::FITS	(	const String &	name,
		RWmode	rwmode,
		const std::vector< String > &	hduNames,
		bool	readDataFlag = `false`,
		const std::vector< String > &	primaryKey = `std::vector<String>()`
	)

This is intended as a convenience where the file consists of single versions of HDUs and data only, not keys are to be read.

If extended file name syntax is used and selects an extension not listed in hduNames, a FITS::OperationNotSupported exception will be thrown.

Parameters

hduNames array of HDU names to be read.

see above for other parameter definitions.

◆ FITS() [4/8]

CCfits::FITS::FITS	(	const String &	fileName,
		const FITS &	source
	)

Create a new FITS object and corresponding file with a copy of the primary header of the source. If the filename corresponds to an existing file and does not start with the '!' character, the construction will fail with a CantCreate exception.

Parameters

fileName	New file to be created.
source	A previously created FITS object to be copied.

◆ FITS() [5/8]

CCfits::FITS::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>()`
	)

FITS read constructor in full generality.

Parameters

hduVersions	an optional version number for each HDU to be read
hduKeys	an array of keywords for each HDU to be read. see above for other parameter definitions.

◆ FITS() [6/8]

CCfits::FITS::FITS	(	const String &	name,
		int	bitpix,
		int	naxis,
		long *	naxes
	)

Constructor for creating new FITS objects containing images.

This constructor is only called for creating new files (mode is not an argument) and creates a new primary HDU with the datatype & axes specified by bitpix, naxis, and naxes. The data are added to the new fits object and file by subsequent calls to FITS::pHDU().write( <arguments> )

A file with a compressed image may be creating by appending to the end of the file name the same "[compress ...]" syntax specified in the cfitsio manual. Note however that the compressed image will be placed in the first extension and NOT in the primary HDU.

If the filename corresponds to an existing file and does not start with the '!' character the construction will fail with a CantCreate exception.

The arguments are:

Parameters

name	The file to be written to disk
bitpix	the datatype of the primary image. bitpix may be one of the following CFITSIO constants: BYTE_IMG, SHORT_IMG, LONG_IMG, FLOAT_IMG, DOUBLE_IMG, USHORT_IMG, ULONG_IMG, LONGLONG_IMG. Note that if you send in a bitpix of USHORT_IMG or ULONG_IMG, CCfits will set HDU::bitpix() to its signed equivalent (SHORT_IMG or LONG_IMG), and then set BZERO to 2^15 or 2^31.
naxis	the data dimension of the primary image
naxes	the array of axis lengths for the primary image. Ignored if naxis =0, i.e. the primary header is empty. extensions can be added arbitrarily to the file after this constructor is called. The constructors should write header information to disk:

◆ FITS() [7/8]

CCfits::FITS::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>()`
	)

read a single numbered HDU.

Constructor analogous to the version that reads by name. This is required since HDU extensions are not required to have the EXTNAME or HDUNAME keyword by the standard. If there is no name, a dummy name based on the HDU number is created and becomes the key.

If extended file name syntax is used and selects an extension other than hduIndex, a FITS::OperationNotSupported exception will be thrown.

Parameters

hduIndex The index of the HDU to be read. see above for other parameter definitions.

◆ FITS() [8/8]

CCfits::FITS::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`
	)

open fits file and read HDU which contains supplied 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 columns and keywords in the HDU of interest.

Parameters

name	The name of the FITS file to be read
rwmode	The read/write mode: must be Read or Write
searchKeys	A string vector of keywords to search for in each header
searchValues	A string vector of values those keywords are required to have for success. Note that the keys must be of type string. If any value does not need to be checked the corresponding searchValue element can be empty.
readDataFlag	boolean: if true, read data if HDU is found
hduKeys	Allows optional reading of keys in the HDU that is searched for if it is successfully found
primaryKey	Allows optional reading of primary header keys on construction
version	Optional version number. If specified, checks the EXTVER keyword.

Exceptions

FitsError thrown on non-zero status code from cfitsio when not overriden by FitsException error to produce more illuminating message.

Member Function Documentation

◆ addImage()

void CCfits::FITS::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).

Does not make primary images, which are built in the constructor for the FITS file. The image data is not added here: it can be added by a call to one of the ExtHDU::write functions.

bpix may be one of the following CFITSIO constants: BYTE_IMG, SHORT_IMG, LONG_IMG, FLOAT_IMG, DOUBLE_IMG, USHORT_IMG, ULONG_IMG, LONGLONG_IMG. Note that if you send in a bpix of USHORT_IMG or ULONG_IMG, CCfits will set HDU::bitpix() to its signed equivalent (SHORT_IMG or LONG_IMG), and then set BZERO to 2^15 or 2^31.

Todo:: Add a function for replacing the primary image

◆ addTable()

Table * CCfits::FITS::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 access.

Parameters

rows	The number of rows in the table to be created.
columnName	(Optional) A vector containing the table column names
columnFmt	(Optional) A vector containing the table column formats
columnUnit	(Optional) A vector giving the units of the columns.
type	(Optional) The table type - AsciiTbl or BinaryTbl (defaults to BinaryTbl) the lists of columns are optional - one can create an empty table extension but if supplied, colType, columnName and colFmt must have equal dimensions.
version	(Optional) The EXTVER keyword for the extension version number, defaults to 1

Todo:: the code should one day check that the version keyword is higher than any other versions already added to the FITS object (although cfitsio doesn't do this either).

◆ copy()

void CCfits::FITS::copy ( const HDU & source )

copy the HDU source into the FITS object.

This function adds a copy of an HDU from another file into *this. It does not create a duplicate of an HDU in the file associated with *this.

◆ currentExtensionName()

const String & CCfits::FITS::currentExtensionName ( ) const

inline

return the name of the extension that the fitsfile is currently addressing.

If the extension in question does not have an EXTNAME or HDUNAME keyword, then the function returns $HDU$n, where n is the sequential HDU index number (primary HDU = 0).

◆ deleteExtension() [1/2]

void CCfits::FITS::deleteExtension	(	const String &	doomed,
		int	version = `1`
	)

Delete extension specified by name and version number.

Removes extension from FITS object and memory copy. The index numbers of all HDU objects which follow this in the file will be decremented by 1.

Parameters

doomed	the name of the extension to be deleted
version	an optional version number, the EXTVER keyword, defaults to 1

Exceptions

NoSuchHDU	Thrown if there is no extension with the specified version number
FitsError	Thrown if there is a non-zero status code from cfitsio, e.g. if the delete operation is applied to a FITS file opened for read only access.

◆ deleteExtension() [2/2]

void CCfits::FITS::deleteExtension ( int doomed )

Delete extension specified by extension number.

The index numbers of all HDU objects which follow this in the file will be decremented by 1.

◆ destroy()

void CCfits::FITS::destroy	(	)
throw	(
	)

Erase FITS object and close corresponding file.

Force deallocation and erase of elements of a FITS memory object. Allows a reset of everything inside the FITS object, and closes the file. The object is inaccessible after this call.

destroy is public to allow users to reuse a symbol for a new file, but it is identical in operation to the destructor.

◆ extension()

const ExtMap & CCfits::FITS::extension ( ) const

inline

return const reference to the extension container

This is useful for such operations as extension().size() etc.

◆ filter()

Table & CCfits::FITS::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 resulting Table.

This function provides an object oriented version of cfitsio's fits_select_rows call. The expression string is any boolean expression involving the names of the columns in the input table (e.g., if there were a column called "density", a valid expression might be "DENSITY > 3.5": see the cfitsio documentation for further details).

[N.B. the "append" functionality described below does not work when linked with cfitsio 2.202 or prior because of a known issue with that version of the library. This causes the output to be a new extension with a correct header copy and version number but without the filtered data]. If the inputTable is an Extension HDU of this FITS object, then if overwrite is true the operation will overwrite the inputTable with the filtered version, otherwise it will append a new HDU with the same extension name but the next highest version (EXTVER) number available.

◆ flush()

void CCfits::FITS::flush ( )

flush buffer contents to disk

Provides manual control of disk writing operation. Image data are flushed automatically to disk after the write operation is completed, but not column data.

◆ getTileDimensions()

void CCfits::FITS::getTileDimensions ( std::vector< long > & tileSizes ) const

Get the current settings of dimension sizes for tiles used in image compression.

Parameters

tileSizes A vector to be filled with cfitsio's current tile dimension settings. CCfits will resize this vector to contain the proper number of values.

◆ read() [1/5]

void CCfits::FITS::read	(	const std::vector< String > &	hduNames,
		bool	readDataFlag = `false`
	)

get data from a set of HDUs from disk file.

This is provided to allow reading of HDUs after construction. see above for parameter definitions.

◆ read() [2/5]

void CCfits::FITS::read	(	const std::vector< String > &	hduNames,
		const std::vector< std::vector< String > > &	keys,
		bool	readDataFlag = `false`,
		const std::vector< int > &	hduVersions = `std::vector<int>()`
	)

get data from a set of HDUs from disk file, specifying keys and version numbers.

This is provided to allow reading of HDUs after construction. see above for parameter definitions.

◆ read() [3/5]

CCfits::FITS::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`
	)

read method for read header or HDU that contains specified keywords.

Parameters

searchKeys	A string vector of keywords to search for in each header
searchValues	A string vector of values those keywords are required to have for success. Note that the keys must be of type string. If any value does not need to be checked the corresponding searchValue element can be empty.
readDataFlag	boolean: if true, read data if HDU is found
hduKeys	Allows optional reading of keys in the HDU that is searched for if it is successfully found
version	Optional version number. If specified, checks the EXTVER keyword.

◆ read() [4/5]

void CCfits::FITS::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.

This is provided to allow the adding of additional HDUs to the FITS object after construction of the FITS object. After the read() functions have been called for the FITS object, subsequent read method to the Primary, ExtHDU, and Column objects will retrieve data from the FITS object in memory (those methods can be called to read data in those HDU objects that was not read when the HDU objects were constructed.

All the read functions will throw NoSuchHDU exceptions on seek errors since they involve constructing HDU objects.

The parameter definitions are as documented for the corresponding constructor.

◆ read() [5/5]

void CCfits::FITS::read	(	int	hduIndex,
		bool	readDataFlag = `false`,
		const std::vector< String > &	keys = `std::vector<String>()`
	)

read an HDU specified by index number.

This is provided to allow reading of HDUs after construction. see above for parameter definitions.

◆ setCompressionType()

void CCfits::FITS::setCompressionType ( int compType )

set the compression algorithm to be used when adding image extensions to the FITS object.

Parameters

compType Currently 3 symbolic constants are defined in cfitsio for specifying compression algorithms: GZIP_1, RICE_1, and PLIO_1. See the cfitsio documentation for more information about these algorithms. Entering NULL for compType will turn off compression and cause normal FITS images to be written.

◆ setNoiseBits()

void CCfits::FITS::setNoiseBits ( int noiseBits )

Set the cfitsio noisebits parameter used when compressing floating-point images.

The default value is 4. Decreasing the value of noisebits will improve the overall compression efficiency at the expense of losing more information.

◆ setTileDimensions()

void CCfits::FITS::setTileDimensions ( const std::vector< long > & tileSizes )

Set the dimensions of the tiles into which the image is divided during compression.

Parameters

tileSizes A vector of length N containing the tile dimesions. If N is less than the number of dimensions of the image it is applied to, the unspecified dimensions will be assigned a size of 1 pixel. If N is larger than the number of image dimensions, the extra dimensions will be ignored.

The default cfitsio behavior is to create tiles with dimensions NAXIS1 x 1 x 1 etc. up to the number of image dimensions.

◆ verboseMode()

bool CCfits::FITS::verboseMode ( )

inlinestatic

return verbose setting for library

If true, all messages that are reported by exceptions are printed to std::cerr.

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

FITS.h
FITS.cxx

Classes

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ FITS() [1/8]

◆ FITS() [2/8]

◆ FITS() [3/8]

◆ FITS() [4/8]

◆ FITS() [5/8]

◆ FITS() [6/8]

◆ FITS() [7/8]

◆ FITS() [8/8]

Member Function Documentation

◆ addImage()

◆ addTable()

◆ copy()

◆ currentExtensionName()

◆ deleteExtension() [1/2]

◆ deleteExtension() [2/2]

◆ destroy()

◆ extension()

◆ filter()

◆ flush()

◆ getTileDimensions()

◆ read() [1/5]

◆ read() [2/5]

◆ read() [3/5]

◆ read() [4/5]

◆ read() [5/5]

◆ setCompressionType()

◆ setNoiseBits()

◆ setTileDimensions()

◆ verboseMode()