Class Fits

Class Documentation

class Fits

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.

Unnamed Group

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.

void updateKey(std::string const &key, char const *value, std::string const &comment)
template<typename T>
void updateKey(std::string const &key, T const &value)
void updateKey(std::string const &key, char const *value)

Unnamed Group

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.

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 writeKey(std::string const &key, char const *value, std::string const &comment)
template<typename T>
void writeKey(std::string const &key, T const &value)
void writeKey(std::string const &key, char const *value)

Unnamed Group

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.

void updateColumnKey(std::string const &prefix, int n, char const *value, std::string const &comment)
template<typename T>
void updateColumnKey(std::string const &prefix, int n, T const &value)
void updateColumnKey(std::string const &prefix, int n, char const *value)

Unnamed Group

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.

void writeColumnKey(std::string const &prefix, int n, char const *value, std::string const &comment)
template<typename T>
void writeColumnKey(std::string const &prefix, int n, T const &value)
void writeColumnKey(std::string const &prefix, int n, char const *value)

Public Types

enum BehaviorFlags

Values:

AUTO_CLOSE = 0x01
AUTO_CHECK = 0x02

Public Functions

std::string getFileName() const

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

int getHdu()

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

void setHdu(int hdu, bool relative = false)

Set the current HDU.

Parameters

  • [in] hdu: The HDU to move to (0-indexed; 0 is the Primary HDU). The special value of DEFAULT_HDU 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.

int countHdus()

Return the number of HDUs in the file.

void writeMetadata(daf::base::PropertySet const &metadata)

Read a FITS header into a PropertySet or PropertyList.

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.

Parameters

  • [in] metadata: A PropertySet or PropertyList whose items will be appended to the FITS header.

void readMetadata(daf::base::PropertySet &metadata, bool strip = false)

Read a FITS header into a PropertySet or PropertyList.

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

Parameters

  • [inout] 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.

template<typename T>
void readKey(std::string const &key, T &value)

Read a FITS header key into the given reference.

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

void 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 createImage(ndarray::Vector<ndarray::Size, N> const &shape)

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

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.

Note

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

template<int N>
void createImage(int bitpix, ndarray::Vector<ndarray::Size, N> const &shape)
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.

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.

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.

The HDU must already exist and have the correct bitpix.

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

No compression or scaling is performed.

template<typename T>
void writeImage(image::ImageBase<T> const &image, ImageWriteOptions const &options, std::shared_ptr<daf::base::PropertySet const> header = std::shared_ptr<daf::base::PropertyList>(), std::shared_ptr<image::Mask<image::MaskPixel> const> mask = std::shared_ptr<image::Mask<image::MaskPixel>>())

Write an image to FITS

This method is all-inclusive, and covers creating the HDU (with the correct BITPIX), writing the header and optional scaling and compression of the image.

Parameters

  • [in] image: Image to write to FITS.

  • [in] options: Options controlling the write (scaling, compression).

  • [in] header: FITS header to write.

  • [in] mask: Mask for image (used for statistics when scaling).

int getImageDim()

Return the number of dimensions in the current HDU.

template<int N>
ndarray::Vector<ndarray::Size, N> getImageShape()

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.

template<typename T>
bool checkImageType()

Return true if the current HDU is compatible with the given pixel type.

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

std::string getImageDType()

Return the numpy dtype equivalent of the image pixel type (e.g. “uint16”, “float64”).

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.

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.

void createTable()

Create a new binary table extension.

template<typename T>
int 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 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 addRows(std::size_t nRows)

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

std::size_t countRows()

Return the number of row in a table.

template<typename T>
void writeTableArray(std::size_t row, int col, int nElements, T const *value)

Write an array value to a binary table.

template<typename T>
void writeTableScalar(std::size_t row, int col, T value)

Write a scalar value to a binary table.

void writeTableScalar(std::size_t row, int col, std::string const &value)

Write a string to a binary table.

template<typename T>
void readTableArray(std::size_t row, int col, int nElements, T *value)

Read an array value from a binary table.

template<typename T>
void readTableScalar(std::size_t row, int col, T &value)

Read an array scalar from a binary table.

void readTableScalar(std::size_t row, int col, std::string &value, bool isVariableLength)

Read a string from a binary table.

long getTableArraySize(int col)

Return the size of an array column.

long getTableArraySize(std::size_t row, int col)

Return the size of an variable-length array field.

Fits()

Default constructor; set all data members to 0.

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

Open or create a FITS file from disk.

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

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

void closeFile()

Close a FITS file.

void setImageCompression(ImageCompressionOptions const &options)

Set compression options for writing FITS images

See

ImageCompressionContext

ImageCompressionOptions getImageCompression()

Return the current image compression settings.

bool checkCompressedImagePhu()

Go to the first image header in the FITS file

If a single image is written compressed, it appears as an extension, rather than the primary HDU (PHU). This method is useful before reading an image, as it checks whether we are positioned on an empty PHU and if the next HDU is a compressed image; if so, it leaves the file pointer on the compresed image, ready for reading.

~Fits()
Fits(const Fits&)
Fits &operator=(const Fits&)
Fits(Fits&&)
Fits &operator=(Fits&&)

Public Members

void *fptr
int status
int behavior