PRO symmetric_point_match_2d, x1, y1, x2, y2, tol, nmatch, subs1, subs2, dist, X1_ALREADY_SORTED = x1_already_sorted, X2_ALREADY_SORTED = x2_already_sorted, $
; 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 Euclidean distance between P and Q is less than or
; equal to "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.
; Note that it is quite possible that multiple points from one coordinate
; list are equally close to the same point from the other coordinate list.
; In each of these cases, this module will only return one pair of
; symmetrically matching points.
;
; Input Parameters:
;
; x1 - FLOAT/DOUBLE SCALAR/VECTOR/ARRAY - A scalar/vector/array of x coordinates for
; the points in the first coordinate list.
; y1 - FLOAT/DOUBLE SCALAR/VECTOR/ARRAY - A scalar/vector/array of y coordinates for
; the points in the first coordinate list.
; This parameter must have the same number
; of elements as "x1".
; x2 - FLOAT/DOUBLE SCALAR/VECTOR/ARRAY - A scalar/vector/array of x coordinates for
; the points in the second coordinate list.
; y2 - FLOAT/DOUBLE SCALAR/VECTOR/ARRAY - A scalar/vector/array of y coordinates for
; the points in the second coordinate list.
; This parameter must have the same number
; of elements as "x2".
; tol - FLOAT/DOUBLE - A pair of points P and Q from each coordinate list are
; considered a match if the Euclidean distance between them is
; less than or equal to "tol". This parameter must be
; non-negative.
;
; Output Parameters:
;
; nmatch - LONG - The number of matching coordinate pairs between the coordinate
; lists. If the module fails, then the value of this parameter is
; set to "-1".
; 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 Euclidean distances between
; the matched points, corresponding to each entry in the
; output vectors "subs1" and "subs2".
;
; Keywords:
;
; If the keyword X1_ALREADY_SORTED is set (as "/X1_ALREADY_SORTED"), then the
; module will assume that the values of "x1" are sorted into ascending order. This
; option can be used to avoid a sort operation on the input parameter "x1", which
; allows the user to build more efficient code with this module.
;
; If the keyword X2_ALREADY_SORTED is set (as "/X2_ALREADY_SORTED"), then the
; module will assume that the values of "x2" are sorted into ascending order. This
; option can be used to avoid a sort operation on the input parameter "x2", which
; allows the user to build more efficient code with this module.
;
; If the keyword NO_PAR_CHECK is set (as "/NO_PAR_CHECK"), then the module will not
; perform parameter checking on the input parameters, reducing module overheads.
;
; Author: Dan Bramich (dan.bramich@hotmail.co.uk)
;
; History:
;
; 05/01/2012 - Module created (dmb).
;Set the default output parameter values
;Perform parameter checking if not instructed otherwise
;Check that "x1" and "y1" are of the correct number type
;Check that "y1" has the same number of elements as "x1"
;Check that "x2" and "y2" are of the correct number type
;Check that "y2" has the same number of elements as "x2"
;Check that "tol" is a non-negative number of the correct type
;If the keyword X1_ALREADY_SORTED is not set, then determine the subscripts of "x1"
;when it is sorted into ascending order, and sort the first coordinate list such that
;the elements of "x1" are in ascending order
;If the keyword X2_ALREADY_SORTED is not set, then determine the subscripts of "x2"
;when it is sorted into ascending order, and sort the second coordinate list such that
;the elements of "x2" are in ascending order
;For each point in the first coordinate list, 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 in the first coordinate list
;For each point in the first coordinate list, find the closest point in the second
;coordinate list within the specified distance tolerance "tol"
;For the current point in 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 set of points from the first
;coordinate list with x coordinates within a distance of "tol" from the x coordinate
;of the current point in the second coordinate list
;For each point in the second coordinate list, find the closest point in the first
;coordinate list within the specified distance tolerance "tol"
;For the current point in 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
;If there is at least one point in the first coordinate list for which the closest point
;in the second coordinate list is within the specified distance tolerance "tol"
;Determine which pairs of points P and Q from each coordinate list satisfy P being the
;closest point to Q, and Q being the closest point to P, and that have a Euclidean
;distance between them of less than or equal to the specified distance tolerance "tol"
;If there is at least one symmetrically matching coordinate pair between the two
;coordinate lists
;Set the values of the output parameters "subs1", "subs2", and "dist" appropriately
;If there are no points in the first coordinate list for which the closest point in the
;second coordinate list is within the specified distance tolerance "tol", then there no
;matching coordinate pairs between the two coordinate lists