lsst.meas.astrom gf1cff7945b+bd2ed33bd6
Loading...
Searching...
No Matches
Public Member Functions | Public Attributes | Protected Member Functions | Protected Attributes | List of all members
lsst.meas.astrom.pessimistic_pattern_matcher_b_3D.PessimisticPatternMatcherB Class Reference

Public Member Functions

 __init__ (self, reference_array, log)
 
 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
 

Protected Member Functions

 _build_distances_and_angles (self)
 
 _compute_test_vectors (self, source_array)
 
 _construct_pattern_and_shift_rot_matrix (self, src_pattern_array, n_match, max_cos_theta_shift, max_cos_rot_sq, max_dist_rad)
 
 _intermediate_verify (self, src_pattern, ref_pattern, shift_rot_matrix, max_dist_rad)
 
 _create_spherical_rotation_matrix (self, rot_axis, cos_rotation, sin_rotion)
 
 _intermediate_verify_comparison (self, pattern_a, pattern_b, shift_rot_matrix, max_dist_rad)
 
 _test_pattern_lengths (self, test_pattern, max_dist_rad)
 
 _test_rotation_agreement (self, rot_vects, max_dist_rad)
 
 _final_verify (self, source_array, shift_rot_matrix, max_dist_rad, min_matches)
 
 _clip_distances (self, distances_rad)
 
 _match_sources (self, source_array, shift_rot_matrix)
 
 _handshake_match (self, matches_src, matches_ref)
 

Protected Attributes

 _reference_array
 
 _n_reference
 
 _dist_array
 
 _id_array
 

Detailed Description

Class implementing a pessimistic version of Optimistic Pattern Matcher
B (OPMb) from `Tabur (2007)`_, as described in `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` or `logging.Logger`
    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.

.. _Tabur (2007): https://doi.org/10.1071/AS07028
.. _DMTN-031: https://dmtn-031.lsst.io/

Definition at line 77 of file pessimistic_pattern_matcher_b_3D.py.

Constructor & Destructor Documentation

◆ __init__()

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

Definition at line 104 of file pessimistic_pattern_matcher_b_3D.py.

Member Function Documentation

◆ _build_distances_and_angles()

lsst.meas.astrom.pessimistic_pattern_matcher_b_3D.PessimisticPatternMatcherB._build_distances_and_angles ( self)
protected
Create the data structures we will use to search for our pattern
match in.

Throughout this function and the rest of the class we use id to
reference the position in the input reference catalog and index to
'index' into the arrays sorted on distance.

Definition at line 114 of file pessimistic_pattern_matcher_b_3D.py.

◆ _clip_distances()

lsst.meas.astrom.pessimistic_pattern_matcher_b_3D.PessimisticPatternMatcherB._clip_distances ( self,
distances_rad )
protected
Compute a clipped max distance and calculate the number of pairs
that pass the clipped dist.

Parameters
----------
distances_rad : `numpy.ndarray`, (N,)
    Distances between pairs.

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

    - ``n_matched_clipped`` : Number of pairs that survive the
      clipping on distance. (`float`)
    - ``clipped_max_dist`` : Maximum distance after clipping.
      (`float`).

Definition at line 764 of file pessimistic_pattern_matcher_b_3D.py.

◆ _compute_test_vectors()

lsst.meas.astrom.pessimistic_pattern_matcher_b_3D.PessimisticPatternMatcherB._compute_test_vectors ( self,
source_array )
protected
Compute spherical 3 vectors at the edges of the x, y, z extent
of the input source catalog.

Parameters
----------
source_array : `numpy.ndarray`, (N, 3)
    array of 3 vectors representing positions on the unit
    sphere.

Returns
-------
test_vectors : `numpy.ndarray`, (N, 3)
    Array of vectors representing the maximum extents in x, y, z
    of the input source array. These are used with the rotations
    the code finds to test for agreement from different patterns
    when the code is running in pessimistic mode.

Definition at line 345 of file pessimistic_pattern_matcher_b_3D.py.

◆ _construct_pattern_and_shift_rot_matrix()

lsst.meas.astrom.pessimistic_pattern_matcher_b_3D.PessimisticPatternMatcherB._construct_pattern_and_shift_rot_matrix ( self,
src_pattern_array,
n_match,
max_cos_theta_shift,
max_cos_rot_sq,
max_dist_rad )
protected
Test an input source pattern against the reference catalog.
Returns the candidate matched patterns and their
implied rotation matrices or None.

Parameters
----------
src_pattern_array : `numpy.ndarray`, (N, 3)
    Sub selection of source 3 vectors to create a pattern from
n_match : `int`
    Number of points to attempt to create a pattern from. Must be
    >= len(src_pattern_array)
max_cos_theta_shift : `float`
    Maximum shift allowed between two patterns' centers.
max_cos_rot_sq : `float`
    Maximum rotation between two patterns that have been shifted
    to have their centers on top of each other.
max_dist_rad : `float`
    Maximum delta distance allowed between the source and reference
    pair distances to consider the reference pair a candidate for
    the source pair. Also sets the tolerance between the opening
    angles of the spokes when compared to the reference.

Return
-------
output_matched_pattern : `lsst.pipe.base.Struct`
    Result struct with components:

    - ``ref_candidates`` : ids of the matched pattern in the internal
      reference_array object (`list` of `int`).
    - ``src_candidates`` : Pattern ids of the sources matched
      (`list` of `int`).
    - ``shift_rot_matrix_src_to_ref`` : 3x3 matrix specifying the full
      shift and rotation between the reference and source objects.
      Rotates source into reference frame. `None` if match is not
      found. (`numpy.ndarray`, (3, 3))
    - ``shift_rot_matrix_ref_to_src`` : 3x3 matrix specifying the full
      shift and rotation of the reference and source objects. Rotates
      reference into source frame. None if match is not found
      (`numpy.ndarray`, (3, 3)).
    - ``cos_shift`` : Magnitude of the shift found between the two
      patten centers. `None` if match is not found (`float`).
    - ``sin_rot`` : float value of the rotation to align the already
      shifted source pattern to the reference pattern. `None` if no match
      found (`float`).

Definition at line 396 of file pessimistic_pattern_matcher_b_3D.py.

◆ _create_spherical_rotation_matrix()

lsst.meas.astrom.pessimistic_pattern_matcher_b_3D.PessimisticPatternMatcherB._create_spherical_rotation_matrix ( self,
rot_axis,
cos_rotation,
sin_rotion )
protected
Construct a generalized 3D rotation matrix about a given
axis.

Parameters
----------
rot_axis : `numpy.ndarray`, (3,)
    3 vector defining the axis to rotate about.
cos_rotation : `float`
    cosine of the rotation angle.
sin_rotation : `float`
    sine of the rotation angle.

Return
------
shift_matrix : `numpy.ndarray`, (3, 3)
    3x3 spherical, rotation matrix.

Definition at line 535 of file pessimistic_pattern_matcher_b_3D.py.

◆ _final_verify()

lsst.meas.astrom.pessimistic_pattern_matcher_b_3D.PessimisticPatternMatcherB._final_verify ( self,
source_array,
shift_rot_matrix,
max_dist_rad,
min_matches )
protected
Match the all sources into the reference catalog using the shift/rot
matrix.

After the initial shift/rot matrix is found, we refit the shift/rot
matrix using the matches the initial matrix produces to find a more
stable solution.

Parameters
----------
source_array : `numpy.ndarray` (N, 3)
    3-vector positions on the unit-sphere representing the sources to
    match
shift_rot_matrix : `numpy.ndarray` (3, 3)
    Rotation matrix representing inferred shift/rotation of the
    sources onto the reference catalog. Matrix need not be unitary.
max_dist_rad : `float`
    Maximum distance allowed for a match.
min_matches : `int`
    Minimum number of matched objects required to consider the
    match good.

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

    - ``match_ids`` : Pairs of indexes into the source and reference
      data respectively defining a match (`numpy.ndarray`, (N, 2)).
    - ``distances_rad`` : distances to between the matched objects in
      the shift/rotated frame. (`numpy.ndarray`, (N,)).
    - ``max_dist_rad`` : Value of the max matched distance. Either
      returning the input value of the 2 sigma clipped value of the
      shift/rotated distances. (`float`).

Definition at line 665 of file pessimistic_pattern_matcher_b_3D.py.

◆ _handshake_match()

lsst.meas.astrom.pessimistic_pattern_matcher_b_3D.PessimisticPatternMatcherB._handshake_match ( self,
matches_src,
matches_ref )
protected
Return only those matches where both the source
and reference objects agree they they are each others'
nearest neighbor.

Parameters
----------
matches_src : `numpy.ndarray`, (N, 2)
    int array of nearest neighbor matches between shifted and
    rotated reference objects matched into the sources.
matches_ref : `numpy.ndarray`, (N, 2)
    int array of nearest neighbor matches between shifted and
    rotated source objects matched into the references.

Return
------
handshake_mask_array : `numpy.ndarray`, (N,)
    Array positions where the two match catalogs agree.

Definition at line 862 of file pessimistic_pattern_matcher_b_3D.py.

◆ _intermediate_verify()

lsst.meas.astrom.pessimistic_pattern_matcher_b_3D.PessimisticPatternMatcherB._intermediate_verify ( self,
src_pattern,
ref_pattern,
shift_rot_matrix,
max_dist_rad )
protected
 Perform an intermediate verify step.
Rotate the matches references into the source frame and test their
distances against tolerance. Only return true if all points are within
tolerance.

Parameters
----------
src_pattern : `numpy.ndarray`, (N,3)
    Array of 3 vectors representing the points that make up our source
    pinwheel pattern.
ref_pattern : `numpy.ndarray`, (N,3)
    Array of 3 vectors representing our candidate reference pinwheel
    pattern.
shift_rot_matrix : `numpy.ndarray`, (3,3)
    3x3 rotation matrix that takes the source objects and rotates them
    onto the frame of the reference objects
max_dist_rad : `float`
    Maximum distance allowed to consider two objects the same.

Returns
-------
fit_shift_rot_matrix : `numpy.ndarray`, (3,3)
   Fitted shift/rotation matrix if all of the points in our
   source pattern are within max_dist_rad of their matched reference
   objects. Returns None if this criteria is not satisfied.

Definition at line 479 of file pessimistic_pattern_matcher_b_3D.py.

◆ _intermediate_verify_comparison()

lsst.meas.astrom.pessimistic_pattern_matcher_b_3D.PessimisticPatternMatcherB._intermediate_verify_comparison ( self,
pattern_a,
pattern_b,
shift_rot_matrix,
max_dist_rad )
protected
Test the input rotation matrix against one input pattern and
a second one.

If every point in the pattern after rotation is within a distance of
max_dist_rad to its candidate point in the other pattern, we return
True.

Parameters
----------
pattern_a :  `numpy.ndarray`, (N,3)
    Array of 3 vectors representing the points that make up our source
    pinwheel pattern.
pattern_b :  `numpy.ndarray`, (N,3)
    Array of 3 vectors representing our candidate reference pinwheel
    pattern.
shift_rot_matrix :  `numpy.ndarray`, (3,3)
    3x3 rotation matrix that takes the source objects and rotates them
    onto the frame of the reference objects
max_dist_rad : `float`
    Maximum distance allowed to consider two objects the same.


Returns
-------
bool
    True if all rotated source points are within max_dist_rad of
    the candidate references matches.

Definition at line 564 of file pessimistic_pattern_matcher_b_3D.py.

◆ _match_sources()

lsst.meas.astrom.pessimistic_pattern_matcher_b_3D.PessimisticPatternMatcherB._match_sources ( self,
source_array,
shift_rot_matrix )
protected
 Shift both the reference and source catalog to the the respective
frames and find their nearest neighbor using a kdTree.

Removes all matches who do not agree when either the reference or
source catalog is rotated. Cuts on a maximum distance are left to an
external function.

Parameters
----------
source_array : `numpy.ndarray`, (N, 3)
    array of 3 vectors representing the source objects we are trying
    to match into the source catalog.
shift_rot_matrix : `numpy.ndarray`, (3, 3)
    3x3 rotation matrix that performs the spherical rotation from the
    source frame into the reference frame.

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

    - ``matches`` : array of integer ids into the source and
      reference arrays. Matches are only returned for those that
      satisfy the distance and handshake criteria
      (`numpy.ndarray`, (N, 2)).
    - ``distances`` : Distances between each match in radians after
      the shift and rotation is applied (`numpy.ndarray`, (N)).

Definition at line 798 of file pessimistic_pattern_matcher_b_3D.py.

◆ _test_pattern_lengths()

lsst.meas.astrom.pessimistic_pattern_matcher_b_3D.PessimisticPatternMatcherB._test_pattern_lengths ( self,
test_pattern,
max_dist_rad )
protected
 Test that the all vectors in a pattern are unit length within
tolerance.

This is useful for assuring the non unitary transforms do not contain
too much distortion.

Parameters
----------
test_pattern : `numpy.ndarray`, (N, 3)
    Test vectors at the maximum and minimum x, y, z extents.
max_dist_rad : `float`
    maximum distance in radians to consider two points "agreeing" on
    a rotation

Returns
-------
test : `bool`
    Length tests pass.

Definition at line 602 of file pessimistic_pattern_matcher_b_3D.py.

◆ _test_rotation_agreement()

lsst.meas.astrom.pessimistic_pattern_matcher_b_3D.PessimisticPatternMatcherB._test_rotation_agreement ( self,
rot_vects,
max_dist_rad )
protected
 Test this rotation against the previous N found and return
the number that a agree within tolerance to where our test
points are.

Parameters
----------
rot_vects : `numpy.ndarray`, (N, 3)
    Arrays of rotated 3 vectors representing the maximum x, y,
    z extent on the unit sphere of the input source objects rotated by
    the candidate rotations into the reference frame.
max_dist_rad : `float`
    maximum distance in radians to consider two points "agreeing" on
    a rotation

Returns
-------
tot_consent : `int`
    Number of candidate rotations that agree for all of the rotated
    test 3 vectors.

Definition at line 629 of file pessimistic_pattern_matcher_b_3D.py.

◆ match()

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 160 of file pessimistic_pattern_matcher_b_3D.py.

Member Data Documentation

◆ _dist_array

lsst.meas.astrom.pessimistic_pattern_matcher_b_3D.PessimisticPatternMatcherB._dist_array
protected

Definition at line 124 of file pessimistic_pattern_matcher_b_3D.py.

◆ _id_array

lsst.meas.astrom.pessimistic_pattern_matcher_b_3D.PessimisticPatternMatcherB._id_array
protected

Definition at line 127 of file pessimistic_pattern_matcher_b_3D.py.

◆ _n_reference

lsst.meas.astrom.pessimistic_pattern_matcher_b_3D.PessimisticPatternMatcherB._n_reference
protected

Definition at line 106 of file pessimistic_pattern_matcher_b_3D.py.

◆ _reference_array

lsst.meas.astrom.pessimistic_pattern_matcher_b_3D.PessimisticPatternMatcherB._reference_array
protected

Definition at line 105 of file pessimistic_pattern_matcher_b_3D.py.

◆ log

lsst.meas.astrom.pessimistic_pattern_matcher_b_3D.PessimisticPatternMatcherB.log

Definition at line 107 of file pessimistic_pattern_matcher_b_3D.py.


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