Class Psf

Inheritance Relationships

Base Types

Derived Types

Class Documentation

class Psf : public lsst::afw::table::io::PersistableFacade<Psf>, public Storable

A polymorphic base class for representing an image’s Point Spread Function

Most of a Psf’s functionality involves its evaluation at a position and color, either or both of which may be unspecified (which will result in evaluation at some average position or color). Unlike the closely-related Kernel class, there is no requirement that a Psf have a well-defined spatial function or any parameters. Psfs are not necessarily continuous, and the dimensions of image of the Psf at a point may not be fixed.

Psfs have two methods for getting at image at a point:

  • the image returned by computeImage() is in the same coordinate system as the pixelized image

  • the image returned by computeKernelImage() is in an offset coordinate system with the point P at (0,0); this implies that the image (x0,y0) will be negative

Because P does not need to have integer coordinates, these two images are fractionally offset from each other and we use interpolation to get (1) from (2).

Psfs are immutable - derived classes should have no non-const methods, and hence should be fully-defined after construction. This allows shared_ptrs to Psfs to be passed around and shared between objects without concern for whether they will be unexpectedly modified.

In most cases, Psf derived classes should inherit from meas::algorithms::ImagePsf or meas::algorithms::KernelPsf, as these will provide default implementions for several member functions.

Subclassed by lsst::afw::detection::GaussianPsf, lsst::meas::algorithms::ImagePsf

Public Types

enum ImageOwnerEnum

Enum passed to computeImage and computeKernelImage to determine image ownership.

Values:

COPY = 0

The image will be copied before returning; caller will own it.

INTERNAL = 1

An internal image will be returned without copying. The caller must not modify it, and it may be invalidated the next time a Psf member function is called with different color and/or position.

typedef math::Kernel::Pixel Pixel

Pixel type of Image returned by computeImage.

typedef image::Image<Pixel> Image

Image type returned by computeImage.

Public Functions

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

Polymorphic deep-copy.

Because Psfs are immutable, clones should generally be unnecessary, but they may be useful in allowing Psfs to maintain separate caches for their most recently returned images.

std::shared_ptr<typehandling::Storable> cloneStorable() const

This method is an alias of clone that can be called from a reference to Storable.

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

Return clone with specified kernel dimensions

Must be implemented by derived classes.

Parameters

  • [in] width: Number of columns in pixels

  • [in] height: Number of rows in pixels

std::shared_ptr<Image> computeImage(lsst::geom::Point2D position = makeNullPoint(), image::Color color = image::Color(), ImageOwnerEnum owner = COPY) const

Return an Image of the PSF, in a form that can be compared directly with star images.

The specified position is a floating point number, and the resulting image will have a Psf centered on that point when the returned image’s xy0 is taken into account.

The returned image is normalized to sum to unity.

The

Psf class caches the most recent return value of computeImage, so repeated calls with the same arguments will be highly optimized.
Parameters

  • [in] position: Position to evaluate the PSF at; defaults to getAveragePosition().

  • [in] color: Color of the source for which to evaluate the PSF; defaults to getAverageColor().

  • [in] owner: Whether to copy the return value or return an internal image that must be handled with care (see ImageOwnerEnum).

Note

The real work is done in the virtual private member function Psf::doComputeImage; computeImage only handles caching and default arguments.

std::shared_ptr<Image> computeKernelImage(lsst::geom::Point2D position = makeNullPoint(), image::Color color = image::Color(), ImageOwnerEnum owner = COPY) const

Return an Image of the PSF, in a form suitable for convolution.

While the position need not be an integer, the center of the PSF image returned by computeKernelImage will in the center of the center pixel of the image, which will be (0,0) when the Image’s xy0 is taken into account; this is the same behavior as Kernel::computeImage().

The returned image is normalized to sum to unity.

The

Psf class caches the most recent return value of computeKernelImage, so repeated calls with the same arguments will be highly optimized.
Parameters

  • [in] position: Position to evaluate the PSF at; defaults to getAveragePosition().

  • [in] color: Color of the source for which to evaluate the PSF; defaults to getAverageColor().

  • [in] owner: Whether to copy the return value or return an internal image that must be handled with care (see ImageOwnerEnum).

Note

The real work is done in the virtual private member function Psf::doComputeKernelImage; computeKernelImage only handles caching and default arguments.

double computePeak(lsst::geom::Point2D position = makeNullPoint(), image::Color color = image::Color()) const

Return the peak value of the PSF image.

This calls computeKernelImage internally, but because this will usually be cached, it shouldn’t be expensive (but be careful not to accidentally call it with no arguments when you actually want to call it with the same arguments just used to call computeImage or computeKernelImage).

Parameters

double computeApertureFlux(double radius, lsst::geom::Point2D position = makeNullPoint(), image::Color color = image::Color()) const

Compute the “flux” of the Psf model within a circular aperture of the given radius.

The flux is relative to a

Psf image that has been normalized to unit integral, and the radius is in pixels.
Parameters

  • [in] radius: Radius of the aperture to measure.

  • [in] position: Position to evaluate the PSF at; defaults to getAveragePosition().

  • [in] color: Color of the source for which to evaluate the PSF; defaults to getAverageColor().

geom::ellipses::Quadrupole computeShape(lsst::geom::Point2D position = makeNullPoint(), image::Color color = image::Color()) const

Compute the ellipse corresponding to the second moments of the Psf.

The algorithm used to compute the moments is up to the derived class, and hence this method should not be used when a particular algorithm or weight function is required.

Parameters

std::shared_ptr<math::Kernel const> getLocalKernel(lsst::geom::Point2D position = makeNullPoint(), image::Color color = image::Color()) const

Return a FixedKernel corresponding to the Psf image at the given point.

This is implemented by calling computeKernelImage, and is simply provided for convenience.

image::Color getAverageColor() const

Return the average Color of the stars used to construct the Psf

This is also the Color used to return an image if you don’t specify a Color.

virtual lsst::geom::Point2D getAveragePosition() const

Return the average position of the stars used to construct the Psf.

This is also the position used to return an image if you don’t specify a position.

lsst::geom::Box2I computeBBox(lsst::geom::Point2D position = makeNullPoint(), image::Color color = image::Color()) const

Return the bounding box of the image returned by computeKernelImage()

std::size_t getCacheCapacity() const

Return the capacity of the caches

Both the image and kernel image caches have the same capacity.

void setCacheCapacity(std::size_t capacity)

Set the capacity of the caches

Both the image and kernel image caches will be set to this capacity.

Public Static Functions

static std::shared_ptr<Image> recenterKernelImage(std::shared_ptr<Image> im, lsst::geom::Point2D const &position, std::string const &warpAlgorithm = "lanczos5", unsigned int warpBuffer = 5)

Helper function for Psf::doComputeImage(): converts a kernel image (centered at (0,0) when xy0 is taken into account) to an image centered at position when xy0 is taken into account.

warpAlgorithm is passed to afw::math::makeWarpingKernel() and can be “nearest”, “bilinear”, or “lanczosN”

warpBuffer zero-pads the image before recentering. Recommended value is 1 for bilinear, N for lanczosN (note that it would be cleaner to infer this value from the warping algorithm but this would require mild API changes; same issue occurs in e.g. afw::math::offsetImage()).

The point with integer coordinates (0,0) in the source image (with xy0 taken into account) corresponds to the point position in the destination image. If position is not integer-valued then we will need to fractionally shift the image using interpolation.

Note: if fractional recentering is performed, then a new image will be allocated and returned. If not, then the original image will be returned (after setting XY0).

Protected Functions

Psf(bool isFixed = false, std::size_t capacity = 100)

Main constructor for subclasses.

Parameters

  • [in] isFixed: Should be true for Psf for which doComputeKernelImage always returns the same image, regardless of color or position arguments.

  • [in] capacity: Capacity of the caches.