lsst.meas.astrom.pessimistic_pattern_matcher_b_3D.PessimisticPatternMatcherB Class Reference

Public Member Functions
def	__init__ (self, reference_array, log)
def	match (self, source_array, n_check, n_match, n_agree, max_n_patterns, max_shift, max_rotation, max_dist, min_matches, pattern_skip_array=None)

Public Attributes
	log

Detailed Description

Class implementing a pessimistic version of Optimistic Pattern Matcher
B (OPMb) from Tabur 2007. See `DMTN-031 <http://ls.st/DMTN-031`_

Parameters
----------
reference_array : `numpy.ndarray`, (N, 3)
    spherical points x, y, z of to use as reference objects for
    pattern matching.
log : `lsst.log.Log`
    Logger for outputting debug info.

Notes
-----
The class loads and stores the reference object
in a convenient data structure for matching any set of source objects that
are assumed to contain each other. The pessimistic nature of the algorithm
comes from requiring that it discovers at least two patterns that agree on
the correct shift and rotation for matching before exiting. The original
behavior of OPMb can be recovered simply. Patterns matched between the
input datasets are n-spoked pinwheels created from n+1 points. Refer to
DMTN #031 for more details. http://github.com/lsst-dm/dmtn-031

Definition at line 53 of file pessimistic_pattern_matcher_b_3D.py.

Constructor & Destructor Documentation

__init__()

def lsst.meas.astrom.pessimistic_pattern_matcher_b_3D.PessimisticPatternMatcherB.__init__	(		self,
			reference_array,
			log
	)

Definition at line 77 of file pessimistic_pattern_matcher_b_3D.py.

    def __init__(self, reference_array, log):
        self._reference_array = reference_array
        self._n_reference = len(self._reference_array)
        self.log = log
 
        if self._n_reference > 0:
            self._build_distances_and_angles()
        else:
            raise ValueError("No reference objects supplied")
 

Member Function Documentation

match()

def lsst.meas.astrom.pessimistic_pattern_matcher_b_3D.PessimisticPatternMatcherB.match	(		self,
			source_array,
			n_check,
			n_match,
			n_agree,
			max_n_patterns,
			max_shift,
			max_rotation,
			max_dist,
			min_matches,
			pattern_skip_array = None
	)

Match a given source catalog into the loaded reference catalog.

Given array of points on the unit sphere and tolerances, we
attempt to match a pinwheel like pattern between these input sources
and the reference objects this class was created with. This pattern
informs of the shift and rotation needed to align the input source
objects into the frame of the references.

Parameters
----------
source_array : `numpy.ndarray`, (N, 3)
    An array of spherical x,y,z coordinates and a magnitude in units
    of objects having a lower value for sorting. The array should be
    of shape (N, 4).
n_check  : `int`
    Number of sources to create a pattern from. Not all objects may be
    checked if n_match criteria is before looping through all n_check
    objects.
n_match : `int`
    Number of objects to use in constructing a pattern to match.
n_agree : `int`
    Number of found patterns that must agree on their shift and
    rotation before exiting. Set this value to 1 to recover the
    expected behavior of Optimistic Pattern Matcher B.
max_n_patters : `int`
    Number of patterns to create from the input source objects to
    attempt to match into the reference objects.
max_shift : `float`
    Maximum allowed shift to match patterns in arcseconds.
max_rotation : `float`
    Maximum allowed rotation between patterns in degrees.
max_dist : `float`
    Maximum distance in arcseconds allowed between candidate spokes in
    the source and reference objects. Also sets that maximum distance
    in the intermediate verify, pattern shift/rotation agreement, and
    final verify steps.
pattern_skip_array : `int`
    Patterns we would like to skip. This could be due to the pattern
    being matched on a previous iteration that we now consider invalid.
    This assumes the ordering of the source objects is the same
    between different runs of the matcher which, assuming no object
    has been inserted or the magnitudes have changed, it should be.

Returns
-------
output_struct : `lsst.pipe.base.Struct`
    Result struct with components

    - ``matches`` : (N, 2) array of matched ids for pairs. Empty list if no
      match found (`numpy.ndarray`, (N, 2) or `list`)
    - ``distances_rad`` : Radian distances between the matched objects.
      Empty list if no match found (`numpy.ndarray`, (N,))
    - ``pattern_idx``: Index of matched pattern. None if no match found
      (`int`).
    - ``shift`` : Magnitude for the shift between the source and reference
      objects in arcseconds. None if no match found (`float`).

Definition at line 166 of file pessimistic_pattern_matcher_b_3D.py.

              min_matches, pattern_skip_array=None):
        """Match a given source catalog into the loaded reference catalog.
 
        Given array of points on the unit sphere and tolerances, we
        attempt to match a pinwheel like pattern between these input sources
        and the reference objects this class was created with. This pattern
        informs of the shift and rotation needed to align the input source
        objects into the frame of the references.
 
        Parameters
        ----------
        source_array : `numpy.ndarray`, (N, 3)
            An array of spherical x,y,z coordinates and a magnitude in units
            of objects having a lower value for sorting. The array should be
            of shape (N, 4).
        n_check  : `int`
            Number of sources to create a pattern from. Not all objects may be
            checked if n_match criteria is before looping through all n_check
            objects.
        n_match : `int`
            Number of objects to use in constructing a pattern to match.
        n_agree : `int`
            Number of found patterns that must agree on their shift and
            rotation before exiting. Set this value to 1 to recover the
            expected behavior of Optimistic Pattern Matcher B.
        max_n_patters : `int`
            Number of patterns to create from the input source objects to
            attempt to match into the reference objects.
        max_shift : `float`
            Maximum allowed shift to match patterns in arcseconds.
        max_rotation : `float`
            Maximum allowed rotation between patterns in degrees.
        max_dist : `float`
            Maximum distance in arcseconds allowed between candidate spokes in
            the source and reference objects. Also sets that maximum distance
            in the intermediate verify, pattern shift/rotation agreement, and
            final verify steps.
        pattern_skip_array : `int`
            Patterns we would like to skip. This could be due to the pattern
            being matched on a previous iteration that we now consider invalid.
            This assumes the ordering of the source objects is the same
            between different runs of the matcher which, assuming no object
            has been inserted or the magnitudes have changed, it should be.
 
        Returns
        -------
        output_struct : `lsst.pipe.base.Struct`
            Result struct with components
 
            - ``matches`` : (N, 2) array of matched ids for pairs. Empty list if no
              match found (`numpy.ndarray`, (N, 2) or `list`)
            - ``distances_rad`` : Radian distances between the matched objects.
              Empty list if no match found (`numpy.ndarray`, (N,))
            - ``pattern_idx``: Index of matched pattern. None if no match found
              (`int`).
            - ``shift`` : Magnitude for the shift between the source and reference
              objects in arcseconds. None if no match found (`float`).
        """
 
        # Given our input source_array we sort on magnitude.
        sorted_source_array = source_array[source_array[:, -1].argsort(), :3]
        n_source = len(sorted_source_array)
 
        # Initialize output struct.
        output_match_struct = pipeBase.Struct(
            match_ids=[],
            distances_rad=[],
            pattern_idx=None,
            shift=None,
            max_dist_rad=None,)
 
        if n_source <= 0:
            self.log.warn("Source object array is empty. Unable to match. "
                          "Exiting matcher.")
            return None
 
        # To test if the shifts and rotations we find agree with each other,
        # we first create two test points situated at the top and bottom of
        # where the z axis on the sphere bisects the source catalog.
        test_vectors = self._compute_test_vectors(source_array[:, :3])
 
        # We now create an empty list of our resultant rotated vectors to
        # compare the different rotations we find.
        rot_vect_list = []
 
        # Convert the tolerances to values we will use in the code.
        max_cos_shift = np.cos(np.radians(max_shift / 3600.))
        max_cos_rot_sq = np.cos(np.radians(max_rotation)) ** 2
        max_dist_rad = np.radians(max_dist / 3600.)
 
        # Loop through the sources from brightest to faintest, grabbing a
        # chunk of n_check each time.
        for pattern_idx in range(np.min((max_n_patterns,
                                         n_source - n_match))):
 
            # If this pattern is one that we matched on the past but we
            # now want to skip, we do so here.
            if pattern_skip_array is not None and \
               np.any(pattern_skip_array == pattern_idx):
                self.log.debug(
                    "Skipping previously matched bad pattern %i..." %
                    pattern_idx)
                continue
            # Grab the sources to attempt to create this pattern.
            pattern = sorted_source_array[
                pattern_idx: np.min((pattern_idx + n_check, n_source)), :3]
 
            # Construct a pattern given the number of points defining the
            # pattern complexity. This is the start of the primary tests to
            # match our source pattern into the reference objects.
            construct_return_struct = \
                self._construct_pattern_and_shift_rot_matrix(
                    pattern, n_match, max_cos_shift, max_cos_rot_sq,
                    max_dist_rad)
 
            # Our struct is None if we could not match the pattern.
            if construct_return_struct.ref_candidates is None or \
               construct_return_struct.shift_rot_matrix is None or \
               construct_return_struct.cos_shift is None or \
               construct_return_struct.sin_rot is None:
                continue
 
            # Grab the output data from the Struct object.
            ref_candidates = construct_return_struct.ref_candidates
            shift_rot_matrix = construct_return_struct.shift_rot_matrix
            cos_shift = construct_return_struct.cos_shift
            sin_rot = construct_return_struct.sin_rot
 
            # If we didn't match enough candidates we continue to the next
            # pattern.
            if len(ref_candidates) < n_match:
                continue
 
            # Now that we know our pattern and shift/rotation are valid we
            # store the the rotated versions of our test points for later
            # use.
            tmp_rot_vect_list = []
            for test_vect in test_vectors:
                tmp_rot_vect_list.append(np.dot(shift_rot_matrix, test_vect))
            # Since our test point are in the source frame, we can test if
            # their lengths are mostly preserved under the transform.
            if not self._test_pattern_lengths(np.array(tmp_rot_vect_list),
                                              max_dist_rad):
                continue
 
            tmp_rot_vect_list.append(pattern_idx)
            rot_vect_list.append(tmp_rot_vect_list)
 
            # Test if we have enough rotations, which agree, or if we
            # are in optimistic mode.
            if self._test_rotation_agreement(rot_vect_list, max_dist_rad) < \
               n_agree - 1:
                continue
 
            # Run the final verify step.
            match_struct = self._final_verify(source_array[:, :3],
                                              shift_rot_matrix,
                                              max_dist_rad,
                                              min_matches)
            if match_struct.match_ids is None or \
               match_struct.distances_rad is None or \
               match_struct.max_dist_rad is None:
                continue
 
            # Convert the observed shift to arcseconds
            shift = np.degrees(np.arccos(cos_shift)) * 3600.
            # Print information to the logger.
            self.log.debug("Succeeded after %i patterns." % pattern_idx)
            self.log.debug("\tShift %.4f arcsec" % shift)
            self.log.debug("\tRotation: %.4f deg" %
                           np.degrees(np.arcsin(sin_rot)))
 
            # Fill the struct and return.
            output_match_struct.match_ids = \
                match_struct.match_ids
            output_match_struct.distances_rad = \
                match_struct.distances_rad
            output_match_struct.pattern_idx = pattern_idx
            output_match_struct.shift = shift
            output_match_struct.max_dist_rad = match_struct.max_dist_rad
            return output_match_struct
 
        self.log.debug("Failed after %i patterns." % (pattern_idx + 1))
        return output_match_struct
 

Member Data Documentation

log

lsst.meas.astrom.pessimistic_pattern_matcher_b_3D.PessimisticPatternMatcherB.log

Definition at line 80 of file pessimistic_pattern_matcher_b_3D.py.

---

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

• /j/snowflake/release/lsstsw/stack/lsst-scipipe-0.7.0/Linux64/meas_astrom/22.0.1-4-g8623105+b8044ec9de/python/lsst/meas/astrom/pessimistic_pattern_matcher_b_3D.py