PRO sympoint_match_2d, x1, y1, x2, y2, tol, nmatch, subs1, subs2, dist, SORT1 = sort1, SORT2 = sort2

; Description: This module searches for matching coordinate pairs between a pair of 
;              coordinate lists of two-dimensional points. A pair of two-dimensional
;              points P and Q from each coordinate list are considered a match if 
;              P is the closest point to Q and Q is the closest point to P (symmetric
;              point matching), and the distance between P and Q is less than "tol". 
;              A binary search algorithm is used for speed and efficiency. The module
;              returns the number of matched points "nmatch" along with the subscripts
;              "subs1" and "subs2" of the matching points within the two coordinate
;              lists.
; 
; Input Parameters:
;   
;   x1 - FLOAT/DOUBLE VECTOR - A one-dimensional vector of x coordinates for the points 
;                              in the first coordinate list. It is essential that these 
;                              values are in ascending order, unless the SORT1 keyword 
;                              is set.
;   y1 - FLOAT/DOUBLE VECTOR - A one-dimensional vector of y coordinates for the points 
;                              in the first coordinate list.
;   x2 - FLOAT/DOUBLE VECTOR - A one-dimensional vector of x coordinates for the points 
;                              in the second coordinate list. It is essential that these 
;                              values are in ascending order, unless the SORT2 keyword 
;                              is set.
;   y2 - FLOAT/DOUBLE VECTOR - A one-dimensional vector of y coordinates for the points 
;                              in the second coordinate list.
;   tol - DOUBLE - The maximum distance between points from each coordinate list that
;                  are considered as a match.
;
; Output Parameters:
;
;   nmatch - LONG - The number of matching coordinate pairs between the coordinate
;                   lists.
;   subs1 - LONG VECTOR - A one-dimensional vector of subscripts from the first 
;                         coordinate list corresponding to the matched points. This
;                         vector has "nmatch" elements, and each element in "subs1" 
;                         corresponds in order with the subscripts of the matching
;                         points from the second coordinate list "subs2".
;   subs2 - LONG VECTOR - A one-dimensional vector of subscripts from the second
;                         coordinate list corresponding to the matched points. This
;                         vector has "nmatch" elements, and each element in "subs2"
;                         corresponds in order with the subscripts of the matching
;                         points from the first coordinate list "subs1".
;   dist - DOUBLE VECTOR - A one-dimensional vector of distances between the matched
;                          points, corresponding to each entry in the vectors "subs1"
;                          and "subs2".
;
; Keywords:
; 
;   If the keyword SORT1 is set (as "/SORT1"), then the program will sort the values
;   of "x1" in to ascending order, adjusting the order of "y1" appropriately, in 
;   preparation for the binary search algorithm. The sort operation is time 
;   consuming and simply unnecessary if the vector "x1" is already sorted in
;   ascending order, and hence the SORT1 keyword is supplied as an option to allow 
;   the user to build more efficient code with this module.
;
;   Similarly, if the keyword SORT2 is set (as "/SORT2"), then the program will sort 
;   the values of "x2" in to ascending order, adjusting the order of "y2"
;   appropriately, in preparation for the binary search algorithm.
;
; Author: Dan Bramich (dan.bramich@hotmail.co.uk)
;
; History:
;
;   24/04/2009 - Further module optimisation performed (dmb).
;   03/07/2008 - Module created (dmb)  

;Check that "x1" is a vector containing number data

;Check that "y1" is a vector containing number data

;If the number of x coordinates is not equal to the number of y coordinates for the 
;first coordinate list, then return with zero matches

;Check that "x2" is a vector containing number data

;Check that "y2" is a vector containing number data

;If the number of x coordinates is not equal to the number of y coordinates for the
;second coordinate list, then return with zero matches

;Check that "tol" is a non-negative number

;If required to do so by the SORT1 keyword, then sort the "x1" values from the first 
;coordinate list in to ascending order, adjusting the order of "y1" appropriately

;If required to do so by the SORT2 keyword, then sort the "x2" values from the first
;coordinate list in to ascending order, adjusting the order of "y2" appropriately

;For each point in the first coordinate list, find the closest point in the second
;coordinate list within the specified distance tolerance "tol"

  ;Find the set of points from the second coordinate list with x coordinates within
  ;a distance of "tol" from the x coordinate of the current point from the first
  ;coordinate list

  ;Find the closest point from the second coordinate list within the specified
  ;distance tolerance, if at least one such point exists

;For each point in the second coordinate list, find the closest point in the first
;coordinate list within the specified distance tolerance "tol"

  ;Find the set of points from the first coordinate list with x coordinates within
  ;a distance of "tol" from the x coordinate of the current point from the second
  ;coordinate list

  ;Find the closest point from the first coordinate list within the specified   
  ;distance tolerance, if at least one such point exists

;Find the set of symmetric point matches