find_closest_points

pyhelpers.geom.find_closest_points(pts, ref_pts, k=1, unique=False, as_geom=False, ret_idx=False, ret_dist=False, **kwargs)[source]

Find the closest points from a list of reference points to a set of query points.

This function computes the closest points from a list of reference points ref_pts to a set of query points pts. Various options are available for customisation, such as returning multiple nearest neighbours (k), removing duplicated points, returning points as Shapely Points (shapely.geometry.Point), returning indices of the closest points, and returning distances between pts and the closest points in ref_pts.

See also [GEOM-FCPB-1].

Parameters:

  • pts (numpy.ndarray | list | tuple | Iterable | shapely.geometry.base.BaseGeometry) – Array of query points with shape (n, 2).

  • ref_pts (numpy.ndarray | list | tuple | shapely.geometry.base.BaseGeometry) – Array of reference points with shape (m, 2).

  • k (int | list) – Number of closest neighbours to find; defaults to 1.

  • unique (bool) – Whether to remove duplicated points from the results; defaults to False.

  • as_geom (bool) – Whether to return the closest points as shapely.geometry.Point; defaults to False.

  • ret_idx (bool) – Whether to return indices of the closest points in ref_pts; defaults to False.

  • ret_dist (bool) – Whether to return distances between pts and the closest points in ref_pts; defaults to False.

  • kwargs – [Optional] Additional parameters for the class scipy.spatial.cKDTree.

Returns:

Closest points among ref_pts to each point in pts.

Return type:

numpy.ndarray | shapely.geometry.MultiPoint

Examples:

>>> from pyhelpers.geom import find_closest_points
>>> from pyhelpers._cache import example_dataframe
>>> from shapely.geometry import LineString, MultiPoint
>>> example_df = example_dataframe()
>>> example_df
            Longitude   Latitude
City
London      -0.127647  51.507322
Birmingham  -1.902691  52.479699
Manchester  -2.245115  53.479489
Leeds       -1.543794  53.797418
>>> cities = [[-2.9916800, 53.4071991],  # Liverpool
...           [-4.2488787, 55.8609825],  # Glasgow
...           [-1.6131572, 54.9738474]]  # Newcastle
>>> ref_cities = example_df.to_numpy()
>>> closest_to_each = find_closest_points(pts=cities, ref_pts=ref_cities, k=1)
>>> closest_to_each  # Liverpool: Manchester; Glasgow: Manchester; Newcastle: Leeds
array([[-2.2451148, 53.4794892],
       [-2.2451148, 53.4794892],
       [-1.5437941, 53.7974185]])
>>> closest_to_each = find_closest_points(
...     pts=cities, ref_pts=ref_cities, k=1, as_geom=True)
>>> closest_to_each.wkt
'MULTIPOINT (-2.2451148 53.4794892, -2.2451148 53.4794892, -1.5437941 53.7974185)'
>>> _, idx = find_closest_points(pts=cities, ref_pts=ref_cities, k=1, ret_idx=True)
>>> idx
array([2, 2, 3], dtype=int64)
>>> _, _, dist = find_closest_points(
...     cities, ref_cities, k=1, ret_idx=True, ret_dist=True)
>>> dist
array([0.75005697, 3.11232712, 1.17847198])
>>> cities_geoms_1 = LineString(cities)
>>> closest_to_each = find_closest_points(pts=cities_geoms_1, ref_pts=ref_cities, k=1)
>>> closest_to_each
array([[-2.2451148, 53.4794892],
       [-2.2451148, 53.4794892],
       [-1.5437941, 53.7974185]])
>>> cities_geoms_2 = MultiPoint(cities)
>>> closest_to_each = find_closest_points(cities_geoms_2, ref_cities, k=1, as_geom=True)
>>> closest_to_each.wkt
'MULTIPOINT (-2.2451148 53.4794892, -2.2451148 53.4794892, -1.5437941 53.7974185)'