Skip to main content
`Ctrl`+`K`

# search_around_3d

astropy.coordinates.search_around_3d(coords1, coords2, distlimit, storekdtree='kdtree_3d')

  Searches for pairs of points that are at least as close as a specified distance in 3D space.

  This is intended for use on coordinate objects with arrays of coordinates, not scalars. For scalar coordinates, it is better to use the `separation_3d` methods.

  Parameters:
    coords1 `BaseCoordinateFrame` or `SkyCoord`

      The first set of coordinates, which will be searched for matches from `coords2` within `seplimit`. Must be a one-dimensional coordinate array.

    coords2 `BaseCoordinateFrame` or `SkyCoord`

      The second set of coordinates, which will be searched for matches from `coords1` within `seplimit`. Must be a one-dimensional coordinate array.

    distlimit `Quantity` [:ref: ‘length’]

      The physical radius to search within. It should be broadcastable to the same shape as `coords1`.

    storekdtree bool or `python:str`, optional

      If a string, will store the KD-Tree used in the search with the name `storekdtree` in `coords2.cache`. This speeds up subsequent calls to this function. If False, the KD-Trees are not saved.

  Returns:
    `CoordinateSearchResult`

      A `NamedTuple` with attributes representing the indices of the elements of found pairs in both source sets and angular and physical separations of the pairs.

  Notes

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

  If you are using this function to search in a catalog for matches around specific points, the convention is for `coords2` to be the catalog, and `coords1` are the points to search around. While these operations are mathematically the same if `coords1` and `coords2` are flipped, some of the optimizations may work better if this convention is obeyed.

  In the current implementation, the return values are always sorted in the same order as the `coords1` (so `idx1` is in ascending order). This is considered an implementation detail, though, so it could change in a future release.