Skip to main content
`Ctrl`+`K`

# match_coordinates_3d

astropy.coordinates.match_coordinates_3d(matchcoord, catalogcoord, nthneighbor=1, storekdtree='kdtree_3d')

  Finds the nearest 3-dimensional matches of a coordinate or coordinates in a set of catalog coordinates.

  This finds the 3-dimensional closest neighbor, which is only different from the on-sky distance if `distance` is set in either `matchcoord` or `catalogcoord`.

  Parameters:
    matchcoord `BaseCoordinateFrame` or `SkyCoord`

      The coordinate(s) to match to the catalog.

    catalogcoord `BaseCoordinateFrame` or `SkyCoord`

      The base catalog in which to search for matches. Typically this will be a coordinate object that is an array (i.e., `catalogcoord.isscalar == False`)

    nthneighbor `python:int`, optional

      Which closest neighbor to search for. Typically `1` is desired here, as that is correct for matching one set of coordinates to another. The next likely use case is `2`, for matching a coordinate catalog against itself (`1` is inappropriate because each point will find itself as the closest match).

    storekdtree bool or `python:str`, optional

      If a string, will store the KD-Tree used for the computation in the `catalogcoord`, as in `catalogcoord.cache` with the provided name. This dramatically speeds up subsequent calls with the same catalog. If False, the KD-Tree is discarded after use.

  Returns:
    `CoordinateMatchResult`

      A `NamedTuple` with attributes representing for each source in `matchcoord` the indices and angular and physical separations of the match in `catalogcoord`.

  Notes

  This function requires SciPy to be installed or it will fail.