Class Kernel

Nested Relationships

Inheritance Relationships

Base Types

Derived Types

Class Documentation

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

Kernels are used for convolution with MaskedImages and (eventually) Images

Kernel is a virtual base class; it cannot be instantiated. The following notes apply to Kernel and to its subclasses.

The template type should usually be float or double; integer kernels should be used with caution because they do not normalize well.

The center pixel of a Kernel is at index: (width-1)/2, (height-1)/2. Thus it is centered along columns/rows if the kernel has an odd number of columns/rows and shifted 1/2 pixel towards 0 otherwise. A kernel should have an odd number of columns and rows unless it is intended to shift an image.

Spatially Varying Kernels

Kernels may optionally vary spatially (so long as they have any kernel parameters). To make a spatially varying kernel, specify a spatial function at construction (you cannot change your mind once the kernel is constructed). You must also specify a set of spatial parameters, and you may do this at construction and/or later by calling setSpatialParameters. The spatial parameters are a vector (one per kernel function parameter) of spatial function parameters. In other words the spatial parameters are a vector of vectors indexed as [kernel parameter][spatial parameter]. The one spatial function is used to compute the kernel parameters at a given spatial position by computing each kernel parameter using its associated vector of spatial function parameters.

The convolve function computes the spatial function at the pixel position (not index) of the image. See the convolve function for details.

Note that if a kernel is spatially varying then you may not set the kernel parameters directly; that is the job of the spatial function! However, you may change the spatial parameters at any time.

Design Notes

The basic design is to use the same kernel class for both spatially varying and spatially invariant kernels. The user either does or does not supply a function describing the spatial variation at creation time. In addition, analytic kernels are described by a user-supplied function of the same basic type as the spatial variation function.

Several other designs were considered, including: A) Use different classes for spatially varying and spatially invariant versions of each kernel. Thus instead of three basic kernel classes (FixedKernel, AnalyticKernel and LinearCombinationKernel) we would have five (since FixedKernel cannot be spatially varying). Robert Lupton argued that was a needless expansion of the class hiearchy and I agreed. B) Construct analytic kernels by defining a subclass of AnalyticKernel that is specific to the desired functional (e.g. GaussianAnalyticKernel). If spatial models are handled the same way then this creates a serious proliferation of kernel classes (even if we only have two different spatial models, e.g. polynomial and Chebyshev polynomial). I felt it made more sense to define the spatial model by some kind of function class (often called a “functor”), and since we needed such a class, I chose to use it for the analytic kernel as well.

However, having a separate function class does introduce some potential inefficiencies. If a function is part of the class it can potentially be evaluated more quickly than calling a function for each pixel or spatial position.

A possible variant on the current design is to define the spatial model and analytic kernel by specifying the functions as template parameters. This has the potential to regain some efficiency in evaluating the functions. However, it would be difficult or impossible to pre-instantiate the desired template classes, a requirement of the LSST coding standards.

Subclassed by lsst::afw::math::AnalyticKernel, lsst::afw::math::DeltaFunctionKernel, lsst::afw::math::FixedKernel, lsst::afw::math::LinearCombinationKernel, lsst::afw::math::SeparableKernel

Public Types

typedef double Pixel
typedef std::shared_ptr<lsst::afw::math::Function2<double>> SpatialFunctionPtr
typedef lsst::afw::math::Function2<double> SpatialFunction
typedef lsst::afw::math::NullFunction2<double> NullSpatialFunction
typedef generic_kernel_tag kernel_fill_factor

Public Functions

Kernel()

Construct a null Kernel of size 0,0.

A null constructor is primarily intended for persistence.

Kernel(int width, int height, unsigned int nKernelParams, SpatialFunction const &spatialFunction = NullSpatialFunction())

Construct a spatially invariant Kernel or a spatially varying Kernel with one spatial function that is duplicated as needed.

Parameters

  • width: number of columns

  • height: number of height

  • nKernelParams: number of kernel parameters

  • spatialFunction: spatial function, or NullSpatialFunction() if none specified

Exceptions

  • lsst::pex::exceptions::InvalidParameterError: if a spatial function is specified and the kernel has no parameters.

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

Kernel(int width, int height, const std::vector<SpatialFunctionPtr> spatialFunctionList)

Construct a spatially varying Kernel with a list of spatial functions (one per kernel parameter)

Note: if the list of spatial functions is empty then the kernel is not spatially varying.

Parameters

  • width: number of columns

  • height: number of height

  • spatialFunctionList: list of spatial function, one per kernel parameter

Exceptions

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

Kernel(const Kernel&)
Kernel(Kernel&&)
Kernel &operator=(const Kernel&)
Kernel &operator=(Kernel&&)
~Kernel()
virtual std::shared_ptr<Kernel> clone() const = 0

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

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

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

double computeImage(lsst::afw::image::Image<Pixel> &image, bool doNormalize, double x = 0.0, double y = 0.0) const

Compute an image (pixellized representation of the kernel) in place

Return

The kernel sum

Note

computeNewImage has been retired; it doesn’t need to be a member

Parameters

  • image: image whose pixels are to be set (output); xy0 of the image will be set to -kernel.getCtr()

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

  • x: x (column position) at which to compute spatial function

  • y: y (row position) at which to compute spatial function

Exceptions

  • lsst::pex::exceptions::InvalidParameterError: if the image is the wrong size

  • lsst::pex::exceptions::OverflowError: if doNormalize is true and the kernel sum is exactly 0

lsst::geom::Extent2I const getDimensions() const

Return the Kernel’s dimensions (width, height)

void setDimensions(lsst::geom::Extent2I dims)
void setWidth(int width)
void setHeight(int height)
int getWidth() const

Return the Kernel’s width

int getHeight() const

Return the Kernel’s height

lsst::geom::Point2I getCtr() const

Return index of kernel’s center

int getCtrX() const

Return x index of kernel’s center

int getCtrY() const

Return y index of kernel’s center

lsst::geom::Box2I getBBox() const

return parent bounding box, with XY0 = -center

unsigned int getNKernelParameters() const

Return the number of kernel parameters (0 if none)

int getNSpatialParameters() const

Return the number of spatial parameters (0 if not spatially varying)

SpatialFunctionPtr getSpatialFunction(unsigned int index) const

Return a clone of the specified spatial function (one component of the spatial model)

Return

a shared pointer to a spatial function. The function is a deep copy, so setting its parameters has no effect on the kernel.

Parameters

  • index: index of desired spatial function; must be in range [0, number spatial parameters - 1]

Exceptions

  • lsst::pex::exceptions::InvalidParameterError: if kernel not spatially varying

  • lsst::pex::exceptions::InvalidParameterError: if index out of range

std::vector<SpatialFunctionPtr> getSpatialFunctionList() const

Return a list of clones of the spatial functions.

Return

a list of shared pointers to spatial functions. The functions are deep copies, so setting their parameters has no effect on the kernel.

virtual double getKernelParameter(unsigned int i) const

Return a particular Kernel Parameter (no bounds checking). This version is slow, but specialisations may be faster

virtual 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.

lsst::geom::Box2I growBBox(lsst::geom::Box2I const &bbox) const

Given a bounding box for pixels one wishes to compute by convolving an image with this kernel, return the bounding box of pixels that must be accessed on the image to be convolved. Thus the box shifted by -kernel.getCtr() and its size is expanded by kernel.getDimensions()-1.

Return

the bbox expanded by the kernel.

lsst::geom::Box2I shrinkBBox(lsst::geom::Box2I const &bbox) const

Given a bounding box for an image one wishes to convolve with this kernel, return the bounding box for the region of pixels that can be computed. Thus the box shifted by kernel.getCtr() and its size is reduced by kernel.getDimensions()-1.

Return

the bbox shrunk by the kernel.

Exceptions

  • lsst::pex::exceptions::InvalidParameterError: if the resulting box would have dimension < 1 in either axis

void setCtr(lsst::geom::Point2I ctr)

Set index of kernel’s center

void setCtrX(int ctrX)

Set x index of kernel’s center

void setCtrY(int ctrY)

Set y index of kernel’s center

std::vector<std::vector<double>> getSpatialParameters() const

Return the spatial parameters parameters (an empty vector if not spatially varying)

bool isSpatiallyVarying() const

Return true iff the kernel is spatially varying (has a spatial function)

void setKernelParameters(std::vector<double> const &params)

Set the kernel parameters of a spatially invariant kernel.

Exceptions

  • lsst::pex::exceptions::RuntimeError: if the kernel has a spatial function

  • lsst::pex::exceptions::InvalidParameterError: if the params vector is the wrong length

void setKernelParameters(std::pair<double, double> const &params)

Set the kernel parameters of a 2-component spatially invariant kernel.

Warning

This is a low-level method intended for maximum efficiency when using warping kernels. No error checking is performed. Use the std::vector<double> form if you want safety.

void setSpatialParameters(const std::vector<std::vector<double>> params)

Set the parameters of all spatial functions

Params is indexed as [kernel parameter][spatial parameter]

Exceptions

  • lsst::pex::exceptions::InvalidParameterError: if params is the wrong shape (if this exception is thrown then no parameters are changed)

void computeKernelParametersFromSpatialModel(std::vector<double> &kernelParams, double x, double y) const

Compute the kernel parameters at a specified point

Warning: this is a low-level function that assumes kernelParams is the right length. It will fail in unpredictable ways if that condition is not met.

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

Return a string representation of the kernel

virtual void computeCache(int const)

Parameters

  • const: desired cache size

Compute a cache of Kernel values, if desired

Warning

: few kernel classes actually support this, in which case this is a no-op and getCacheSize always returns 0.

virtual int getCacheSize() const

Get the current size of the kernel cache (0 if none or if caches not supported)

Protected Functions

std::string getPythonModule() const

Return the fully-qualified Python module that should be imported to guarantee that its factory is registered.

Must be less than ArchiveIndexSchema::MAX_MODULE_LENGTH characters.

Will be ignored if empty.

virtual 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)

void setKernelParametersFromSpatialModel(double x, double y) const

Set the kernel parameters from the spatial model (if any).

This function has no effect if there is no spatial model.

This function is marked “const”, despite modifying unimportant internals, so that computeImage can be const.

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

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)?

Protected Attributes

std::vector<SpatialFunctionPtr> _spatialFunctionList
struct PersistenceHelper

Public Functions

PersistenceHelper(int nSpatialFunctions)
PersistenceHelper(afw::table::Schema const &schema_)
std::shared_ptr<afw::table::BaseRecord> write(afw::table::io::OutputArchiveHandle &handle, Kernel const &kernel) const
void writeSpatialFunctions(afw::table::io::OutputArchiveHandle &handle, afw::table::BaseRecord &record, std::vector<SpatialFunctionPtr> const &spatialFunctionList) const
std::vector<SpatialFunctionPtr> readSpatialFunctions(afw::table::io::InputArchive const &archive, afw::table::BaseRecord const &record) const

Public Members

afw::table::Schema schema
afw::table::PointKey<int> dimensions
afw::table::PointKey<int> center
afw::table::Key<afw::table::Array<int>> spatialFunctions