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