Template Function lsst::afw::math::convolve(OutImageT&, InImageT const&, KernelT const&, ConvolutionControl const&)

Function Documentation

template<typename OutImageT, typename InImageT, typename KernelT>
void lsst::afw::math::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