lsst::afw::fits Namespace Reference

Namespaces
namespace	_fitsContinued
namespace	_pickleFits
namespace	detail

Classes
struct	CompressionOptions
	Options controlling image compression with FITS. More...
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. More...
class	FitsError
	An exception thrown when problems are found when reading or writing FITS files. More...
class	FitsTypeError
	An exception thrown when a FITS file has the wrong type. More...
class	HduMoveGuard
	RAII scoped guard for moving the HDU in a Fits object. More...
class	HeaderIterationFunctor
	Base class for polymorphic functors used to iterator over FITS key headers. More...
class	MemFileManager
	Lifetime-management for memory that goes into FITS memory files. More...
struct	QuantizationOptions
	Options controlling quantization for image compression with FITS. More...

Typedefs
using	dafPlistPtr = std::shared_ptr<daf::base::PropertyList>

Enumerations
enum class	HduType : int { IMAGE = 0 , ASCII_TABLE = 1 , BIN_TABLE = 2 , ANY = -1 }
	an enum representing the various types of FITS HDU that are available in cfitsio library More...
enum class	CompressionAlgorithm { GZIP_1_ , GZIP_2_ , RICE_1_ }
	FITS compression algorithms. More...
enum class	DitherAlgorithm { NO_DITHER_ , SUBTRACTIVE_DITHER_1_ , SUBTRACTIVE_DITHER_2_ }
	FITS quantization algorithms. More...
enum class	ScalingAlgorithm { RANGE , STDEV_MASKED , STDEV_CFITSIO , MANUAL }
	Algorithms used to compute the scaling factor used in quantization. More...

Functions
std::string	makeErrorMessage (std::string const &fileName="", int status=0, std::string const &msg="")
	Return an error message reflecting FITS I/O errors.
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.
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.
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.
std::shared_ptr< daf::base::PropertyList >	combineMetadata (daf::base::PropertyList const &first, daf::base::PropertyList const &second)
	Combine two sets of metadata in a FITS-appropriate fashion.
std::shared_ptr< daf::base::PropertyList >	readMetadata (std::string const &fileName, int hdu=DEFAULT_HDU, bool strip=false)
	Read FITS header.
std::shared_ptr< daf::base::PropertyList >	readMetadata (std::string const &fileName, std::string const &hduname, HduType type=HduType::ANY, int hduver=0, bool strip=false)
	Read FITS header.
std::shared_ptr< daf::base::PropertyList >	readMetadata (fits::MemFileManager &manager, int hdu=DEFAULT_HDU, bool strip=false)
	Read FITS header.
std::shared_ptr< daf::base::PropertyList >	readMetadata (fits::MemFileManager &manager, std::string const &hduname, HduType type=HduType::ANY, int hduver=0, bool strip=false)
	Read FITS header.
std::shared_ptr< daf::base::PropertyList >	readMetadata (fits::Fits &fitsfile, bool strip=false)
	Read FITS header.
	PYBIND11_MODULE (_fits, mod)

Variables
const int	DEFAULT_HDU = INT_MIN
	Specify that the default HDU should be read.

Typedef Documentation

dafPlistPtr

using lsst::afw::fits::dafPlistPtr = std::shared_ptr<daf::base::PropertyList>

Definition at line 1825 of file fits.cc.

Enumeration Type Documentation

CompressionAlgorithm

enum class lsst::afw::fits::CompressionAlgorithm

strong

FITS compression algorithms.

See the standard for details.

These have a trailing underscore to avoid conflict with CFITSIO's preprocessor macros (the trailing underscore is dropped in the Python bindings). Not all FITS compression algorithms are supported.

Enumerator
GZIP_1_
GZIP_2_
RICE_1_

Definition at line 28 of file fitsCompression.h.

                                {
    GZIP_1_,
    GZIP_2_,
    RICE_1_
};

DitherAlgorithm

enum class lsst::afw::fits::DitherAlgorithm

strong

FITS quantization algorithms.

See the standard for details.

These have a trailing underscore to avoid conflict with CFITSIO's preprocessor macros (the trailing underscore is dropped in the Python bindings).

Enumerator
NO_DITHER_
SUBTRACTIVE_DITHER_1_
SUBTRACTIVE_DITHER_2_

Definition at line 41 of file fitsCompression.h.

                           {
    NO_DITHER_,
    SUBTRACTIVE_DITHER_1_,
    SUBTRACTIVE_DITHER_2_,
};

HduType

enum class lsst::afw::fits::HduType : int

strong

an enum representing the various types of FITS HDU that are available in cfitsio library

This is an int because the value it maps to in cfitsio is also an int.

Enumerator
IMAGE
ASCII_TABLE
BIN_TABLE
ANY

Definition at line 224 of file fits.h.

: int { IMAGE = 0, ASCII_TABLE = 1, BIN_TABLE = 2, ANY = -1 };

ScalingAlgorithm

enum class lsst::afw::fits::ScalingAlgorithm

strong

Algorithms used to compute the scaling factor used in quantization.

Enumerator
RANGE	Scale to preserve dynamic range with bad pixels msasked out.
STDEV_MASKED	Scale based on the standard deviation with bad pixels masked out.
STDEV_CFITSIO	Let CFITSIO work out the scaling (per-tile; does not respect mask planes)
MANUAL	Scale set manually.

Definition at line 48 of file fitsCompression.h.

                            {
    RANGE,           
    STDEV_MASKED,    
    STDEV_CFITSIO,   
    MANUAL,          
};

Function Documentation

combineMetadata()

std::shared_ptr< daf::base::PropertyList > lsst::afw::fits::combineMetadata	(	daf::base::PropertyList const &	first,
		daf::base::PropertyList const &	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

Parameters

[in]	first	The first set of metadata to combine
[in]	second	The second set of metadata to combine

Returns

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

Definition at line 1796 of file fits.cc.

                                            {
    auto combined = std::make_shared<daf::base::PropertyList>();
    bool const asScalar = true;
    for (auto const &name : first.getOrderedNames()) {
        auto const iscv = isCommentIsValid(first, name);
        if (iscv.isComment) {
            if (iscv.isValid) {
                combined->add<std::string>(name, first.getArray<std::string>(name));
            }
        } else {
            combined->copy(name, first, name, asScalar);
        }
    }
    for (auto const &name : second.getOrderedNames()) {
        auto const iscv = isCommentIsValid(second, name);
        if (iscv.isComment) {
            if (iscv.isValid) {
                combined->add<std::string>(name, second.getArray<std::string>(name));
            }
        } else {
            // `copy` will replace an item, even if has a different type, so no need to call `remove`
            combined->copy(name, second, name, asScalar);
        }
    }
    return combined;
}

getBitPix()

template<typename T>

int lsst::afw::fits::getBitPix

(

)

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

Definition at line 466 of file fits.cc.

                {
    return cfitsio_bitpix<T>;
}

makeContiguousArray()

template<typename T, int N, int C>

ndarray::Array< T const, N, N > const lsst::afw::fits::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.

Definition at line 213 of file fits.h.

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

makeErrorMessage() [1/4]

std::string lsst::afw::fits::makeErrorMessage ( std::string const & fileName, int status, boost::format const & msg )

inline

Definition at line 66 of file fits.h.

                                                                                                 {
    return makeErrorMessage(fileName, status, msg.str());
}

makeErrorMessage() [2/4]

std::string lsst::afw::fits::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.

Definition at line 396 of file fits.cc.

                                                                                        {
    std::ostringstream os;
    os << "cfitsio error";
    if (fileName != "") {
        os << " (" << fileName << ")";
    }
    if (status != 0) {
        char fitsErrMsg[FLEN_ERRMSG];
        fits_get_errstatus(status, fitsErrMsg);
        os << ": " << fitsErrMsg << " (" << status << ")";
    }
    if (msg != "") {
        os << " : " << msg;
    }
    os << "\ncfitsio error stack:\n";
    char cfitsioMsg[FLEN_ERRMSG];
    // fits_read_errmsg can return a junk string with non printable characters
    // creating problem with python exception bindings
    while (fits_read_errmsg(cfitsioMsg) != 0) {
        cfitsioMsg[FLEN_ERRMSG-1] = char(0); // ensure termination
        std::size_t len=strlen(cfitsioMsg);
        for(std::size_t i = 0; i < len; i++)
            if( !isprint(cfitsioMsg[i]) ) cfitsioMsg[i] = '.';
        os << "  " << cfitsioMsg << "\n";
    }
    return os.str();
}

makeErrorMessage() [3/4]

std::string lsst::afw::fits::makeErrorMessage ( void * fptr, int status, boost::format const & msg )

inline

Definition at line 80 of file fits.h.

                                                                                  {
    return makeErrorMessage(fptr, status, msg.str());
}

makeErrorMessage() [4/4]

std::string lsst::afw::fits::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.

Definition at line 424 of file fits.cc.

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

makeLimitedFitsHeader()

std::string lsst::afw::fits::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.

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

Returns

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

Definition at line 433 of file fits.cc.

                                                                         {
    daf::base::PropertyList const *pl = dynamic_cast<daf::base::PropertyList const *>(&metadata);
    std::vector<std::string> allParamNames;
    if (pl) {
        allParamNames = pl->getOrderedNames();
    } else {
        allParamNames = metadata.paramNames(false);
    }
    std::vector<std::string> desiredParamNames;
    for (auto const &name : allParamNames) {
        if (excludeNames.count(name) == 0) {
            desiredParamNames.push_back(name);
        }
    }
    return makeLimitedFitsHeaderImpl(desiredParamNames, metadata);
}

PYBIND11_MODULE()

lsst::afw::fits::PYBIND11_MODULE	(	_fits	,
		mod	)

Definition at line 195 of file _fits.cc.

                            {
    lsst::cpputils::python::WrapperCollection wrappers(mod, "lsst.afw.fits");
    wrappers.addInheritanceDependency("lsst.pex.exceptions");
    wrappers.addSignatureDependency("lsst.daf.base");
    // FIXME: after afw.image pybind wrappers are converted
    //wrappers.addSignatureDependency("lsst.afw.image");
    auto cls = wrappers.wrapException<FitsError, lsst::pex::exceptions::IoError>("FitsError", "IoError");
    cls.def(py::init<std::string const &>());
    declareCompression(wrappers);
    declareFits(wrappers);
    declareFitsModule(wrappers);
    wrappers.finish();
}

readMetadata() [1/5]

std::shared_ptr< daf::base::PropertyList > lsst::afw::fits::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.

Definition at line 1855 of file fits.cc.

                                                                                {
    auto metadata = std::make_shared<lsst::daf::base::PropertyList>();
    fitsfile.readMetadata(*metadata, strip);
    // if INHERIT=T, we want to also include header entries from the primary HDU
    int oldHdu = fitsfile.getHdu();
    if (oldHdu != 0 && metadata->exists("INHERIT")) {
        bool inherit = false;
        if (metadata->typeOf("INHERIT") == typeid(std::nullptr_t)) {
            // Assume false if INHERIT exists but is undefined.
            inherit = false;
        } else if (metadata->typeOf("INHERIT") == typeid(std::string)) {
            inherit = (metadata->get<std::string>("INHERIT") == "T");
        } else {
            inherit = metadata->get<bool>("INHERIT");
        }
        if (strip) metadata->remove("INHERIT");
        if (inherit) {
            HduMoveGuard guard(fitsfile, 0);
            // Combine the metadata from the primary HDU with the metadata from the specified HDU,
            // with non-comment values from the specified HDU superseding those in the primary HDU
            // and comments from the specified HDU appended to comments from the primary HDU
            auto primaryHduMetadata = std::make_shared<daf::base::PropertyList>();
            fitsfile.readMetadata(*primaryHduMetadata, strip);
            metadata = combineMetadata(*primaryHduMetadata, *metadata);
        } else {
            // Purge invalid values
            auto const emptyMetadata = std::make_shared<lsst::daf::base::PropertyList>();
            metadata = combineMetadata(*metadata, *emptyMetadata);
        }
    }
    return metadata;
}

readMetadata() [2/5]

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

Definition at line 1846 of file fits.cc.

                                                                           {
    return detail::_readMetadata(manager, strip, hdu);
}

readMetadata() [3/5]

dafPlistPtr lsst::afw::fits::readMetadata	(	fits::MemFileManager &	manager,
		std::string const &	hduname,
		HduType	type = HduType::ANY,
		int	hduver = 0,
		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
hduname	the name of the HDU to read
type	type of FITS header to match. Defaults to ANY_HDU
hduver	version of HDU header to match, defaults to 0 (version ignored)
strip	if true, common FITS keys that usually have non-metadata intepretations (e.g. NAXIS, BITPIX) will be ignored.

Definition at line 1850 of file fits.cc.

                                     {
    return detail::_readMetadata(manager, strip, hduname, type, hduver);
}

readMetadata() [4/5]

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

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.

Definition at line 1837 of file fits.cc.

                                                                         {
    return detail::_readMetadata(fileName, strip, hdu);
}

readMetadata() [5/5]

dafPlistPtr lsst::afw::fits::readMetadata	(	std::string const &	fileName,
		std::string const &	hduname,
		HduType	type = HduType::ANY,
		int	hduver = 0,
		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

fileName	the file whose header will be read
hduname	the name of the HDU to read
type	type of FITS header to match. Defaults to ANY_HDU
hduver	version of HDU header to match, defaults to 0 (version ignored)
strip	if true, common FITS keys that usually have non-metadata intepretations (e.g. NAXIS, BITPIX) will be ignored.

Definition at line 1841 of file fits.cc.

                                     {
    return detail::_readMetadata(fileName, strip, hduname, type, hduver);
}

Variable Documentation

DEFAULT_HDU

const int lsst::afw::fits::DEFAULT_HDU = INT_MIN

Specify that the default HDU should be read.

This special HDU number indicates that the first extension should be used if the primary HDU is empty (i.e., has NAXIS=0) and the Primary HDU is the current.

Definition at line 18 of file fitsDefaults.h.