lsst.meas.astrom  14.0
 All Classes Namespaces Files Functions Variables Typedefs Friends Macros Groups Pages
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 from __future__ import absolute_import, division, print_function
23 
24 __all__ = ["AstrometryConfig", "AstrometryTask"]
25 
26 from builtins import range
27 
28 import lsst.pex.config as pexConfig
29 import lsst.pipe.base as pipeBase
30 import lsst.afw.geom as afwGeom
31 from .ref_match import RefMatchTask, RefMatchConfig
32 from .fitTanSipWcs import FitTanSipWcsTask
33 from .display import displayAstrometry
34 from .createMatchMetadata import createMatchMetadata
35 
36 
37 class AstrometryConfig(RefMatchConfig):
38  wcsFitter = pexConfig.ConfigurableField(
39  target=FitTanSipWcsTask,
40  doc="WCS fitter",
41  )
42  forceKnownWcs = pexConfig.Field(
43  dtype=bool,
44  doc="If True then load reference objects and match sources but do not fit a WCS; " +
45  " this simply controls whether 'run' calls 'solve' or 'loadAndMatch'",
46  default=False,
47  )
48  maxIter = pexConfig.RangeField(
49  doc="maximum number of iterations of match sources and fit WCS" +
50  "ignored if not fitting a WCS",
51  dtype=int,
52  default=3,
53  min=1,
54  )
55  minMatchDistanceArcSec = pexConfig.RangeField(
56  doc="the match distance below which further iteration is pointless (arcsec); "
57  "ignored if not fitting a WCS",
58  dtype=float,
59  default=0.001,
60  min=0,
61  )
62 
63 # The following block adds links to this task from the Task Documentation page.
64 ## \addtogroup LSST_task_documentation
65 ## \{
66 ## \page measAstrom_astrometryTask
67 ## \ref AstrometryTask_ "AstrometryTask"
68 ## Match an input source catalog with objects from a reference catalog and solve for the WCS
69 ## \}
70 
71 
72 class AstrometryTask(RefMatchTask):
73  """!Match an input source catalog with objects from a reference catalog and solve for the WCS
74 
75  @anchor AstrometryTask_
76 
77  @section meas_astrom_astrometry_Contents Contents
78 
79  - @ref meas_astrom_astrometry_Purpose
80  - @ref meas_astrom_astrometry_Initialize
81  - @ref meas_astrom_astrometry_IO
82  - @ref meas_astrom_astrometry_Config
83  - @ref meas_astrom_astrometry_Example
84  - @ref meas_astrom_astrometry_Debug
85 
86  @section meas_astrom_astrometry_Purpose Description
87 
88  Match input sourceCat with a reference catalog and solve for the Wcs
89 
90  There are three steps, each performed by different subtasks:
91  - Find position reference stars that overlap the exposure
92  - Match sourceCat to position reference stars
93  - Fit a WCS based on the matches
94 
95  @section meas_astrom_astrometry_Initialize Task initialisation
96 
97  @copydoc \_\_init\_\_
98 
99  @section meas_astrom_astrometry_IO Invoking the Task
100 
101  @copydoc run
102 
103  @copydoc loadAndMatch
104 
105  @section meas_astrom_astrometry_Config Configuration parameters
106 
107  See @ref AstrometryConfig
108 
109  @section meas_astrom_astrometry_Example A complete example of using AstrometryTask
110 
111  See \ref pipe_tasks_photocal_Example.
112 
113  @section meas_astrom_astrometry_Debug Debug variables
114 
115  The @link lsst.pipe.base.cmdLineTask.CmdLineTask command line task@endlink interface supports a
116  flag @c -d to import @b debug.py from your @c PYTHONPATH; see @ref baseDebug for more about
117  @b debug.py files.
118 
119  The available variables in AstrometryTask are:
120  <DL>
121  <DT> @c display (bool)
122  <DD> If True display information at three stages: after finding reference objects,
123  after matching sources to reference objects, and after fitting the WCS; defaults to False
124  <DT> @c frame (int)
125  <DD> ds9 frame to use to display the reference objects; the next two frames are used
126  to display the match list and the results of the final WCS; defaults to 0
127  </DL>
128 
129  To investigate the @ref meas_astrom_astrometry_Debug, put something like
130  @code{.py}
131  import lsstDebug
132  def DebugInfo(name):
133  debug = lsstDebug.getInfo(name) # N.b. lsstDebug.Info(name) would call us recursively
134  if name == "lsst.meas.astrom.astrometry":
135  debug.display = True
136 
137  return debug
138 
139  lsstDebug.Info = DebugInfo
140  @endcode
141  into your debug.py file and run this task with the @c --debug flag.
142  """
143  ConfigClass = AstrometryConfig
144  _DefaultName = "astrometricSolver"
145 
146  def __init__(self, refObjLoader, schema=None, **kwargs):
147  """!Construct an AstrometryTask
148 
149  @param[in] refObjLoader A reference object loader object
150  @param[in] schema ignored; available for compatibility with an older astrometry task
151  @param[in] kwargs additional keyword arguments for pipe_base Task.\_\_init\_\_
152  """
153  RefMatchTask.__init__(self, refObjLoader, schema=schema, **kwargs)
154 
155  if schema is not None:
156  self.usedKey = schema.addField("calib_astrometryUsed", type="Flag",
157  doc="set if source was used in astrometric calibration")
158  else:
159  self.usedKey = None
160 
161  self.makeSubtask("wcsFitter")
162 
163  @pipeBase.timeMethod
164  def run(self, sourceCat, exposure):
165  """!Load reference objects, match sources and optionally fit a WCS
166 
167  This is a thin layer around solve or loadAndMatch, depending on config.forceKnownWcs
168 
169  @param[in,out] exposure exposure whose WCS is to be fit
170  The following are read only:
171  - bbox
172  - calib (may be absent)
173  - filter (may be unset)
174  - detector (if wcs is pure tangent; may be absent)
175  The following are updated:
176  - wcs (the initial value is used as an initial guess, and is required)
177  @param[in] sourceCat catalog of sources detected on the exposure (an lsst.afw.table.SourceCatalog)
178  @return an lsst.pipe.base.Struct with these fields:
179  - refCat reference object catalog of objects that overlap the exposure (with some margin)
180  (an lsst::afw::table::SimpleCatalog)
181  - matches astrometric matches, a list of lsst.afw.table.ReferenceMatch
182  - scatterOnSky median on-sky separation between reference objects and sources in "matches"
183  (an lsst.afw.geom.Angle), or None if config.forceKnownWcs True
184  - matchMeta metadata needed to unpersist matches (an lsst.daf.base.PropertyList)
185  """
186  if self.config.forceKnownWcs:
187  res = self.loadAndMatch(exposure=exposure, sourceCat=sourceCat)
188  res.scatterOnSky = None
189  else:
190  res = self.solve(exposure=exposure, sourceCat=sourceCat)
191  return res
192 
193  @pipeBase.timeMethod
194  def solve(self, exposure, sourceCat):
195  """!Load reference objects overlapping an exposure, match to sources and fit a WCS
196 
197  @return an lsst.pipe.base.Struct with these fields:
198  - refCat reference object catalog of objects that overlap the exposure (with some margin)
199  (an lsst::afw::table::SimpleCatalog)
200  - matches astrometric matches, a list of lsst.afw.table.ReferenceMatch
201  - scatterOnSky median on-sky separation between reference objects and sources in "matches"
202  (an lsst.afw.geom.Angle)
203  - matchMeta metadata needed to unpersist matches (an lsst.daf.base.PropertyList)
204 
205  @note ignores config.forceKnownWcs
206  """
207  import lsstDebug
208  debug = lsstDebug.Info(__name__)
209 
210  matchMeta = createMatchMetadata(exposure, border=self.refObjLoader.config.pixelMargin)
211  expMd = self._getExposureMetadata(exposure)
212  exp_bbox = expMd.bbox
213  exp_bbox.grow(afwGeom.Extent2I(self.config.matcher.maxOffsetPix,
214  self.config.matcher.maxOffsetPix))
215 
216  loadRes = self.refObjLoader.loadPixelBox(
217  bbox=exp_bbox,
218  wcs=expMd.wcs,
219  filterName=expMd.filterName,
220  calib=expMd.calib,
221  )
222  if debug.display:
223  frame = int(debug.frame)
225  refCat=loadRes.refCat,
226  sourceCat=sourceCat,
227  exposure=exposure,
228  bbox=expMd.bbox,
229  frame=frame,
230  title="Reference catalog",
231  )
232 
233  res = None
234  wcs = expMd.wcs
235  match_tolerance = None
236  for i in range(self.config.maxIter):
237  iterNum = i + 1
238  try:
239  tryRes = self._matchAndFitWcs( # refCat, sourceCat, refFluxField, bbox, wcs, exposure=None
240  refCat=loadRes.refCat,
241  sourceCat=sourceCat,
242  refFluxField=loadRes.fluxField,
243  bbox=expMd.bbox,
244  wcs=wcs,
245  exposure=exposure,
246  match_tolerance=match_tolerance,
247  )
248  except Exception as e:
249  # if we have had a succeessful iteration then use that; otherwise fail
250  if i > 0:
251  self.log.info("Fit WCS iter %d failed; using previous iteration: %s" % (iterNum, e))
252  iterNum -= 1
253  break
254  else:
255  raise
256 
257  match_tolerance = tryRes.match_tolerance
258  tryMatchDist = self._computeMatchStatsOnSky(tryRes.matches)
259  self.log.debug(
260  "Match and fit WCS iteration %d: found %d matches with scatter = %0.3f +- %0.3f arcsec; "
261  "max match distance = %0.3f arcsec",
262  iterNum, len(tryRes.matches), tryMatchDist.distMean.asArcseconds(),
263  tryMatchDist.distStdDev.asArcseconds(), tryMatchDist.maxMatchDist.asArcseconds())
264 
265  maxMatchDist = tryMatchDist.maxMatchDist
266  res = tryRes
267  wcs = res.wcs
268  if maxMatchDist.asArcseconds() < self.config.minMatchDistanceArcSec:
269  self.log.debug(
270  "Max match distance = %0.3f arcsec < %0.3f = config.minMatchDistanceArcSec; "
271  "that's good enough",
272  maxMatchDist.asArcseconds(), self.config.minMatchDistanceArcSec)
273  break
274  match_tolerance.maxMatchDist = maxMatchDist
275 
276  self.log.info(
277  "Matched and fit WCS in %d iterations; "
278  "found %d matches with scatter = %0.3f +- %0.3f arcsec" %
279  (iterNum, len(tryRes.matches), tryMatchDist.distMean.asArcseconds(),
280  tryMatchDist.distStdDev.asArcseconds()))
281 
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.image.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.image.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
Match sources to reference objects and fit a WCS.
Definition: astrometry.py:296
def __init__
Construct an AstrometryTask.
Definition: astrometry.py:146
def run
Load reference objects, match sources and optionally fit a WCS.
Definition: astrometry.py:164
def solve
Load reference objects overlapping an exposure, match to sources and fit a WCS.
Definition: astrometry.py:194
Match an input source catalog with objects from a reference catalog and solve for the WCS...
Definition: astrometry.py:72