Template Class Exposure

Class Documentation

template<typename ImageT, typename MaskT = lsst::afw::image::MaskPixel, typename VarianceT = lsst::afw::image::VariancePixel>
class Exposure

A class to contain the data, WCS, and other information needed to describe an image of the sky. Exposure Class Implementation for LSST: a templated framework class for creating an Exposure from a MaskedImage and a Wcs.

An Exposure is required to take one afwImage::MaskedImage or a region (col, row) defining the size of a MaskedImage (this can be of size 0,0). An Exposure can (but is not required to) contain an afwImage::SkyWcs.

The template types should optimally be a float, double, unsigned int 16 bit, or unsigned int 32 bit for the image (pixel) type and an unsigned int 32 bit for the mask type. These types have been explicitly instantiated for the Exposure class. All MaskedImage and Wcs constructors are ‘const’ to allow for views and copying.

An Exposure can get and return its MaskedImage, SkyWcs, and a subExposure. The getSubExposure member takes a BBox region defining the subRegion of the original Exposure to be returned. The member retrieves the MaskedImage corresponding to the subRegion. The MaskedImage class throws an exception for any subRegion extending beyond the original MaskedImage bounding box. This member is not yet fully implemented because it requires the SkyWcs class to return the SkyWcs metadata to the member so the CRPIX values of the SkyWcs can be adjusted to reflect the new subMaskedImage origin. The getSubExposure member will eventually return a subExposure consisting of the subMAskedImage and the SkyWcs object with its corresponding adjusted metadata.

The hasWcs member is used to determine if the Exposure has a SkyWcs. It is not required to have one.

Public Types

typedef MaskedImage<ImageT, MaskT, VarianceT> MaskedImageT

Public Functions

Exposure(unsigned int width, unsigned int height, std::shared_ptr<geom::SkyWcs const> wcs = std::shared_ptr<geom::SkyWcs const>())

Construct an Exposure with a blank MaskedImage of specified size (default 0x0) and a SkyWcs (which may be default constructed)

Parameters

  • width: number of columns

  • height: number of rows

  • wcs: the SkyWcs

Exposure(lsst::geom::Extent2I const &dimensions = lsst::geom::Extent2I(), std::shared_ptr<geom::SkyWcs const> wcs = std::shared_ptr<geom::SkyWcs const>())

Construct an Exposure with a blank MaskedImage of specified size (default 0x0) and a SkyWcs (which may be default constructed)

Parameters

  • dimensions: desired image width/height

  • wcs: the SkyWcs

Exposure(lsst::geom::Box2I const &bbox, std::shared_ptr<geom::SkyWcs const> wcs = std::shared_ptr<geom::SkyWcs const>())

Construct an Exposure with a blank MaskedImage of specified size (default 0x0) and a SkyWcs.

Parameters

  • bbox: desired image width/height, and origin

  • wcs: the SkyWcs

Exposure(MaskedImageT &maskedImage, std::shared_ptr<geom::SkyWcs const> wcs = std::shared_ptr<geom::SkyWcs const>())

Construct an Exposure from a MaskedImage and an optional SkyWcs

Parameters

Exposure(MaskedImageT &maskedImage, std::shared_ptr<ExposureInfo> info)

Construct an Exposure from a MaskedImage and an ExposureInfo

If the ExposureInfo is an empty pointer then a new empty ExposureInfo is used

Parameters

Exposure(std::string const &fileName, lsst::geom::Box2I const &bbox = lsst::geom::Box2I(), ImageOrigin origin = PARENT, bool conformMasks = false, bool allowUnsafe = false)

Construct an Exposure by reading a regular FITS file.

Parameters

  • [in] fileName: File to read.

  • [in] bbox: If non-empty, read only the pixels within the bounding box.

  • [in] origin: Coordinate system of the bounding box; if PARENT, the bounding box should take into account the xy0 saved with the image.

  • [in] conformMasks: If true, make Mask conform to the mask layout in the file.

  • [in] allowUnsafe: Permit reading into the requested pixel type even when on-disk values may overflow or truncate.

Exposure(fits::MemFileManager &manager, lsst::geom::Box2I const &bbox = lsst::geom::Box2I(), ImageOrigin origin = PARENT, bool conformMasks = false, bool allowUnsafe = false)

Construct an Exposure by reading a FITS image in memory.

Parameters

  • [in] manager: An object that manages the memory buffer to read.

  • [in] bbox: If non-empty, read only the pixels within the bounding box.

  • [in] origin: Coordinate system of the bounding box; if PARENT, the bounding box should take into account the xy0 saved with the image.

  • [in] conformMasks: If true, make Mask conform to the mask layout in the file.

  • [in] allowUnsafe: Permit reading into the requested pixel type even when on-disk values may overflow or truncate.

Exposure(fits::Fits &fitsfile, lsst::geom::Box2I const &bbox = lsst::geom::Box2I(), ImageOrigin origin = PARENT, bool conformMasks = false, bool allowUnsafe = false)

Construct an Exposure from an already-open FITS object.

Parameters

  • [in] fitsfile: A FITS object to read from. Current HDU is ignored.

  • [in] bbox: If non-empty, read only the pixels within the bounding box.

  • [in] origin: Coordinate system of the bounding box; if PARENT, the bounding box should take into account the xy0 saved with the image.

  • [in] conformMasks: If true, make Mask conform to the mask layout in the file.

  • [in] allowUnsafe: Permit reading into the requested pixel type even when on-disk values may overflow or truncate.

Exposure(Exposure const &src, bool const deep = false)

Copy an Exposure

Parameters

  • src: Parent Exposure

  • deep: Should we copy the pixels?

Exposure(Exposure &&src)
Exposure(Exposure const &src, lsst::geom::Box2I const &bbox, ImageOrigin const origin = PARENT, bool const deep = false)

Construct a subExposure given an Exposure and a bounding box

Parameters

  • src: Parent Exposure

  • bbox: Desired region in Exposure

  • origin: Coordinate system for bbox

  • deep: Should we copy the pixels?

Exceptions

  • lsst::pex::exceptions::InvalidParameterError: if the requested subRegion is not fully contained by the original MaskedImage BBox.

template<typename OtherPixelT>
Exposure(Exposure<OtherPixelT, MaskT, VarianceT> const &rhs, const bool deep)

Parameters

  • rhs: Input Exposure

  • deep: Must be true; needed to disambiguate

generalised copy constructor; defined here in the header so that the compiler can instantiate N(N-1)/2 conversions between N ImageBase types.

We only support converting the Image part

Exposure &operator=(Exposure const&)
Exposure &operator=(Exposure&&)
Exposure subset(lsst::geom::Box2I const &bbox, ImageOrigin origin = PARENT) const

Return a subimage corresponding to the given box.

This method is wrapped as

getitem in Python.
Return

A subimage view into this.

Parameters

  • bbox: Bounding box of the subimage returned.

  • origin: Origin bbox is rleative to; PARENT accounts for xy0, LOCAL does not.

Note

This method permits mutable views to be obtained from const references to images (just as the copy constructor does). This is an intrinsic flaw in Image’s design.

Exposure operator[](lsst::geom::Box2I const &bbox) const

Return a subimage corresponding to the given box (interpreted as PARENT coordinates).

virtual ~Exposure()

Destructor

MaskedImageT getMaskedImage()

Return the MaskedImage.

MaskedImageT getMaskedImage() const

Return the MaskedImage.

std::shared_ptr<geom::SkyWcs const> getWcs() const
std::shared_ptr<lsst::afw::cameraGeom::Detector const> getDetector() const

Return the Exposure’s Detector information.

Filter getFilter() const

Return the Exposure’s filter.

std::shared_ptr<lsst::daf::base::PropertySet> getMetadata() const

Return flexible metadata.

void setMetadata(std::shared_ptr<lsst::daf::base::PropertySet> metadata)
int getWidth() const

Return the Exposure’s width.

int getHeight() const

Return the Exposure’s height.

lsst::geom::Extent2I getDimensions() const

Return the Exposure’s size.

int getX0() const

Return the Exposure’s column-origin

See

getXY0()

int getY0() const

Return the Exposure’s row-origin

See

getXY0()

lsst::geom::Point2I getXY0() const

Return the Exposure’s origin

This will usually be (0, 0) except for images created using the Exposure(fileName, hdu, BBox, mode) ctor or Exposure(Exposure, BBox) cctor The origin can be reset with setXY0

lsst::geom::Box2I getBBox(ImageOrigin const origin = PARENT) const
void setXY0(lsst::geom::Point2I const &origin)

Set the Exposure’s origin (including correcting the Wcs)

The origin is usually set by the constructor, so you shouldn’t need this function

Note

There are use cases (e.g. memory overlays) that may want to set these values, but don’t do so unless you are an Expert.

void setMaskedImage(MaskedImageT &maskedImage)

Set the MaskedImage of the Exposure.

void setWcs(std::shared_ptr<geom::SkyWcs> wcs)
void setDetector(std::shared_ptr<lsst::afw::cameraGeom::Detector const> detector)

Set the Exposure’s Detector information.

void setFilter(Filter const &filter)

Set the Exposure’s filter.

void setPhotoCalib(std::shared_ptr<PhotoCalib const> photoCalib)

Set the Exposure’s PhotoCalib object.

std::shared_ptr<PhotoCalib const> getPhotoCalib() const

Return the Exposure’s PhotoCalib object.

void setPsf(std::shared_ptr<lsst::afw::detection::Psf const> psf)

Set the Exposure’s Psf.

std::shared_ptr<lsst::afw::detection::Psf const> getPsf() const

Return the Exposure’s Psf object.

bool hasPsf() const

Does this Exposure have a Psf?

bool hasWcs() const

Does this Exposure have a Wcs?

std::shared_ptr<ExposureInfo> getInfo()

Get the ExposureInfo that aggregates all the non-image components. Never null.

std::shared_ptr<ExposureInfo const> getInfo() const

Get the ExposureInfo that aggregates all the non-image components. Never null.

void setInfo(std::shared_ptr<ExposureInfo> exposureInfo)

Set the ExposureInfo that aggregates all the non-image components.

void writeFits(std::string const &fileName) const

Write an Exposure to a regular multi-extension FITS file.

As with

MaskedImage persistence, an empty primary HDU will be created and all images planes will be saved to extension HDUs. Most metadata will be saved only to the header of the main image HDU, but the WCS will be saved to the header of the mask and variance as well. If present, the Psf will be written to one or more additional HDUs.
Parameters

  • [in] fileName: Name of the file to write.

Note that the LSST pixel origin differs from the FITS convention by one, so the values of CRPIX and LTV saved in the file are not the same as those in the C++ objects in memory, but are rather modified so they are interpreted by external tools (like ds9).

void writeFits(fits::MemFileManager &manager) const

Write an Exposure to a multi-extension FITS file in memory.

See

writeFits

Parameters

  • [in] manager: Manager for the memory to write to.

void writeFits(fits::Fits &fitsfile) const

Write an Exposure to an already-open FITS file object.

See

writeFits

Parameters

  • [in] fitsfile: FITS object to write.

void writeFits(std::string const &fileName, fits::ImageWriteOptions const &imageOptions, fits::ImageWriteOptions const &maskOptions, fits::ImageWriteOptions const &varianceOptions) const

Write an Exposure to a regular multi-extension FITS file.

Parameters

  • [in] fileName: Name of the file to write.

  • [in] imageOptions: Options controlling writing of image as FITS.

  • [in] maskOptions: Options controlling writing of mask as FITS.

  • [in] varianceOptions: Options controlling writing of variance as FITS.

void writeFits(fits::MemFileManager &manager, fits::ImageWriteOptions const &imageOptions, fits::ImageWriteOptions const &maskOptions, fits::ImageWriteOptions const &varianceOptions) const

Write an Exposure to a regular multi-extension FITS file.

Parameters

  • [in] manager: Manager for the memory to write to.

  • [in] imageOptions: Options controlling writing of image as FITS.

  • [in] maskOptions: Options controlling writing of mask as FITS.

  • [in] varianceOptions: Options controlling writing of variance as FITS.

void writeFits(fits::Fits &fitsfile, fits::ImageWriteOptions const &imageOptions, fits::ImageWriteOptions const &maskOptions, fits::ImageWriteOptions const &varianceOptions) const

Write an Exposure to a regular multi-extension FITS file.

Parameters

  • [in] fitsfile: FITS object to which to write.

  • [in] imageOptions: Options controlling writing of image as FITS.

  • [in] maskOptions: Options controlling writing of mask as FITS.

  • [in] varianceOptions: Options controlling writing of variance as FITS.

Exposure getCutout(lsst::geom::SpherePoint const &center, lsst::geom::Extent2I const &size) const

Return an Exposure that is a small cutout of the original.

Return

An Exposure of the requested size centered on center to within half a pixel in either dimension. Pixels past the edge of the original exposure will equal math::edgePixel<MaskedImageT>.

Parameters

  • center: desired center of cutout (in RA and Dec)

  • size: width and height (in that order) of cutout in pixels

Exceptions

  • lsst::pex::exceptions::LogicError: Thrown if this Exposure does not have a WCS.

  • lsst::pex::exceptions::InvalidParameterError: Thrown if center falls outside this Exposure or if size is not a valid size.

Public Static Functions

static Exposure readFits(std::string const &filename)

Read an Exposure from a regular FITS file.

Parameters

  • [in] filename: Name of the file to read.

static Exposure readFits(fits::MemFileManager &manager)

Read an Exposure from a FITS RAM file.

Parameters

  • [in] manager: Object that manages the memory to be read.