xrspatial.pathfinding.multi_stop_search

xrspatial.pathfinding.multi_stop_search(surface: DataArray, waypoints: list, barriers: list = [], x: str | None = 'x', y: str | None = 'y', connectivity: int = 8, snap: bool = False, friction: DataArray = None, search_radius: int | None = None, optimize_order: bool = False) → DataArray

Find the least-cost path visiting a sequence of waypoints in order.

Wraps a_star_search() to route through N waypoints, stitching segments into a single cumulative-cost surface. When optimize_order=True, the interior waypoints are reordered to minimize total travel cost (TSP), keeping the first and last waypoints fixed.

Parameters:

• surface (xr.DataArray or xr.Dataset) – 2-D elevation / cost surface. A Dataset routes each data variable through the same waypoints independently and returns a Dataset of the per-variable results.

• waypoints (list of array-like) – Sequence of (y, x) coordinate pairs to visit. Must contain at least two points.

• barriers (list, default=[]) – Surface values that are impassable.

• x (str, default 'x' / 'y') – Coordinate dimension names.

• y (str, default 'x' / 'y') – Coordinate dimension names.

• connectivity (int, default=8) – 4 or 8 connectivity.

• snap (bool, default=False) – Snap each waypoint to the nearest valid pixel. Not supported with dask-backed arrays.

• friction (xr.DataArray, optional) – Friction surface (same shape as surface).

• search_radius (int, optional) – Passed to each a_star_search() call.

• optimize_order (bool, default=False) – Reorder interior waypoints to minimize total cost. Uses exact Held-Karp when N <= 12, nearest-neighbor + 2-opt otherwise.

Returns:

Cumulative path cost surface. Attributes include waypoint_order, segment_costs, and total_cost. A Dataset input returns a Dataset of per-variable results.

Return type:

xr.DataArray or xr.Dataset

Raises:

ValueError – If the surface is not 2-D, fewer than two waypoints are given, waypoints fall outside the surface bounds, or a segment is unreachable.