lsst::afw::fits::Fits Class Reference

A simple struct that combines the two arguments that must be passed to most cfitsio routines and contains thin and/or templated wrappers around common cfitsio routines. More...

#include <fits.h>

Inheritance diagram for lsst::afw::fits::Fits:

Public Types
enum	BehaviorFlags { AUTO_CLOSE = 0x01, AUTO_CHECK = 0x02 }

Public Member Functions
std::string	getFileName () const
	Return the file name associated with the FITS object or "<unknown>" if there is none. More...
int	getHdu ()
	Return the current HDU (1-indexed; 1 is the Primary HDU). More...
void	setHdu (int hdu, bool relative=false)
	Set the current HDU. More...
int	countHdus ()
	Return the number of HDUs in the file. More...
void	writeMetadata (daf::base::PropertySet const &metadata)
	Read a FITS header into a PropertySet or PropertyList. More...
void	readMetadata (daf::base::PropertySet &metadata, bool strip=false)
	Read a FITS header into a PropertySet or PropertyList. More...
template<typename T >
void	readKey (std::string const &key, T &value)
	Read a FITS header key into the given reference. More...
void	forEachKey (HeaderIterationFunctor &functor)
	Call a polymorphic functor for every key in the header. More...
void	createEmpty ()
	Create an empty image HDU with NAXIS=0 at the end of the file. More...
template<typename PixelT , int N>
void	createImage (ndarray::Vector< int, N > const &shape)
	Create an image with pixel type provided by the given explicit PixelT template parameter and shape defined by an ndarray index. More...
template<typename PixelT >
void	createImage (long x, long y)
	Create a 2-d image with pixel type provided by the given explicit PixelT template parameter. More...
template<typename T , int N, int C>
void	writeImage (ndarray::Array< T const, N, C > const &array)
	Write an ndarray::Array to a FITS image HDU. More...
int	getImageDim ()
	Return the number of dimensions in the current HDU. More...
template<int N>
ndarray::Vector< int, N >	getImageShape ()
	Return the shape of the current (image) HDU. More...
template<typename T >
bool	checkImageType ()
	Return true if the current HDU has the given pixel type.. More...
template<typename T , int N>
void	readImage (ndarray::Array< T, N, N > const &array, ndarray::Vector< int, N > const &offset)
	Read an array from a FITS image. More...
void	createTable ()
	Create a new binary table extension. More...
template<typename T >
int	addColumn (std::string const &ttype, int size, std::string const &comment)
	Add a column to a table. More...
template<typename T >
int	addColumn (std::string const &ttype, int size)
	Add a column to a table. More...
std::size_t	addRows (std::size_t nRows)
	Append rows to a table, and return the index of the first new row. More...
std::size_t	countRows ()
	Return the number of row in a table. More...
template<typename T >
void	writeTableArray (std::size_t row, int col, int nElements, T const *value)
	Write an array value to a binary table. More...
template<typename T >
void	writeTableScalar (std::size_t row, int col, T value)
	Write an scalar value to a binary table. More...
void	writeTableScalar (std::size_t row, int col, std::string const &value)
	Write a string to a binary table. More...
template<typename T >
void	readTableArray (std::size_t row, int col, int nElements, T *value)
	Read an array value from a binary table. More...
template<typename T >
void	readTableScalar (std::size_t row, int col, T &value)
	Read an array scalar from a binary table. More...
void	readTableScalar (std::size_t row, int col, std::string &value)
	Read a string from a binary table. More...
long	getTableArraySize (int col)
	Return the size of an array column. More...
long	getTableArraySize (std::size_t row, int col)
	Return the size of an variable-length array field. More...
	Fits ()
	Default constructor; set all data members to 0. More...
	Fits (std::string const &filename, std::string const &mode, int behavior)
	Open or create a FITS file from disk. More...
	Fits (MemFileManager &manager, std::string const &mode, int behavior)
	Open or create a FITS file from an in-memory file. More...
void	closeFile ()
	Close a FITS file. More...
	~Fits ()
template<typename T >
void	updateKey (std::string const &key, T const &value, std::string const &comment)
	Set a FITS header key, editing if it already exists and appending it if not. More...
void	updateKey (std::string const &key, char const *value, std::string const &comment)
	Set a FITS header key, editing if it already exists and appending it if not. More...
template<typename T >
void	updateKey (std::string const &key, T const &value)
	Set a FITS header key, editing if it already exists and appending it if not. More...
void	updateKey (std::string const &key, char const *value)
	Set a FITS header key, editing if it already exists and appending it if not. More...
template<typename T >
void	writeKey (std::string const &key, T const &value, std::string const &comment)
	Add a FITS header key to the bottom of the header. More...
void	writeKey (std::string const &key, char const *value, std::string const &comment)
	Add a FITS header key to the bottom of the header. More...
template<typename T >
void	writeKey (std::string const &key, T const &value)
	Add a FITS header key to the bottom of the header. More...
void	writeKey (std::string const &key, char const *value)
	Add a FITS header key to the bottom of the header. More...
template<typename T >
void	updateColumnKey (std::string const &prefix, int n, T const &value, std::string const &comment)
	Update a key of the form XXXXXnnn, where XXXXX is the prefix and nnn is a column number. More...
void	updateColumnKey (std::string const &prefix, int n, char const *value, std::string const &comment)
	Update a key of the form XXXXXnnn, where XXXXX is the prefix and nnn is a column number. More...
template<typename T >
void	updateColumnKey (std::string const &prefix, int n, T const &value)
	Update a key of the form XXXXXnnn, where XXXXX is the prefix and nnn is a column number. More...
void	updateColumnKey (std::string const &prefix, int n, char const *value)
	Update a key of the form XXXXXnnn, where XXXXX is the prefix and nnn is a column number. More...
template<typename T >
void	writeColumnKey (std::string const &prefix, int n, T const &value, std::string const &comment)
	Write a key of the form XXXXXnnn, where XXXXX is the prefix and nnn is a column number. More...
void	writeColumnKey (std::string const &prefix, int n, char const *value, std::string const &comment)
	Write a key of the form XXXXXnnn, where XXXXX is the prefix and nnn is a column number. More...
template<typename T >
void	writeColumnKey (std::string const &prefix, int n, T const &value)
	Write a key of the form XXXXXnnn, where XXXXX is the prefix and nnn is a column number. More...
void	writeColumnKey (std::string const &prefix, int n, char const *value)
	Write a key of the form XXXXXnnn, where XXXXX is the prefix and nnn is a column number. More...

Public Attributes
void *	fptr
int	status
int	behavior

Private Member Functions
template<typename T >
void	createImageImpl (int nAxis, long *nAxes)
template<typename T >
void	writeImageImpl (T const *data, int nElements)
template<typename T >
void	readImageImpl (int nAxis, T *data, long *begin, long *end, long *increment)
void	getImageShapeImpl (int nAxis, long *nAxes)

Detailed Description

A simple struct that combines the two arguments that must be passed to most cfitsio routines and contains thin and/or templated wrappers around common cfitsio routines.

This is NOT intended to be an object-oriented C++ wrapper around cfitsio; it's simply a thin layer that saves a lot of repetition, const/reinterpret casts, and replaces void pointer args and type codes with templates and overloads.

Like a cfitsio pointer, a Fits object always considers one HDU the "active" one, and most operations will be applied to that HDU.

All member functions are non-const because they may modify the 'status' data member.

Note

All functions that take a row or column number below are 0-indexed; the internal cfitsio calls are all 1-indexed.

Definition at line 194 of file fits.h.

Member Enumeration Documentation

enum lsst::afw::fits::Fits::BehaviorFlags

Enumerator
AUTO_CLOSE
AUTO_CHECK

Definition at line 201 of file fits.h.

                       {
        AUTO_CLOSE = 0x01, // Close files when the Fits object goes out of scope if fptr != NULL
        AUTO_CHECK = 0x02  // Call LSST_FITS_CHECK_STATUS after every cfitsio call
    };

Constructor & Destructor Documentation

lsst::afw::fits::Fits::Fits ( )

inline

Default constructor; set all data members to 0.

Definition at line 478 of file fits.h.

: fptr(0), status(0), behavior(0) {}

lsst::afw::fits::Fits::Fits	(	std::string const &	filename,
		std::string const &	mode,
		int	behavior
	)

Open or create a FITS file from disk.

lsst::afw::fits::Fits::Fits	(	MemFileManager &	manager,
		std::string const &	mode,
		int	behavior
	)

Open or create a FITS file from an in-memory file.

lsst::afw::fits::Fits::~Fits ( )

inline

Definition at line 489 of file fits.h.

{ if ((fptr) && (behavior & AUTO_CLOSE)) closeFile(); }

Member Function Documentation

template<typename T >

int lsst::afw::fits::Fits::addColumn	(	std::string const &	ttype,
		int	size,
		std::string const &	comment
	)

Add a column to a table.

If size <= 0, the field will be a variable length array, with max set by (-size), or left unknown if size == 0.

template<typename T >

int lsst::afw::fits::Fits::addColumn	(	std::string const &	ttype,
		int	size
	)

Add a column to a table.

If size <= 0, the field will be a variable length array, with max set by (-size), or left unknown if size == 0.

std::size_t lsst::afw::fits::Fits::addRows

(

std::size_t

nRows

)

Append rows to a table, and return the index of the first new row.

template<typename T >

bool lsst::afw::fits::Fits::checkImageType

(

)

Return true if the current HDU has the given pixel type..

This takes into account the BUNIT and BSCALE keywords, which can allow integer images to be interpreted as floating point.

void lsst::afw::fits::Fits::closeFile

(

)

Close a FITS file.

int lsst::afw::fits::Fits::countHdus

(

)

Return the number of HDUs in the file.

std::size_t lsst::afw::fits::Fits::countRows

(

)

Return the number of row in a table.

void lsst::afw::fits::Fits::createEmpty

(

)

Create an empty image HDU with NAXIS=0 at the end of the file.

This is primarily useful to force the first "real" HDU to be an extension HDU by creating an empty Primary HDU. The new HDU is set as the active one.

template<typename PixelT , int N>

void lsst::afw::fits::Fits::createImage ( ndarray::Vector< int, N > const &  shape )

inline

Create an image with pixel type provided by the given explicit PixelT template parameter and shape defined by an ndarray index.

Note

The shape parameter is ordered fastest-dimension last (i.e. [y, x]) as is conventional with ndarray.

The new image will be in a new HDU at the end of the file, which may be the Primary HDU if the FITS file is empty.

Definition at line 343 of file fits.h.

                                                         {
        ndarray::Vector<long,N> nAxes(shape.reverse());
        createImageImpl<PixelT>(N, nAxes.elems);
    }

template<typename PixelT >

void lsst::afw::fits::Fits::createImage ( long  x, long  y  )

inline

Create a 2-d image with pixel type provided by the given explicit PixelT template parameter.

The new image will be in a new HDU at the end of the file, which may be the Primary HDU if the FITS file is empty.

Definition at line 355 of file fits.h.

                                     {
        long naxes[2] = { x, y };
        createImageImpl<PixelT>(2, naxes);
    }

template<typename T >

void lsst::afw::fits::Fits::createImageImpl ( int  nAxis, long *  nAxes  )

private

void lsst::afw::fits::Fits::createTable

(

)

Create a new binary table extension.

void lsst::afw::fits::Fits::forEachKey

(

HeaderIterationFunctor &

functor

)

Call a polymorphic functor for every key in the header.

Each value is passed in as a string, and the single quotes that mark an actual string value are not removed (neither are extra spaces). However, long strings that make use of the CONTINUE keyword are concatenated to look as if they were on a single line.

std::string lsst::afw::fits::Fits::getFileName

(

)

const

Return the file name associated with the FITS object or "<unknown>" if there is none.

int lsst::afw::fits::Fits::getHdu

(

)

Return the current HDU (1-indexed; 1 is the Primary HDU).

int lsst::afw::fits::Fits::getImageDim

(

)

Return the number of dimensions in the current HDU.

template<int N>

ndarray::Vector<int,N> lsst::afw::fits::Fits::getImageShape ( )

inline

Return the shape of the current (image) HDU.

The order of dimensions is reversed from the FITS ordering, reflecting the usual (y,x) ndarray convention.

The template parameter must match the actual number of dimension in the image.

Definition at line 386 of file fits.h.

                                         {
        ndarray::Vector<long,N> nAxes(1);
        getImageShapeImpl(N, nAxes.elems);
        ndarray::Vector<int,N> shape;
        for (int i = 0; i < N; ++i) shape[i] = nAxes[N-i-1];
        return shape;
    }

void lsst::afw::fits::Fits::getImageShapeImpl ( int  nAxis, long *  nAxes  )

private

long lsst::afw::fits::Fits::getTableArraySize

(

int

col

)

Return the size of an array column.

long lsst::afw::fits::Fits::getTableArraySize	(	std::size_t	row,
		int	col
	)

Return the size of an variable-length array field.

template<typename T , int N>

void lsst::afw::fits::Fits::readImage ( ndarray::Array< T, N, N > const &  array, ndarray::Vector< int, N > const &  offset  )

inline

Read an array from a FITS image.

Parameters

[out]	array	Array to be filled. Must already be allocated to the desired shape.
[in]	offset	Indices of the first pixel to be read from the image.

Definition at line 410 of file fits.h.

      {
        ndarray::Vector<long,N> begin(offset.reverse());
        ndarray::Vector<long,N> end(begin);
        end += array.getShape().reverse();
        ndarray::Vector<long,N> increment(1);
        begin += increment;  // first FITS pixel is 1, not 0
        readImageImpl(N, array.getData(), begin.elems, end.elems, increment.elems);
    }

template<typename T >

void lsst::afw::fits::Fits::readImageImpl ( int  nAxis, T *  data, long *  begin, long *  end, long *  increment  )

private

template<typename T >

void lsst::afw::fits::Fits::readKey	(	std::string const &	key,
		T &	value
	)

Read a FITS header key into the given reference.

void lsst::afw::fits::Fits::readMetadata	(	daf::base::PropertySet &	metadata,
		bool	strip = false
	)

Read a FITS header into a PropertySet or PropertyList.

Parameters

[in,out]	metadata	A PropertySet or PropertyList that FITS header items will be added to.
[in]	strip	If true, common FITS keys that usually have non-metadata intepretations (e.g. NAXIS, BITPIX) will be ignored.

Order will preserved if and only if the metadata object is actually a PropertyList.

template<typename T >

void lsst::afw::fits::Fits::readTableArray	(	std::size_t	row,
		int	col,
		int	nElements,
		T *	value
	)

Read an array value from a binary table.

template<typename T >

void lsst::afw::fits::Fits::readTableScalar ( std::size_t  row, int  col, T &  value  )

inline

Read an array scalar from a binary table.

Definition at line 466 of file fits.h.

{ readTableArray(row, col, 1, &value); }

void lsst::afw::fits::Fits::readTableScalar	(	std::size_t	row,
		int	col,
		std::string &	value
	)

Read a string from a binary table.

void lsst::afw::fits::Fits::setHdu	(	int	hdu,
		bool	relative = false
	)

Set the current HDU.

Parameters

[in]	hdu	The HDU to move to (1-indexed; 1 is the Primary HDU). The special value of 0 moves to the first extension if the Primary HDU is empty (has NAXIS==0) and the the Primary HDU is the current one.
[in]	relative	If true, move relative to the current HDU.

template<typename T >

void lsst::afw::fits::Fits::updateColumnKey	(	std::string const &	prefix,
		int	n,
		T const &	value,
		std::string const &	comment
	)

Update a key of the form XXXXXnnn, where XXXXX is the prefix and nnn is a column number.

void lsst::afw::fits::Fits::updateColumnKey ( std::string const &  prefix, int  n, char const *  value, std::string const &  comment  )

inline

Update a key of the form XXXXXnnn, where XXXXX is the prefix and nnn is a column number.

Definition at line 264 of file fits.h.

                                                                                                         {
        updateColumnKey(prefix, n, std::string(value), comment);
    }

template<typename T >

void lsst::afw::fits::Fits::updateColumnKey	(	std::string const &	prefix,
		int	n,
		T const &	value
	)

Update a key of the form XXXXXnnn, where XXXXX is the prefix and nnn is a column number.

void lsst::afw::fits::Fits::updateColumnKey ( std::string const &  prefix, int  n, char const *  value  )

inline

Update a key of the form XXXXXnnn, where XXXXX is the prefix and nnn is a column number.

Definition at line 269 of file fits.h.

                                                                              {
        updateColumnKey(prefix, n, std::string(value));
    }

template<typename T >

void lsst::afw::fits::Fits::updateKey	(	std::string const &	key,
		T const &	value,
		std::string const &	comment
	)

Set a FITS header key, editing if it already exists and appending it if not.

void lsst::afw::fits::Fits::updateKey ( std::string const &  key, char const *  value, std::string const &  comment  )

inline

Set a FITS header key, editing if it already exists and appending it if not.

Definition at line 230 of file fits.h.

                                                                                         {
        updateKey(key, std::string(value), comment);
    }

template<typename T >

void lsst::afw::fits::Fits::updateKey	(	std::string const &	key,
		T const &	value
	)

Set a FITS header key, editing if it already exists and appending it if not.

void lsst::afw::fits::Fits::updateKey ( std::string const &  key, char const *  value  )

inline

Set a FITS header key, editing if it already exists and appending it if not.

Definition at line 235 of file fits.h.

                                                              {
        updateKey(key, std::string(value));
    }

template<typename T >

void lsst::afw::fits::Fits::writeColumnKey	(	std::string const &	prefix,
		int	n,
		T const &	value,
		std::string const &	comment
	)

Write a key of the form XXXXXnnn, where XXXXX is the prefix and nnn is a column number.

void lsst::afw::fits::Fits::writeColumnKey ( std::string const &  prefix, int  n, char const *  value, std::string const &  comment  )

inline

Write a key of the form XXXXXnnn, where XXXXX is the prefix and nnn is a column number.

Definition at line 278 of file fits.h.

                                                                                                        {
        writeColumnKey(prefix, n, std::string(value), comment);
    }

template<typename T >

void lsst::afw::fits::Fits::writeColumnKey	(	std::string const &	prefix,
		int	n,
		T const &	value
	)

Write a key of the form XXXXXnnn, where XXXXX is the prefix and nnn is a column number.

void lsst::afw::fits::Fits::writeColumnKey ( std::string const &  prefix, int  n, char const *  value  )

inline

Write a key of the form XXXXXnnn, where XXXXX is the prefix and nnn is a column number.

Definition at line 283 of file fits.h.

                                                                             {
        writeColumnKey(prefix, n, std::string(value));
    }

template<typename T , int N, int C>

void lsst::afw::fits::Fits::writeImage ( ndarray::Array< T const, N, C > const &  array )

inline

Write an ndarray::Array to a FITS image HDU.

The HDU must already exist and have the correct bitpix.

An extra deep-copy may be necessary if the array is not fully contiguous.

Definition at line 368 of file fits.h.

                                                             {
        ndarray::Array<T const,N,N> contiguous = ndarray::dynamic_dimension_cast<2>(array);
        if (contiguous.empty()) contiguous = ndarray::copy(array);
        writeImageImpl(contiguous.getData(), contiguous.getNumElements());
    }

template<typename T >

void lsst::afw::fits::Fits::writeImageImpl ( T const *  data, int  nElements  )

private

template<typename T >

void lsst::afw::fits::Fits::writeKey	(	std::string const &	key,
		T const &	value,
		std::string const &	comment
	)

Add a FITS header key to the bottom of the header.

If the key is HISTORY or COMMENT and the value is a std::string or C-string, a special HISTORY or COMMENT key will be appended (and the comment argument will be ignored if present).

void lsst::afw::fits::Fits::writeKey ( std::string const &  key, char const *  value, std::string const &  comment  )

inline

Add a FITS header key to the bottom of the header.

If the key is HISTORY or COMMENT and the value is a std::string or C-string, a special HISTORY or COMMENT key will be appended (and the comment argument will be ignored if present).

Definition at line 250 of file fits.h.

                                                                                        {
        writeKey(key, std::string(value), comment);
    }

template<typename T >

void lsst::afw::fits::Fits::writeKey	(	std::string const &	key,
		T const &	value
	)

Add a FITS header key to the bottom of the header.

If the key is HISTORY or COMMENT and the value is a std::string or C-string, a special HISTORY or COMMENT key will be appended (and the comment argument will be ignored if present).

void lsst::afw::fits::Fits::writeKey ( std::string const &  key, char const *  value  )

inline

Add a FITS header key to the bottom of the header.

If the key is HISTORY or COMMENT and the value is a std::string or C-string, a special HISTORY or COMMENT key will be appended (and the comment argument will be ignored if present).

Definition at line 255 of file fits.h.

                                                             {
        writeKey(key, std::string(value));
    }

void lsst::afw::fits::Fits::writeMetadata

(

daf::base::PropertySet const &

metadata

)

Read a FITS header into a PropertySet or PropertyList.

Parameters

[in]

metadata

A PropertySet or PropertyList whose items will be appended to the FITS header.

All keys will be appended to the FITS header rather than used to update existing keys. Order of keys will be preserved if and only if the metadata object is actually a PropertyList.

template<typename T >

void lsst::afw::fits::Fits::writeTableArray	(	std::size_t	row,
		int	col,
		int	nElements,
		T const *	value
	)

Write an array value to a binary table.

template<typename T >

void lsst::afw::fits::Fits::writeTableScalar ( std::size_t  row, int  col, T  value  )

inline

Write an scalar value to a binary table.

Definition at line 455 of file fits.h.

{ writeTableArray(row, col, 1, &value); }

void lsst::afw::fits::Fits::writeTableScalar	(	std::size_t	row,
		int	col,
		std::string const &	value
	)

Write a string to a binary table.

Member Data Documentation

int lsst::afw::fits::Fits::behavior

Definition at line 493 of file fits.h.

void* lsst::afw::fits::Fits::fptr

Definition at line 491 of file fits.h.

int lsst::afw::fits::Fits::status

Definition at line 492 of file fits.h.

---

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

• /home/lsstsw/stack/Linux64/afw/11.0-2-g04d2804/include/lsst/afw/fits.h