docs: def match_lists(pos1, pos2, tolerance=MATCH_TOLERANCE, spherical=False):
      """
      Given two sets of x/y positions match the lists, uniquely.
  
      :rtype : numpy.ma, numpy.ma
      :param pos1: list of x/y positions.
      :param pos2: list of x/y positions.
      :param tolerance: float distance, in pixels, to consider a match
  
      Algorithm:
          - Find all the members of pos2 that are within tolerance of pos1[idx1].
                  These pos2 members are match_group_1
          - Find all the members of pos1 that are within tolerance of match_group_1[idx2].
                  These pos1 members are match_group_2
          - If pos1[idx] is in match_group_2 then pos1[idx] is a match of object at match_group_1[idx2]
  
      """
  
      assert isinstance(pos1, numpy.ndarray)
      assert isinstance(pos2, numpy.ndarray)
  
  
      # build some arrays to hold the index of things that matched between lists.
      npts2 = npts1 = 0
  
      if len(pos1) > 0:
          npts1 = len(pos1[:, 0])
      pos1_idx_array = numpy.arange(npts1, dtype=numpy.int16)
  
      if len(pos2) > 0:
          npts2 = len(pos2[:, 0])
      pos2_idx_array = numpy.arange(npts2, dtype=numpy.int16)
  
      # this is the array of final matched index, -1 indicates no match found.
      match1 = numpy.ma.zeros(npts1, dtype=numpy.int16)
      match1.mask = True
  
      # this is the array of matches in pos2, -1 indicates no match found.
      match2 = numpy.ma.zeros(npts2, dtype=numpy.int16)
      match2.mask = True
  
      # if one of the two input arrays are zero length then there is no matching to do.
      if npts1 * npts2 == 0:
          return match1, match2
  
      for idx1 in range(npts1):
  
          # compute the distance source idx1 to each member of pos2
          if not spherical :
             sep = numpy.sqrt((pos2[:, 0] - pos1[idx1, 0]) ** 2 + (pos2[:, 1] - pos1[idx1, 1]) ** 2)
          else:
             sep = numpy.sqrt((numpy.cos(numpy.radians(pos1[idx1,1]))*(pos2[:, 0] - pos1[idx1, 0])) ** 2 + (pos2[:, 1] - pos1[idx1, 1]) ** 2)
          
  
          # considered a match if sep is below tolerance and is the closest match available.
          match_condition = numpy.all((sep <= tolerance, sep == sep.min()), axis=0)
  
          # match_group_1 is list of the indexes of pos2 entries that qualified as possible matches to pos1[idx1]
          match_group_1 = pos2_idx_array[match_condition]
  
          # For each of those pos2 objects that could be a match to pos1[idx] find the best match in all of pos1
          for idx2 in match_group_1:
              # compute the distance from this pos2 object that is a possible match to pos1[idx1] to all members of pos1
              sep = numpy.sqrt((pos1[:, 0] - pos2[idx2, 0]) ** 2 + (pos1[:, 1] - pos2[idx2, 1]) ** 2)
  
              # considered a match if sep is below tolerance and is the closest match available.
              match_condition = numpy.all((sep <= tolerance, sep == sep.min()), axis=0)
              match_group_2 = pos1_idx_array[match_condition]
  
              # Are any of the pos1 members that were matches to the matched pos2 member the pos1[idx] entry?
              if idx1 in match_group_2:
                  match1[idx1] = idx2
                  match2[idx2] = idx1
                  # this BREAK is in here since once we have a match we're done.
                  break
  
      return match1, match2