File warpExposure.h

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 math

Functions

std::shared_ptr<SeparableKernel> makeWarpingKernel(std::string name)

Return a warping kernel given its name.

Intended for use with warpImage() and warpExposure().

Allowed names are:

A warping kernel is a subclass of SeparableKernel with the following properties (though for the sake of speed few, if any, of these are enforced):

  • Width and height are even. This is unusual for a kernel, but it is more efficient because if the extra pixel was included it would always have value 0.

  • The center pixels should be adjacent to the kernel center. Again, this avoids extra pixels that are sure to have value 0.

  • It has two parameters: fractional x and fractional row position on the source image. The fractional position is the offset of the pixel position on the source from the center of a nearby source pixel:

    • The pixel whose center is just below or to the left of the source position: 0 <= fractional x and y < 0 and the kernel center is the default (size-1)/2.

    • The pixel whose center is just above or to the right of the source position: -1.0 < fractional x and y <= 0 and the kernel center must be set to (size+1)/2.

template<typename DestExposureT, typename SrcExposureT>
int warpExposure(DestExposureT &destExposure, SrcExposureT const &srcExposure, WarpingControl const &control, typename DestExposureT::MaskedImageT::SinglePixel padValue = lsst::afw::math::edgePixel<typename DestExposureT::MaskedImageT>(typename lsst::afw::image::detail::image_traits<typename DestExposureT::MaskedImageT>::image_category()))

Parameters

  • destExposure: Remapped exposure. Wcs and xy0 are read, MaskedImage is set, and PhotoCalib, Filter and VisitInfo are copied from srcExposure. All other attributes are left alone (including Detector and Psf)

  • srcExposure: Source exposure

  • control: control parameters

  • padValue: use this value for undefined (edge) pixels

Warp (remap) one exposure to another.

This is a convenience wrapper around warpImage().

template<typename DestImageT, typename SrcImageT>
int warpImage(DestImageT &destImage, geom::SkyWcs const &destWcs, SrcImageT const &srcImage, geom::SkyWcs const &srcWcs, WarpingControl const &control, typename DestImageT::SinglePixel padValue = lsst::afw::math::edgePixel<DestImageT>(typename lsst::afw::image::detail::image_traits<DestImageT>::image_category()))

Warp an Image or MaskedImage to a new Wcs. See also convenience function warpExposure() to warp an Exposure.

Parameters

  • destImage: remapped image

  • destWcs: WCS of remapped image

  • srcImage: source image

  • srcWcs: WCS of source image

  • control: control parameters

  • padValue: use this value for undefined (edge) pixels

Edge pixels are set to padValue; these are pixels that cannot be computed because they are too near the edge of srcImage or miss srcImage entirely.

Algorithm Without Interpolation:

Return

the number of valid pixels in destImage (those that are not edge pixels).

For each integer pixel position in the remapped Exposure:

  • The associated pixel position on srcImage is determined using the destination and source WCS

  • The warping kernel’s parameters are set based on the fractional part of the pixel position on srcImage

  • The warping kernel is applied to srcImage at the integer portion of the pixel position to compute the remapped pixel value

  • A flux-conservation factor is determined from the source and destination WCS and is applied to the remapped pixel

The scaling of intensity for relative area of source and destination uses two minor approximations:

  • The area of the sky marked out by a pixel on the destination image corresponds to a parallellogram on the source image.

  • The area varies slowly enough across the image that we can get away with computing the source area shifted by half a pixel up and to the left of the true area.

Algorithm With Interpolation:

Interpolation simply reduces the number of times WCS is used to map between destination and source pixel position. This computation is only made at a grid of points on the destination image, separated by interpLen pixels along rows and columns. All other source pixel positions are determined by linear interpolation between those grid points. Everything else remains the same.

Exceptions

  • lsst::pex::exceptions::InvalidParameterError: if destImage overlaps srcImage

  • std::bad_alloc: when allocation of CPU memory fails

Warning

The code that tests for image overlap is not guranteed to work correctly, based on the C++ standard. It is, in theory, possible for the code to report a “false positive”, meaning that it may claim that images overlap when they do not. We don’t believe that any of our current compilers have this problem. If, in the future, this becomes a problem then we will probably have to remove the test and rely on users being careful.

template<typename DestImageT, typename SrcImageT>
int warpImage(DestImageT &destImage, SrcImageT const &srcImage, geom::TransformPoint2ToPoint2 const &srcToDest, WarpingControl const &control, typename DestImageT::SinglePixel padValue = lsst::afw::math::edgePixel<DestImageT>(typename lsst::afw::image::detail::image_traits<DestImageT>::image_category()))

A variant of warpImage that uses a Transform<Point2Endpoint, Point2Endpoint> instead of a pair of WCS to describe the transformation.

Return

the number of good pixels

Parameters

  • [inout] destImage: Destination image; all pixels are set

  • [in] srcImage: Source image

  • [in] srcToDest: Transformation from source to destination pixels, in parent coordinates; the inverse must be defined (and is the only direction used). makeWcsPairTransform(srcWcs, destWcs) is one way to compute this transform.

  • [in] control: Warning control parameters

  • [in] padValue: Value used for pixels in the destination image that are outside the region of pixels that can be computed from the source image

template<typename DestImageT, typename SrcImageT>
int warpCenteredImage(DestImageT &destImage, SrcImageT const &srcImage, lsst::geom::LinearTransform const &linearTransform, lsst::geom::Point2D const &centerPosition, WarpingControl const &control, typename DestImageT::SinglePixel padValue = lsst::afw::math::edgePixel<DestImageT>(typename lsst::afw::image::detail::image_traits<DestImageT>::image_category()))

Parameters

  • destImage: remapped image

  • srcImage: source image

  • linearTransform: linear transformation to apply

  • centerPosition: pixel position for location of linearTransform

  • control: control parameters

  • padValue: use this value for undefined (edge) pixels

Warp an image with a LinearTranform about a specified point.

This enables warping an image of e.g. a PSF without translating the centroid.

class BilinearWarpingKernel : public lsst::afw::math::SeparableKernel
#include <warpExposure.h>

Bilinear warping: fast; good for undersampled data.

The kernel size is 2 x 2.

For more information about warping kernels see makeWarpingKernel

Public Functions

BilinearWarpingKernel()
BilinearWarpingKernel(const BilinearWarpingKernel&)
BilinearWarpingKernel(BilinearWarpingKernel&&)
BilinearWarpingKernel &operator=(const BilinearWarpingKernel&)
BilinearWarpingKernel &operator=(BilinearWarpingKernel&&)
~BilinearWarpingKernel()
std::shared_ptr<Kernel> clone() const

Return a pointer to a deep copy of this kernel

This kernel exists instead of a copy constructor so one can obtain a copy of an actual kernel instead of a useless copy of the base class.

Every kernel subclass must override this method.

Return

a pointer to a deep copy of the kernel

Protected Functions

void setKernelParameter(unsigned int ind, double value) const

Set one kernel parameter

Classes that have kernel parameters must subclass this function.

This function is marked “const”, despite modifying unimportant internals, so that computeImage can be const.

Exceptions

  • lsst::pex::exceptions::InvalidParameterError: always (unless subclassed)

class BilinearFunction1 : public lsst::afw::math::Function1<Kernel::Pixel>
#include <warpExposure.h>

1-dimensional bilinear interpolation function.

Optimized for bilinear warping so only accepts two values: 0 and 1 (which is why it defined in the BilinearWarpingKernel class instead of being made available as a standalone function).

Public Types

typedef std::shared_ptr<Function1<Kernel::Pixel>> Function1Ptr

Public Functions

BilinearFunction1(double fracPos)

Parameters

  • fracPos: fractional position; must be >= 0 and < 1

Construct a Bilinear interpolation function

~BilinearFunction1()
Function1Ptr clone() const

Return a pointer to a deep copy of this function

This function exists instead of a copy constructor so one can obtain a copy of an actual function instead of a useless copy of the base class.

Every concrete subclass must override this method.

Return

a pointer to a deep copy of the function

Kernel::Pixel operator()(double x) const

Solve bilinear equation

Only the following arguments will give reliably meaningful values:

  • 0.0 or 1.0 if the kernel center index is 0 in this axis

  • -1.0 or 0.0 if the kernel center index is 1 in this axis

std::string toString(std::string const& = "") const

Return string representation.

class LanczosWarpingKernel : public lsst::afw::math::SeparableKernel
#include <warpExposure.h>

Lanczos warping: accurate but slow and can introduce ringing artifacts.

This kernel is the product of two 1-dimensional Lanczos functions. The number of minima and maxima in the 1-dimensional Lanczos function is 2*order + 1. The kernel has one pixel per function minimum or maximum; but as applied to warping, the first or last pixel is always zero and can be omitted. Thus the kernel size is 2*order x 2*order.

For more information about warping kernels see makeWarpingKernel

Public Functions

LanczosWarpingKernel(int order)

Parameters

  • order: order of Lanczos function

LanczosWarpingKernel(const LanczosWarpingKernel&)
LanczosWarpingKernel(LanczosWarpingKernel&&)
LanczosWarpingKernel &operator=(const LanczosWarpingKernel&)
LanczosWarpingKernel &operator=(LanczosWarpingKernel&&)
~LanczosWarpingKernel()
std::shared_ptr<Kernel> clone() const

Return a pointer to a deep copy of this kernel

This kernel exists instead of a copy constructor so one can obtain a copy of an actual kernel instead of a useless copy of the base class.

Every kernel subclass must override this method.

Return

a pointer to a deep copy of the kernel

int getOrder() const

get the order of the kernel

Protected Functions

void setKernelParameter(unsigned int ind, double value) const

Set one kernel parameter

Classes that have kernel parameters must subclass this function.

This function is marked “const”, despite modifying unimportant internals, so that computeImage can be const.

Exceptions

  • lsst::pex::exceptions::InvalidParameterError: always (unless subclassed)

class NearestWarpingKernel : public lsst::afw::math::SeparableKernel
#include <warpExposure.h>

Nearest neighbor warping: fast; good for undersampled data.

The kernel size is 2 x 2.

For more information about warping kernels see makeWarpingKernel

Public Functions

NearestWarpingKernel()
NearestWarpingKernel(const NearestWarpingKernel&)
NearestWarpingKernel(NearestWarpingKernel&&)
NearestWarpingKernel &operator=(const NearestWarpingKernel&)
NearestWarpingKernel &operator=(NearestWarpingKernel&&)
~NearestWarpingKernel()
std::shared_ptr<Kernel> clone() const

Return a pointer to a deep copy of this kernel

This kernel exists instead of a copy constructor so one can obtain a copy of an actual kernel instead of a useless copy of the base class.

Every kernel subclass must override this method.

Return

a pointer to a deep copy of the kernel

Protected Functions

void setKernelParameter(unsigned int ind, double value) const

Set one kernel parameter

Classes that have kernel parameters must subclass this function.

This function is marked “const”, despite modifying unimportant internals, so that computeImage can be const.

Exceptions

  • lsst::pex::exceptions::InvalidParameterError: always (unless subclassed)

class NearestFunction1 : public lsst::afw::math::Function1<Kernel::Pixel>
#include <warpExposure.h>

1-dimensional nearest neighbor interpolation function.

Optimized for nearest neighbor warping so only accepts two values: 0 and 1 (which is why it defined in the NearestWarpingKernel class instead of being made available as a standalone function).

Public Types

typedef std::shared_ptr<Function1<Kernel::Pixel>> Function1Ptr

Public Functions

NearestFunction1(double fracPos)

Parameters

  • fracPos: fractional position

Construct a Nearest interpolation function

~NearestFunction1()
Function1Ptr clone() const

Return a pointer to a deep copy of this function

This function exists instead of a copy constructor so one can obtain a copy of an actual function instead of a useless copy of the base class.

Every concrete subclass must override this method.

Return

a pointer to a deep copy of the function

Kernel::Pixel operator()(double x) const

Solve nearest neighbor equation

Only the following arguments will give reliably meaningful values:

  • 0.0 or 1.0 if the kernel center index is 0 in this axis

  • -1.0 or 0.0 if the kernel center index is 1 in this axis

std::string toString(std::string const& = "") const

Return string representation.

class WarpingControl
#include <warpExposure.h>

Parameters to control convolution

Note

padValue is not member of this class to avoid making this a templated class.

Public Functions

WarpingControl(std::string const &warpingKernelName, std::string const &maskWarpingKernelName = "", int cacheSize = 0, int interpLength = 0, lsst::afw::image::MaskPixel growFullMask = 0)

Parameters

  • warpingKernelName: name of warping kernel; used as the argument to makeWarpingKernel

  • maskWarpingKernelName: name of warping kernel used for the mask plane; if “” then the regular warping kernel is used. Intended so one can use a bilinear kernel or other compact kernel for the mask plane to avoid smearing mask bits too far. The theory is that bad pixels are already interpolated over, so we don’t need to worry about bad values spreading very far.

  • cacheSize: cache size for warping kernel; no cache if 0 (used as the argument to the warping kernels’ computeCache method)

  • interpLength: distance over which the WCS can be linearly interpolated

  • growFullMask: mask bits to grow to full width of image/variance kernel

Construct a WarpingControl object

Exceptions

  • pex::exceptions::InvalidParameterError: if the warping kernel is smaller than the mask warping kernel.

virtual ~WarpingControl()
int getCacheSize() const

get the cache size for the interpolation kernel(s)

void setCacheSize(int cacheSize)

Parameters

  • cacheSize: cache size

set the cache size for the interpolation kernel(s)

A value of 0 disables the cache for maximum accuracy. 10,000 typically results in a warping error of a fraction of a count. 100,000 typically results in a warping error of less than 0.01 count. Note the new cache is not computed until getWarpingKernel or getMaskWarpingKernel is called.

int getInterpLength() const

get the interpolation length (pixels)

void setInterpLength(int interpLength)

Parameters

  • interpLength: interpolation length (pixels)

set the interpolation length

Interpolation length is the distance over which the WCS can be linearly interpolated, in pixels:

  • 0 means no interpolation and uses an optimized branch of the code

  • 1 also performs no interpolation but it runs the interpolation code branch (and so is only intended for unit tests)

std::shared_ptr<SeparableKernel> getWarpingKernel() const

get the warping kernel

void setWarpingKernelName(std::string const &warpingKernelName)

Parameters

  • warpingKernelName: name of warping kernel

set the warping kernel by name

void setWarpingKernel(SeparableKernel const &warpingKernel)

Parameters

  • warpingKernel: warping kernel

set the warping kernel

Exceptions

  • lsst::pex::exceptions::InvalidParameterError: if new kernel pointer is empty.

std::shared_ptr<SeparableKernel> getMaskWarpingKernel() const

get the mask warping kernel

bool hasMaskWarpingKernel() const

return true if there is a mask kernel

void setMaskWarpingKernelName(std::string const &maskWarpingKernelName)

Parameters

  • maskWarpingKernelName: name of mask warping kernel; use “” to clear the kernel

set or clear the mask warping kernel by name

void setMaskWarpingKernel(SeparableKernel const &maskWarpingKernel)

Parameters

  • maskWarpingKernel: mask warping kernel

set the mask warping kernel

Note

To clear the mask warping kernel use setMaskWarpingKernelName(“”).

lsst::afw::image::MaskPixel getGrowFullMask() const

get mask bits to grow to full width of image/variance kernel

void setGrowFullMask(lsst::afw::image::MaskPixel growFullMask)

Parameters

  • growFullMask: mask bits to grow to full width of image/variance kernel

set mask bits to grow to full width of image/variance kernel

Private Functions

void _testWarpingKernels(SeparableKernel const &warpingKernel, SeparableKernel const &maskWarpingKernel) const

Parameters

  • warpingKernel: warping kernel

  • maskWarpingKernel: mask warping kernel

Throw an exception if the two kernels are not compatible in shape

Exceptions

  • lsst::pex::exceptions::InvalidParameterError: if the two kernels are not compatible in shape

Private Members

std::shared_ptr<SeparableKernel> _warpingKernelPtr
std::shared_ptr<SeparableKernel> _maskWarpingKernelPtr
int _cacheSize
int _interpLength
lsst::afw::image::MaskPixel _growFullMask