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)

Find the closest points from a list of reference points (applicable for vectorized computation).

See also [GEOM-FCPB-1].

Parameters

  • pts (numpy.ndarray or list or tuple or Iterable or shapely.geometry.Point or shapely.geometry.MultiPoint or shapely.geometry.LineString or shapely.geometry.MultiLineString or shapely.geometry.Polygon or shapely.geometry.MultiPolygon or shapely.geometry.GeometryCollection) – an array (of size (n, 2)) of points

  • ref_pts (numpy.ndarray or list or tuple or shapely.geometry.Point or shapely.geometry.MultiPoint or shapely.geometry.LineString or shapely.geometry.MultiLineString or shapely.geometry.Polygon or shapely.geometry.MultiPolygon or shapely.geometry.GeometryCollection) – an array (of size (n, 2)) of reference points

  • k (int or list) – (up to) the k-th nearest neighbour(s), defaults to 1

  • unique (bool) – whether to remove duplicated points, defaults to False

  • as_geom (bool) – whether to return 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] parameters of scipy.spatial.cKDTree

Returns

point (or points) among the list of ref_pts, which is (or are) closest to pts

Return type

numpy.ndarray or 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)'