lsst.meas.astrom  14.0-7-g0d69b06+3
Public Member Functions | Public Attributes | Static Public Attributes | List of all members
lsst.meas.astrom.fitSipDistortion.FitSipDistortionTask Class Reference
Inheritance diagram for lsst.meas.astrom.fitSipDistortion.FitSipDistortionTask:

Public Member Functions

def __init__ (self, kwds)
 
def fitWcs (self, matches, initWcs, bbox=None, refCat=None, sourceCat=None, exposure=None)
 
def display (self, revFitter, exposure=None, bbox=None, frame=0, pause=True)
 
def makeInitialWcs (self, matches, wcs)
 

Public Attributes

 outlierRejectionCtrl
 

Static Public Attributes

 ConfigClass = FitSipDistortionConfig
 

Detailed Description

Fit a TAN-SIP WCS given a list of reference object/source matches

FitSipDistortionTask is a drop-in replacement for
:py:class:`lsst.meas.astrom.FitTanSipWcsTask`.  It is built on fundamentally
stronger fitting algorithms, but has received significantly less testing.

Like :py:class:`lsst.meas.astrom.FitTanSipWcsTask`, this task is most
easily used as the wcsFitter component of
:py:class:`lsst.meas.astrom.AstrometryTask`; it can be enabled in a config
file via e.g.

.. code-block:: py

   from lsst.meas.astrom import FitSipDistortionTask
   config.(...).astometry.wcsFitter.retarget(FitSipDistortionTask)

Algorithm
---------

The algorithm used by FitSipDistortionTask involves three steps:

 - We set the CRVAL and CRPIX reference points to the mean positions of
   the matches, while holding the CD matrix fixed to the value passed in
   to the run() method.  This work is done by the makeInitialWcs method.

 - We fit the SIP "reverse transform" (the AP and BP polynomials that map
   "intermediate world coordinates" to pixels).  This happens iteratively;
   while fitting for the polynomial coefficients given a set of matches is
   a linear operation that can be done without iteration, outlier
   rejection using sigma-clipping and estimation of the intrinsic scatter
   are not. By fitting the reverse transform first, we can do outlier
   rejection in pixel coordinates, where we can better handle the source
   measurement uncertainties that contribute to the overall scatter.  This
   fit results in a
   :cpp:class:`lsst::meas::astrom::ScaledPolynomialTransform`, which is
   somewhat more general than the SIP reverse transform in that it allows
   an affine transform both before and after the polynomial.  This is
   somewhat more numerically stable than the SIP form, which applies only
   a linear transform (with no offset) before the polynomial and only a
   shift afterwards.  We only convert to SIP form once the fitting is
   complete.  This conversion is exact (though it may be subject to
   significant round-off error) as long as we do not attempt to null the
   low-order SIP polynomial terms (we do not).

 - Once the SIP reverse transform has been fit, we use it to populate a
   grid of points that we use as the data points for fitting its inverse,
   the SIP forward transform.  Because our "data" here is artificial,
   there is no need for outlier rejection or uncertainty handling.  We
   again fit a general scaled polynomial, and only convert to SIP form
   when the fit is complete.


Debugging
---------

Enabling DEBUG-level logging on this task will report the number of
outliers rejected and the current estimate of intrinsic scatter at each
iteration.

FitSipDistortionTask also supports the following lsstDebug variables to
control diagnostic displays:
  - FitSipDistortionTask.display: if True, enable display diagnostics.
  - FitSipDistortionTask.frame: frame to which the display will be sent
  - FitSipDistortionTask.pause: whether to pause (by dropping into pdb)
                                between iterations (default is True).  If
                                False, multiple frames will be used,
                                starting at the given number.

The diagnostic display displays the image (or an empty image if
exposure=None) overlaid with the positions of sources and reference
objects will be shown for every iteration in the reverse transform fit.
The legend for the overlay is:

Red X
    Reference sources transformed without SIP distortion terms; this
    uses a TAN WCS whose CRPIX, CRVAL and CD matrix are the same
    as those in the TAN-SIP WCS being fit.  These are not expected to
    line up with sources unless distortion is small.

Magenta X
    Same as Red X, but for matches that were rejected as outliers.

Red O
    Reference sources using the current best-fit TAN-SIP WCS.  These
    are connected to the corresponding non-distorted WCS position by
    a red line, and should be a much better fit to source positions
    than the Red Xs.

Magenta O
    Same as Red O, but for matches that were rejected as outliers.

Green Ellipse
    Source positions and their error ellipses, including the current
    estimate of the intrinsic scatter.

Cyan Ellipse
    Same as Green Ellipse, but for matches that were rejected as outliers.


Parameters
----------
See :py:class:`lsst.pipe.base.Task`; FitSipDistortionTask does not add any
additional constructor parameters.

Definition at line 81 of file fitSipDistortion.py.

Constructor & Destructor Documentation

◆ __init__()

def lsst.meas.astrom.fitSipDistortion.FitSipDistortionTask.__init__ (   self,
  kwds 
)

Definition at line 191 of file fitSipDistortion.py.

Member Function Documentation

◆ display()

def lsst.meas.astrom.fitSipDistortion.FitSipDistortionTask.display (   self,
  revFitter,
  exposure = None,
  bbox = None,
  frame = 0,
  pause = True 
)
Display positions and outlier status overlaid on an image.

This method is called by fitWcs when display debugging is enabled.  It
always drops into pdb before returning to allow interactive inspection,
and hence it should never be called in non-interactive contexts.

Parameters
----------

revFitter : :cpp:class:`lsst::meas::astrom::ScaledPolynomialTransformFitter`
    Fitter object initialized with `fromMatches` for fitting a "reverse"
    distortion: the mapping from intermediate world coordinates to
    pixels.
exposure : :cpp:class:`lsst::afw::image::Exposure`
    An Exposure or other displayable image on which matches can be
    overplotted.
bbox : :cpp:class:`lsst::afw::geom::Box2I`
    Bounding box of the region on which matches should be plotted.

Definition at line 348 of file fitSipDistortion.py.

◆ fitWcs()

def lsst.meas.astrom.fitSipDistortion.FitSipDistortionTask.fitWcs (   self,
  matches,
  initWcs,
  bbox = None,
  refCat = None,
  sourceCat = None,
  exposure = None 
)
Fit a TAN-SIP WCS from a list of reference object/source matches

Parameters
----------

matches : list of :cpp:class:`lsst::afw::table::ReferenceMatch`
    A sequence of reference object/source matches.
    The following fields are read:
    - match.first (reference object) coord
    - match.second (source) centroid
    The following fields are written:
    - match.first (reference object) centroid,
    - match.second (source) centroid
    - match.distance (on sky separation, in radians)
initWcs : :cpp:class:`lsst::afw::geom::SkyWcs`
    An initial WCS whose CD matrix is used as the final CD matrix.
bbox : :cpp:class:`lsst::afw::geom::Box2I`
    The region over which the WCS will be valid (PARENT pixel coordinates);
    if None or an empty box then computed from matches
refCat : :cpp:class:`lsst::afw::table::SimpleCatalog`
    Reference object catalog, or None.
    If provided then all centroids are updated with the new WCS,
    otherwise only the centroids for ref objects in matches are updated.
    Required fields are "centroid_x", "centroid_y", "coord_ra", and "coord_dec".
sourceCat : :cpp:class:`lsst::afw::table::SourceCatalog`
    Source catalog, or None.
    If provided then coords are updated with the new WCS;
    otherwise only the coords for sources in matches are updated.
    Required input fields are "slot_Centroid_x", "slot_Centroid_y",
    "slot_Centroid_xSigma", "slot_Centroid_ySigma", and optionally
    "slot_Centroid_x_y_Cov".  The "coord_ra" and "coord_dec" fields
    will be updated but are not used as input.
exposure : :cpp:class:`lsst::afw::image::Exposure`
    An Exposure or other displayable image on which matches can be
    overplotted.  Ignored (and may be None) if display-based debugging
    is not enabled via lsstDebug.

Returns
-------

An lsst.pipe.base.Struct with the following fields:

wcs : :cpp:class:`lsst::afw::geom::SkyWcs`
    The best-fit WCS.
scatterOnSky : :cpp:class:`lsst::afw::geom::Angle`
    The median on-sky separation between reference objects and
    sources in "matches", as an lsst.afw.geom.Angle

Definition at line 199 of file fitSipDistortion.py.

◆ makeInitialWcs()

def lsst.meas.astrom.fitSipDistortion.FitSipDistortionTask.makeInitialWcs (   self,
  matches,
  wcs 
)
Generate a guess Wcs from the astrometric matches

We create a Wcs anchored at the center of the matches, with the scale
of the input Wcs.  This is necessary because the Wcs may have a very
approximation position (as is common with telescoped-generated Wcs).
We're using the best of each: positions from the matches, and scale
from the input Wcs.

Parameters
----------
matches : list of :cpp:class:`lsst::afw::table::ReferenceMatch`
    A sequence of reference object/source matches.
    The following fields are read:
    - match.first (reference object) coord
    - match.second (source) centroid
wcs : :cpp:class:`lsst::afw::geom::SkyWcs`
    An initial WCS whose CD matrix is used as the CD matrix of the
    result.

Returns
-------

A new :cpp:class:`lsst::afw::geom::SkyWcs`.

Definition at line 404 of file fitSipDistortion.py.

Member Data Documentation

◆ ConfigClass

lsst.meas.astrom.fitSipDistortion.FitSipDistortionTask.ConfigClass = FitSipDistortionConfig
static

Definition at line 188 of file fitSipDistortion.py.

◆ outlierRejectionCtrl

lsst.meas.astrom.fitSipDistortion.FitSipDistortionTask.outlierRejectionCtrl

Definition at line 193 of file fitSipDistortion.py.


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