LSST framework

Files
file	Coord.h
	Functions to handle coordinates.
file	Observatory.h
	Class to hold observatory information.
file	PsfFormatter.h
	Interface for PsfFormatter class.
file	DecoratedImageFormatter.h
	Interface for DecoratedImageFormatter class.
file	ExposureFormatter.h
	Interface for ExposureFormatter class.
file	ImageFormatter.h
	Interface for ImageFormatter class.
file	MaskedImageFormatter.h
	Interface for MaskedImageFormatter class.
file	MaskFormatter.h
	Interface for MaskFormatter class.
file	TanWcsFormatter.h
	Interface for TanWcsFormatter class.
file	WcsFormatter.h
	Interface for WcsFormatter class.
file	CudaMemory.h
	Functions and a class to help allocating GPU global memory and transferring data to and from a GPU.
file	CudaQueryDevice.h
	Functions to query the properties of currently selected GPU device.
file	CudaSelectGpu.h
	Functions to help managing setup for GPU kernels.
file	GpuBuffer2D.h
	contains GpuBuffer2D class (for simple handling of images or 2D arrays)
file	DevicePreference.h
	Interface for CPU/GPU device selection.
file	GpuExceptions.h
	additional GPU exceptions
file	IsGpuBuild.h
	A function to determine whether compiling for GPU is enabled.
file	ImageSlice.h
	Define a single column or row of an Image.
file	ConvolveImage.h
	Convolve and convolveAtAPoint functions for Image and Kernel.
file	ConvCpuGpuShared.h
	CPU and GPU convolution shared code.
file	convCUDA.h
	GPU convolution code.
file	Convolve.h
	Convolution support.
file	ConvolveGPU.h
	Convolution support.
file	cudaConvWrapper.h
	Set up for convolution, calls GPU convolution kernels.
file	CudaLanczos.h
	Declaration of a GPU kernel for image warping and declarations of requred datatypes.
file	CudaLanczosWrapper.h
	GPU accelerared image warping.
file	PositionFunctor.h
	GPU accelerared image warping.
file	detail.h
	An include file to include the header files for lsst::afw::math::detail.
file	Function.h
	Define the basic Function classes.
file	FunctionLibrary.h
	Define a collection of useful Functions.
file	Integrate.h
	Compute 1d and 2d integral.
file	Kernel.h
	Declare the Kernel class and subclasses.
file	KernelFunctions.h
	Utility functions for kernels.
file	minimize.h
	Adaptor for minuit.
file	Random.h
	Random number generator class.
file	SpatialCell.h
	Class to ensure constraints for spatial modeling.
file	Statistics.h
	Compute Image Statistics.
file	warpExposure.h
	Support for warping an image to a new WCS.
file	Coord.cc
	Provide functions to handle coordinates.
file	Observatory.cc
	Provide functions to handle dates.
file	PsfFormatter.cc
	Implementation of PsfFormatter class.
file	DecoratedImageFormatter.cc
	Implementation of DecoratedImageFormatter class.
file	ExposureFormatter.cc
	Implementation of ExposureFormatter class.
file	ImageFormatter.cc
	Implementation of ImageFormatter class.
file	MaskedImageFormatter.cc
	Implementation of MaskedImageFormatter class.
file	MaskFormatter.cc
	Implementation of MaskFormatter class.
file	TanWcsFormatter.cc
	Implementation of TanWcsFormatter class.
file	WcsFormatter.cc
	Implementation of WcsFormatter class.
file	CudaMemory.cc
	Functions to help managing setup for GPU kernels.
file	CudaQueryDevice.cc
	Functions to query the properties of currently selected GPU device.
file	CudartClose.cc
	Calls cudaThreadExit from a destructor of a global object.
file	CudaSelectGpu.cc
	Functions for simplifying selecting GPU device, implementation file.
file	DevicePreference.cc
	Implementation file for CPU/GPU device selection.
file	Background.cc
	Background estimation class code.
file	Background.cc
	Background estimation class code.
file	ConvolveImage.cc
	Definition of functions declared in ConvolveImage.h.
file	BasicConvolve.cc
	Definition of basicConvolve and convolveWithBruteForce functions declared in detail/ConvolveImage.h.
file	BasicConvolveGPU.cc
	Definition of basicConvolveGPU, convolveLinearCombinationGPU and convolveSpatiallyInvariantGPU functions declared in ConvolveGPU.h.
file	convCpuGpuShared.cc
	Contains AssertDimensionsOK function.
file	ConvolveWithInterpolation.cc
	Definition of convolveWithInterpolation and helper functions declared in detail/ConvolveImage.h.
file	cudaConvWrapper.cc
	Set up for convolution, calls GPU convolution kernels.
file	cudaLanczosWrapper.cc
	GPU image warping implementation.
file	KernelImagesForRegion.cc
	Definition of KernelImagesForRegion class declared in detail/ConvolveImage.h.
file	KernelFunctions.cc
	Definitions of members of lsst::afw::math.
file	minimize.cc
	Definition of member functions for minuit adaptors.
file	Random.cc
	Random number generator implementaion.
file	RandomImage.cc
	Fill Images with Random numbers.
file	SpatialCell.cc
	Implementation of SpatialCell class.
file	Statistics.cc
	Support statistical operations on images.
file	warpExposure.cc
	Support for warping an image to a new Wcs.

Namespaces
	lsst
	Estimate image backgrounds.

Classes
class	lsst::afw::gpu::detail::GpuBuffer2D< PixelT >
	Class for representing an image or 2D array in general) More...
class	lsst::afw::math::ApproximateControl
	Control how to make an approximation. More...
class	lsst::afw::math::Approximate< T >
	Approximate values for a MaskedImage. More...
class	lsst::afw::math::ConvolutionControl
	Parameters to control convolution. More...
class	lsst::afw::math::Function< ReturnT >
	Basic Function class. More...
class	lsst::afw::math::Function1< ReturnT >
	A Function taking one argument. More...
class	lsst::afw::math::Function2< ReturnT >
	A Function taking two arguments. More...
class	lsst::afw::math::BasePolynomialFunction2< ReturnT >
	Base class for 2-dimensional polynomials of the form: More...
class	lsst::afw::math::IntegerDeltaFunction1< ReturnT >
	1-dimensional integer delta function. More...
class	lsst::afw::math::IntegerDeltaFunction2< ReturnT >
	2-dimensional integer delta function. More...
class	lsst::afw::math::GaussianFunction1< ReturnT >
	1-dimensional Gaussian More...
class	lsst::afw::math::GaussianFunction2< ReturnT >
	2-dimensional Gaussian More...
class	lsst::afw::math::DoubleGaussianFunction2< ReturnT >
	double Guassian (sum of two Gaussians) More...
class	lsst::afw::math::PolynomialFunction1< ReturnT >
	1-dimensional polynomial function. More...
class	lsst::afw::math::PolynomialFunction2< ReturnT >
	2-dimensional polynomial function with cross terms More...
class	lsst::afw::math::Chebyshev1Function1< ReturnT >
	1-dimensional weighted sum of Chebyshev polynomials of the first kind. More...
class	lsst::afw::math::Chebyshev1Function2< ReturnT >
	2-dimensional weighted sum of Chebyshev polynomials of the first kind. More...
class	lsst::afw::math::LanczosFunction1< ReturnT >
	1-dimensional Lanczos function More...
class	lsst::afw::math::LanczosFunction2< ReturnT >
	2-dimensional separable Lanczos function More...
class	lsst::afw::math::Interpolate
	Interpolate values for a set of x,y vector<>s. More...
class	lsst::afw::math::Kernel
	Kernels are used for convolution with MaskedImages and (eventually) Images. More...
class	lsst::afw::math::FixedKernel
	A kernel created from an Image. More...
class	lsst::afw::math::AnalyticKernel
	A kernel described by a function. More...
class	lsst::afw::math::DeltaFunctionKernel
	A kernel that has only one non-zero pixel (of value 1) More...
class	lsst::afw::math::LinearCombinationKernel
	A kernel that is a linear combination of fixed basis kernels. More...
class	lsst::afw::math::SeparableKernel
	A kernel described by a pair of functions: func(x, y) = colFunc(x) * rowFunc(y) More...
class	lsst::afw::math::StatisticsControl
	Pass parameters to a Statistics objectA class to pass parameters which control how the stats are calculated. More...
class	lsst::afw::math::Statistics
class	lsst::afw::math::WarpingControl
	Parameters to control convolution. More...
class	lsst::afw::detection::PsfFormatter
	Formatter for persistence of Psf instances. More...
class	lsst::afw::formatters::DecoratedImageFormatter< ImagePixelT >
	Class implementing persistence and retrieval for DecoratedImages. More...
class	lsst::afw::formatters::ExposureFormatter< ImagePixelT, MaskPixelT, VariancePixelT >
	Class implementing persistence and retrieval for Exposures. More...
class	lsst::afw::formatters::ImageFormatter< ImagePixelT >
	Class implementing persistence and retrieval for Images. More...
class	lsst::afw::formatters::MaskedImageFormatter< ImagePixelT, MaskPixelT, VariancePixelT >
	Class implementing persistence and retrieval for MaskedImages. More...
class	lsst::afw::formatters::MaskFormatter< MaskPixelT >
	Class implementing persistence and retrieval for Masks. More...
class	lsst::afw::formatters::TanWcsFormatter
	Class implementing persistence and retrieval for TanWcs objects. More...
class	lsst::afw::formatters::WcsFormatter
	Class implementing persistence and retrieval for Wcs objects. More...
class	lsst::afw::image::ImageSlice< PixelT >
	A class to specify a slice of an image. More...

Functions
template<typename OutImageT , typename InImageT >
OutImageT::SinglePixel	lsst::afw::math::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. More...
template<typename OutImageT , typename InImageT >
OutImageT::SinglePixel	lsst::afw::math::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. More...
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. More...
template<typename OutImageT , typename InImageT >
void	lsst::afw::math::detail::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. More...
template<typename OutImageT , typename InImageT >
void	lsst::afw::math::detail::basicConvolve (OutImageT &convolvedImage, InImageT const &inImage, lsst::afw::math::DeltaFunctionKernel const &kernel, lsst::afw::math::ConvolutionControl const &)
	A version of basicConvolve that should be used when convolving delta function kernels. More...
template<typename OutImageT , typename InImageT >
void	lsst::afw::math::detail::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. More...
template<typename OutImageT , typename InImageT >
void	lsst::afw::math::detail::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. More...
template<typename OutImageT , typename InImageT >
void	lsst::afw::math::detail::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). More...
void	lsst::afw::math::printKernel (lsst::afw::math::Kernel const &kernel, bool doNormalize, double x=0, double y=0, std::string pixelFmt="%7.3f")
	Print the pixel values of a Kernel to std::cout. More...

Detailed Description

Function Documentation

template<typename OutImageT , typename InImageT >

void lsst::afw::math::detail::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

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
lsst::pex::exceptions::MemoryError	when allocation of CPU memory fails
lsst::afw::gpu::GpuMemoryError	when allocation or transfer to/from GPU memory fails
lsst::afw::gpu::GpuRuntimeError	when GPU code run fails

Parameters

convolvedImage	convolved image
inImage	image to convolve
kernel	convolution kernel
convolutionControl	convolution control parameters

Definition at line 159 of file BasicConvolve.cc.

{
    // Because convolve isn't a method of Kernel we can't always use Kernel's vtbl to dynamically
    // dispatch the correct version of basicConvolve. The case that fails is convolving with a kernel
    // obtained from a pointer or reference to a Kernel (base class), e.g. as used in LinearCombinationKernel.
    if (IS_INSTANCE(kernel, afwMath::DeltaFunctionKernel)) {
        pexLog::TTrace<4>("lsst.afw.math.convolve",
            "generic basicConvolve: dispatch to DeltaFunctionKernel basicConvolve");
        mathDetail::basicConvolve(convolvedImage, inImage,
            *dynamic_cast<afwMath::DeltaFunctionKernel const*>(&kernel),
            convolutionControl);
        return;
    } else if (IS_INSTANCE(kernel, afwMath::SeparableKernel)) {
        pexLog::TTrace<4>("lsst.afw.math.convolve",
            "generic basicConvolve: dispatch to SeparableKernel basicConvolve");
        mathDetail::basicConvolve(convolvedImage, inImage,
            *dynamic_cast<afwMath::SeparableKernel const*>(&kernel),
            convolutionControl);
        return;
    } else if (IS_INSTANCE(kernel, afwMath::LinearCombinationKernel) && kernel.isSpatiallyVarying()) {
        pexLog::TTrace<4>("lsst.afw.math.convolve",
            "generic basicConvolve: dispatch to spatially varying LinearCombinationKernel basicConvolve");
        mathDetail::basicConvolve(convolvedImage, inImage,
            *dynamic_cast<afwMath::LinearCombinationKernel const*>(&kernel),
            convolutionControl);
        return;
    }
    // OK, use general (and slower) form
    if (kernel.isSpatiallyVarying() && (convolutionControl.getMaxInterpolationDistance() > 1)) {
        // use linear interpolation
        pexLog::TTrace<3>("lsst.afw.math.convolve", "generic basicConvolve: using linear interpolation");
        mathDetail::convolveWithInterpolation(convolvedImage, inImage, kernel, convolutionControl);

    } else {
        // use brute force
        pexLog::TTrace<3>("lsst.afw.math.convolve", "generic basicConvolve: using brute force");
        mathDetail::convolveWithBruteForce(convolvedImage, inImage, kernel,convolutionControl);
    }
}

template<typename OutImageT , typename InImageT >

void lsst::afw::math::detail::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.

Exceptions

lsst::pex::exceptions::InvalidParameterError

when GPU acceleration forced

Parameters

convolvedImage	convolved image
inImage	image to convolve
kernel	convolution kernel
convolutionControl	convolution control parameters

Definition at line 211 of file BasicConvolve.cc.

{
    assert (!kernel.isSpatiallyVarying());
    assertDimensionsOK(convolvedImage, inImage, kernel);

    CheckForceGpuOnUnsupportedKernel(convolutionControl);

    int const mImageWidth = inImage.getWidth(); // size of input region
    int const mImageHeight = inImage.getHeight();
    int const cnvWidth = mImageWidth + 1 - kernel.getWidth();
    int const cnvHeight = mImageHeight + 1 - kernel.getHeight();
    int const cnvStartX = kernel.getCtrX();
    int const cnvStartY = kernel.getCtrY();
    int const inStartX = kernel.getPixel().getX();
    int const inStartY = kernel.getPixel().getY();

    pexLog::TTrace<3>("lsst.afw.math.convolve", "DeltaFunctionKernel basicConvolve");

    for (int i = 0; i < cnvHeight; ++i) {
        typename InImageT::x_iterator inPtr = inImage.x_at(inStartX, i +  inStartY);
        for (typename OutImageT::x_iterator cnvPtr = convolvedImage.x_at(cnvStartX, i + cnvStartY),
                 cnvEnd = cnvPtr + cnvWidth; cnvPtr != cnvEnd; ++cnvPtr, ++inPtr){
            *cnvPtr = *inPtr;
        }
    }
}

template<typename OutImageT , typename InImageT >

void lsst::afw::math::detail::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

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
lsst::pex::exceptions::MemoryError	when allocation of CPU memory fails
lsst::afw::gpu::GpuMemoryError	when allocation or transfer to/from GPU memory fails
lsst::afw::gpu::GpuRuntimeError	when GPU code run fails

Parameters

convolvedImage	convolved image
inImage	image to convolve
kernel	convolution kernel
convolutionControl	convolution control parameters

Definition at line 261 of file BasicConvolve.cc.

{
    if (!kernel.isSpatiallyVarying()) {
        // use the standard algorithm for the spatially invariant case
        pexLog::TTrace<3>("lsst.afw.math.convolve",
            "basicConvolve for LinearCombinationKernel: spatially invariant; using brute force");
        return mathDetail::convolveWithBruteForce(convolvedImage, inImage, kernel,
            convolutionControl.getDoNormalize());
    } else {
        CheckForceGpuOnNoGpu(convolutionControl);
        if (lsst::afw::gpu::isGpuBuild() && lsst::afw::gpu::isGpuEnabled()==true) {
            if (convolutionControl.getDevicePreference() == lsst::afw::gpu::AUTO_WITH_CPU_FALLBACK) {
                try {
                    mathDetail::ConvolveGpuStatus::ReturnCode rc =
                               mathDetail::convolveLinearCombinationGPU(convolvedImage,inImage,kernel,
                                                                                convolutionControl);
                    if (rc == mathDetail::ConvolveGpuStatus::OK) return;
                } catch(lsst::afw::gpu::GpuMemoryError) { }
                catch(pexExcept::MemoryError) { }
                catch(lsst::afw::gpu::GpuRuntimeError) { }
            } else if (convolutionControl.getDevicePreference() != lsst::afw::gpu::USE_CPU) {
                mathDetail::ConvolveGpuStatus::ReturnCode rc =
                              mathDetail::convolveLinearCombinationGPU(convolvedImage,inImage,kernel,
                                                                            convolutionControl);
                if (rc == mathDetail::ConvolveGpuStatus::OK) return;
                if (convolutionControl.getDevicePreference() == lsst::afw::gpu::USE_GPU) {
                    throw LSST_EXCEPT(pexExcept::RuntimeError, "Gpu will not process this kernel");
                }
            }
        }

        // refactor the kernel if this is reasonable and possible;
        // then use the standard algorithm for the spatially varying case
        PTR(afwMath::Kernel) refKernelPtr; // possibly refactored version of kernel
        if (static_cast<int>(kernel.getNKernelParameters()) > kernel.getNSpatialParameters()) {
            // refactoring will speed convolution, so try it
            refKernelPtr = kernel.refactor();
            if (!refKernelPtr) {
                refKernelPtr = kernel.clone();
            }
        } else {
            // too few basis kernels for refactoring to be worthwhile
            refKernelPtr = kernel.clone();
        }
        if (convolutionControl.getMaxInterpolationDistance() > 1) {
            pexLog::TTrace<3>("lsst.afw.math.convolve",
                "basicConvolve for LinearCombinationKernel: using interpolation");
            return mathDetail::convolveWithInterpolation(convolvedImage, inImage, *refKernelPtr, convolutionControl);
        } else {
            pexLog::TTrace<3>("lsst.afw.math.convolve",
                "basicConvolve for LinearCombinationKernel: maxInterpolationError < 0; using brute force");
            return mathDetail::convolveWithBruteForce(convolvedImage, inImage, *refKernelPtr,
                convolutionControl.getDoNormalize());
        }
    }
}

template<typename OutImageT , typename InImageT >

void lsst::afw::math::detail::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.

Exceptions

lsst::pex::exceptions::InvalidParameterError

when GPU acceleration forced

Parameters

convolvedImage	convolved image
inImage	image to convolve
kernel	convolution kernel
convolutionControl	convolution control parameters

Definition at line 330 of file BasicConvolve.cc.

{
    typedef typename afwMath::Kernel::Pixel KernelPixel;
    typedef typename std::vector<KernelPixel> KernelVector;
    typedef KernelVector::const_iterator KernelIterator;
    typedef typename InImageT::const_x_iterator InXIterator;
    typedef typename InImageT::const_xy_locator InXYLocator;
    typedef typename OutImageT::x_iterator OutXIterator;
    typedef typename OutImageT::y_iterator OutYIterator;
    typedef typename OutImageT::SinglePixel OutPixel;

    assertDimensionsOK(convolvedImage, inImage, kernel);

    CheckForceGpuOnUnsupportedKernel(convolutionControl);

    afwGeom::Box2I const fullBBox = inImage.getBBox(image::LOCAL);
    afwGeom::Box2I const goodBBox = kernel.shrinkBBox(fullBBox);

    KernelVector kernelXVec(kernel.getWidth());
    KernelVector kernelYVec(kernel.getHeight());

    if (kernel.isSpatiallyVarying()) {
        pexLog::TTrace<3>("lsst.afw.math.convolve",
            "SeparableKernel basicConvolve: kernel is spatially varying");

        for (int cnvY = goodBBox.getMinY(); cnvY <= goodBBox.getMaxY(); ++cnvY) {
            double const rowPos = inImage.indexToPosition(cnvY, afwImage::Y);

            InXYLocator inImLoc = inImage.xy_at(0, cnvY - goodBBox.getMinY());
            OutXIterator cnvXIter = convolvedImage.row_begin(cnvY) + goodBBox.getMinX();
            for (int cnvX = goodBBox.getMinX(); cnvX <= goodBBox.getMaxX();
                ++cnvX, ++inImLoc.x(), ++cnvXIter) {
                double const colPos = inImage.indexToPosition(cnvX, afwImage::X);

                KernelPixel kSum = kernel.computeVectors(kernelXVec, kernelYVec,
                    convolutionControl.getDoNormalize(), colPos, rowPos);

                // why does this trigger warnings? It did not in the past.
                *cnvXIter = afwMath::convolveAtAPoint<OutImageT, InImageT>(inImLoc, kernelXVec, kernelYVec);
                if (convolutionControl.getDoNormalize()) {
                    *cnvXIter = *cnvXIter/kSum;
                }
            }
        }
    } else {
        // kernel is spatially invariant
        // The basic sequence:
        // - For each output row:
        // - Compute x-convolved data: a kernel height's strip of input image convolved with kernel x vector
        // - Compute one row of output by dotting each column of x-convolved data with the kernel y vector
        // The x-convolved data is stored in a kernel-height by good-width buffer.
        // This is circular buffer along y (to avoid shifting pixels before setting each new row);
        // so for each new row the kernel y vector is rotated to match the order of the x-convolved data.

        pexLog::TTrace<3>("lsst.afw.math.convolve",
            "SeparableKernel basicConvolve: kernel is spatially invariant");

        kernel.computeVectors(kernelXVec, kernelYVec, convolutionControl.getDoNormalize());
        KernelIterator const kernelXVecBegin = kernelXVec.begin();
        KernelIterator const kernelYVecBegin = kernelYVec.begin();

        // buffer for x-convolved data
        OutImageT buffer(afwGeom::Extent2I(goodBBox.getWidth(), kernel.getHeight()));

        // pre-fill x-convolved data buffer with all but one row of data
        int yInd = 0; // during initial fill bufY = inImageY
        int const yPrefillEnd = buffer.getHeight() - 1;
        for (; yInd < yPrefillEnd; ++yInd) {
            OutXIterator bufXIter = buffer.x_at(0, yInd);
            OutXIterator const bufXEnd = buffer.x_at(goodBBox.getWidth(), yInd);
            InXIterator inXIter = inImage.x_at(0, yInd);
            for ( ; bufXIter != bufXEnd; ++bufXIter, ++inXIter) {
                *bufXIter = kernelDotProduct<OutPixel, InXIterator, KernelIterator, KernelPixel>(
                    inXIter, kernelXVecBegin, kernel.getWidth());
            }
        }

        // compute output pixels using the sequence described above
        int inY = yPrefillEnd;
        int bufY = yPrefillEnd;
        int cnvY = goodBBox.getMinY();
        while (true) {
            // fill next buffer row and compute output row
            InXIterator inXIter = inImage.x_at(0, inY);
            OutXIterator bufXIter = buffer.x_at(0, bufY);
            OutXIterator cnvXIter = convolvedImage.x_at(goodBBox.getMinX(), cnvY);
            for (int bufX = 0; bufX < goodBBox.getWidth(); ++bufX, ++cnvXIter, ++bufXIter, ++inXIter) {
                // note: bufXIter points to the row of the buffer that is being updated,
                // whereas bufYIter points to row 0 of the buffer
                *bufXIter = kernelDotProduct<OutPixel, InXIterator, KernelIterator, KernelPixel>(
                    inXIter, kernelXVecBegin, kernel.getWidth());

                OutYIterator bufYIter = buffer.y_at(bufX, 0);
                *cnvXIter = kernelDotProduct<OutPixel, OutYIterator, KernelIterator, KernelPixel>(
                    bufYIter, kernelYVecBegin, kernel.getHeight());
            }

            // test for done now, instead of the start of the loop,
            // to avoid an unnecessary extra rotation of the kernel Y vector
            if (cnvY >= goodBBox.getMaxY()) break;

            // update y indices, including bufY, and rotate the kernel y vector to match
            ++inY;
            bufY = (bufY + 1) % kernel.getHeight();
            ++cnvY;
            std::rotate(kernelYVec.begin(), kernelYVec.end()-1, kernelYVec.end());
        }
    }
}

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:

• FixedKernel: a kernel based on an image
• AnalyticKernel: a kernel based on a Function
• SeparableKernel: a kernel described by the product of two one-dimensional Functions: f0(x) * f1(y)
• LinearCombinationKernel: a linear combination of a set of spatially invariant basis kernels.
• DeltaFunctionKernel: a kernel that is all zeros except one pixel whose value is 1. Typically used as a basis kernel for LinearCombinationKernel.

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.

Note

This function is able to use GPU acceleration (for spatially invariant kernels and for LinearCombinationKernel). There is a limit on maximum kernel size, but kernels sized at most 17x17 should be accelerated on all supported GPU hardware (SM 1.3 and better). SM 2.x can accelerate kernels sized up to 22x22.

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.
lsst::pex::exceptions::MemoryError	when allocation of CPU memory fails
lsst::afw::gpu::GpuMemoryError	when allocation or transfer to/from GPU memory fails
lsst::afw::gpu::GpuRuntimeError	when GPU code run fails

Parameters

convolvedImage	convolved image; must be the same size as inImage
inImage	image to convolve
kernel	convolution kernel
convolutionControl	convolution control parameters

Definition at line 328 of file ConvolveImage.cc.

{
    mathDetail::basicConvolve(convolvedImage, inImage, kernel, convolutionControl);
    setEdgePixels(convolvedImage, kernel, inImage, convolutionControl.getDoCopyEdge(),
        typename lsst::afw::image::detail::image_traits<OutImageT>::image_category()
    );
    convolvedImage.setXY0(inImage.getXY0());
}

template<typename OutImageT , typename InImageT >

OutImageT::SinglePixel lsst::afw::math::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  )

inline

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

Definition at line 186 of file ConvolveImage.h.

{
    typename OutImageT::SinglePixel outValue = 0;
    for (int kRow = 0; kRow != kHeight; ++kRow) {
        for (lsst::afw::image::Image<lsst::afw::math::Kernel::Pixel>::const_xy_locator kEnd =
            kernelLocator + lsst::afw::image::detail::difference_type(kWidth, 0);
            kernelLocator != kEnd; ++inImageLocator.x(), ++kernelLocator.x()) {
            typename lsst::afw::math::Kernel::Pixel const kVal = kernelLocator[0];
            if (kVal != 0) {
                outValue += *inImageLocator*kVal;
            }
        }

        inImageLocator  += lsst::afw::image::detail::difference_type(-kWidth, 1);
        kernelLocator += lsst::afw::image::detail::difference_type(-kWidth, 1);
    }

    return outValue;
}

template<typename OutImageT , typename InImageT >

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

inline

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

Definition at line 222 of file ConvolveImage.h.

{
    typedef typename std::vector<lsst::afw::math::Kernel::Pixel>::const_iterator k_iter;

    typedef typename OutImageT::SinglePixel OutT;
    OutT outValue = 0;
    for (k_iter kernelYIter = kernelYList.begin(), yEnd = kernelYList.end();
         kernelYIter != yEnd; ++kernelYIter) {

        OutT outValueY = 0;
        for (k_iter kernelXIter = kernelXList.begin(), xEnd = kernelXList.end();
             kernelXIter != xEnd; ++kernelXIter, ++inImageLocator.x()) {
            typename lsst::afw::math::Kernel::Pixel const kValX = *kernelXIter;
            if (kValX != 0) {
                outValueY += *inImageLocator*kValX;
            }
        }

        double const kValY = *kernelYIter;
        if (kValY != 0) {
            outValue += outValueY*kValY;
        }

        inImageLocator += lsst::afw::image::detail::difference_type(-kernelXList.size(), 1);
    }

    return outValue;
}

template<typename OutImageT , typename InImageT >

void lsst::afw::math::detail::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).

Warning

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

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
lsst::pex::exceptions::InvalidParameterError	when GPU acceleration forced on spatially varying kernel
lsst::pex::exceptions::MemoryError	when allocation of CPU memory fails
lsst::afw::gpu::GpuMemoryError	when allocation or transfer to/from GPU memory fails
lsst::afw::gpu::GpuRuntimeError	when GPU code run fails

Parameters

convolvedImage	convolved image
inImage	image to convolve
kernel	convolution kernel
convolutionControl	convolution control parameters

Definition at line 468 of file BasicConvolve.cc.

{
    bool doNormalize=convolutionControl.getDoNormalize();

    typedef typename afwMath::Kernel::Pixel KernelPixel;
    typedef afwImage::Image<KernelPixel> KernelImage;

    typedef typename KernelImage::const_x_iterator KernelXIterator;
    typedef typename KernelImage::const_xy_locator KernelXYLocator;
    typedef typename InImageT::const_x_iterator InXIterator;
    typedef typename InImageT::const_xy_locator InXYLocator;
    typedef typename OutImageT::x_iterator OutXIterator;
    typedef typename OutImageT::SinglePixel OutPixel;

    assertDimensionsOK(convolvedImage, inImage, kernel);

    int const inImageWidth = inImage.getWidth();
    int const inImageHeight = inImage.getHeight();
    int const kWidth = kernel.getWidth();
    int const kHeight = kernel.getHeight();
    int const cnvWidth = inImageWidth + 1 - kernel.getWidth();
    int const cnvHeight = inImageHeight + 1 - kernel.getHeight();
    int const cnvStartX = kernel.getCtrX();
    int const cnvStartY = kernel.getCtrY();
    int const cnvEndX = cnvStartX + cnvWidth;  // end index + 1
    int const cnvEndY = cnvStartY + cnvHeight; // end index + 1

    KernelImage kernelImage(kernel.getDimensions());
    KernelXYLocator const kernelLoc = kernelImage.xy_at(0,0);

    if (kernel.isSpatiallyVarying()) {
        pexLog::TTrace<5>("lsst.afw.math.convolve",
            "convolveWithBruteForce: kernel is spatially varying");

        CheckForceGpuOnUnsupportedKernel(convolutionControl);

        for (int cnvY = cnvStartY; cnvY != cnvEndY; ++cnvY) {
            double const rowPos = inImage.indexToPosition(cnvY, afwImage::Y);

            InXYLocator  inImLoc =  inImage.xy_at(0, cnvY - cnvStartY);
            OutXIterator cnvXIter = convolvedImage.x_at(cnvStartX, cnvY);
            for (int cnvX = cnvStartX; cnvX != cnvEndX; ++cnvX, ++inImLoc.x(), ++cnvXIter) {
                double const colPos = inImage.indexToPosition(cnvX, afwImage::X);

                KernelPixel kSum = kernel.computeImage(kernelImage, false, colPos, rowPos);
                *cnvXIter = afwMath::convolveAtAPoint<OutImageT, InImageT>(
                    inImLoc, kernelLoc, kWidth, kHeight);
                if (doNormalize) {
                    *cnvXIter = *cnvXIter/kSum;
                }
            }
        }
    } else {
        pexLog::TTrace<5>("lsst.afw.math.convolve",
            "convolveWithBruteForce: kernel is spatially invariant");

        CheckForceGpuOnNoGpu(convolutionControl);
        if (lsst::afw::gpu::isGpuBuild() && lsst::afw::gpu::isGpuEnabled()==true) {
            if (convolutionControl.getDevicePreference() == lsst::afw::gpu::AUTO_WITH_CPU_FALLBACK) {
                try {
                    mathDetail::ConvolveGpuStatus::ReturnCode rc =
                              mathDetail::convolveSpatiallyInvariantGPU(convolvedImage,inImage,kernel,
                                                                                 convolutionControl);
                    if (rc == mathDetail::ConvolveGpuStatus::OK) return;
                } catch(lsst::afw::gpu::GpuMemoryError) { }
                catch(pexExcept::MemoryError) { }
                catch(lsst::afw::gpu::GpuRuntimeError) { }
            } else if (convolutionControl.getDevicePreference() != lsst::afw::gpu::USE_CPU) {
                mathDetail::ConvolveGpuStatus::ReturnCode rc =
                            mathDetail::convolveSpatiallyInvariantGPU(convolvedImage,inImage,kernel,
                                                                             convolutionControl);
                if (rc == mathDetail::ConvolveGpuStatus::OK) return;
                if (convolutionControl.getDevicePreference() == lsst::afw::gpu::USE_GPU) {
                    throw LSST_EXCEPT(pexExcept::RuntimeError, "Gpu will not process this kernel");
                }
            }
        }

        (void)kernel.computeImage(kernelImage, doNormalize);

        for (int inStartY = 0, cnvY = cnvStartY; inStartY < cnvHeight; ++inStartY, ++cnvY) {
            KernelXIterator kernelXIter = kernelImage.x_at(0, 0);
            InXIterator inXIter = inImage.x_at(0, inStartY);
            OutXIterator cnvXIter = convolvedImage.x_at(cnvStartX, cnvY);
            for (int x = 0; x < cnvWidth; ++x, ++cnvXIter, ++inXIter) {
                *cnvXIter = kernelDotProduct<OutPixel, InXIterator, KernelXIterator, KernelPixel>(
                    inXIter, kernelXIter, kWidth);
            }
            for (int kernelY = 1, inY = inStartY + 1; kernelY < kHeight; ++inY, ++kernelY) {
                KernelXIterator kernelXIter = kernelImage.x_at(0, kernelY);
                InXIterator inXIter = inImage.x_at(0, inY);
                OutXIterator cnvXIter = convolvedImage.x_at(cnvStartX, cnvY);
                for (int x = 0; x < cnvWidth; ++x, ++cnvXIter, ++inXIter) {
                    *cnvXIter += kernelDotProduct<OutPixel, InXIterator, KernelXIterator, KernelPixel>(
                        inXIter, kernelXIter, kWidth);
                }
            }
        }
    }
}

void lsst::afw::math::printKernel	(	lsst::afw::math::Kernel const &	kernel,
		bool	doNormalize,
		double	xPos = 0,
		double	yPos = 0,
		std::string	pixelFmt = "%7.3f"
	)

Print the pixel values of a Kernel to std::cout.

Rows increase upward and columns to the right; thus the lower left pixel is (0,0).

Parameters

kernel	the kernel
doNormalize	if true, normalize kernel
xPos	x at which to evaluate kernel
yPos	y at which to evaluate kernel
pixelFmt	format for pixel values

Definition at line 46 of file KernelFunctions.cc.

  {
    typedef lsst::afw::math::Kernel::Pixel Pixel;

    lsst::afw::image::Image<Pixel> kImage(kernel.getDimensions());
    double kSum = kernel.computeImage(kImage, doNormalize, xPos, yPos);

    for (int y = kImage.getHeight() - 1; y >= 0; --y) {
        for (lsst::afw::image::Image<Pixel>::const_x_iterator ptr = kImage.row_begin(y);
             ptr != kImage.row_end(y); ++ptr) {
            std::cout << boost::format(pixelFmt) % *ptr << " ";
        }
        std::cout << std::endl;
    }

    if (doNormalize && std::abs(static_cast<double>(kSum) - 1.0) > 1.0e-5) {
        std::cout << boost::format("Warning! Sum of all pixels = %9.5f != 1.0\n") % kSum;
    }
    std::cout << std::endl;
}