File Convolve.h

Defines

IS_INSTANCE(A, B)
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
namespace detail

Functions

template<typename OutImageT, typename InImageT>
void basicConvolve(OutImageT &convolvedImage, InImageT const &inImage, lsst::afw::math::Kernel const &kernel, lsst::afw::math::ConvolutionControl const &convolutionControl)

Low-level convolution function that does not set edge pixels.

convolvedImage must be the same size as inImage. convolvedImage has a border in which the output pixels are not set. This border 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

Parameters

  • [out] convolvedImage: convolved image

  • [in] inImage: image to convolve

  • [in] kernel: convolution kernel

  • [in] convolutionControl: convolution control parameters

Exceptions

  • lsst::pex::exceptions::InvalidParameterError: if convolvedImage dimensions != inImage dimensions

  • lsst::pex::exceptions::InvalidParameterError: if inImage smaller than kernel in width or height

  • lsst::pex::exceptions::InvalidParameterError: if kernel width or height < 1

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

template<typename OutImageT, typename InImageT>
void basicConvolve(OutImageT &convolvedImage, InImageT const &inImage, lsst::afw::math::DeltaFunctionKernel const &kernel, lsst::afw::math::ConvolutionControl const &convolutionControl)

A version of basicConvolve that should be used when convolving delta function kernels

Parameters

  • [out] convolvedImage: convolved image

  • [in] inImage: image to convolve

  • [in] kernel: convolution kernel

  • [in] convolutionControl: convolution control parameters

template<typename OutImageT, typename InImageT>
void basicConvolve(OutImageT &convolvedImage, InImageT const &inImage, lsst::afw::math::LinearCombinationKernel const &kernel, lsst::afw::math::ConvolutionControl const &convolutionControl)

A version of basicConvolve that should be used when convolving a LinearCombinationKernel

The Algorithm:

  • If the kernel is spatially varying and contains only DeltaFunctionKernels then convolves the input Image by each basis kernel in turn, solves the spatial model for that component and adds in the appropriate amount of the convolved image.

  • In all other cases uses normal convolution

Parameters

  • [out] convolvedImage: convolved image

  • [in] inImage: image to convolve

  • [in] kernel: convolution kernel

  • [in] convolutionControl: convolution control parameters

Exceptions

  • lsst::pex::exceptions::InvalidParameterError: if convolvedImage dimensions != inImage dimensions

  • lsst::pex::exceptions::InvalidParameterError: if inImage smaller than kernel in width or height

  • lsst::pex::exceptions::InvalidParameterError: if kernel width or height < 1

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

template<typename OutImageT, typename InImageT>
void basicConvolve(OutImageT &convolvedImage, InImageT const &inImage, lsst::afw::math::SeparableKernel const &kernel, lsst::afw::math::ConvolutionControl const &convolutionControl)

A version of basicConvolve that should be used when convolving separable kernels

Parameters

  • [out] convolvedImage: convolved image

  • [in] inImage: image to convolve

  • [in] kernel: convolution kernel

  • [in] convolutionControl: convolution control parameters

template<typename OutImageT, typename InImageT>
void convolveWithBruteForce(OutImageT &convolvedImage, InImageT const &inImage, lsst::afw::math::Kernel const &kernel, lsst::afw::math::ConvolutionControl const &convolutionControl)

Convolve an Image or MaskedImage with a Kernel by computing the kernel image at every point. (If the kernel is not spatially varying then only compute it once).

convolvedImage must be the same size as inImage. convolvedImage has a border in which the output pixels are not set. This border 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

Warning

Low-level convolution function that does not set edge pixels.

Parameters

  • [out] convolvedImage: convolved image

  • [in] inImage: image to convolve

  • [in] kernel: convolution kernel

  • [in] convolutionControl: convolution control parameters

Exceptions

  • lsst::pex::exceptions::InvalidParameterError: if convolvedImage dimensions != inImage dimensions

  • lsst::pex::exceptions::InvalidParameterError: if inImage smaller than kernel in width or height

  • lsst::pex::exceptions::InvalidParameterError: if kernel width or height < 1

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

template<typename OutImageT, typename InImageT>
void convolveWithInterpolation(OutImageT &outImage, InImageT const &inImage, lsst::afw::math::Kernel const &kernel, ConvolutionControl const &convolutionControl)

Convolve an Image or MaskedImage with a spatially varying Kernel using linear interpolation.

This is a low-level convolution function that does not set edge pixels.

The algorithm is as follows:

  • divide the image into regions whose size is no larger than maxInterpolationDistance

  • for each region:

    • convolve it using convolveRegionWithInterpolation (which see)

Note that this routine will also work with spatially invariant kernels, but not efficiently.

Parameters

  • [out] outImage: convolved image = inImage convolved with kernel

  • [in] inImage: input image

  • [in] kernel: convolution kernel

  • [in] convolutionControl: convolution control parameters

Exceptions

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

template<typename OutImageT, typename InImageT>
void convolveRegionWithInterpolation(OutImageT &outImage, InImageT const &inImage, KernelImagesForRegion const &region, ConvolveWithInterpolationWorkingImages &workingImages)

Convolve a region of an Image or MaskedImage with a spatially varying Kernel using interpolation.

This is a low-level convolution function that does not set edge pixels.

Warning

: this is a low-level routine that performs no bounds checking.

Parameters

  • [out] outImage: convolved image = inImage convolved with kernel

  • [in] inImage: input image

  • [in] region: kernel image region over which to convolve

  • [in] workingImages: working kernel images

struct ConvolveWithInterpolationWorkingImages
#include <Convolve.h>

kernel images used by convolveRegionWithInterpolation

Public Types

typedef lsst::afw::image::Image<lsst::afw::math::Kernel::Pixel> Image

Public Functions

ConvolveWithInterpolationWorkingImages(lsst::geom::Extent2I const &dimensions)

Public Members

Image leftImage
Image rightImage
Image leftDeltaImage
Image rightDeltaImage
Image deltaImage
Image kernelImage
class KernelImagesForRegion
#include <Convolve.h>

A collection of Kernel images for special locations on a rectangular region of an image

See the Location enum for a list of those special locations.

This is a low-level helper class for recursive convolving with interpolation. Many of these objects may be created during a convolution, and many will share kernel images. It uses shared pointers to kernels and kernel images for increased speed and decreased memory usage (at the expense of safety). Note that null pointers are NOT acceptable for the constructors!

Warning

The kernel images along the top and right edges are computed one row or column past the bounding box. This allows abutting KernelImagesForRegion to share corner and edge kernel images, which is useful when dividing a KernelImagesForRegion into subregions.

Warning

The bounding box for the region applies to the parent image.

Also note that it uses lazy evaluation: images are computed when they are wanted.

Public Types

enum Location

locations of various points in the region

RIGHT and TOP are one column/row beyond the region’s bounding box. Thus adjacent regions share corner images.

The posiitions are: BOTTOM_LEFT, BOTTOM_RIGHT, TOP_LEFT, TOP_RIGHT

These locations always refer to the center of a pixel. Thus if the region has an odd size along an axis (so that the span to the top and right, which are one beyond, is even), the middle pixel will be 1/2 pixel off from the true center along that axis (in an unspecified direction).

Values:

BOTTOM_LEFT
BOTTOM_RIGHT
TOP_LEFT
TOP_RIGHT
typedef std::shared_ptr<lsst::afw::math::Kernel const> KernelConstPtr
typedef lsst::afw::image::Image<lsst::afw::math::Kernel::Pixel> Image
typedef std::shared_ptr<Image> ImagePtr
typedef std::shared_ptr<Image const> ImageConstPtr

Public Functions

KernelImagesForRegion(KernelConstPtr kernelPtr, lsst::geom::Box2I const &bbox, lsst::geom::Point2I const &xy0, bool doNormalize)

Construct a KernelImagesForRegion

Parameters

  • kernelPtr: kernel

  • bbox: bounding box of region of an image for which we want to compute kernel images (inclusive and relative to parent image)

  • xy0: xy0 of image for which we want to compute kernel images

  • doNormalize: normalize the kernel images?

Exceptions

  • lsst::pex::exceptions::InvalidParameterError: if kernelPtr is null

KernelImagesForRegion(KernelConstPtr kernelPtr, lsst::geom::Box2I const &bbox, lsst::geom::Point2I const &xy0, bool doNormalize, ImagePtr bottomLeftImagePtr, ImagePtr bottomRightImagePtr, ImagePtr topLeftImagePtr, ImagePtr topRightImagePtr)

Construct a KernelImagesForRegion with some or all corner images

Null corner image pointers are ignored.

Warning

: if any images are incorrect you will get a mess.

Parameters

  • kernelPtr: kernel

  • bbox: bounding box of region of an image for which we want to compute kernel images (inclusive and relative to parent image)

  • xy0: xy0 of image

  • doNormalize: normalize the kernel images?

  • bottomLeftImagePtr: kernel image and sum at bottom left of region

  • bottomRightImagePtr: kernel image and sum at bottom right of region

  • topLeftImagePtr: kernel image and sum at top left of region

  • topRightImagePtr: kernel image and sum at top right of region

Exceptions

  • lsst::pex::exceptions::InvalidParameterError: if kernelPtr is null

  • lsst::pex::exceptions::InvalidParameterError: if an image has the wrong dimensions

lsst::geom::Box2I getBBox() const

Get the bounding box for the region

lsst::geom::Point2I getXY0() const

Get xy0 of the image

bool getDoNormalize() const

Get the doNormalize parameter

ImagePtr getImage(Location location) const

Return the image and sum at the specified location

If the image has not yet been computed, it is computed at this time.

Parameters

  • location: location of image

KernelConstPtr getKernel() const

Get the kernel (as a shared pointer to const)

lsst::geom::Point2I getPixelIndex(Location location) const

Compute pixel index of a given location, relative to the parent image (thus offset by bottom left corner of bounding box)

Parameters

  • location: location for which to return pixel index

bool computeNextRow(RowOfKernelImagesForRegion &regionRow) const

Compute next row of subregions

For the first row call with a new RowOfKernelImagesForRegion (with the desired number of columns and rows). Every subequent call updates the data in the RowOfKernelImagesForRegion.

Return

true if a new row was computed, false if supplied RowOfKernelImagesForRegion is for the last row.

Parameters

Public Static Functions

static int getMinInterpolationSize()

Get the minInterpolationSize class constant

Private Types

typedef std::vector<Location> LocationList

Private Functions

void _computeImage(Location location) const

Compute image at a particular location

Exceptions

  • lsst::pex::exceptions::NotFoundError: if there is no pointer at that location

void _insertImage(Location location, ImagePtr imagePtr) const

Parameters

  • location: location at which to insert image

  • imagePtr: image to insert

Insert an image in the cache.

Exceptions

  • lsst::pex::exceptions::InvalidParameterError: if image pointer is null

  • lsst::pex::exceptions::InvalidParameterError: if image has the wrong dimensions

void _moveUp(bool isFirst, int newHeight)

Move the region up one segment

To avoid reallocating memory for kernel images, swap the top and bottom kernel image pointers and recompute the top images. Actually, only does this to the right-hande images if isFirst is false since it assumes the left images were already handled.

Intended to support computeNextRow; as such assumes that a list of adjacent regions will be moved, left to right.

Parameters

  • isFirst: true if the first region in a row (or the only region you are moving)

  • newHeight: the height of the region after moving it

Private Members

KernelConstPtr _kernelPtr
lsst::geom::Box2I _bbox
lsst::geom::Point2I _xy0
bool _doNormalize
std::vector<ImagePtr> _imagePtrList

Private Static Functions

int _computeNextSubregionLength(int length, int nDivisions)

Parameters

  • length: length of region

  • nDivisions: number of divisions of region

Compute length of next subregion if the region is to be divided into pieces of approximately equal length.

Return

length of next subregion

Warning

: no range checking

static std::vector<int> _computeSubregionLengths(int length, int nDivisions)

Compute length of each subregion for a region divided into nDivisions pieces of approximately equal length.

Return

a list of subspan lengths

Parameters

  • length: length of region

  • nDivisions: number of divisions of region

Exceptions

  • lsst::pex::exceptions::InvalidParameterError: if nDivisions >= length

Private Static Attributes

int const _MinInterpolationSize
class RowOfKernelImagesForRegion
#include <Convolve.h>

A row of KernelImagesForRegion

Intended for iterating over subregions of a KernelImagesForRegion using computeNextRow.

Public Types

typedef std::vector<std::shared_ptr<KernelImagesForRegion>> RegionList
typedef RegionList::iterator Iterator
typedef RegionList::const_iterator ConstIterator

Public Functions

RowOfKernelImagesForRegion(int nx, int ny)

Construct a RowOfKernelImagesForRegion

Parameters

  • nx: number of columns

  • ny: number of rows

RegionList::const_iterator begin() const

Return the begin iterator for the list

RegionList::const_iterator end() const

Return the end iterator for the list

RegionList::iterator begin()

Return the begin iterator for the list

RegionList::iterator end()

Return the end iterator for the list

std::shared_ptr<KernelImagesForRegion> front()

Return the first region in the list

std::shared_ptr<KernelImagesForRegion> back()

Return the last region in the list

int getNX() const
int getNY() const
int getYInd() const
std::shared_ptr<KernelImagesForRegion const> getRegion(int ind) const

get the specified region (range-checked)

Exceptions

  • std::range_error: if ind out of range

bool hasData() const
bool isLastRow() const
int incrYInd()

Private Members

int _nx
int _ny
int _yInd
RegionList _regionList