File ConvolveImage.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

template<typename OutImageT, typename InImageT>
void scaledPlus(OutImageT &outImage, double c1, InImageT const &inImage1, double c2, InImageT const &inImage2)

Compute the scaled sum of two images

outImage = c1 inImage1 + c2 inImage2

For example to linearly interpolate between two images set: c1 = 1.0 - fracDist c2 = fracDist where fracDist is the fractional distance of outImage from inImage1: location of outImage - location of inImage1 fracDist = —————————————- location of inImage2 - location of inImage1

Parameters

  • [out] outImage: output image

  • [in] c1: coefficient for image 1

  • [in] inImage1: input image 1

  • [in] c2: coefficient for image 2

  • [in] inImage2: input image 2

Exceptions

  • lsst::pex::exceptions::InvalidParameterError: if outImage is not same dimensions as inImage1 and inImage2.

template<typename OutImageT, typename InImageT>
OutImageT::SinglePixel convolveAtAPoint(typename InImageT::const_xy_locator inImageLocator, typename lsst::afw::image::Image<lsst::afw::math::Kernel::Pixel>::const_xy_locator kernelLocator, int kWidth, int kHeight)

Apply convolution kernel to an image at one point

Note

This subroutine sacrifices convenience for performance. The user is expected to figure out the kernel center and adjust the supplied pixel accessors accordingly. For an example of how to do this see convolve().

Parameters

  • inImageLocator: locator for image pixel that overlaps pixel (0,0) of kernel (the origin of the kernel, not its center)

  • kernelLocator: locator for (0,0) pixel of kernel (the origin of the kernel, not its center)

  • kWidth: number of columns in kernel

  • kHeight: number of rows in kernel

template<typename OutImageT, typename InImageT>
OutImageT::SinglePixel convolveAtAPoint(typename InImageT::const_xy_locator inImageLocator, std::vector<lsst::afw::math::Kernel::Pixel> const &kernelColList, std::vector<lsst::afw::math::Kernel::Pixel> const &kernelRowList)

Apply separable convolution kernel to an image at one point

Note

This subroutine sacrifices convenience for performance. The user is expected to figure out the kernel center and adjust the supplied pixel accessors accordingly. For an example of how to do this see convolve().

Parameters

  • inImageLocator: locator for image pixel that overlaps pixel (0,0) of kernel (the origin of the kernel, not its center)

  • kernelXList: kernel column vector

  • kernelYList: kernel row vector

template<typename OutImageT, typename InImageT, typename KernelT>
void convolve(OutImageT &convolvedImage, InImageT const &inImage, KernelT const &kernel, ConvolutionControl const &convolutionControl = ConvolutionControl())

Convolve an Image or MaskedImage with a Kernel, setting pixels of an existing output image.

Various convolution kernels are available, including:

If a kernel is spatially varying, its spatial model is computed at each pixel position on the image (pixel position, not pixel index). At present (2009-09-24) this position is computed relative to the lower left corner of the sub-image, but it will almost certainly change to be the lower left corner of the parent image.

All convolution is performed in real space. This allows convolution to handle masked pixels and spatially varying kernels. Although convolution of an Image with a spatially invariant kernel could, in fact, be performed in Fourier space, the code does not do this.

Note that mask bits are smeared by convolution; all nonzero pixels in the kernel smear the mask, even pixels that have very small values. Larger kernels smear the mask more and are also slower to convolve. Use the smallest kernel that will do the job.

convolvedImage has a border of edge pixels which cannot be computed normally. Normally these pixels are set to the standard edge pixel, as returned by edgePixel(). However, if your code cannot handle nans in the image or infs in the variance, you may set doCopyEdge true, in which case the edge pixels are set to the corresponding pixels of the input image and (if there is a mask) the mask EDGE bit is set.

The border of edge pixels has size:

  • kernel.getCtrX() along the left edge

  • kernel.getCtrY() along the bottom edge

  • kernel.getWidth() - 1 - kernel.getCtrX() along the right edge

  • kernel.getHeight() - 1 - kernel.getCtrY() along the top edge You can obtain a bounding box for the good pixels in the convolved image from a bounding box for the entire image using the Kernel method shrinkBBox.

Convolution has been optimized for the various kinds of kernels, as follows (listed approximately in order of decreasing speed):

  • DeltaFunctionKernel convolution is a simple image shift.

  • SeparableKernel convolution is performed by convolving the input by one of the two functions, then the result by the other function. Thus convolution with a kernel of size nCols x nRows becomes convolution with a kernel of size nCols x 1, followed by convolution with a kernel of size 1 x nRows.

  • Convolution with spatially invariant versions of the other kernels is performed by computing the kernel image once and convolving with that. The code has been optimized for cache performance and so should be fairly efficient.

  • Convolution with a spatially varying LinearCombinationKernel is performed by convolving the image by each basis kernel and combining the result by solving the spatial model. This will be efficient provided the kernel does not contain too many or very large basis kernels.

  • Convolution with spatially varying AnalyticKernel is likely to be slow. The code simply computes the output one pixel at a time by computing the AnalyticKernel at that point and applying it to the input image. This is not favorable for cache performance (especially for large kernels) but avoids recomputing the AnalyticKernel. It is probably possible to do better.

Additional convolution functions include:

  • convolveAtAPoint(): convolve a Kernel to an Image or MaskedImage at a point.

  • basicConvolve(): convolve a Kernel with an Image or MaskedImage, but do not set the edge pixels of the output. Optimization of convolution for different types of Kernel are handled by different specializations of basicConvolve().

afw/examples offers programs that time convolution including timeConvolve and timeSpatiallyVaryingConvolve.

Parameters

  • [out] convolvedImage: convolved image; must be the same size as inImage

  • [in] inImage: image to convolve

  • [in] kernel: convolution kernel

  • [in] convolutionControl: convolution control parameters

Exceptions

  • lsst::pex::exceptions::InvalidParameterError: if convolvedImage is not the same size as inImage

  • lsst::pex::exceptions::InvalidParameterError: if inImage is smaller than kernel in columns and/or rows.

  • std::bad_alloc: when allocation of memory fails

template<typename OutImageT, typename InImageT, typename KernelT>
void convolve(OutImageT &convolvedImage, InImageT const &inImage, KernelT const &kernel, bool doNormalize, bool doCopyEdge = false)

Old, deprecated version of convolve.

Parameters

  • [out] convolvedImage: convolved image; must be the same size as inImage

  • [in] inImage: image to convolve

  • [in] kernel: convolution kernel

  • [in] doNormalize: if true, normalize the kernel, else use “as is”

  • [in] doCopyEdge: if false (default), set edge pixels to the standard edge pixel; if true, copy edge pixels from input and set EDGE bit of mask

template<typename ImageT>
ImageT::SinglePixel edgePixel(lsst::afw::image::detail::Image_tag)

Return an off-the-edge pixel appropriate for a given Image type

The value is quiet_NaN if that exists for the pixel type, else 0

template<typename MaskedImageT>
MaskedImageT::SinglePixel edgePixel(lsst::afw::image::detail::MaskedImage_tag)

Return an off-the-edge pixel appropriate for a given MaskedImage type

The components are:

  • image = quiet_NaN if that exists for the pixel type, else 0

  • mask = NO_DATA bit set

  • variance = infinity if that exists for the pixel type, else 0

Exceptions

  • lsst::pex::exceptions::LogicError: Thrown if the global mask plane dictionary does not have a NO_DATA bit.

template<typename OutImageT, typename InImageT>
OutImageT::SinglePixel convolveAtAPoint(typename InImageT::const_xy_locator inImageLocator, std::vector<Kernel::Pixel> const &kernelXList, std::vector<Kernel::Pixel> const &kernelYList)

Apply separable convolution kernel to an image at one point

Note

This subroutine sacrifices convenience for performance. The user is expected to figure out the kernel center and adjust the supplied pixel accessors accordingly. For an example of how to do this see convolve().

Parameters

  • inImageLocator: locator for image pixel that overlaps pixel (0,0) of kernel (the origin of the kernel, not its center)

  • kernelXList: kernel column vector

  • kernelYList: kernel row vector

class ConvolutionControl
#include <ConvolveImage.h>

Parameters to control convolution

Public Functions

ConvolutionControl(bool doNormalize = true, bool doCopyEdge = false, int maxInterpolationDistance = 10)

Parameters

  • doNormalize: normalize the kernel to sum=1?

  • doCopyEdge: copy edge pixels from source image instead of setting them to the standard edge pixel?

  • maxInterpolationDistance: maximum width or height of a region over which to use linear interpolation interpolate

bool getDoNormalize() const
bool getDoCopyEdge() const
int getMaxInterpolationDistance() const
void setDoNormalize(bool doNormalize)
void setDoCopyEdge(bool doCopyEdge)
void setMaxInterpolationDistance(int maxInterpolationDistance)

Private Members

bool _doNormalize

normalize the kernel to sum=1?

bool _doCopyEdge

copy edge pixels from source image instead of setting them to the standard edge pixel?

int _maxInterpolationDistance

maximum width or height of a region over which to attempt interpolation