Coverage for python / lsst / meas / base / sfm.py: 31%
60 statements
« prev ^ index » next coverage.py v7.13.5, created at 2026-04-23 08:30 +0000
1# This file is part of meas_base.
2#
3# Developed for the LSST Data Management System.
4# This product includes software developed by the LSST Project
5# (https://www.lsst.org).
6# See the COPYRIGHT file at the top-level directory of this distribution
7# for details of code ownership.
8#
9# This program is free software: you can redistribute it and/or modify
10# it under the terms of the GNU General Public License as published by
11# the Free Software Foundation, either version 3 of the License, or
12# (at your option) any later version.
13#
14# This program is distributed in the hope that it will be useful,
15# but WITHOUT ANY WARRANTY; without even the implied warranty of
16# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17# GNU General Public License for more details.
18#
19# You should have received a copy of the GNU General Public License
20# along with this program. If not, see <https://www.gnu.org/licenses/>.
22r"""Base classes for single-frame measurement plugins and the associated task.
24In single-frame measurement, we assume that detection and probably deblending
25have already been run on the same frame, so a `~lsst.afw.table.SourceCatalog`
26has already been created with `lsst.afw.detection.Footprint`\ s (which may be
27"heavy" — that is, include pixel data). Measurements are generally recorded in
28the coordinate system of the image being measured (and all slot-eligible
29fields must be), but non-slot fields may be recorded in other coordinate
30systems if necessary to avoid information loss (this should, of course, be
31indicated in the field documentation).
32"""
34from lsst.utils.logging import PeriodicLogger
35from lsst.utils.timer import timeMethod
37from .pluginRegistry import PluginRegistry
38from .baseMeasurement import (BaseMeasurementPluginConfig, BaseMeasurementPlugin,
39 BaseMeasurementConfig, BaseMeasurementTask)
41__all__ = ("SingleFramePluginConfig", "SingleFramePlugin",
42 "SingleFrameMeasurementConfig", "SingleFrameMeasurementTask")
45class SingleFramePluginConfig(BaseMeasurementPluginConfig):
46 """Base class for single-frame plugin configuration classes.
47 """
48 pass
51class SingleFramePlugin(BaseMeasurementPlugin):
52 """Base class for single-frame measurement plugin.
54 Parameters
55 ----------
56 config : `SingleFramePlugin.ConfigClass`
57 Configuration for this plugin.
58 name : `str`
59 The string with which the plugin was registered.
60 schema : `lsst.afw.table.Schema`
61 The schema for the source table . New fields are added here to
62 hold measurements produced by this plugin.
63 metadata : `lsst.daf.base.PropertySet`
64 Plugin metadata that will be attached to the output catalog
65 logName : `str`, optional
66 Name to use when logging errors.
68 Notes
69 -----
70 New plugins can be created in Python by inheriting directly from this
71 class and implementing the `measure`, `fail` (from `BasePlugin`), and
72 optionally `__init__` and `measureN` methods. Plugins can also be defined
73 in C++ via the `WrappedSingleFramePlugin` class.
74 """
76 registry = PluginRegistry(SingleFramePluginConfig)
77 """Registry of subclasses of `SingleFramePlugin` (`PluginRegistry`).
78 """
80 ConfigClass = SingleFramePluginConfig
82 def __init__(self, config, name, schema, metadata, logName=None, **kwds):
83 BaseMeasurementPlugin.__init__(self, config, name, logName=logName)
85 def measure(self, measRecord, exposure):
86 """Measure the properties of a source on a single image.
88 The image may be from a single epoch, or it may be a coadd.
90 Parameters
91 ----------
92 measRecord : `lsst.afw.table.SourceRecord`
93 Record describing the object being measured. Previously-measured
94 quantities may be retrieved from here, and it will be updated
95 in-place tih the outputs of this plugin.
96 exposure : `lsst.afw.image.ExposureF`
97 The pixel data to be measured, together with the associated PSF,
98 WCS, etc. All other sources in the image should have been replaced
99 by noise according to deblender outputs.
100 """
101 raise NotImplementedError()
104class SingleFrameMeasurementConfig(BaseMeasurementConfig):
105 """Config class for single frame measurement driver task.
106 """
108 plugins = SingleFramePlugin.registry.makeField(
109 multi=True,
110 default=["base_PixelFlags",
111 "base_SdssCentroid",
112 "base_SdssShape",
113 "base_GaussianFlux",
114 "base_PsfFlux",
115 "base_CircularApertureFlux",
116 "base_SkyCoord",
117 "base_Variance",
118 "base_Blendedness",
119 "base_LocalBackground",
120 "base_CompensatedTophatFlux",
121 "base_ClassificationSizeExtendedness",
122 ],
123 doc="Plugins to be run and their configuration"
124 )
125 algorithms = property(lambda self: self.plugins, doc="backwards-compatibility alias for plugins")
126 undeblended = SingleFramePlugin.registry.makeField(
127 multi=True,
128 default=[],
129 doc="Plugins to run on undeblended image"
130 )
133class SingleFrameMeasurementTask(BaseMeasurementTask):
134 """A subtask for measuring the properties of sources on a single exposure.
136 Parameters
137 ----------
138 schema : `lsst.afw.table.Schema`
139 Schema of the output resultant catalog. Will be updated to provide
140 fields to accept the outputs of plugins which will be executed by this
141 task.
142 algMetadata : `lsst.daf.base.PropertyList`, optional
143 Used to record metadaa about algorithm execution. An empty
144 `lsst.daf.base.PropertyList` will be created if `None`.
145 **kwds
146 Keyword arguments forwarded to `BaseMeasurementTask`.
147 """
149 ConfigClass = SingleFrameMeasurementConfig
151 def __init__(self, schema, algMetadata=None, **kwds):
152 super(SingleFrameMeasurementTask, self).__init__(algMetadata=algMetadata, **kwds)
153 self.schema = schema
154 self.config.slots.setupSchema(self.schema)
155 self.initializePlugins(schema=self.schema)
156 self.addInvalidPsfFlag(self.schema)
158 # Check to see if blendedness is one of the plugins
159 if 'base_Blendedness' in self.plugins:
160 self.doBlendedness = True
161 self.blendPlugin = self.plugins['base_Blendedness']
162 else:
163 self.doBlendedness = False
165 @timeMethod
166 def run(
167 self,
168 measCat,
169 exposure,
170 noiseImage=None,
171 exposureId=None,
172 beginOrder=None,
173 endOrder=None,
174 footprints=None,
175 ):
176 r"""Run single frame measurement over an exposure and source catalog.
178 Parameters
179 ----------
180 measCat : `lsst.afw.table.SourceCatalog`
181 Catalog to be filled with the results of measurement. Must contain
182 all the `lsst.afw.table.SourceRecord`\ s to be measured (with
183 `lsst.afw.detection.Footprint`\ s attached), and have a schema
184 that is a superset of ``self.schema``.
185 exposure : `lsst.afw.image.ExposureF`
186 Image containing the pixel data to be measured together with
187 associated PSF, WCS, etc.
188 noiseImage : `lsst.afw.image.ImageF`, optional
189 Can be used to specify the a predictable noise replacement field
190 for testing purposes.
191 exposureId : `int`, optional
192 Unique exposure identifier used to calculate the random number
193 generator seed during noise replacement.
194 beginOrder : `float`, optional
195 Start execution order (inclusive): measurements with
196 ``executionOrder < beginOrder`` are not executed. `None` for no
197 limit.
198 endOrder : `float`, optional
199 Final execution order (exclusive): measurements with
200 ``executionOrder >= endOrder`` are not executed. `None` for no
201 limit.
202 footprints : `dict` {`int`: `lsst.afw.detection.Footprint`}, optional
203 List of footprints to use for noise replacement. If this is not
204 supplied then the footprints from the measCat are used.
205 """
206 assert measCat.getSchema().contains(self.schema)
207 if footprints is None:
208 footprints = self.getFootprintsFromCatalog(measCat)
210 # noiseReplacer is used to fill the footprints with noise and save
211 # heavy footprints of the source pixels so that they can be restored
212 # one at a time for measurement. After the NoiseReplacer is
213 # constructed, all pixels in the exposure.getMaskedImage() which
214 # belong to objects in measCat will be replaced with noise
216 # Initialize the noise replacer
217 noiseReplacer = self.initNoiseReplacer(exposure, measCat, footprints, exposureId, noiseImage)
219 self.runPlugins(noiseReplacer, measCat, exposure, beginOrder, endOrder)
221 def runPlugins(
222 self,
223 noiseReplacer,
224 measCat,
225 exposure,
226 beginOrder=None,
227 endOrder=None,
228 ):
229 r"""Call the configured measument plugins on an image.
231 Parameters
232 ----------
233 noiseReplacer : `NoiseReplacer`
234 Used to fill sources not being measured with noise.
235 measCat : `lsst.afw.table.SourceCatalog`
236 Catalog to be filled with the results of measurement. Must contain
237 all the `lsst.afw.table.SourceRecord`\ s to be measured (with
238 `lsst.afw.detection.Footprint`\ s attached), and have a schema
239 that is a superset of ``self.schema``.
240 exposure : `lsst.afw.image.ExposureF`
241 Image containing the pixel data to be measured together with
242 associated PSF, WCS, etc.
243 beginOrder : `float`, optional
244 Start execution order (inclusive): measurements with
245 ``executionOrder < beginOrder`` are not executed. `None` for no
246 limit.
247 endOrder : `float`, optional
248 Final execution order (exclusive): measurements with
249 ``executionOrder >= endOrder`` are not executed. `None` for no
250 limit.
251 """
252 nMeasCat = len(measCat)
253 self.log.info("Measuring %d source%s", nMeasCat, ("" if nMeasCat == 1 else "s"))
255 # Wrap the task logger into a period logger
256 periodicLog = PeriodicLogger(self.log)
258 for recordIndex, measRecord in enumerate(measCat):
259 noiseReplacer.insertSource(measRecord.getId())
260 self.callMeasure(measRecord, exposure, beginOrder=beginOrder, endOrder=endOrder)
262 if self.doBlendedness:
263 self.blendPlugin.cpp.measureChildPixels(exposure.getMaskedImage(), measRecord)
265 noiseReplacer.removeSource(measRecord.getId())
266 # Log a message if it has been a while since the last log.
267 periodicLog.log("Measurement complete for %d sources out of %d", recordIndex + 1, nMeasCat)
269 # When done, restore the exposure to its original state
270 noiseReplacer.end()
272 # Undeblended plugins only fire if we're running everything
273 if endOrder is None:
274 for sourceIndex, source in enumerate(measCat):
275 for plugin in self.undeblendedPlugins.iter():
276 self.doMeasurement(plugin, source, exposure)
277 # Log a message if it has been a while since the last log.
278 periodicLog.log("Undeblended measurement complete for %d sources out of %d",
279 sourceIndex + 1, nMeasCat)
281 # Now we loop over all of the sources one more time to compute the
282 # blendedness metrics
283 if self.doBlendedness:
284 for source in measCat:
285 self.blendPlugin.cpp.measureParentPixels(exposure.getMaskedImage(), source)
287 def measure(self, measCat, exposure):
288 """Backwards-compatibility alias for `run`.
289 """
290 self.run(measCat, exposure)