Name

---

    MATCHALL_2D

Purpose

---

    Determines which of a set of 2D coordinates are within a given distance from
    each of a vector of points. Based on JD's MATCH_2D and my MATCHALL_SPH.

Category

---

    Astro

Calling Sequence

---

    Result = MATCHALL_2D(X1, Y1, X2, Y2, MaxDistance, Nwithin)

Inputs

---

    X1: Vector of X coordinates.
    Y1: Vector of Y coordinates.
    X2: Vector of X coordinates.
    Y2: Vector of Y coordinates.
    MaxDistance: Maximum distance.

Outputs

---

    The function returns the list of indices of X2, Y2 that lie within
    Sphrad of each point X1,Y1. The format of the returned array is
    similar to the REVERSE_INDICES array from HISTOGRAM: the indices
    into X2,Y2 that are close enough to element i of X1,Y1 are
    contained in Result[Result[i]:Result[i+1]-1] (note, however, that
    these indices are not guaranteed to be sorted). If there are no matches,
    then Result[i] eq Result[i+1].

Optional Outputs

---

    Nwithin: A vector containing the number of matches for each of X1,Y1.

Keyword Parameters

---

    DISTANCE: Optional output containing the distances between each pair.
              The distances are stored in the same order as the Result
              array but starting at 0, i.e. if j is match number k to
              element i then
                  j = Result[Result[i]+k]
              and the distance between points i and j is
                  DISTANCE[Result[i]+k-Result[0]]

Example

---

    Note that the routine is similar to finding
      WHERE( (X2-X1[i])^2 + (Y2-Y1[i])^2 LE Distance^2, Nwithin)
    for each element of X1 and Y1, but is much more efficient.
    Shows which random points are within 0.1 of various coordinates:
    seed=43
    nrandcoords = 5000l
    xrand = 2. * RANDOMU(seed, nrandcoords) - 1.
    yrand = 2. * RANDOMU(seed, nrandcoords) - 1.
    xcoords = [0.25, 0.5, 0.75]
    ycoords = [0.75, 0.5, 0.25]
    ncoords = N_ELEMENTS(xcoords)
    matches = MATCHALL_2D(xcoords, ycoords, xrand, yrand, 0.1, nmatches)
    PLOT, /ISO, PSYM=3, xrand, yrand
    OPLOT, PSYM=1, COLOR=FSC_COLOR('blue'), xcoords, ycoords
    OPLOT, PSYM=3, COLOR=FSC_COLOR('red'), xrand[matches[ncoords+1:*]], $
      yrand[matches[ncoords+1:*]]

Modification History

---

    Written by: Jeremy Bailin
    10 June 2008 Public release in JBIU as WITHINSPHRAD
    24 April 2009 Vectorized as WITHINSPHRAD_VEC
    25 April 2009 Polished to improve memory use
    9 May 2009 Radical efficiency re-write as WITHINSPHRAD_VEC3D borrowing
                  heavily from JD Smith's MATCH_2D
    13 May 2009 Removed * from LHS index in final remapping for speed
    6 May 2010 Changed to MATCHALL_2D and just using Euclidean 2D coordinates
                    (add a bunch of stuff back in from MATCH_2D and take out a bunch
                    of angle stuff)
    25 May 2010 Bug fix to allow X2 and Y2 to have any dimension.
    9 Feb 2011 Added DISTANCE output keyword.