lsst.meas.astrom  16.0-13-g5f6c0b1+2
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_astrometry_used", 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  epoch=expMd.epoch,
214  )
215  matchMeta = self.refObjLoader.getMetadataBox(
216  bbox=expMd.bbox,
217  wcs=expMd.wcs,
218  filterName=expMd.filterName,
219  calib=expMd.calib,
220  epoch=expMd.epoch,
221  )
222 
223  if debug.display:
224  frame = int(debug.frame)
226  refCat=loadRes.refCat,
227  sourceCat=sourceCat,
228  exposure=exposure,
229  bbox=expMd.bbox,
230  frame=frame,
231  title="Reference catalog",
232  )
233 
234  res = None
235  wcs = expMd.wcs
236  match_tolerance = None
237  for i in range(self.config.maxIter):
238  iterNum = i + 1
239  try:
240  tryRes = self._matchAndFitWcs( # refCat, sourceCat, refFluxField, bbox, wcs, exposure=None
241  refCat=loadRes.refCat,
242  sourceCat=sourceCat,
243  refFluxField=loadRes.fluxField,
244  bbox=expMd.bbox,
245  wcs=wcs,
246  exposure=exposure,
247  match_tolerance=match_tolerance,
248  )
249  except Exception as e:
250  # if we have had a succeessful iteration then use that; otherwise fail
251  if i > 0:
252  self.log.info("Fit WCS iter %d failed; using previous iteration: %s" % (iterNum, e))
253  iterNum -= 1
254  break
255  else:
256  raise
257 
258  match_tolerance = tryRes.match_tolerance
259  tryMatchDist = self._computeMatchStatsOnSky(tryRes.matches)
260  self.log.debug(
261  "Match and fit WCS iteration %d: found %d matches with scatter = %0.3f +- %0.3f arcsec; "
262  "max match distance = %0.3f arcsec",
263  iterNum, len(tryRes.matches), tryMatchDist.distMean.asArcseconds(),
264  tryMatchDist.distStdDev.asArcseconds(), tryMatchDist.maxMatchDist.asArcseconds())
265 
266  maxMatchDist = tryMatchDist.maxMatchDist
267  res = tryRes
268  wcs = res.wcs
269  if maxMatchDist.asArcseconds() < self.config.minMatchDistanceArcSec:
270  self.log.debug(
271  "Max match distance = %0.3f arcsec < %0.3f = config.minMatchDistanceArcSec; "
272  "that's good enough",
273  maxMatchDist.asArcseconds(), self.config.minMatchDistanceArcSec)
274  break
275  match_tolerance.maxMatchDist = maxMatchDist
276 
277  self.log.info(
278  "Matched and fit WCS in %d iterations; "
279  "found %d matches with scatter = %0.3f +- %0.3f arcsec" %
280  (iterNum, len(tryRes.matches), tryMatchDist.distMean.asArcseconds(),
281  tryMatchDist.distStdDev.asArcseconds()))
282  for m in res.matches:
283  if self.usedKey:
284  m.second.set(self.usedKey, True)
285  exposure.setWcs(res.wcs)
286 
287  return pipeBase.Struct(
288  refCat=loadRes.refCat,
289  matches=res.matches,
290  scatterOnSky=res.scatterOnSky,
291  matchMeta=matchMeta,
292  )
293 
294  @pipeBase.timeMethod
295  def _matchAndFitWcs(self, refCat, sourceCat, refFluxField, bbox, wcs, match_tolerance,
296  exposure=None):
297  """!Match sources to reference objects and fit a WCS
298 
299  @param[in] refCat catalog of reference objects
300  @param[in] sourceCat catalog of sources detected on the exposure (an lsst.afw.table.SourceCatalog)
301  @param[in] refFluxField field of refCat to use for flux
302  @param[in] bbox bounding box of exposure (an lsst.afw.geom.Box2I)
303  @param[in] wcs initial guess for WCS of exposure (an lsst.afw.geom.Wcs)
304  @param[in] match_tolerance a MatchTolerance object (or None) specifying
305  internal tolerances to the matcher. See the MatchTolerance
306  definition in the respective matcher for the class definition.
307  @param[in] exposure exposure whose WCS is to be fit, or None; used only for the debug display
308 
309  @return an lsst.pipe.base.Struct with these fields:
310  - matches astrometric matches, a list of lsst.afw.table.ReferenceMatch
311  - wcs the fit WCS (an lsst.afw.geom.Wcs)
312  - scatterOnSky median on-sky separation between reference objects and sources in "matches"
313  (an lsst.afw.geom.Angle)
314  """
315  import lsstDebug
316  debug = lsstDebug.Info(__name__)
317  matchRes = self.matcher.matchObjectsToSources(
318  refCat=refCat,
319  sourceCat=sourceCat,
320  wcs=wcs,
321  refFluxField=refFluxField,
322  match_tolerance=match_tolerance,
323  )
324  self.log.debug("Found %s matches", len(matchRes.matches))
325  if debug.display:
326  frame = int(debug.frame)
328  refCat=refCat,
329  sourceCat=matchRes.usableSourceCat,
330  matches=matchRes.matches,
331  exposure=exposure,
332  bbox=bbox,
333  frame=frame + 1,
334  title="Initial WCS",
335  )
336 
337  self.log.debug("Fitting WCS")
338  fitRes = self.wcsFitter.fitWcs(
339  matches=matchRes.matches,
340  initWcs=wcs,
341  bbox=bbox,
342  refCat=refCat,
343  sourceCat=sourceCat,
344  exposure=exposure,
345  )
346  fitWcs = fitRes.wcs
347  scatterOnSky = fitRes.scatterOnSky
348  if debug.display:
349  frame = int(debug.frame)
351  refCat=refCat,
352  sourceCat=matchRes.usableSourceCat,
353  matches=matchRes.matches,
354  exposure=exposure,
355  bbox=bbox,
356  frame=frame + 2,
357  title="Fit TAN-SIP WCS",
358  )
359 
360  return pipeBase.Struct(
361  matches=matchRes.matches,
362  wcs=fitWcs,
363  scatterOnSky=scatterOnSky,
364  match_tolerance=matchRes.match_tolerance,
365  )
def _matchAndFitWcs(self, refCat, sourceCat, refFluxField, bbox, wcs, match_tolerance, exposure=None)
Match sources to reference objects and fit a WCS.
Definition: astrometry.py:296
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:158
def _getExposureMetadata(self, exposure)
Extract metadata from an exposure.
Definition: ref_match.py:178
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:65
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:87
Match an input source catalog with objects from a reference catalog and solve for the WCS...
Definition: astrometry.py:68