File Kernel.h¶

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

Typedefs

typedef std::vector<std::shared_ptr<Kernel>> KernelList¶

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

#include <Kernel.h>

A kernel described by a function.

The function’s x, y arguments are as follows:

-getCtr() for the lower left corner pixel
0, 0 for the center pixel
(getDimensions() - 1) - getCtr() for the upper right pixel

Note: each pixel is set to the value of the kernel function at the center of the pixel (rather than averaging the function over the area of the pixel).

Public Types

typedef lsst::afw::math::Function2<Pixel> KernelFunction

typedef std::shared_ptr<lsst::afw::math::Function2<Pixel>> KernelFunctionPtr

Public Functions

AnalyticKernel(): Construct an empty spatially invariant AnalyticKernel of size 0x0

AnalyticKernel(int width, int height, KernelFunction const &kernelFunction, Kernel::SpatialFunction const &spatialFunction = NullSpatialFunction())

Construct a spatially invariant AnalyticKernel, or a spatially varying AnalyticKernel where the spatial model is described by one function (that is cloned to give one per analytic function parameter).

Parameters

width: width of kernel
height: height of kernel
kernelFunction: kernel function; a deep copy is made
spatialFunction: spatial function; one deep copy is made for each kernel function parameter; if omitted or set to Kernel::NullSpatialFunction() then the kernel is spatially invariant

AnalyticKernel(int width, int height, KernelFunction const &kernelFunction, std::vector<Kernel::SpatialFunctionPtr> const &spatialFunctionList)

Construct a spatially varying AnalyticKernel, where the spatial model is described by a list of functions (one per analytic function parameter).

Parameters

width: width of kernel
height: height of kernel
kernelFunction: kernel function; a deep copy is made
spatialFunctionList: list of spatial functions, one per kernel function parameter; a deep copy is made of each function

Exceptions

lsst::pex::exceptions::InvalidParameterError: if the length of spatialFunctionList != # kernel function parameters.

AnalyticKernel(const AnalyticKernel&)

AnalyticKernel(AnalyticKernel&&)

AnalyticKernel &operator=(const AnalyticKernel&)

AnalyticKernel &operator=(AnalyticKernel&&)

~AnalyticKernel()

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

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

This special version accepts any size image (though you can get in trouble if the image is large enough that the image is evaluated outside its domain).

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() - border, where border = (image.getDimensions() - kernel.getDimensions()) / 2
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

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 KernelFunctionPtr getKernelFunction() const: Get a deep copy of the kernel function

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)

Protected Attributes

KernelFunctionPtr _kernelFunctionPtr

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

#include <Kernel.h>

A kernel that has only one non-zero pixel (of value 1)

It has no adjustable parameters and so cannot be spatially varying.

Public Types

typedef deltafunction_kernel_tag kernel_fill_factor

Public Functions

DeltaFunctionKernel(int width, int height, lsst::geom::Point2I const &point)

Construct a spatially invariant DeltaFunctionKernel

Parameters

width: kernel size (columns)
height: kernel size (rows)
point: index of active pixel (where 0,0 is the lower left corner)

Exceptions

pex::exceptions::InvalidParameterError: if active pixel is off the kernel

DeltaFunctionKernel(const DeltaFunctionKernel&)

DeltaFunctionKernel(DeltaFunctionKernel&&)

DeltaFunctionKernel &operator=(const DeltaFunctionKernel&)

DeltaFunctionKernel &operator=(DeltaFunctionKernel&&)

~DeltaFunctionKernel()

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

lsst::geom::Point2I getPixel() const

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.

Private Members

lsst::geom::Point2I _pixel¶

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

#include <Kernel.h>

A kernel created from an Image

It has no adjustable parameters and so cannot be spatially varying.

Public Functions

FixedKernel(): Construct an empty FixedKernel of size 0x0

FixedKernel(lsst::afw::image::Image<Pixel> const &image)

Parameters

image: image for kernel

Construct a FixedKernel from an image

FixedKernel(lsst::afw::math::Kernel const &kernel, lsst::geom::Point2D const &pos)

Parameters

kernel: Kernel to convert to Fixed
pos: desired position

Construct a FixedKernel from a generic Kernel

FixedKernel(const FixedKernel&)

FixedKernel(FixedKernel&&)

FixedKernel &operator=(const FixedKernel&)

FixedKernel &operator=(FixedKernel&&)

~FixedKernel()

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::string toString(std::string const &prefix = "") const: Return a string representation of the kernel

virtual Pixel getSum() const

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.

Private Members

lsst::afw::image::Image<Pixel> _image¶

Pixel _sum¶

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

#include <Kernel.h>

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

Private Functions

virtual void _setKernelXY()¶

Private Members

int _width¶

int _height¶

int _ctrX¶

int _ctrY¶

unsigned int _nKernelParams¶

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

#include <Kernel.h>

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)

Private Functions

void _setKernelList(KernelList const &kernelList)¶: Set _kernelList by cloning each input kernel and update the kernel image cache.

Private Members

KernelList _kernelList¶: basis kernels

std::vector<std::shared_ptr<lsst::afw::image::Image<Pixel>>> _kernelImagePtrList¶: image of each basis kernel (a cache)

std::vector<double> _kernelSumList¶: sum of each basis kernel (a cache)

std::vector<double> _kernelParams¶

bool _isDeltaFunctionBasis¶

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

#include <Kernel.h>

A kernel described by a pair of functions: func(x, y) = colFunc(x) * rowFunc(y)

The function’s x, y arguments are as follows:

-getCtr() for the lower left corner pixel
0, 0 for the center pixel
(getDimensions() - 1) - getCtr() for the upper right pixel

Note: each pixel is set to the value of the kernel function at the center of the pixel (rather than averaging the function over the area of the pixel).

Subclassed by lsst::afw::math::BilinearWarpingKernel, lsst::afw::math::LanczosWarpingKernel, lsst::afw::math::NearestWarpingKernel

Public Types

typedef lsst::afw::math::Function1<Pixel> KernelFunction

typedef std::shared_ptr<KernelFunction> KernelFunctionPtr

Public Functions

SeparableKernel(): Construct an empty spatially invariant SeparableKernel of size 0x0

SeparableKernel(int width, int height, KernelFunction const &kernelColFunction, KernelFunction const &kernelRowFunction, Kernel::SpatialFunction const &spatialFunction = NullSpatialFunction())

Construct a spatially invariant SeparableKernel, or a spatially varying SeparableKernel that uses the same functional form to model each function parameter.

Parameters

width: width of kernel
height: height of kernel
kernelColFunction: kernel column function
kernelRowFunction: kernel row function
spatialFunction: spatial function; one deep copy is made for each kernel column and row function parameter; if omitted or set to Kernel::NullSpatialFunction then the kernel is spatially invariant

SeparableKernel(int width, int height, KernelFunction const &kernelColFunction, KernelFunction const &kernelRowFunction, std::vector<Kernel::SpatialFunctionPtr> const &spatialFunctionList)

Construct a spatially varying SeparableKernel

Parameters

width: width of kernel
height: height of kernel
kernelColFunction: kernel column function
kernelRowFunction: kernel row function
spatialFunctionList: list of spatial funcs, one per kernel column and row function parameter; a deep copy is made of each function

Exceptions

lsst::pex::exceptions::InvalidParameterError: if the length of spatialFunctionList != # kernel function parameters.

SeparableKernel(const SeparableKernel&)

SeparableKernel(SeparableKernel&&)

SeparableKernel &operator=(const SeparableKernel&)

SeparableKernel &operator=(SeparableKernel&&)

~SeparableKernel()

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

double computeVectors(std::vector<Pixel> &colList, std::vector<Pixel> &rowList, bool doNormalize, double x = 0.0, double y = 0.0) const

Compute the column and row arrays in place, where kernel(col, row) = colList(col) * rowList(row)

x, y are ignored if there is no spatial function.

Return

the kernel sum (1.0 if doNormalize true)

Parameters

colList: column vector
rowList: row vector
doNormalize: normalize the image (so sum of each 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 colList or rowList is the wrong size
lsst::pex::exceptions::OverflowError: if doNormalize is true and the kernel sum is exactly 0

double getKernelParameter(unsigned int i) const: Return a particular Kernel Parameter (no bounds checking). This version is slow, but specialisations may be faster

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.

KernelFunctionPtr getKernelColFunction() const: Get a deep copy of the col kernel function

KernelFunctionPtr getKernelRowFunction() const: Get a deep copy of the row kernel function

std::string toString(std::string const &prefix = "") const: Return a string representation of the kernel

void computeCache(int const const)

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.

int getCacheSize() const: Get the current cache size (0 if none)

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

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)

Private Functions

double basicComputeVectors(std::vector<Pixel> &colList, std::vector<Pixel> &rowList, bool doNormalize) const¶

Compute the column and row arrays in place, where kernel(col, row) = colList(col) * rowList(row)

Warning: the length of colList and rowList are not verified!

Return

the kernel sum (1.0 if doNormalize true)

Parameters

colList: column vector
rowList: row vector
doNormalize: normalize the arrays (so sum of each is 1)?

Exceptions

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

virtual void _setKernelXY()¶

Private Members

KernelFunctionPtr _kernelColFunctionPtr¶

KernelFunctionPtr _kernelRowFunctionPtr¶

std::vector<Pixel> _localColList¶

std::vector<Pixel> _localRowList¶

std::vector<double> _kernelX¶

std::vector<double> _kernelY¶

std::vector<std::vector<double>> _kernelRowCache¶

std::vector<std::vector<double>> _kernelColCache¶

Navigation

File Kernel.h¶