lsst::afw::image::ImageFitsReader Class Reference

A FITS reader class for regular Images. More...

#include <ImageFitsReader.h>

Inheritance diagram for lsst::afw::image::ImageFitsReader:

Public Member Functions
template<typename PixelT >
Image< PixelT >	read (lsst::geom::Box2I const &bbox=lsst::geom::Box2I(), ImageOrigin origin=PARENT, bool allowUnsafe=false)
	Read the Image. More...
std::string	readDType () const
	Read a string describing the pixel type of the on-disk image. More...
lsst::geom::Box2I	readBBox (ImageOrigin origin=PARENT)
	Read the bounding box of the on-disk image. More...
lsst::geom::Point2I	readXY0 (lsst::geom::Box2I const &bbox=lsst::geom::Box2I(), ImageOrigin origin=PARENT)
	Read the image origin from the on-disk image or a subimage thereof. More...
std::shared_ptr< daf::base::PropertyList >	readMetadata ()
	Read the image's FITS header. More...
template<typename T >
ndarray::Array< T, 2, 2 >	readArray (lsst::geom::Box2I const &bbox, ImageOrigin origin=PARENT, bool allowUnsafe=false)
	Read the image's data array. More...
int	getHdu () const noexcept
	Return the HDU this reader targets. More...
std::string	getFileName () const
	Return the name of the file this reader targets. More...

Detailed Description

A FITS reader class for regular Images.

Exception Safety

All ImageFitsReader methods provide strong exception safety, but exceptions thrown by the internal fits::Fits object itself may change its status variable or HDU pointer; ImageFitsReader guards against this by resetting those before any use of the Fits object.

Definition at line 39 of file ImageFitsReader.h.

Member Function Documentation

getFileName()

std::string lsst::afw::image::ImageBaseFitsReader::getFileName ( ) const

inlineinherited

Return the name of the file this reader targets.

Definition at line 141 of file ImageBaseFitsReader.h.

{ return _fitsFile->getFileName(); }

getHdu()

int lsst::afw::image::ImageBaseFitsReader::getHdu ( ) const

inlinenoexceptinherited

Return the HDU this reader targets.

Definition at line 136 of file ImageBaseFitsReader.h.

{ return _hdu; }

read()

template<typename PixelT >

template Image< std::uint64_t > lsst::afw::image::ImageFitsReader::read	(	lsst::geom::Box2I const &	bbox = lsst::geom::Box2I(),
		ImageOrigin	origin = PARENT,
		bool	allowUnsafe = false
	)

Read the Image.

Parameters

bbox	A bounding box used to defined a subimage, or an empty box (default) to read the whole image.
origin	Coordinate system convention for the given box.
allowUnsafe	Permit reading into the requested pixel type even when on-disk values may overflow or truncate.

In Python, this templated method is wrapped with an additional dtype argument to provide the type to read. This defaults to the type of the on-disk image.

Definition at line 27 of file ImageFitsReader.cc.

                                                                                                    {
    return Image<PixelT>(readArray<PixelT>(bbox, origin, allowUnsafe), false, readXY0(bbox, origin));
}

readArray()

template<typename T >

template ndarray::Array< std::uint64_t, 2, 2 > lsst::afw::image::ImageBaseFitsReader::readArray ( lsst::geom::Box2I const &  bbox, ImageOrigin  origin = PARENT, bool  allowUnsafe = false  )

inherited

Read the image's data array.

Parameters

bbox	A bounding box used to defined a subimage, or an empty box (default) to read the whole image.
origin	Coordinate system convention for the given box.
allowUnsafe	Permit reading into the requested pixel type even when on-disk values may overflow or truncate.

Definition at line 171 of file ImageBaseFitsReader.cc.

                                                                         {
    checkFitsFile(_fitsFile);
    auto fullBBox = readBBox(origin);
    auto subBBox = bbox;
    if (subBBox.isEmpty()) {
        subBBox = fullBBox;
    } else if (!fullBBox.contains(subBBox)) {
        throw LSST_EXCEPT(
            pex::exceptions::LengthError,
            str(boost::format("Subimage box (%d,%d) %dx%d doesn't fit in image (%d,%d) %dx%d in HDU %d") %
                subBBox.getMinX() % subBBox.getMinY() % subBBox.getWidth() % subBBox.getHeight() %
                fullBBox.getMinX() % fullBBox.getMinY() % fullBBox.getWidth() % fullBBox.getHeight() % _hdu)
        );
    }
    fits::HduMoveGuard guard(*_fitsFile, _hdu);
    if (!allowUnsafe & !_fitsFile->checkImageType<T>()) {
        throw LSST_FITS_EXCEPT(
            fits::FitsTypeError, *_fitsFile,
            str(boost::format("Incompatible type for FITS image: on disk is %s (HDU %d), in-memory is %s. "
                              "Read with allowUnsafe=True to permit conversions that may overflow.") %
                _fitsFile->getImageDType() % _hdu % makeDTypeString<T>())
        );
    }
    ndarray::Array<T, 2, 2> result = ndarray::allocate(subBBox.getHeight(), subBBox.getWidth());
    ndarray::Vector<int, 2> offset = ndarray::makeVector(subBBox.getMinY() - fullBBox.getMinY(),
                                                         subBBox.getMinX() - fullBBox.getMinX());
    _fitsFile->readImage(result, offset);
    return result;
}

readBBox()

lsst::geom::Box2I lsst::afw::image::ImageBaseFitsReader::readBBox ( ImageOrigin  origin = PARENT )

inherited

Read the bounding box of the on-disk image.

Parameters

origin

Coordinate system convention for the returned box. If LOCAL, the returned box will always have a minimum of (0, 0).

Definition at line 86 of file ImageBaseFitsReader.cc.

                                                              {
    readMetadata();  // guarantees _bbox is initialized
    if (origin == LOCAL) {
        return lsst::geom::Box2I(lsst::geom::Point2I(), _bbox.getDimensions());
    }
    return _bbox;
}

readDType()

std::string lsst::afw::image::ImageBaseFitsReader::readDType ( ) const

inherited

Read a string describing the pixel type of the on-disk image.

Returns

A string of the form [u](int|float)<bits> (e.g. "uint16", "float64").

Definition at line 80 of file ImageBaseFitsReader.cc.

                                               {
    checkFitsFile(_fitsFile);
    fits::HduMoveGuard guard(*_fitsFile, _hdu);
    return _fitsFile->getImageDType();
}

readMetadata()

std::shared_ptr< daf::base::PropertyList > lsst::afw::image::ImageBaseFitsReader::readMetadata ( )

inherited

Read the image's FITS header.

Definition at line 105 of file ImageBaseFitsReader.cc.

                                                                     {
    checkFitsFile(_fitsFile);
    if (_metadata == nullptr) {
        fits::HduMoveGuard guard(*_fitsFile, _hdu);
        auto metadata = fits::readMetadata(*_fitsFile, /*strip=*/true);
        // One-use lambda avoids declare-then-initialize; see C++ Core Guidelines, ES28.
        auto computeShape = [this](){
            int nAxis = _fitsFile->getImageDim();
            if (nAxis == 2) {
                return _fitsFile->getImageShape<2>();
            }
            if (nAxis == 3) {
                ndarray::Vector<ndarray::Size, 3> shape3 = _fitsFile->getImageShape<3>();
                if (shape3[0] != 1) {
                    throw LSST_EXCEPT(
                        fits::FitsError,
                        str(boost::format("Error reading %s: HDU %d has 3rd dimension %d != 1") %
                            getFileName() % _hdu % shape3[0]));
                }
                return shape3.last<2>();
            }
            throw LSST_EXCEPT(
                fits::FitsError,
                str(boost::format("Error reading %s: HDU %d has %d dimensions") %
                    getFileName() % _hdu % nAxis)
            );
        };
        // Construct _bbox and check dimensions at the same time both to make
        // one less valid state for this class to be in and to make sure
        // the appropriate metadata is stripped before we ever return it.
        ndarray::Vector<ndarray::Size, 2> shape = computeShape();
        auto xy0 = afw::geom::getImageXY0FromMetadata(*metadata, detail::wcsNameForXY0, /*strip=*/true);
        _bbox = lsst::geom::Box2I(xy0, lsst::geom::Extent2I(shape[1], shape[0]));
        _metadata = std::move(metadata);
    }
    return _metadata;
}

readXY0()

lsst::geom::Point2I lsst::afw::image::ImageBaseFitsReader::readXY0 ( lsst::geom::Box2I const &  bbox = lsst::geom::Box2I(), ImageOrigin  origin = PARENT  )

inherited

Read the image origin from the on-disk image or a subimage thereof.

Parameters

bbox	A bounding box used to defined a subimage, or an empty box (default) to use the whole image.
origin	Coordinate system convention for the given box. Ignored if bbox is empty.

Definition at line 94 of file ImageBaseFitsReader.cc.

                                                                                           {
    if (bbox.isEmpty()) {
        return readBBox().getMin();
    } else if (origin == PARENT) {
        return bbox.getMin();
    } else {
        auto full = readBBox();
        return full.getMin() + lsst::geom::Extent2I(bbox.getMin());
    }
}

---

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

• /j/snowflake/release/lsstsw/stack/Linux64/afw/19.0.0-4-ga671dab3b+1/include/lsst/afw/image/ImageFitsReader.h
• /j/snowflake/release/lsstsw/stack/Linux64/afw/19.0.0-4-ga671dab3b+1/src/image/ImageFitsReader.cc