Class LinearCombinationKernel

Inheritance Relationships

Base Types

Class Documentation

class LinearCombinationKernel : public lsst::afw::table::io::PersistableFacade<LinearCombinationKernel>, public lsst::afw::math::Kernel

A kernel that is a linear combination of fixed basis kernels.

Convolution may be performed by first convolving the image with each fixed kernel, then adding the resulting images using the (possibly spatially varying) kernel coefficients.

The basis kernels are cloned (deep copied) so you may safely modify your own copies.

Warnings:

  • This class does not normalize the individual basis kernels; they are used “as is”.

Public Functions

LinearCombinationKernel()

Construct an empty LinearCombinationKernel of size 0x0

LinearCombinationKernel(KernelList const &kernelList, std::vector<double> const &kernelParameters)

Construct a spatially invariant LinearCombinationKernel

Parameters

  • kernelList: list of (shared pointers to const) basis kernels

  • kernelParameters: kernel coefficients

LinearCombinationKernel(KernelList const &kernelList, Kernel::SpatialFunction const &spatialFunction)

Construct a spatially varying LinearCombinationKernel, where the spatial model is described by one function (that is cloned to give one per basis kernel).

Parameters

  • kernelList: list of (shared pointers to const) basis kernels

  • spatialFunction: spatial function; one deep copy is made for each basis kernel

LinearCombinationKernel(KernelList const &kernelList, std::vector<Kernel::SpatialFunctionPtr> const &spatialFunctionList)

Construct a spatially varying LinearCombinationKernel, where the spatial model is described by a list of functions (one per basis kernel).

Parameters

  • kernelList: list of (shared pointers to const) kernels

  • spatialFunctionList: list of spatial functions, one per basis kernel

Exceptions

  • lsst::pex::exceptions::InvalidParameterError: if the length of spatialFunctionList != # kernels

LinearCombinationKernel(const LinearCombinationKernel&)
LinearCombinationKernel(LinearCombinationKernel&&)
LinearCombinationKernel &operator=(const LinearCombinationKernel&)
LinearCombinationKernel &operator=(LinearCombinationKernel&&)
~LinearCombinationKernel()
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

std::shared_ptr<Kernel> resized(int width, int height) const

Return a pointer to a clone with specified kernel dimensions

Must be implemented by derived classes.

Return

a pointer to a clone with new dimensions.

Parameters

  • width: Number of columns in pixels

  • height: Number of rows in pixels

std::vector<double> getKernelParameters() const

Return the current kernel parameters

If the kernel is spatially varying then the parameters are those last computed. See also computeKernelParametersFromSpatialModel. If there are no kernel parameters then returns an empty vector.

virtual KernelList const &getKernelList() const

Get the fixed basis kernels

std::vector<double> getKernelSumList() const

Get the sum of the pixels of each fixed basis kernel

int getNBasisKernels() const

Get the number of basis kernels

void checkKernelList(const KernelList &kernelList) const

Check that all kernels have the same size and center and that none are spatially varying

Exceptions

  • lsst::pex::exceptions::InvalidParameterError: if the check fails

bool isDeltaFunctionBasis() const

Return true if all basis kernels are instances of DeltaFunctionKernel

std::shared_ptr<Kernel> refactor() const

Refactor the kernel as a linear combination of N bases where N is the number of parameters for the spatial model.

Refactoring is only possible if all of the following are true:

  • Kernel is spatially varying

  • The spatial functions are a linear combination of coefficients (return isLinearCombination() true).

  • The spatial functions all are the same class (and so have the same functional form) Refactoring produces a kernel that is faster to compute only if the number of basis kernels is greater than the number of parameters in the spatial model.

Details: A spatially varying LinearCombinationKernel consisting of M basis kernels and using a spatial model that is a linear combination of N coefficients can be expressed as: K(x,y) = K0 (C00 F0(x,y) + C10 F1(x,y) + C20 F2(x,y) + … + CN0 FN(x,y))

  • K1 (C01 F0(x,y) + C11 F1(x,y) + C21 F2(x,y) + … + CN1 FN(x,y))

  • K2 (C02 F0(x,y) + C12 F1(x,y) + C22 F2(x,y) + … + CN2 FN(x,y))

  • …

  • KM (C0M F0(x,y) + C1M F1(x,y) + C2M F2(x,y) + … + CNM FN(x,y))

This is equivalent to the following linear combination of N basis kernels: 

    =      K0' F0(x,y) + K1' F1(x,y) + K2' F2(x,y) + ... + KN' FN(x,y)

      where Ki' = sum over j of Kj Cij

This is what refactor returns provided the required conditions are met. However, the spatial functions for the refactored kernel are the same as those for the original kernel (for generality and simplicity) with all coefficients equal to 0 except one that is set to 1; hence they are not computed optimally.

Thanks to Kresimir Cosic for inventing or reinventing this useful technique.

Return

a shared pointer to new kernel, or empty pointer if refactoring not possible

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

Return a string representation of the kernel

bool isPersistable() const

Return true if this particular object can be persisted using afw::table::io.

Protected Functions

double doComputeImage(lsst::afw::image::Image<Pixel> &image, bool doNormalize) const

Low-level version of computeImage

Before this is called the image dimensions are checked, the image’s xy0 is set and the kernel’s parameters are set. This routine sets the pixels, including normalization if requested.

Return

The kernel sum

Parameters

  • image: image whose pixels are to be set (output)

  • doNormalize: normalize the image (so sum is 1)?

std::string getPersistenceName() const

Return the unique name used to persist this object and look up its factory.

Must be less than ArchiveIndexSchema::MAX_NAME_LENGTH characters.

void write(OutputArchiveHandle &handle) const

Write the object to one or more catalogs.

The handle object passed to this function provides an interface for adding new catalogs and adding nested objects to the same archive (while checking for duplicates). See OutputArchiveHandle for more information.

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)