File fits.h

Defines

LSST_FITS_EXCEPT(type, fitsObj, ...)

A FITS-related replacement for LSST_EXCEPT that takes an additional Fits object and uses makeErrorMessage(fitsObj.fptr, fitsObj.status, …) to construct the message.

LSST_FITS_CHECK_STATUS(fitsObj, ...)

Throw a FitsError exception if the status of the given Fits object is nonzero.

namespace lsst

Class for a simple mapping implementing a generic AstrometryTransform.

Remove all non-astronomical counts from the Chunk Exposure’s pixels.

Forward declarations for lsst::utils::Cache

For details on the Cache class, see the Cache.h file.

It uses a template rather than a pointer so that the derived classes can use the specifics of the transform. The class simplePolyMapping overloads a few routines.

A base class for image defects

Numeric constants used by the Integrate.h integrator routines.

Compute Image Statistics

Note

Gauss-Kronrod-Patterson quadrature coefficients for use in quadpack routine qng. These coefficients were calculated with 101 decimal digit arithmetic by L. W. Fullerton, Bell Labs, Nov 1981.

Note

The Statistics class itself can only handle lsst::afw::image::MaskedImage() types. The philosophy has been to handle other types by making them look like lsst::afw::image::MaskedImage() and reusing that code. Users should have no need to instantiate a Statistics object directly, but should use the overloaded makeStatistics() factory functions.

namespace afw
namespace fits

Functions

LSST_EXCEPTION_TYPE(FitsError, lsst::pex::exceptions::IoError, lsst::afw::fits::FitsError)

An exception thrown when problems are found when reading or writing FITS files. An exception thrown when a FITS file has the wrong type.

std::string makeErrorMessage(std::string const &fileName = "", int status = 0, std::string const &msg = "")

Return an error message reflecting FITS I/O errors.

Parameters

  • [in] fileName: FITS filename to be included in the error message.

  • [in] status: The last status value returned by the cfitsio library; if nonzero, the error message will include a description from cfitsio.

  • [in] msg: An additional custom message to include.

std::string makeErrorMessage(std::string const &fileName, int status, boost::format const &msg)
std::string makeErrorMessage(void *fptr, int status = 0, std::string const &msg = "")

Return an error message reflecting FITS I/O errors.

Parameters

  • [in] fptr: A cfitsio fitsfile pointer to be inspected for a filename. Passed as void* to avoid including fitsio.h in the header file.

  • [in] status: The last status value returned by the cfitsio library; if nonzero, the error message will include a description from cfitsio.

  • [in] msg: An additional custom message to include.

std::string makeErrorMessage(void *fptr, int status, boost::format const &msg)
std::string makeLimitedFitsHeader(lsst::daf::base::PropertySet const &metadata, std::set<std::string> const &excludeNames = {})

Format a PropertySet into an FITS header string in a simplistic fashion.

This function is designed to format data for creating a WCS. As such, it is quite limited:

  • It skips entries whose name is longer than 8 characters, since none are used for FITS-WCS

  • It skips string entries if the fully formatted string is longer than 80 characters

  • It skips entries with types it cannot handle (e.g. long, long long)

  • For entries that have array data, it only writes the final value, since that is the value that should be used by code that reads FITS headers.

  • It makes no attempt to insure that required entries, such as SIMPLE, are present.

Return

a FITS header string (exactly 80 characters per entry, no line terminators)

Parameters

  • [in] metadata: Metadata to format; if this is a PropertyList then the order of items is preserved

  • [in] excludeNames: Names of entries to exclude from the returned header string

template<typename T>
int getBitPix()

Return the cfitsio integer BITPIX code for the given data type.

template<typename T, int N, int C>
ndarray::Array<T const, N, N> const makeContiguousArray(ndarray::Array<T, N, C> const &array)

Construct a contiguous ndarray

A deep copy is only performed if the array is not already contiguous.

std::shared_ptr<daf::base::PropertyList> combineMetadata(std::shared_ptr<const daf::base::PropertyList> first, std::shared_ptr<const daf::base::PropertyList> second)

Combine two sets of metadata in a FITS-appropriate fashion

“COMMENT” and “HISTORY” entries:

  • If of type std::string then the values in second are appended to values in first

  • If not of type std::string then they are silently ignored

All other entries:

  • Values in second override values in first (regardless of type)

  • Only scalars are copied; if a vector is found, only the last value is copied

Return

The combined metadata. Item names have the following order:

  • names in first, omitting all names except “COMMENT” and “HISTORY” that appear in second

  • names in second, omitting “COMMENT” and “HISTORY” if valid versions appear in first

Parameters

  • [in] first: The first set of metadata to combine

  • [in] second: The second set of metadata to combine

std::shared_ptr<daf::base::PropertyList> readMetadata(std::string const &fileName, int hdu = DEFAULT_HDU, bool strip = false)

Read FITS header

Includes support for the INHERIT convention: if ‘INHERIT = T’ is in the header, the PHU will be read as well, and nominated HDU will override any duplicated values.

Return the metadata (header entries) from a FITS file.

Parameters

  • fileName: the file whose header will be read

  • hdu: the HDU to read (0-indexed; 0 is the Primary HDU).

  • strip: if true, common FITS keys that usually have non-metadata intepretations (e.g. NAXIS, BITPIX) will be ignored.

Parameters

  • [in] fileName: File to read.

  • [in] hdu: HDU to read, 0-indexed. The special value of afw::fits::DEFAULT_HDU will read the first non-empty HDU.

  • [in] strip: If true, ignore special header keys usually managed by cfitsio (e.g. NAXIS).

std::shared_ptr<daf::base::PropertyList> readMetadata(fits::MemFileManager &manager, int hdu = DEFAULT_HDU, bool strip = false)

Read FITS header

Includes support for the INHERIT convention: if ‘INHERIT = T’ is in the header, the PHU will be read as well, and nominated HDU will override any duplicated values.

Parameters

  • manager: the in-memory file whose header will be read

  • hdu: the HDU to read (0-indexed; 0 is the Primary HDU).

  • strip: if true, common FITS keys that usually have non-metadata intepretations (e.g. NAXIS, BITPIX) will be ignored.

std::shared_ptr<daf::base::PropertyList> readMetadata(fits::Fits &fitsfile, bool strip = false)

Read FITS header

Includes support for the INHERIT convention: if ‘INHERIT = T’ is in the header, the PHU will be read as well, and nominated HDU will override any duplicated values.

Parameters

  • fitsfile: the file and HDU to be read

  • strip: if true, common FITS keys that usually have non-metadata intepretations (e.g. NAXIS, BITPIX) will be ignored.

void setAllowImageCompression(bool allow)
bool getAllowImageCompression()
class Fits
#include <fits.h>

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

Private Functions

void createImageImpl(int bitpix, int nAxis, long const *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 maxDim, long *nAxes)
class HduMoveGuard
#include <fits.h>

RAII scoped guard for moving the HDU in a Fits object.

This class attempts to ensure that the HDU state of a Fits object is restored when the guard class goes out of scope, even in the presence of exceptions. (In practice, resetting the HDU can only fail if the Fits object has become sufficiently corrupted that it’s no longer usable at all).

Public Functions

HduMoveGuard()
HduMoveGuard(HduMoveGuard const&)
HduMoveGuard(HduMoveGuard&&)
HduMoveGuard &operator=(HduMoveGuard const&)
HduMoveGuard &operator=(HduMoveGuard&&)
HduMoveGuard(Fits &fits, int hdu, bool relative = false)

Create a guard object and set the HDU of the given Fits object at the same time.

Parameters

  • [inout] fits: FITS file pointer to manipulate.

  • [in] hdu: HDU index moved to within the lifetime of the guard object (0 is primary).

  • [in] relative: If True, interpret hdu as relative to the current HDU rather than an absolute index.

~HduMoveGuard()
void disable()

Disable the guard, leaving the HDU at its current state at destruction.

Private Members

Fits &_fits
int _oldHdu
bool _enabled
class HeaderIterationFunctor
#include <fits.h>

Base class for polymorphic functors used to iterator over FITS key headers.

Subclass this, and then pass an instance to Fits::forEachKey to iterate over all the keys in a header.

Public Functions

virtual void operator()(std::string const &key, std::string const &value, std::string const &comment) = 0
virtual ~HeaderIterationFunctor()
struct ImageWriteOptions
#include <fits.h>

Options for writing an image to FITS

An image being written to FITS may be scaled (quantised) and/or compressed. This struct is a container for options controlling each of those separately.

Public Functions

template<typename T>
ImageWriteOptions(image::Image<T> const &image)

Construct with default options for images.

template<typename T>
ImageWriteOptions(image::Mask<T> const &mask)

Construct with default options for masks.

ImageWriteOptions(ImageCompressionOptions const &compression_ = ImageCompressionOptions(ImageCompressionOptions::NONE), ImageScalingOptions const &scaling_ = ImageScalingOptions())

Construct with specific compression and scaling options.

ImageWriteOptions(ImageScalingOptions const &scaling_)

Construct with specific scaling options.

ImageWriteOptions(daf::base::PropertySet const &config)

Construct from a PropertySet

The PropertySet should include the following elements:

  • compression.scheme (string): compression algorithm to use

  • compression.columns (int): number of columns per tile (0 = entire dimension)

  • compression.rows (int): number of rows per tile (0 = 1 row; that’s what cfitsio does)

  • compression.quantizeLevel (float): cfitsio quantization level

  • scaling.scheme (string): scaling algorithm to use

  • scaling.bitpix (int): bits per pixel (0, 8,16,32,64,-32,-64)

  • scaling.fuzz (bool): fuzz the values when quantising floating-point values?

  • scaling.seed (long): seed for random number generator when fuzzing

  • scaling.maskPlanes (list of string): mask planes to ignore when doing statistics

  • scaling.quantizeLevel: divisor of the standard deviation for STDEV_* scaling

  • scaling.quantizePad: number of stdev to allow on the low side (for STDEV_POSITIVE/NEGATIVE)

  • scaling.bscale: manually specified BSCALE (for MANUAL scaling)

  • scaling.bzero: manually specified BSCALE (for MANUAL scaling)

Use the ‘validate’ method to set default values for the above.

‘scaling.maskPlanes’ is the only entry that is allowed to be missing (because PropertySet can’t represent an empty array); when it is missing, it is interpreted as an empty array.

Parameters

  • [in] config: Configuration of image write options

Public Members

ImageCompressionOptions compression

Options controlling compression.

ImageScalingOptions scaling

Options controlling scaling.

Public Static Functions

static std::shared_ptr<daf::base::PropertySet> validate(daf::base::PropertySet const &config)

Validate a PropertySet

Returns a validated PropertySet with default values added, suitable for use with the constructor.

For details on what elements may be included in the input, see ImageWriteOptions::ImageWriteOptions(daf::base::PropertySet const&).

Return

validated configuration

Parameters

  • [in] config: Configuration of image write options

Exceptions

  • lsst::pex::exceptions::RuntimeError: if entry is not recognized.

class MemFileManager
#include <fits.h>

Lifetime-management for memory that goes into FITS memory files.

Public Functions

MemFileManager()

Construct a MemFileManager with no initial memory buffer.

The manager will still free the memory when it goes out of scope, but all allocation and reallocation will be performed by cfitsio as needed.

MemFileManager(std::size_t len)

Construct a MemFileManager with (len) bytes of initial memory.

The manager will free the memory when it goes out of scope, and cfitsio will be allowed to reallocate the internal memory as needed.

MemFileManager(void *ptr, std::size_t len)

Construct a MemFileManager that references and does not manage external memory.

The manager will not manage the given pointer, and it will not allow cfitsio to do so either. The user must provide enough initial memory and is responsible for freeing it manually after the FITS file has been closed.

void reset()

Return the manager to the same state it would be if default-constructed.

This must not be called while a FITS file that uses this memory is open.

void reset(std::size_t len)

Set the size of the internal memory buffer, freeing the current buffer if necessary.

This must not be called while a FITS file that uses this memory is open.

Memory allocated with this overload of reset can be reallocated by cfitsio and will be freed when the manager goes out of scope or is reset.

void reset(void *ptr, std::size_t len)

Set the internal memory buffer to an manually-managed external block.

This must not be called while a FITS file that uses this memory is open.

Memory passed to this overload of reset cannot be reallocated by cfitsio and will not be freed when the manager goes out of scope or is reset.

~MemFileManager()
MemFileManager(const MemFileManager&)
MemFileManager &operator=(const MemFileManager&)
MemFileManager(MemFileManager&&)
MemFileManager &operator=(MemFileManager&&)
void *getData() const

Return the buffer.

std::size_t getLength() const

Return the buffer length.

Private Members

void *_ptr
std::size_t _len
bool _managed

Friends

friend lsst::afw::fits::Fits