Add an iterative "final verify" step to pessB.

Clarify AstrometryTask doc.
Remove TODO from completed ticket.
Update AstrometryTask doc Parameters.

Add explaination to unittest min pixel value.

Add explaination to unittest regarding number of matched objects.

Reword iterative final verify comment.

Refine iterative final verify comment.

python/lsst/meas/astrom/astrometry.py

@@ -63,14 +63,16 @@ class AstrometryTask(RefMatchTask):
     """Match an input source catalog with objects from a reference catalog and
     solve for the WCS.
 
-    # TODO: DM-16868 remove explicit and unused schema from class input.
+    This task is broken into two main subasks: matching and WCS fitting which
+    are very interactive. The matching here can be considered in part a first
+    pass WCS fitter due to the fitter's sensitivity to outliers.
 
     Parameters
     ----------
     refObjLoader : `lsst.meas.algorithms.ReferenceLoader`
         A reference object loader object
     schema : `lsst.afw.table.Schema`
-        ignored; available for compatibility with an older astrometry task
+        Used to set "calib_astrometry_used" flag in output source catalog.
     **kwargs
         additional keyword arguments for pipe_base
         `lsst.pipe.base.Task.__init__`

python/lsst/meas/astrom/matchPessimisticB.py

@@ -544,9 +544,9 @@ def _doMatch(self, refCat, sourceCat, wcs, refFluxField, numUsableSources,
                 match = afwTable.ReferenceMatch()
                 match.first = refCat[int(match_id_pair[1])]
                 match.second = sourceCat[int(match_id_pair[0])]
-                # We compute the true distance along and sphere instead
-                # and store it in units of arcseconds. The previous
-                # distances we used were approximate.
+                # We compute the true distance along and sphere. This isn't
+                # used in the WCS fitter however it is used in the unittest
+                # to confirm the matches computed.
                 match.distance = match.first.getCoord().separation(
                     match.second.getCoord()).asArcseconds()
                 matches.append(match)

python/lsst/meas/astrom/pessimistic_pattern_matcher_b_3D.py

@@ -318,11 +318,27 @@ def match(self, source_array, n_check, n_match, n_agree,
             match_sources_struct = self._match_sources(source_array[:, :3],
                                                        shift_rot_matrix)
 
-            n_matched = len(match_sources_struct.match_ids[
-                match_sources_struct.distances_rad < max_dist_rad])
+            cut_ids = match_sources_struct.match_ids[
+                match_sources_struct.distances_rad < max_dist_rad]
+            n_matched = len(cut_ids)
 
             # Check that we have enough matches.
             if n_matched >= min_matches:
+                # The shift/rotation matrix returned by
+                # ``_construct_pattern_and_shift_rot_matrix``, above, was
+                # based on only six points. Here, we refine that result by
+                # using all of the good matches from the “final verification”
+                # step, above. This will produce a more consistent result.
+                fit_shift_rot_matrix = least_squares(
+                    _rotation_matrix_chi_sq,
+                    x0=shift_rot_matrix.flatten(),
+                    args=(source_array[cut_ids[:, 0], :3],
+                          self._reference_array[cut_ids[:, 1], :3],
+                          max_dist_rad)
+                ).x.reshape((3, 3))
+                match_sources_struct = self._match_sources(
+                    source_array[:, :3], fit_shift_rot_matrix)
+
                 # Convert the observed shift to arcseconds
                 shift = np.degrees(np.arccos(cos_shift)) * 3600.
                 # Print information to the logger.

tests/test_matchPessimisticB.py

@@ -43,7 +43,10 @@ def setUp(self):
         np.random.seed(12345)
 
         self.config = measAstrom.MatchPessimisticBTask.ConfigClass()
-        self.config.minMatchDistPixels = 3.0
+        # Value below is to assure all matches are selected. The
+        # original test is set for a 3 arcsecond max match distance
+        # using matchOptimisticB.
+        self.config.minMatchDistPixels = 2.0
         self.MatchPessimisticB = measAstrom.MatchPessimisticBTask(
             config=self.config)
 
@@ -56,6 +59,9 @@ def setUp(self):
         self.tolArcsec = .4
         self.tolPixel = .1
 
+        # 3 of the objects are removed by the source selector and are used in
+        # matching hence the 183 number vs the total of 186. This is also why
+        # these three objects are missing in the testReferenceFilter test.
         self.expectedMatches = 183
 
     def tearDown(self):
@@ -220,8 +226,6 @@ def testReferenceFilter(self):
             refFluxField="r_flux",
         )
 
-        # One of the reference objects is part of the 3 that are never matched
-        # in all previous verions of the mathcer including MathcOptimisticB.
         self.assertEqual(len(matchRes.matches), matchPessConfig.maxRefObjects - 3)
 
     def computePosRefCatalog(self, sourceCat):