lsst::meas::base::ApertureFluxAlgorithm Class Reference

Base class for multiple-aperture photometry algorithms. More...

#include <ApertureFlux.h>

Inheritance diagram for lsst::meas::base::ApertureFluxAlgorithm:

Public Types
typedef ApertureFluxControl	Control
typedef ApertureFluxResult	Result
	Result object returned by static methods. More...

Public Member Functions
	ApertureFluxAlgorithm (Control const &ctrl, std::string const &name, afw::table::Schema &schema, daf::base::PropertySet &metadata)
	Construct the algorithm and add its fields to the given Schema. More...
virtual	~ApertureFluxAlgorithm ()
virtual void	measure (afw::table::SourceRecord &record, afw::image::Exposure< float > const &exposure) const =0
	Measure the configured apertures on the given image. More...
virtual void	fail (afw::table::SourceRecord &measRecord, MeasurementError *error=nullptr) const
	Handle an exception thrown by the current algorithm by setting flags in the given record. More...
virtual void	measureForced (afw::table::SourceRecord &measRecord, afw::image::Exposure< float > const &exposure, afw::table::SourceRecord const &refRecord, afw::geom::SkyWcs const &refWcs) const
	Called to measure a single child source in an image. More...
virtual void	measureNForced (afw::table::SourceCatalog const &measCat, afw::image::Exposure< float > const &exposure, afw::table::SourceCatalog const &refRecord, afw::geom::SkyWcs const &refWcs) const
	Called to simultaneously measure all children in a deblend family, in a single image. More...
virtual void	measureN (afw::table::SourceCatalog const &measCat, afw::image::Exposure< float > const &exposure) const
	Called to simultaneously measure all children in a deblend family, in a single image. More...
std::string	getLogName () const

Static Public Member Functions
static FlagDefinitionList const &	getFlagDefinitions ()
static std::string	makeFieldPrefix (std::string const &name, double radius)
	Construct an appropriate prefix for table fields. More...
template<typename T >
static Result	computeSincFlux (afw::image::Image< T > const &image, afw::geom::ellipses::Ellipse const &ellipse, Control const &ctrl=Control())
	Compute the instFlux (and optionally, uncertanties) within an aperture using Sinc photometry. More...
template<typename T >
static Result	computeSincFlux (afw::image::MaskedImage< T > const &image, afw::geom::ellipses::Ellipse const &ellipse, Control const &ctrl=Control())
	Compute the instFlux (and optionally, uncertanties) within an aperture using Sinc photometry. More...
template<typename T >
static Result	computeNaiveFlux (afw::image::Image< T > const &image, afw::geom::ellipses::Ellipse const &ellipse, Control const &ctrl=Control())
	Compute the instFlux (and optionally, uncertanties) within an aperture using naive photometry. More...
template<typename T >
static Result	computeNaiveFlux (afw::image::MaskedImage< T > const &image, afw::geom::ellipses::Ellipse const &ellipse, Control const &ctrl=Control())
	Compute the instFlux (and optionally, uncertanties) within an aperture using naive photometry. More...
template<typename T >
static Result	computeFlux (afw::image::Image< T > const &image, afw::geom::ellipses::Ellipse const &ellipse, Control const &ctrl=Control())
	Compute the instFlux (and optionally, uncertanties) within an aperture using the algorithm determined by its size and the maxSincRadius control parameter. More...
template<typename T >
static Result	computeFlux (afw::image::MaskedImage< T > const &image, afw::geom::ellipses::Ellipse const &ellipse, Control const &ctrl=Control())
	Compute the instFlux (and optionally, uncertanties) within an aperture using the algorithm determined by its size and the maxSincRadius control parameter. More...

Static Public Attributes
static unsigned int const	N_FLAGS = 3
static FlagDefinition const	FAILURE = flagDefinitions.addFailureFlag()
static FlagDefinition const	APERTURE_TRUNCATED
static FlagDefinition const	SINC_COEFFS_TRUNCATED

Protected Member Functions
void	copyResultToRecord (Result const &result, afw::table::SourceRecord &record, int index) const
FlagHandler const &	getFlagHandler (int index) const

Protected Attributes
Control const	_ctrl
SafeCentroidExtractor	_centroidExtractor
std::string	_logName

Detailed Description

Base class for multiple-aperture photometry algorithms.

ApertureFluxAlgorithm serves as an intermediate base class for all aperture fluxes, which it assumes have that capability of measuring multiple apertures (even if they are not always configured to do so).

Concrete implementations for single-aperture flux measurements are provided as static methods, as well as a consistent interface and control object for its derived classes. Currently, we only have one derived class, CircularApertureFluxAlgorithm, but in the future we anticipate adding more derived classes for e.g. elliptical apertures, or apertures that are circular in sky coordinates rather than pixel coordinates.

Definition at line 80 of file ApertureFlux.h.

Member Typedef Documentation

Control

typedef ApertureFluxControl lsst::meas::base::ApertureFluxAlgorithm::Control

Definition at line 89 of file ApertureFlux.h.

Result

typedef ApertureFluxResult lsst::meas::base::ApertureFluxAlgorithm::Result

Result object returned by static methods.

Definition at line 92 of file ApertureFlux.h.

Constructor & Destructor Documentation

ApertureFluxAlgorithm()

lsst::meas::base::ApertureFluxAlgorithm::ApertureFluxAlgorithm ( Control const &  ctrl, std::string const &  name, afw::table::Schema &  schema, daf::base::PropertySet &  metadata  )

explicit

Construct the algorithm and add its fields to the given Schema.

Definition at line 71 of file ApertureFlux.cc.

        : _ctrl(ctrl), _centroidExtractor(schema, name) {
    _keys.reserve(ctrl.radii.size());
    for (std::size_t i = 0; i < ctrl.radii.size(); ++i) {
        metadata.add(name + "_radii", ctrl.radii[i]);
        std::string prefix = ApertureFluxAlgorithm::makeFieldPrefix(name, ctrl.radii[i]);
        std::string doc = (boost::format("instFlux within %f-pixel aperture") % ctrl.radii[i]).str();
        _keys.push_back(Keys(schema, prefix, doc, ctrl.radii[i] <= ctrl.maxSincRadius));
    }
}

~ApertureFluxAlgorithm()

virtual lsst::meas::base::ApertureFluxAlgorithm::~ApertureFluxAlgorithm ( )

inlinevirtual

Definition at line 163 of file ApertureFlux.h.

{}

Member Function Documentation

computeFlux() [1/2]

template<typename T >

ApertureFluxAlgorithm::Result lsst::meas::base::ApertureFluxAlgorithm::computeFlux ( afw::image::Image< T > const &  image, afw::geom::ellipses::Ellipse const &  ellipse, Control const &  ctrl = Control()  )

static

Compute the instFlux (and optionally, uncertanties) within an aperture using the algorithm determined by its size and the maxSincRadius control parameter.

This method delegates to computeSincFlux is the minor axis of the aperture is smaller than ctrl.maxSincRadius, and delegates to computeNaiveFlux otherwise.

Parameters

[in]	image	Image or MaskedImage to be measured. If a MaskedImage is provided, uncertainties will be returned as well as instFluxes.
[in]	ellipse	Ellipse that defines the outer boundary of the aperture.
[in]	ctrl	Control object.

Definition at line 221 of file ApertureFlux.cc.

                                                                                      {
    return (afw::geom::ellipses::Axes(ellipse.getCore()).getB() <= ctrl.maxSincRadius)
                   ? computeSincFlux(image, ellipse, ctrl)
                   : computeNaiveFlux(image, ellipse, ctrl);
}

computeFlux() [2/2]

template<typename T >

ApertureFluxAlgorithm::Result lsst::meas::base::ApertureFluxAlgorithm::computeFlux ( afw::image::MaskedImage< T > const &  image, afw::geom::ellipses::Ellipse const &  ellipse, Control const &  ctrl = Control()  )

static

Compute the instFlux (and optionally, uncertanties) within an aperture using the algorithm determined by its size and the maxSincRadius control parameter.

This method delegates to computeSincFlux is the minor axis of the aperture is smaller than ctrl.maxSincRadius, and delegates to computeNaiveFlux otherwise.

Parameters

[in]	image	Image or MaskedImage to be measured. If a MaskedImage is provided, uncertainties will be returned as well as instFluxes.
[in]	ellipse	Ellipse that defines the outer boundary of the aperture.
[in]	ctrl	Control object.

Definition at line 230 of file ApertureFlux.cc.

                                                                                      {
    return (afw::geom::ellipses::Axes(ellipse.getCore()).getB() <= ctrl.maxSincRadius)
                   ? computeSincFlux(image, ellipse, ctrl)
                   : computeNaiveFlux(image, ellipse, ctrl);
}

computeNaiveFlux() [1/2]

template<typename T >

ApertureFluxAlgorithm::Result lsst::meas::base::ApertureFluxAlgorithm::computeNaiveFlux ( afw::image::Image< T > const &  image, afw::geom::ellipses::Ellipse const &  ellipse, Control const &  ctrl = Control()  )

static

Compute the instFlux (and optionally, uncertanties) within an aperture using naive photometry.

The naive algorithm just counts the instFlux in pixels whose centers lie within the aperture, ignoring the effects of sub-pixel aperture boundaries.

Parameters

[in]	image	Image or MaskedImage to be measured. If a MaskedImage is provided, uncertainties will be returned as well as instFluxes.
[in]	ellipse	Ellipse that defines the outer boundary of the aperture.

Definition at line 174 of file ApertureFlux.cc.

                                                                                                   {
    Result result;
    afw::geom::ellipses::PixelRegion region(ellipse);  // behaves mostly like a Footprint
    if (!image.getBBox().contains(region.getBBox())) {
        result.setFlag(APERTURE_TRUNCATED.number);
        result.setFlag(FAILURE.number);
        return result;
    }
    result.instFlux = 0;
    for (afw::geom::ellipses::PixelRegion::Iterator spanIter = region.begin(), spanEnd = region.end();
         spanIter != spanEnd; ++spanIter) {
        typename afw::image::Image<T>::x_iterator pixIter =
                image.x_at(spanIter->getBeginX() - image.getX0(), spanIter->getY() - image.getY0());
        result.instFlux += std::accumulate(pixIter, pixIter + spanIter->getWidth(), 0.0);
    }
    return result;
}

computeNaiveFlux() [2/2]

template<typename T >

ApertureFluxAlgorithm::Result lsst::meas::base::ApertureFluxAlgorithm::computeNaiveFlux ( afw::image::MaskedImage< T > const &  image, afw::geom::ellipses::Ellipse const &  ellipse, Control const &  ctrl = Control()  )

static

Compute the instFlux (and optionally, uncertanties) within an aperture using naive photometry.

The naive algorithm just counts the instFlux in pixels whose centers lie within the aperture, ignoring the effects of sub-pixel aperture boundaries.

Parameters

[in]	image	Image or MaskedImage to be measured. If a MaskedImage is provided, uncertainties will be returned as well as instFluxes.
[in]	ellipse	Ellipse that defines the outer boundary of the aperture.

Definition at line 194 of file ApertureFlux.cc.

                             {
    Result result;
    afw::geom::ellipses::PixelRegion region(ellipse);  // behaves mostly like a Footprint
    if (!image.getBBox().contains(region.getBBox())) {
        result.setFlag(APERTURE_TRUNCATED.number);
        result.setFlag(FAILURE.number);
        return result;
    }
    result.instFlux = 0.0;
    result.instFluxErr = 0.0;
    for (afw::geom::ellipses::PixelRegion::Iterator spanIter = region.begin(), spanEnd = region.end();
         spanIter != spanEnd; ++spanIter) {
        typename afw::image::MaskedImage<T>::Image::x_iterator pixIter = image.getImage()->x_at(
                spanIter->getBeginX() - image.getX0(), spanIter->getY() - image.getY0());
        typename afw::image::MaskedImage<T>::Variance::x_iterator varIter = image.getVariance()->x_at(
                spanIter->getBeginX() - image.getX0(), spanIter->getY() - image.getY0());
        result.instFlux += std::accumulate(pixIter, pixIter + spanIter->getWidth(), 0.0);
        // we use this to hold variance as we accumulate...
        result.instFluxErr += std::accumulate(varIter, varIter + spanIter->getWidth(), 0.0);
    }
    result.instFluxErr = std::sqrt(result.instFluxErr);  // ...and switch back to sigma here.
    return result;
}

computeSincFlux() [1/2]

template<typename T >

ApertureFluxAlgorithm::Result lsst::meas::base::ApertureFluxAlgorithm::computeSincFlux ( afw::image::Image< T > const &  image, afw::geom::ellipses::Ellipse const &  ellipse, Control const &  ctrl = Control()  )

static

Compute the instFlux (and optionally, uncertanties) within an aperture using Sinc photometry.

The Sinc algorithm is slower than a naive aperture, but more accurate, in that it correctly handles sub-pixel aperture boundaries on well-sampled data. This improved accuracy is most important for smaller apertures.

Parameters

[in]	image	Image or MaskedImage to be measured. If a MaskedImage is provided, uncertainties will be returned as well as instFluxes.
[in]	ellipse	Ellipse that defines the outer boundary of the aperture.
[in]	ctrl	Control object.

Definition at line 144 of file ApertureFlux.cc.

                                                                                                   {
    Result result;
    CONST_PTR(afw::image::Image<T>) cImage = getSincCoeffs<T>(image.getBBox(), ellipse, result, ctrl);
    if (result.getFlag(APERTURE_TRUNCATED.number)) return result;
    afw::image::Image<T> subImage(image, cImage->getBBox());
    result.instFlux =
            (ndarray::asEigenArray(subImage.getArray()) * ndarray::asEigenArray(cImage->getArray())).sum();
    return result;
}

computeSincFlux() [2/2]

template<typename T >

ApertureFluxAlgorithm::Result lsst::meas::base::ApertureFluxAlgorithm::computeSincFlux ( afw::image::MaskedImage< T > const &  image, afw::geom::ellipses::Ellipse const &  ellipse, Control const &  ctrl = Control()  )

static

Compute the instFlux (and optionally, uncertanties) within an aperture using Sinc photometry.

The Sinc algorithm is slower than a naive aperture, but more accurate, in that it correctly handles sub-pixel aperture boundaries on well-sampled data. This improved accuracy is most important for smaller apertures.

Parameters

[in]	image	Image or MaskedImage to be measured. If a MaskedImage is provided, uncertainties will be returned as well as instFluxes.
[in]	ellipse	Ellipse that defines the outer boundary of the aperture.
[in]	ctrl	Control object.

Definition at line 156 of file ApertureFlux.cc.

                             {
    Result result;
    CONST_PTR(afw::image::Image<T>) cImage = getSincCoeffs<T>(image.getBBox(), ellipse, result, ctrl);
    if (result.getFlag(APERTURE_TRUNCATED.number)) return result;
    afw::image::MaskedImage<T> subImage(image, cImage->getBBox(afw::image::PARENT), afw::image::PARENT);
    result.instFlux = (ndarray::asEigenArray(subImage.getImage()->getArray()) *
                       ndarray::asEigenArray(cImage->getArray()))
                              .sum();
    result.instFluxErr =
            std::sqrt((ndarray::asEigenArray(subImage.getVariance()->getArray()).template cast<T>() *
                       ndarray::asEigenArray(cImage->getArray()).square())
                              .sum());
    return result;
}

copyResultToRecord()

void lsst::meas::base::ApertureFluxAlgorithm::copyResultToRecord ( Result const &  result, afw::table::SourceRecord &  record, int  index  ) const

protected

Definition at line 94 of file ApertureFlux.cc.

                                                                {
    record.set(_keys[index].instFluxKey, result);
    if (result.getFlag(FAILURE.number)) {
        _keys[index].flags.setValue(record, FAILURE.number, true);
    }
    if (result.getFlag(APERTURE_TRUNCATED.number)) {
        _keys[index].flags.setValue(record, APERTURE_TRUNCATED.number, true);
    }
    if (result.getFlag(SINC_COEFFS_TRUNCATED.number)) {
        _keys[index].flags.setValue(record, SINC_COEFFS_TRUNCATED.number, true);
    }
}

fail()

void lsst::meas::base::ApertureFluxAlgorithm::fail ( afw::table::SourceRecord &  measRecord, MeasurementError *  error = nullptr  ) const

virtual

Handle an exception thrown by the current algorithm by setting flags in the given record.

fail() is called by the measurement framework when an exception is allowed to propagate out of one the algorithm's measure() methods. It should generally set both a general failure flag for the algorithm as well as a specific flag indicating the error condition, if possible. To aid in this, if the exception was an instance of MeasurementError, it will be passed in, carrying information about what flag to set.

An algorithm can also to chose to set flags within its own measure() methods, and then just return, rather than throw an exception. However, fail() should be implemented even when all known failure modes do not throw exceptions, to ensure that unexpected exceptions thrown in lower-level code are properly handled.

Implements lsst::meas::base::BaseAlgorithm.

Definition at line 85 of file ApertureFlux.cc.

                                                                                                {
    // This should only get called in the case of completely unexpected failures, so it's not terrible
    // that we just set the general failure flags for all radii here instead of trying to figure out
    // which ones we've already done.  Any known failure modes are handled inside measure().
    for (std::size_t i = 0; i < _ctrl.radii.size(); ++i) {
        _keys[i].flags.handleFailure(measRecord, error);
    }
}

getFlagDefinitions()

FlagDefinitionList const & lsst::meas::base::ApertureFluxAlgorithm::getFlagDefinitions ( )

static

Definition at line 49 of file ApertureFlux.cc.

{ return flagDefinitions; }

getFlagHandler()

FlagHandler const& lsst::meas::base::ApertureFluxAlgorithm::getFlagHandler ( int  index ) const

inlineprotected

Definition at line 196 of file ApertureFlux.h.

{ return _keys[index].flags; }

getLogName()

std::string lsst::meas::base::BaseAlgorithm::getLogName ( ) const

inlineinherited

Definition at line 66 of file Algorithm.h.

{ return _logName; }

makeFieldPrefix()

std::string lsst::meas::base::ApertureFluxAlgorithm::makeFieldPrefix ( std::string const &  name, double  radius  )

static

Construct an appropriate prefix for table fields.

Given a plugin name (e.g. base_CircularApertureFlux) and an aperture radius (e.g. 12 pixels) return an appropriate prefix for table fields to contain the measurement results (e.g. base_CircularApertureFlux_12_0). Table fields can then be created named <prefix>_instFlux, <prefix>_instFluxErr, etc.

Parameters

[in]	pluginName	Name of measurement plugin.
[in]	radius	Aperture radius (pixels).

Returns

Table field name prefix.

Definition at line 57 of file ApertureFlux.cc.

                                                                                     {
    std::string prefix = (boost::format("%s_%.1f") % name % radius).str();
    return boost::replace_all_copy(prefix, ".", "_");
}

measure()

virtual void lsst::meas::base::ApertureFluxAlgorithm::measure ( afw::table::SourceRecord &  record, afw::image::Exposure< float > const &  exposure  ) const

pure virtual

Measure the configured apertures on the given image.

Python plugins will delegate to this method.

Parameters

[in,out]	record	Record used to save outputs and retrieve positions.
[in]	exposure	Image to be measured.

Implements lsst::meas::base::SingleFrameAlgorithm.

Implemented in lsst::meas::base::CircularApertureFluxAlgorithm.

measureForced()

virtual void lsst::meas::base::SimpleAlgorithm::measureForced ( afw::table::SourceRecord &  measRecord, afw::image::Exposure< float > const &  exposure, afw::table::SourceRecord const &  refRecord, afw::geom::SkyWcs const &  refWcs  ) const

inlinevirtualinherited

Called to measure a single child source in an image.

Before this method is called, all neighbors will be replaced with noise, using the outputs of the deblender. Outputs should be saved in the given SourceRecord, which can also be used to obtain centroid (see SafeCentroidExtractor) and shape (see SafeShapeExtractor) information.

Implements lsst::meas::base::ForcedAlgorithm.

Reimplemented in lsst::meas::extensions::photometryKron::KronFluxAlgorithm.

Definition at line 172 of file Algorithm.h.

                                                                  {
        measure(measRecord, exposure);
    }

measureN()

void lsst::meas::base::SingleFrameAlgorithm::measureN ( afw::table::SourceCatalog const &  measCat, afw::image::Exposure< float > const &  exposure  ) const

virtualinherited

Called to simultaneously measure all children in a deblend family, in a single image.

Outputs should be saved in the given SourceCatalog, which can also be used to obtain centroid (see SafeCentroidExtractor) and shape (see SafeShapeExtractor) information.

The default implementation simply throws an exception, indicating that simultaneous measurement is not supported.

Definition at line 31 of file Algorithm.cc.

                                                                                   {
    throw LSST_EXCEPT(pex::exceptions::LogicError, "measureN not implemented for this algorithm");
}

measureNForced()

virtual void lsst::meas::base::SimpleAlgorithm::measureNForced ( afw::table::SourceCatalog const &  measCat, afw::image::Exposure< float > const &  exposure, afw::table::SourceCatalog const &  refRecord, afw::geom::SkyWcs const &  refWcs  ) const

inlinevirtualinherited

Called to simultaneously measure all children in a deblend family, in a single image.

Outputs should be saved in the given SourceCatalog, which can also be used to obtain centroid (see SafeCentroidExtractor) and shape (see SafeShapeExtractor) information.

The default implementation simply throws an exception, indicating that simultaneous measurement is not supported.

Reimplemented from lsst::meas::base::ForcedAlgorithm.

Definition at line 179 of file Algorithm.h.

                                                                   {
        measureN(measCat, exposure);
    }

Member Data Documentation

_centroidExtractor

SafeCentroidExtractor lsst::meas::base::ApertureFluxAlgorithm::_centroidExtractor

protected

Definition at line 199 of file ApertureFlux.h.

_ctrl

Control const lsst::meas::base::ApertureFluxAlgorithm::_ctrl

protected

Definition at line 198 of file ApertureFlux.h.

_logName

std::string lsst::meas::base::BaseAlgorithm::_logName

protectedinherited

Definition at line 69 of file Algorithm.h.

APERTURE_TRUNCATED

FlagDefinition const lsst::meas::base::ApertureFluxAlgorithm::APERTURE_TRUNCATED

static

Initial value:

=
        flagDefinitions.add("flag_apertureTruncated", "aperture did not fit within measurement image")

Definition at line 86 of file ApertureFlux.h.

FAILURE

FlagDefinition const lsst::meas::base::ApertureFluxAlgorithm::FAILURE = flagDefinitions.addFailureFlag()

static

Definition at line 85 of file ApertureFlux.h.

N_FLAGS

unsigned int const lsst::meas::base::ApertureFluxAlgorithm::N_FLAGS = 3

static

Definition at line 84 of file ApertureFlux.h.

SINC_COEFFS_TRUNCATED

FlagDefinition const lsst::meas::base::ApertureFluxAlgorithm::SINC_COEFFS_TRUNCATED

static

Initial value:

= flagDefinitions.add(
        "flag_sincCoeffsTruncated", "full sinc coefficient image did not fit within measurement image")

Definition at line 87 of file ApertureFlux.h.

---

The documentation for this class was generated from the following files:

• /j/snowflake/release/lsstsw/stack/Linux64/meas_base/18.1.0/include/lsst/meas/base/ApertureFlux.h
• /j/snowflake/release/lsstsw/stack/Linux64/meas_base/18.1.0/src/ApertureFlux.cc