lsst.meas.astrom  15.0-6-g81517ef
astrometry.py
Go to the documentation of this file.
1 #
2 # LSST Data Management System
3 # Copyright 2008-2016 AURA/LSST.
4 #
5 # This product includes software developed by the
6 # LSST Project (http://www.lsst.org/).
7 #
8 # This program is free software: you can redistribute it and/or modify
9 # it under the terms of the GNU General Public License as published by
10 # the Free Software Foundation, either version 3 of the License, or
11 # (at your option) any later version.
12 #
13 # This program is distributed in the hope that it will be useful,
14 # but WITHOUT ANY WARRANTY; without even the implied warranty of
15 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16 # GNU General Public License for more details.
17 #
18 # You should have received a copy of the LSST License Statement and
19 # the GNU General Public License along with this program. If not,
20 # see <https://www.lsstcorp.org/LegalNotices/>.
21 #
22 
23 __all__ = ["AstrometryConfig", "AstrometryTask"]
24 
25 
26 import lsst.pex.config as pexConfig
27 import lsst.pipe.base as pipeBase
28 from .ref_match import RefMatchTask, RefMatchConfig
29 from .fitTanSipWcs import FitTanSipWcsTask
30 from .display import displayAstrometry
31 
32 
34  wcsFitter = pexConfig.ConfigurableField(
35  target=FitTanSipWcsTask,
36  doc="WCS fitter",
37  )
38  forceKnownWcs = pexConfig.Field(
39  dtype=bool,
40  doc="If True then load reference objects and match sources but do not fit a WCS; " +
41  " this simply controls whether 'run' calls 'solve' or 'loadAndMatch'",
42  default=False,
43  )
44  maxIter = pexConfig.RangeField(
45  doc="maximum number of iterations of match sources and fit WCS" +
46  "ignored if not fitting a WCS",
47  dtype=int,
48  default=3,
49  min=1,
50  )
51  minMatchDistanceArcSec = pexConfig.RangeField(
52  doc="the match distance below which further iteration is pointless (arcsec); "
53  "ignored if not fitting a WCS",
54  dtype=float,
55  default=0.001,
56  min=0,
57  )
58 
59 # The following block adds links to this task from the Task Documentation page.
60 
66 
67 
69  """!Match an input source catalog with objects from a reference catalog and solve for the WCS
70 
71  @anchor AstrometryTask_
72 
73  @section meas_astrom_astrometry_Contents Contents
74 
75  - @ref meas_astrom_astrometry_Purpose
76  - @ref meas_astrom_astrometry_Initialize
77  - @ref meas_astrom_astrometry_IO
78  - @ref meas_astrom_astrometry_Config
79  - @ref meas_astrom_astrometry_Example
80  - @ref meas_astrom_astrometry_Debug
81 
82  @section meas_astrom_astrometry_Purpose Description
83 
84  Match input sourceCat with a reference catalog and solve for the Wcs
85 
86  There are three steps, each performed by different subtasks:
87  - Find position reference stars that overlap the exposure
88  - Match sourceCat to position reference stars
89  - Fit a WCS based on the matches
90 
91  @section meas_astrom_astrometry_Initialize Task initialisation
92 
93  @copydoc \_\_init\_\_
94 
95  @section meas_astrom_astrometry_IO Invoking the Task
96 
97  @copydoc run
98 
99  @copydoc loadAndMatch
100 
101  @section meas_astrom_astrometry_Config Configuration parameters
102 
103  See @ref AstrometryConfig
104 
105  @section meas_astrom_astrometry_Example A complete example of using AstrometryTask
106 
107  See \ref pipe_tasks_photocal_Example.
108 
109  @section meas_astrom_astrometry_Debug Debug variables
110 
111  The @link lsst.pipe.base.cmdLineTask.CmdLineTask command line task@endlink interface supports a
112  flag @c -d to import @b debug.py from your @c PYTHONPATH; see @ref baseDebug for more about
113  @b debug.py files.
114 
115  The available variables in AstrometryTask are:
116  <DL>
117  <DT> @c display (bool)
118  <DD> If True display information at three stages: after finding reference objects,
119  after matching sources to reference objects, and after fitting the WCS; defaults to False
120  <DT> @c frame (int)
121  <DD> ds9 frame to use to display the reference objects; the next two frames are used
122  to display the match list and the results of the final WCS; defaults to 0
123  </DL>
124 
125  To investigate the @ref meas_astrom_astrometry_Debug, put something like
126  @code{.py}
127  import lsstDebug
128  def DebugInfo(name):
129  debug = lsstDebug.getInfo(name) # N.b. lsstDebug.Info(name) would call us recursively
130  if name == "lsst.meas.astrom.astrometry":
131  debug.display = True
132 
133  return debug
134 
135  lsstDebug.Info = DebugInfo
136  @endcode
137  into your debug.py file and run this task with the @c --debug flag.
138  """
139  ConfigClass = AstrometryConfig
140  _DefaultName = "astrometricSolver"
141 
142  def __init__(self, refObjLoader, schema=None, **kwargs):
143  """!Construct an AstrometryTask
144 
145  @param[in] refObjLoader A reference object loader object
146  @param[in] schema ignored; available for compatibility with an older astrometry task
147  @param[in] kwargs additional keyword arguments for pipe_base Task.\_\_init\_\_
148  """
149  RefMatchTask.__init__(self, refObjLoader, schema=schema, **kwargs)
150 
151  if schema is not None:
152  self.usedKey = schema.addField("calib_astrometryUsed", type="Flag",
153  doc="set if source was used in astrometric calibration")
154  else:
155  self.usedKey = None
156 
157  self.makeSubtask("wcsFitter")
158 
159  @pipeBase.timeMethod
160  def run(self, sourceCat, exposure):
161  """!Load reference objects, match sources and optionally fit a WCS
162 
163  This is a thin layer around solve or loadAndMatch, depending on config.forceKnownWcs
164 
165  @param[in,out] exposure exposure whose WCS is to be fit
166  The following are read only:
167  - bbox
168  - calib (may be absent)
169  - filter (may be unset)
170  - detector (if wcs is pure tangent; may be absent)
171  The following are updated:
172  - wcs (the initial value is used as an initial guess, and is required)
173  @param[in] sourceCat catalog of sources detected on the exposure (an lsst.afw.table.SourceCatalog)
174  @return an lsst.pipe.base.Struct with these fields:
175  - refCat reference object catalog of objects that overlap the exposure (with some margin)
176  (an lsst::afw::table::SimpleCatalog)
177  - matches astrometric matches, a list of lsst.afw.table.ReferenceMatch
178  - scatterOnSky median on-sky separation between reference objects and sources in "matches"
179  (an lsst.afw.geom.Angle), or None if config.forceKnownWcs True
180  - matchMeta metadata needed to unpersist matches (an lsst.daf.base.PropertyList)
181  """
182  if self.config.forceKnownWcs:
183  res = self.loadAndMatch(exposure=exposure, sourceCat=sourceCat)
184  res.scatterOnSky = None
185  else:
186  res = self.solve(exposure=exposure, sourceCat=sourceCat)
187  return res
188 
189  @pipeBase.timeMethod
190  def solve(self, exposure, sourceCat):
191  """!Load reference objects overlapping an exposure, match to sources and fit a WCS
192 
193  @return an lsst.pipe.base.Struct with these fields:
194  - refCat reference object catalog of objects that overlap the exposure (with some margin)
195  (an lsst::afw::table::SimpleCatalog)
196  - matches astrometric matches, a list of lsst.afw.table.ReferenceMatch
197  - scatterOnSky median on-sky separation between reference objects and sources in "matches"
198  (an lsst.afw.geom.Angle)
199  - matchMeta metadata needed to unpersist matches (an lsst.daf.base.PropertyList)
200 
201  @note ignores config.forceKnownWcs
202  """
203  import lsstDebug
204  debug = lsstDebug.Info(__name__)
205 
206  expMd = self._getExposureMetadata(exposure)
207 
208  loadRes = self.refObjLoader.loadPixelBox(
209  bbox=expMd.bbox,
210  wcs=expMd.wcs,
211  filterName=expMd.filterName,
212  calib=expMd.calib,
213  )
214  matchMeta = self.refObjLoader.getMetadataBox(
215  bbox=expMd.bbox,
216  wcs=expMd.wcs,
217  filterName=expMd.filterName,
218  calib=expMd.calib,
219  )
220 
221  if debug.display:
222  frame = int(debug.frame)
224  refCat=loadRes.refCat,
225  sourceCat=sourceCat,
226  exposure=exposure,
227  bbox=expMd.bbox,
228  frame=frame,
229  title="Reference catalog",
230  )
231 
232  res = None
233  wcs = expMd.wcs
234  match_tolerance = None
235  for i in range(self.config.maxIter):
236  iterNum = i + 1
237  try:
238  tryRes = self._matchAndFitWcs( # refCat, sourceCat, refFluxField, bbox, wcs, exposure=None
239  refCat=loadRes.refCat,
240  sourceCat=sourceCat,
241  refFluxField=loadRes.fluxField,
242  bbox=expMd.bbox,
243  wcs=wcs,
244  exposure=exposure,
245  match_tolerance=match_tolerance,
246  )
247  except Exception as e:
248  # if we have had a succeessful iteration then use that; otherwise fail
249  if i > 0:
250  self.log.info("Fit WCS iter %d failed; using previous iteration: %s" % (iterNum, e))
251  iterNum -= 1
252  break
253  else:
254  raise
255 
256  match_tolerance = tryRes.match_tolerance
257  tryMatchDist = self._computeMatchStatsOnSky(tryRes.matches)
258  self.log.debug(
259  "Match and fit WCS iteration %d: found %d matches with scatter = %0.3f +- %0.3f arcsec; "
260  "max match distance = %0.3f arcsec",
261  iterNum, len(tryRes.matches), tryMatchDist.distMean.asArcseconds(),
262  tryMatchDist.distStdDev.asArcseconds(), tryMatchDist.maxMatchDist.asArcseconds())
263 
264  maxMatchDist = tryMatchDist.maxMatchDist
265  res = tryRes
266  wcs = res.wcs
267  if maxMatchDist.asArcseconds() < self.config.minMatchDistanceArcSec:
268  self.log.debug(
269  "Max match distance = %0.3f arcsec < %0.3f = config.minMatchDistanceArcSec; "
270  "that's good enough",
271  maxMatchDist.asArcseconds(), self.config.minMatchDistanceArcSec)
272  break
273  match_tolerance.maxMatchDist = maxMatchDist
274 
275  self.log.info(
276  "Matched and fit WCS in %d iterations; "
277  "found %d matches with scatter = %0.3f +- %0.3f arcsec" %
278  (iterNum, len(tryRes.matches), tryMatchDist.distMean.asArcseconds(),
279  tryMatchDist.distStdDev.asArcseconds()))
280  for m in res.matches:
281  if self.usedKey:
282  m.second.set(self.usedKey, True)
283  exposure.setWcs(res.wcs)
284 
285  return pipeBase.Struct(
286  refCat=loadRes.refCat,
287  matches=res.matches,
288  scatterOnSky=res.scatterOnSky,
289  matchMeta=matchMeta,
290  )
291 
292  @pipeBase.timeMethod
293  def _matchAndFitWcs(self, refCat, sourceCat, refFluxField, bbox, wcs, match_tolerance,
294  exposure=None):
295  """!Match sources to reference objects and fit a WCS
296 
297  @param[in] refCat catalog of reference objects
298  @param[in] sourceCat catalog of sources detected on the exposure (an lsst.afw.table.SourceCatalog)
299  @param[in] refFluxField field of refCat to use for flux
300  @param[in] bbox bounding box of exposure (an lsst.afw.geom.Box2I)
301  @param[in] wcs initial guess for WCS of exposure (an lsst.afw.geom.Wcs)
302  @param[in] match_tolerance a MatchTolerance object (or None) specifying
303  internal tolerances to the matcher. See the MatchTolerance
304  definition in the respective matcher for the class definition.
305  @param[in] exposure exposure whose WCS is to be fit, or None; used only for the debug display
306 
307  @return an lsst.pipe.base.Struct with these fields:
308  - matches astrometric matches, a list of lsst.afw.table.ReferenceMatch
309  - wcs the fit WCS (an lsst.afw.geom.Wcs)
310  - scatterOnSky median on-sky separation between reference objects and sources in "matches"
311  (an lsst.afw.geom.Angle)
312  """
313  import lsstDebug
314  debug = lsstDebug.Info(__name__)
315  matchRes = self.matcher.matchObjectsToSources(
316  refCat=refCat,
317  sourceCat=sourceCat,
318  wcs=wcs,
319  refFluxField=refFluxField,
320  match_tolerance=match_tolerance,
321  )
322  self.log.debug("Found %s matches", len(matchRes.matches))
323  if debug.display:
324  frame = int(debug.frame)
326  refCat=refCat,
327  sourceCat=matchRes.usableSourceCat,
328  matches=matchRes.matches,
329  exposure=exposure,
330  bbox=bbox,
331  frame=frame + 1,
332  title="Initial WCS",
333  )
334 
335  self.log.debug("Fitting WCS")
336  fitRes = self.wcsFitter.fitWcs(
337  matches=matchRes.matches,
338  initWcs=wcs,
339  bbox=bbox,
340  refCat=refCat,
341  sourceCat=sourceCat,
342  exposure=exposure,
343  )
344  fitWcs = fitRes.wcs
345  scatterOnSky = fitRes.scatterOnSky
346  if debug.display:
347  frame = int(debug.frame)
349  refCat=refCat,
350  sourceCat=matchRes.usableSourceCat,
351  matches=matchRes.matches,
352  exposure=exposure,
353  bbox=bbox,
354  frame=frame + 2,
355  title="Fit TAN-SIP WCS",
356  )
357 
358  return pipeBase.Struct(
359  matches=matchRes.matches,
360  wcs=fitWcs,
361  scatterOnSky=scatterOnSky,
362  match_tolerance=matchRes.match_tolerance,
363  )
def _matchAndFitWcs(self, refCat, sourceCat, refFluxField, bbox, wcs, match_tolerance, exposure=None)
Match sources to reference objects and fit a WCS.
Definition: astrometry.py:294
def solve(self, exposure, sourceCat)
Load reference objects overlapping an exposure, match to sources and fit a WCS.
Definition: astrometry.py:190
def _computeMatchStatsOnSky(self, matchList)
Definition: ref_match.py:155
def _getExposureMetadata(self, exposure)
Extract metadata from an exposure.
Definition: ref_match.py:175
def run(self, sourceCat, exposure)
Load reference objects, match sources and optionally fit a WCS.
Definition: astrometry.py:160
Match an input source catalog with objects from a reference catalog.
Definition: ref_match.py:62
def __init__(self, refObjLoader, schema=None, kwargs)
Construct an AstrometryTask.
Definition: astrometry.py:142
def displayAstrometry(refCat=None, sourceCat=None, distortedCentroidKey=None, bbox=None, exposure=None, matches=None, frame=1, title="", pause=True)
Definition: display.py:35
def loadAndMatch(self, exposure, sourceCat)
Load reference objects overlapping an exposure and match to sources detected on that exposure...
Definition: ref_match.py:84
Match an input source catalog with objects from a reference catalog and solve for the WCS...
Definition: astrometry.py:68