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>

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.
int	getHdu ()
	Return the current HDU (0-indexed; 0 is the Primary HDU).
void	setHdu (int hdu, bool relative=false)
	Set the current HDU.
void	setHdu (std::string const &name, HduType hdutype=HduType::ANY, int hduver=0)
	Set the current HDU using its name, version and type.
int	countHdus ()
	Return the number of HDUs in the file.
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)
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.
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)
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)
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)
void	writeMetadata (daf::base::PropertySet const &metadata)
	Read a FITS header into a PropertySet or PropertyList.
void	readMetadata (daf::base::PropertySet &metadata, bool strip=false)
	Read a FITS header into a PropertySet or PropertyList.
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.
void	createEmpty ()
	Create an empty image HDU with NAXIS=0 at the end of the file.
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.
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.
template<typename T>
void	writeImage (image::ImageBase< T > const &image, CompressionOptions const *compression=nullptr, daf::base::PropertySet const *header=nullptr, image::Mask< image::MaskPixel > const *mask=nullptr)
	Write an image to FITS.
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.
template<typename T>
bool	checkImageType ()
	Return true if the current HDU is compatible with the given pixel type.
std::string	getImageDType ()
	Return the numpy dtype equivalent of the image pixel type (e.g.
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.
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.
template<typename T>
int	addColumn (std::string const &ttype, int size)
	Add a column to a table.
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.
bool	checkCompressedImagePhu ()
	Go to the first image header in the FITS file.
	~Fits ()
	Fits (const Fits &)=delete
Fits &	operator= (const Fits &)=delete
	Fits (Fits &&)=delete
Fits &	operator= (Fits &&)=delete
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.
template<int N>
void	createImage (int bitpix, 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.

Public Attributes
void *	fptr
int	status
int	behavior

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 242 of file fits.h.

Member Enumeration Documentation

BehaviorFlags

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

Enumerator
AUTO_CLOSE
AUTO_CHECK

Definition at line 251 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

Fits() [1/5]

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

inline

Default constructor; set all data members to 0.

Definition at line 567 of file fits.h.

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

Fits() [2/5]

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

Open or create a FITS file from disk.

Definition at line 1707 of file fits.cc.

        : fptr(nullptr), status(0), behavior(behavior_) {
    if (mode == "r" || mode == "rb") {
        fits_open_file(reinterpret_cast<fitsfile **>(&fptr), const_cast<char *>(filename.c_str()), READONLY,
                       &status);
    } else if (mode == "w" || mode == "wb") {
        std::filesystem::remove(filename);  // cfitsio doesn't like over-writing files
        fits_create_file(reinterpret_cast<fitsfile **>(&fptr), const_cast<char *>(filename.c_str()), &status);
    } else if (mode == "a" || mode == "ab") {
        fits_open_file(reinterpret_cast<fitsfile **>(&fptr), const_cast<char *>(filename.c_str()), READWRITE,
                       &status);
        int nHdu = 0;
        fits_get_num_hdus(reinterpret_cast<fitsfile *>(fptr), &nHdu, &status);
        fits_movabs_hdu(reinterpret_cast<fitsfile *>(fptr), nHdu, nullptr, &status);
        if ((behavior & AUTO_CHECK) && (behavior & AUTO_CLOSE) && (status) && (fptr)) {
            // We're about to throw an exception, and the destructor won't get called
            // because we're in the constructor, so cleanup here first.
            int tmpStatus = 0;
            fits_close_file(reinterpret_cast<fitsfile *>(fptr), &tmpStatus);
        }
    } else {
        throw LSST_EXCEPT(
                FitsError,
                (boost::format("Invalid mode '%s' given when opening file '%s'") % mode % filename).str());
    }
    if (behavior & AUTO_CHECK) {
        LSST_FITS_CHECK_STATUS(*this, boost::format("Opening file '%s' with mode '%s'") % filename % mode);
    }
}

Fits() [3/5]

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

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

Definition at line 1737 of file fits.cc.

        : fptr(nullptr), status(0), behavior(behavior_) {
    using Reallocator = void *(*)(void *, std::size_t);
    // It's a shame this logic is essentially a duplicate of above, but the innards are different enough
    // we can't really reuse it.
    if (mode == "r" || mode == "rb") {
        fits_open_memfile(reinterpret_cast<fitsfile **>(&fptr), "unused", READONLY, &manager._ptr,
                          &manager._len, 0, nullptr,  // no reallocator or deltasize necessary for READONLY
                          &status);
    } else if (mode == "w" || mode == "wb") {
        Reallocator reallocator = nullptr;
        if (manager._managed) reallocator = &std::realloc;
        fits_create_memfile(reinterpret_cast<fitsfile **>(&fptr), &manager._ptr, &manager._len, 0,
                            reallocator,  // use default deltasize
                            &status);
    } else if (mode == "a" || mode == "ab") {
        Reallocator reallocator = nullptr;
        if (manager._managed) reallocator = &std::realloc;
        fits_open_memfile(reinterpret_cast<fitsfile **>(&fptr), "unused", READWRITE, &manager._ptr,
                          &manager._len, 0, reallocator, &status);
        int nHdu = 0;
        fits_get_num_hdus(reinterpret_cast<fitsfile *>(fptr), &nHdu, &status);
        fits_movabs_hdu(reinterpret_cast<fitsfile *>(fptr), nHdu, nullptr, &status);
        if ((behavior & AUTO_CHECK) && (behavior & AUTO_CLOSE) && (status) && (fptr)) {
            // We're about to throw an exception, and the destructor won't get called
            // because we're in the constructor, so cleanup here first.
            int tmpStatus = 0;
            fits_close_file(reinterpret_cast<fitsfile *>(fptr), &tmpStatus);
        }
    } else {
        throw LSST_EXCEPT(FitsError,
                          (boost::format("Invalid mode '%s' given when opening memory file at '%s'") % mode %
                           manager._ptr)
                                  .str());
    }
    if (behavior & AUTO_CHECK) {
        LSST_FITS_CHECK_STATUS(
                *this, boost::format("Opening memory file at '%s' with mode '%s'") % manager._ptr % mode);
    }
}

~Fits()

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

inline

Definition at line 587 of file fits.h.

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

Fits() [4/5]

lsst::afw::fits::Fits::Fits ( const Fits & )

delete

Fits() [5/5]

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

delete

Member Function Documentation

addColumn() [1/2]

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.

Definition at line 1118 of file fits.cc.

                                                    {
    int nCols = 0;
    fits_get_num_cols(reinterpret_cast<fitsfile *>(fptr), &nCols, &status);
    std::string tform = makeColumnFormat<T>(size);
    fits_insert_col(reinterpret_cast<fitsfile *>(fptr), nCols + 1, const_cast<char *>(ttype.c_str()),
                    const_cast<char *>(tform.c_str()), &status);
    if (behavior & AUTO_CHECK) {
        LSST_FITS_CHECK_STATUS(*this, boost::format("Adding column '%s' with size %d") % ttype % size);
    }
    return nCols;
}

addColumn() [2/2]

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.

Definition at line 1131 of file fits.cc.

                                                                              {
    int nCols = addColumn<T>(ttype, size);
    updateColumnKey("TTYPE", nCols, ttype, comment);
    if (behavior & AUTO_CHECK) {
        LSST_FITS_CHECK_STATUS(*this, boost::format("Adding column '%s' with size %d") % ttype % size);
    }
    return nCols;
}

addRows()

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.

Definition at line 1140 of file fits.cc.

                                       {
    long first = 0;
    fits_get_num_rows(reinterpret_cast<fitsfile *>(fptr), &first, &status);
    fits_insert_rows(reinterpret_cast<fitsfile *>(fptr), first, nRows, &status);
    if (behavior & AUTO_CHECK) {
        LSST_FITS_CHECK_STATUS(*this, boost::format("Adding %d rows to binary table") % nRows);
    }
    return first;
}

checkCompressedImagePhu()

bool lsst::afw::fits::Fits::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 compressed image, ready for reading.

Definition at line 1902 of file fits.cc.

                                   {
    auto fits = reinterpret_cast<fitsfile *>(fptr);
    if (getHdu() != 0 || countHdus() == 1) {
        return false;  // Can't possibly be the PHU leading a compressed image
    }
    // Check NAXIS = 0
    int naxis;
    fits_get_img_dim(fits, &naxis, &status);
    if (behavior & AUTO_CHECK) {
        LSST_FITS_CHECK_STATUS(*this, "Checking NAXIS of PHU");
    }
    if (naxis != 0) {
        return false;
    }
    // Check first extension (and move back there when we're done if we're not compressed)
    HduMoveGuard move(*this, 1);
    bool isCompressed = fits_is_compressed_image(fits, &status);
    if (behavior & AUTO_CHECK) {
        LSST_FITS_CHECK_STATUS(*this, "Checking compression");
    }
    if (isCompressed) {
        move.disable();
    }
    return isCompressed;
}

checkImageType()

template<typename T>

bool lsst::afw::fits::Fits::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.

Definition at line 1652 of file fits.cc.

                          {
    int imageType = get_actual_cfitsio_bitpix(*this);
    if (std::numeric_limits<T>::is_integer) {
        if (imageType < 0) {
            return false;  // can't represent floating-point with integer
        }
        bool is_compressed = fits_is_compressed_image(reinterpret_cast<fitsfile*>(fptr), &status);
        if (behavior & AUTO_CHECK) LSST_FITS_CHECK_STATUS(*this, "Checking pixel type compatibility");
        if (is_compressed && sizeof(T) == 8) {
            // CFITSIO can't decompress into [u]int64, at least on some
            // platforms, so we don't support it.
            return false;
        }
        if (std::numeric_limits<T>::is_signed) {
            if (isFitsImageTypeSigned(imageType)) {
                return cfitsio_bitpix<T> >= imageType;
            } else {
                // need extra bits to safely convert unsigned to signed
                return cfitsio_bitpix<T> > imageType;
            }
        } else {
            if (!isFitsImageTypeSigned(imageType)) {
                return cfitsio_bitpix<T> >= imageType;
            } else {
                return false;
            }
        }
    }
    // we allow all conversions to float and double, even if they lose precision
    return true;
}

closeFile()

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

(

)

Close a FITS file.

Definition at line 1778 of file fits.cc.

                     {
    fits_close_file(reinterpret_cast<fitsfile *>(fptr), &status);
    fptr = nullptr;
}

countHdus()

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

(

)

Return the number of HDUs in the file.

Definition at line 518 of file fits.cc.

                    {
    int n = 0;
    fits_get_num_hdus(reinterpret_cast<fitsfile *>(fptr), &n, &status);
    if (behavior & AUTO_CHECK) {
        LSST_FITS_CHECK_STATUS(*this, "Getting number of HDUs in file.");
    }
    return n;
}

countRows()

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

(

)

Return the number of row in a table.

Definition at line 1150 of file fits.cc.

                          {
    long r = 0;
    fits_get_num_rows(reinterpret_cast<fitsfile *>(fptr), &r, &status);
    if (behavior & AUTO_CHECK) {
        LSST_FITS_CHECK_STATUS(*this, "Checking how many rows are in table");
    }
    return r;
}

createEmpty()

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.

Definition at line 1534 of file fits.cc.

                       {
    long naxes = 0;
    fits_create_img(reinterpret_cast<fitsfile *>(fptr), 8, 0, &naxes, &status);
    if (behavior & AUTO_CHECK) {
        LSST_FITS_CHECK_STATUS(*this, "Creating empty image HDU");
    }
}

createImage() [1/3]

template<int N>

void lsst::afw::fits::Fits::createImage ( int bitpix, ndarray::Vector< ndarray::Size, 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 406 of file fits.h.

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

createImage() [2/3]

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 419 of file fits.h.

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

createImage() [3/3]

template<typename PixelT, int N>

void lsst::afw::fits::Fits::createImage ( ndarray::Vector< ndarray::Size, 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 400 of file fits.h.

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

createTable()

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

(

)

Create a new binary table extension.

Definition at line 1108 of file fits.cc.

                       {
    char *ttype = nullptr;
    char *tform = nullptr;
    fits_create_tbl(reinterpret_cast<fitsfile *>(fptr), BINARY_TBL, 0, 0, &ttype, &tform, nullptr, nullptr, &status);
    if (behavior & AUTO_CHECK) {
        LSST_FITS_CHECK_STATUS(*this, "Creating binary table");
    }
}

forEachKey()

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.

Definition at line 765 of file fits.cc.

                                                     {
    char key[81];  // allow for terminating NUL
    char value[81];
    char comment[81];
    int nKeys = 0;
    fits_get_hdrspace(reinterpret_cast<fitsfile *>(fptr), &nKeys, nullptr, &status);
    std::string keyStr;
    std::string valueStr;
    std::string commentStr;
    int i = 1;
    while (i <= nKeys) {
        fits_read_keyn(reinterpret_cast<fitsfile *>(fptr), i, key, value, comment, &status);
        // fits_read_keyn does not convert the key case on read, like other fits methods in cfitsio>=3.38
        // We uppercase to try to be more consistent.
        std::string upperKey(key);
        boost::to_upper(upperKey);
        if (upperKey.compare(key) != 0){
            LOGLS_DEBUG("lsst.afw.fits",
                        boost::format("In %s, standardizing key '%s' to uppercase '%s' on read.") %
                        BOOST_CURRENT_FUNCTION % key % upperKey);
        }
        keyStr = upperKey;
        valueStr = value;
        commentStr = comment;
        ++i;
        while (valueStr.size() > 2 && valueStr[valueStr.size() - 2] == '&' && i <= nKeys) {
            // we're using key to hold the entire record here; the actual key is safe in keyStr
            fits_read_record(reinterpret_cast<fitsfile *>(fptr), i, key, &status);
            if (strncmp(key, "CONTINUE", 8) != 0) {
                // require both trailing '&' and CONTINUE to invoke long-string handling
                break;
            }
            std::string card = key;
            valueStr.erase(valueStr.size() - 2);
            std::size_t firstQuote = card.find('\'');
            if (firstQuote == std::string::npos) {
                throw LSST_EXCEPT(
                        FitsError,
                        makeErrorMessage(
                                fptr, status,
                                boost::format("Invalid CONTINUE at header key %d: \"%s\".") % i % card));
            }
            std::size_t lastQuote = card.find('\'', firstQuote + 1);
            if (lastQuote == std::string::npos) {
                throw LSST_EXCEPT(
                        FitsError,
                        makeErrorMessage(
                                fptr, status,
                                boost::format("Invalid CONTINUE at header key %d: \"%s\".") % i % card));
            }
            valueStr += card.substr(firstQuote + 1, lastQuote - firstQuote);
            std::size_t slash = card.find('/', lastQuote + 1);
            if (slash != std::string::npos) {
                commentStr += strip(card.substr(slash + 1));
            }
            ++i;
        }
        if (behavior & AUTO_CHECK) {
            LSST_FITS_CHECK_STATUS(*this, boost::format("Reading key '%s'") % keyStr);
        }
        functor(keyStr, valueStr, commentStr);
    }
}

getFileName()

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

(

)

const

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

Definition at line 474 of file fits.cc.

                                  {
    std::string fileName = "<unknown>";
    fitsfile *fd = reinterpret_cast<fitsfile *>(fptr);
    if (fd != nullptr && fd->Fptr != nullptr && fd->Fptr->filename != nullptr) {
        fileName = fd->Fptr->filename;
    }
    return fileName;
}

getHdu()

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

(

)

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

Definition at line 483 of file fits.cc.

                 {
    int n = 1;
    fits_get_hdu_num(reinterpret_cast<fitsfile *>(fptr), &n);
    return n - 1;
}

getImageDim()

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

(

)

Return the number of dimensions in the current HDU.

Definition at line 1639 of file fits.cc.

                      {
    int nAxis = 0;
    fits_get_img_dim(reinterpret_cast<fitsfile *>(fptr), &nAxis, &status);
    if (behavior & AUTO_CHECK) LSST_FITS_CHECK_STATUS(*this, "Getting NAXIS");
    return nAxis;
}

getImageDType()

std::string lsst::afw::fits::Fits::getImageDType

(

)

Return the numpy dtype equivalent of the image pixel type (e.g.

"uint16", "float64").

Definition at line 1684 of file fits.cc.

                              {
    int bitpix = get_actual_cfitsio_bitpix(*this);
    if (bitpix < 0) {
        return "float" + std::to_string(-bitpix);
    }
    switch (bitpix) {
        case BYTE_IMG: return "uint8";
        case SBYTE_IMG: return "int8";
        case SHORT_IMG: return "int16";
        case USHORT_IMG: return "uint16";
        case LONG_IMG: return "int32";
        case ULONG_IMG: return "uint32";
        case LONGLONG_IMG: return "int64";
        case ULONGLONG_IMG: return "uint64";
    }
    throw LSST_EXCEPT(
        FitsError,
        (boost::format("Unrecognized BITPIX value: %d") % bitpix).str()
    );
}

getImageShape()

template<int N>

ndarray::Vector< ndarray::Size, 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 470 of file fits.h.

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

getTableArraySize() [1/2]

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

(

int

col

)

Return the size of an array column.

Definition at line 1208 of file fits.cc.

                                    {
    int typecode = 0;
    long result = 0;
    long width = 0;
    fits_get_coltype(reinterpret_cast<fitsfile *>(fptr), col + 1, &typecode, &result, &width, &status);
    if (behavior & AUTO_CHECK) {
        LSST_FITS_CHECK_STATUS(*this, boost::format("Looking up array size for column %d") % col);
    }
    return result;
}

getTableArraySize() [2/2]

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

Return the size of an variable-length array field.

Definition at line 1219 of file fits.cc.

                                                   {
    long result = 0;
    long offset = 0;
    fits_read_descript(reinterpret_cast<fitsfile *>(fptr), col + 1, row + 1, &result, &offset, &status);
    if (behavior & AUTO_CHECK) {
        LSST_FITS_CHECK_STATUS(*this, boost::format("Looking up array size for cell (%d, %d)") % row % col);
    }
    return result;
}

operator=() [1/2]

Fits & lsst::afw::fits::Fits::operator= ( const Fits & )

delete

operator=() [2/2]

Fits & lsst::afw::fits::Fits::operator= ( Fits && )

delete

readImage()

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 499 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);
    }

readKey()

template<typename T>

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

Read a FITS header key into the given reference.

Definition at line 758 of file fits.cc.

                                                 {
    readKeyImpl(*this, key.c_str(), value);
    if (behavior & AUTO_CHECK) {
        LSST_FITS_CHECK_STATUS(*this, boost::format("Reading key '%s'") % key);
    }
}

readMetadata()

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.

Definition at line 1078 of file fits.cc.

                                                                {
    MetadataIterationFunctor f;
    f.strip = strip;
    f.set = &metadata;
    f.list = dynamic_cast<daf::base::PropertyList *>(&metadata);
    forEachKey(f);
}

readTableArray()

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.

Definition at line 1183 of file fits.cc.

                                                                         {
    int anynul = false;
    fits_read_col(reinterpret_cast<fitsfile *>(fptr), FitsTableType<T>::CONSTANT, col + 1, row + 1, 1,
                  nElements, nullptr, value, &anynul, &status);
    if (behavior & AUTO_CHECK) {
        LSST_FITS_CHECK_STATUS(*this, boost::format("Reading value at table cell (%d, %d)") % row % col);
    }
}

readTableScalar() [1/2]

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

Read a string from a binary table.

Definition at line 1192 of file fits.cc.

                                                                                          {
    int anynul = false;
    long size = isVariableLength ? getTableArraySize(row, col) : getTableArraySize(col);
    // We can't directly write into a std::string until C++17.
    std::vector<char> buf(size + 1, 0);
    // cfitsio wants a char** because they imagine we might want an array of strings,
    // but we only want one element.
    char *tmp = &buf.front();
    fits_read_col(reinterpret_cast<fitsfile *>(fptr), TSTRING, col + 1, row + 1, 1, 1, nullptr, &tmp, &anynul,
                  &status);
    if (behavior & AUTO_CHECK) {
        LSST_FITS_CHECK_STATUS(*this, boost::format("Reading value at table cell (%d, %d)") % row % col);
    }
    value = std::string(tmp);
}

readTableScalar() [2/2]

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 553 of file fits.h.

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

setHdu() [1/2]

void lsst::afw::fits::Fits::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.

Definition at line 489 of file fits.cc.

                                        {
    if (relative) {
        fits_movrel_hdu(reinterpret_cast<fitsfile *>(fptr), hdu, nullptr, &status);
        if (behavior & AUTO_CHECK) {
            LSST_FITS_CHECK_STATUS(*this, boost::format("Incrementing HDU by %d") % hdu);
        }
    } else {
        if (hdu != DEFAULT_HDU) {
            fits_movabs_hdu(reinterpret_cast<fitsfile *>(fptr), hdu + 1, nullptr, &status);
        }
        if (hdu == DEFAULT_HDU && getHdu() == 0 && getImageDim() == 0) {
            // want a silent failure here
            int tmpStatus = status;
            fits_movrel_hdu(reinterpret_cast<fitsfile *>(fptr), 1, nullptr, &tmpStatus);
        }
        if (behavior & AUTO_CHECK) {
            LSST_FITS_CHECK_STATUS(*this, boost::format("Moving to HDU %d") % hdu);
        }
    }
}

setHdu() [2/2]

void lsst::afw::fits::Fits::setHdu	(	std::string const &	name,
		HduType	hdutype = HduType::ANY,
		int	hduver = 0 )

Set the current HDU using its name, version and type.

Parameters

[in]	name	The name of the HDU to move to
[in]	hdutype	The type of HDU to match. If not supplied, defaults to ANY_HDU
[in]	hduver	The value of EXTVER to match. If not supplied, defaults to 0

Definition at line 510 of file fits.cc.

                                                                    {
    fits_movnam_hdu(reinterpret_cast<fitsfile *>(fptr), static_cast<int>(hdutype),
                    const_cast<char *>(name.c_str()), hduver, &status);
    if (behavior & AUTO_CHECK)
        LSST_FITS_CHECK_STATUS(*this, boost::format("Moving to named HDU %s, type %d, hduver %d") % name %
                                              static_cast<int>(hdutype) % hduver);
}

updateColumnKey() [1/4]

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

inline

Definition at line 325 of file fits.h.

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

updateColumnKey() [2/4]

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

inline

Definition at line 320 of file fits.h.

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

updateColumnKey() [3/4]

template<typename T>

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

Definition at line 691 of file fits.cc.

                                                                         {
    updateKey((boost::format("%s%d") % prefix % (n + 1)).str(), value);
    if (behavior & AUTO_CHECK) {
        LSST_FITS_CHECK_STATUS(*this, boost::format("Updating key '%s%d': '%s'") % prefix % (n + 1) % value);
    }
}

updateColumnKey() [4/4]

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.

Definition at line 675 of file fits.cc.

                                                                                                   {
    updateKey((boost::format("%s%d") % prefix % (n + 1)).str(), value, comment);
    if (behavior & AUTO_CHECK) {
        LSST_FITS_CHECK_STATUS(*this, boost::format("Updating key '%s%d': '%s'") % prefix % (n + 1) % value);
    }
}

updateKey() [1/4]

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

inline

Definition at line 295 of file fits.h.

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

updateKey() [2/4]

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

inline

Definition at line 290 of file fits.h.

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

updateKey() [3/4]

template<typename T>

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

Definition at line 659 of file fits.cc.

                                                         {
    updateKeyImpl(*this, key.c_str(), value, nullptr);
    if (behavior & AUTO_CHECK) {
        LSST_FITS_CHECK_STATUS(*this, boost::format("Updating key '%s': '%s'") % key % value);
    }
}

updateKey() [4/4]

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.

Definition at line 643 of file fits.cc.

                                                                                   {
    updateKeyImpl(*this, key.c_str(), value, comment.c_str());
    if (behavior & AUTO_CHECK) {
        LSST_FITS_CHECK_STATUS(*this, boost::format("Updating key '%s': '%s'") % key % value);
    }
}

writeColumnKey() [1/4]

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

inline

Definition at line 339 of file fits.h.

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

writeColumnKey() [2/4]

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

inline

Definition at line 334 of file fits.h.

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

writeColumnKey() [3/4]

template<typename T>

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

Definition at line 699 of file fits.cc.

                                                                        {
    writeKey((boost::format("%s%d") % prefix % (n + 1)).str(), value);
    if (behavior & AUTO_CHECK) {
        LSST_FITS_CHECK_STATUS(*this, boost::format("Writing key '%s%d': '%s'") % prefix % (n + 1) % value);
    }
}

writeColumnKey() [4/4]

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.

Definition at line 683 of file fits.cc.

                                                                                                  {
    writeKey((boost::format("%s%d") % prefix % (n + 1)).str(), value, comment);
    if (behavior & AUTO_CHECK) {
        LSST_FITS_CHECK_STATUS(*this, boost::format("Writing key '%s%d': '%s'") % prefix % (n + 1) % value);
    }
}

writeImage() [1/2]

template<typename T>

void lsst::afw::fits::Fits::writeImage	(	image::ImageBase< T > const &	image,
		CompressionOptions const *	compression = nullptr,
		daf::base::PropertySet const *	header = nullptr,
		image::Mask< image::MaskPixel > const *	mask = nullptr )

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]	compression	Options for compressing the image.
[in]	header	FITS header to write.
[in]	mask	Mask for image (used for statistics when scaling).

Definition at line 1564 of file fits.cc.

                                                              {
    // Context will restore the original settings when it is destroyed.
    CompressionContext context(*this, compression, image, mask);
    if (behavior & AUTO_CHECK) {
        LSST_FITS_CHECK_STATUS(*this, "Activating compression for write image");
    }
    // We need a place to put the image+header, and CFITSIO needs to know the
    // dimensions.
    ndarray::Vector<long, 2> dims(image.getArray().getShape().reverse());
    createImageImpl(cfitsio_bitpix<T>, 2, dims.elems);
    // Write the header
    std::shared_ptr<daf::base::PropertyList> wcsMetadata =
            geom::createTrivialWcsMetadata(image::detail::wcsNameForXY0, image.getXY0());
    std::shared_ptr<daf::base::PropertySet> fullMetadata;
    if (header) {
        fullMetadata = header->deepCopy();
        fullMetadata->combine(*wcsMetadata);
    } else {
        fullMetadata = wcsMetadata;
    }
    writeMetadata(*fullMetadata);
    std::optional<T> explicit_null = std::nullopt;
    if constexpr(std::is_floating_point_v<T>) {
        if (compression && compression->quantization) {
            explicit_null = -std::numeric_limits<T>::infinity();
        }
    }
    // Write the image itself.
    writeImageImpl(context.get_pixel_data<T>(), context.get_n_pixels(), explicit_null);
}

writeImage() [2/2]

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.

No compression or scaling is performed.

Definition at line 434 of file fits.h.

                                                              {
        writeImageImpl(makeContiguousArray(array).getData(), array.getNumElements());
    }

writeKey() [1/4]

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

inline

Definition at line 313 of file fits.h.

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

writeKey() [2/4]

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

inline

Definition at line 308 of file fits.h.

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

writeKey() [3/4]

template<typename T>

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

Definition at line 667 of file fits.cc.

                                                        {
    writeKeyImpl(*this, key.c_str(), value, nullptr);
    if (behavior & AUTO_CHECK) {
        LSST_FITS_CHECK_STATUS(*this, boost::format("Writing key '%s': '%s'") % key % value);
    }
}

writeKey() [4/4]

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

Definition at line 651 of file fits.cc.

                                                                                  {
    writeKeyImpl(*this, key.c_str(), value, comment.c_str());
    if (behavior & AUTO_CHECK) {
        LSST_FITS_CHECK_STATUS(*this, boost::format("Writing key '%s': '%s'") % key % value);
    }
}

writeMetadata()

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.

Definition at line 1086 of file fits.cc.

                                                           {
    using NameList = std::vector<std::string>;
    daf::base::PropertyList const *pl = dynamic_cast<daf::base::PropertyList const *>(&metadata);
    NameList paramNames;
    if (pl) {
        paramNames = pl->getOrderedNames();
    } else {
        paramNames = metadata.paramNames(false);
    }
    for (auto const &paramName : paramNames) {
        if (!isKeyIgnored(paramName, true)) {
            if (pl) {
                writeKeyFromProperty(*this, metadata, paramName, pl->getComment(paramName).c_str());
            } else {
                writeKeyFromProperty(*this, metadata, paramName);
            }
        }
    }
}

writeTableArray()

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.

Definition at line 1160 of file fits.cc.

                                                                                {
    fits_write_col(reinterpret_cast<fitsfile *>(fptr), FitsTableType<T>::CONSTANT, col + 1, row + 1, 1,
                   nElements, const_cast<T *>(value), &status);
    if (behavior & AUTO_CHECK) {
        LSST_FITS_CHECK_STATUS(*this, boost::format("Writing %d-element array at table cell (%d, %d)") %
                                              nElements % row % col);
    }
}

writeTableScalar() [1/2]

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

Write a string to a binary table.

Definition at line 1169 of file fits.cc.

                                                                          {
    // cfitsio doesn't let us specify the size of a string, it just looks for null terminator.
    // Using std::string::c_str() guarantees that we have one.  But we can't store arbitrary
    // data in a string field because cfitsio will also chop off anything after the first null
    // terminator.
    char const *tmp = value.c_str();
    fits_write_col(reinterpret_cast<fitsfile *>(fptr), TSTRING, col + 1, row + 1, 1, 1,
                   const_cast<char const **>(&tmp), &status);
    if (behavior & AUTO_CHECK) {
        LSST_FITS_CHECK_STATUS(*this, boost::format("Writing value at table cell (%d, %d)") % row % col);
    }
}

writeTableScalar() [2/2]

template<typename T>

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

inline

Write a scalar value to a binary table.

Definition at line 541 of file fits.h.

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

Member Data Documentation

behavior

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

Definition at line 601 of file fits.h.

fptr

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

Definition at line 599 of file fits.h.

status

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

Definition at line 600 of file fits.h.

---

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

• /j/snowflake/release/lsstsw/stack/lsst-scipipe-12.0.0/Linux/afw/g7ae74a0b1c+a25e60b391/include/lsst/afw/fits.h
• /j/snowflake/release/lsstsw/stack/lsst-scipipe-12.0.0/Linux/afw/g7ae74a0b1c+a25e60b391/src/fits.cc