search_around_3d

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

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. Cannot be a scalar coordinate.

coords2 : BaseCoordinateFrame or SkyCoord

The second set of coordinates, which will be searched for matches from coords1 within seplimit. Cannot be a scalar coordinate.

distlimit : Quantity with distance units

The physical radius to search within.

storekdtree : bool or 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 : integer array

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

idx2 : integer 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

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

Notes

This function requires SciPy (>=0.12.0) 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.