gaussianPsfFactory.py

Go to the documentation of this file.

#
# LSST Data Management System
#
# Copyright 2008-2017  AURA/LSST.
#
# This product includes software developed by the
# LSST Project (http://www.lsst.org/).
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
#
# You should have received a copy of the LSST License Statement and
# the GNU General Public License along with this program.  If not,
# see <https://www.lsstcorp.org/LegalNotices/>.
#
 
__all__ = ["GaussianPsfFactory", "SigmaPerFwhm"]
 
import math
 
from lsst.pex.config import Config, Field, ConfigurableField
from ._algorithmsLib import DoubleGaussianPsf, SingleGaussianPsf
 
SigmaPerFwhm = 1.0 / (2.0 * math.sqrt(2.0 * math.log(2.0)))
 
 
def isPositive(x):
    return x > 0
 
 
class GaussianPsfFactory(Config):
    """Factory for simple Gaussian PSF models
 
    Provides a high-level interface to DoubleGaussianPsf and SingleGaussianPsf
    by specifying Gaussian PSF model width in FWHM instead of sigma,
    and supporting computing kernel size as a multiple of PSF width.
    This makes it suitable for tasks where PSF width is not known in advance.
    """
    size = Field(
        doc="Kernel size (width and height) (pixels); if None then sizeFactor is used",
        dtype=int,
        optional=True,
        default=None,
        check=isPositive,
    )
    sizeFactor = Field(
        doc="Kernel size as a factor of fwhm (dimensionless); "
            "size = sizeFactor * fwhm; ignored if size is not None",
        dtype=float,
        optional=False,
        default=3.0,
        check=isPositive,
    )
    minSize = Field(
        doc="Minimum kernel size if using sizeFactor (pixels); ignored if size is not None",
        dtype=int,
        optional=True,
        default=5,
        check=isPositive,
    )
    maxSize = Field(
        doc="Maximum kernel size if using sizeFactor (pixels); ignored if size is not None",
        dtype=int,
        optional=True,
        default=None,
        check=isPositive,
    )
    defaultFwhm = Field(
        doc="Default FWHM of Gaussian model of core of star (pixels)",
        dtype=float,
        default=3.0,
        check=isPositive,
    )
    addWing = Field(
        doc="Add a Gaussian to represent wings?",
        dtype=bool,
        optional=False,
        default=True,
    )
    wingFwhmFactor = Field(
        doc="wing width, as a multiple of core width (dimensionless); ignored if addWing false",
        dtype=float,
        optional=False,
        default=2.5,
        check=isPositive,
    )
    wingAmplitude = Field(
        doc="wing amplitude, as a multiple of core amplitude (dimensionless); ignored if addWing false",
        dtype=float,
        optional=False,
        default=0.1,
        check=isPositive,
    )
 
    def computeSizeAndSigma(self, fwhm=None):
        """Compute kernel size and star width as sigma. The kernel size will be
        odd unless minSize or maxSize is used and that value is even. Assumes
        a valid config.
 
        Parameters
        ----------
        fwhm : `float`
            FWHM of core star (pixels); if None then defaultFwhm is used
 
        Returns
        -------
        size : `int`
            Kernel size (width == height) in pixels
        sigma : `float`
            Sigma equivalent to supplied FWHM, assuming a Gaussian (pixels)
        """
        if fwhm is None:
            fwhm = self.defaultFwhm
 
        if self.size is not None:
            size = self.size
        else:
            desSize = (int(self.sizeFactor * fwhm) // 2) * 2 + 1  # make result odd
            if self.minSize and self.minSize > desSize:
                size = self.minSize
            elif self.maxSize and self.maxSize < desSize:
                size = self.maxSize
            else:
                size = desSize
 
        return size, fwhm * SigmaPerFwhm
 
    def validate(self):
        Config.validate(self)
        if self.minSize and self.maxSize and self.minSize > self.maxSize:
            raise RuntimeError("minSize=%s > maxSize=%s" % (self.minSize, self.maxSize))
 
    def apply(self, fwhm=None):
        """Construct a GaussianPsf
 
        Parameters
        ----------
        fwhm : `float`
            FWHM of core of star (pixels); if None then self.defaultFwhm is used
 
        Returns
        -------
        DoubleGaussianPsf : ``lsst.meas.algorithms.DoubleGaussianPsf``
            Returns if self.addWing is True
        SingleGaussianPsf : ``lsst.meas.algorithms.SingleGaussianPsf``
            Returns if self.addWing is False
        """
        kernelSize, sigma = self.computeSizeAndSigma(fwhm)
        if self.addWing:
            wingsSigma = sigma * self.wingFwhmFactor
            return DoubleGaussianPsf(kernelSize, kernelSize, sigma, wingsSigma, self.wingAmplitude)
        else:
            return SingleGaussianPsf(kernelSize, kernelSize, sigma)
 
    @classmethod
    def makeField(cls, doc):
        """Make an lsst.pex.config.ConfigurableField
        """
        def applyWrapper(config, **kwargs):
            """Construct a Gaussian PSF
 
            Parameters
            ----------
            config : instance of ``GaussianPsfFactory``
            """
            return config.apply(**kwargs)
        return ConfigurableField(
            doc=doc,
            target=applyWrapper,
            ConfigClass=cls
        )