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:
    idx1 `python:int` `array`

      Indices into `coords1` that matches to the corresponding element of `idx2`. Shape matches `idx2`.

    idx2 `python:int` `array`

      Indices into `coords2` that matches to the corresponding element of `idx1`. Shape matches `idx1`.

    sep2d `Angle`

      The on-sky separation between the coordinates. Shape matches `idx1` and `idx2`.

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

      The 3D distance between the coordinates. Shape matches `idx1` and `idx2`. The unit is that of `coords1`.

  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.