logistics.route-distance

def route_distance(stops: Sequence[GeoPoint], return_to_start: bool) -> RouteDistance

@dataclass(frozen=True)
class RouteDistance:
    """The whole route and each leg, in metres to the millimetre."""

    #: the sum of the legs, summed exactly in millimetres
    total_metres: float
    #: one per leg: stops[0] to stops[1], stops[1] to stops[2], ...
    leg_metres: List[float]

from fune.logistics.route_distance import route_distance  # logistics.route-distance@^1

import math
from typing import List, Sequence

from .geo_distance import distance  ← from geo.distance ^1.0.0 · built alongside by fune
from .geo_point_in_polygon import GeoPoint  ← from geo.point-in-polygon ^1.0.0 · built alongside by fune
from .logistics_route_distance_types import RouteDistance


def route_distance(stops: Sequence[GeoPoint], return_to_start: bool) -> RouteDistance:
    """Great-circle length of a route through the stops in order, leg by leg,
    optionally closing back to the first stop."""
    if len(stops) == 0:
        raise ValueError("stops must not be empty")
    leg_metres: List[float] = []
    # Each leg is a whole number of millimetres; adding them as integers and
    # dividing once avoids floating-point drift (and is the same double everywhere).
    total_millimetres = 0

    def add_leg(a: GeoPoint, b: GeoPoint) -> None:
        nonlocal total_millimetres
        metres = distance(a.lat, a.lng, b.lat, b.lng)
        leg_metres.append(metres)
        total_millimetres += math.floor(metres * 1000 + 0.5)

    for i in range(1, len(stops)):
        add_leg(stops[i - 1], stops[i])
    if return_to_start and len(stops) > 1:
        add_leg(stops[-1], stops[0])
    return RouteDistance(total_metres=total_millimetres / 1000, leg_metres=leg_metres)

Install

fune build

With that line in your source, in a Python project (language python in fune.project), fune build resolves it and its 2 dependencies, pins them in fune.lock, downloads only the Python package of each, and builds the code above into your project’s .fune/build, one readable file per capability with a header linking back here. Or pin a range in fune.project and build in one step:

fune add logistics.route-distance

The manifest, vectors and README with only the Python implementation. Install it without the registry with fune add ./logistics.route-distance-1.0.0-python.fune, or fetch it from a terminal with fune pull logistics.route-distance@1.0.0:python.

The whole function, every language, is one file too: logistics.route-distance-1.0.0.fune, 10,910 bytes, sha256 466edb4c820220ce3afbcc8bdacd67502202c89f2f192576ce8b885c7f53a9a8. It installs into a project of any language.

# fune: before logistics.route-distance

# fune: after logistics.route-distance

# fune: replace geo.distance in logistics.route-distance
# fune: replace geo.point-in-polygon in logistics.route-distance

# fune: step logistics.route-distance after <n|label>

More from the author

## Exact totals

Each leg is `geo.distance`'s answer, a whole number of millimetres expressed in metres. Adding those as floating-point numbers drifts: three legs of 2,886,448.43 m add up to 8,659,345.290000001 m. So each leg is turned back into integer millimetres, the millimetres are added as integers, and the total is divided by 1000 once, which gives the same double in every language (8,659,345.29). The manifest says `floats exact` and the vectors hold the three implementations to it.

## Edge cases

- One stop is a route of no legs: total 0, `legMetres` empty, with or without `returnToStart` (there is nowhere to return from). - Two identical stops in a row are a leg of 0. - An empty list is an error, not 0: it usually means the stops were never loaded. - Coordinates are checked by `geo.distance`: out of range is an error, not wrapped, because it usually means latitude and longitude were swapped.

## Types

A stop is `GeoPoint` from `geo.point-in-polygon`, the registry's one latitude/longitude record, so a polygon's vertices and a route's stops are the same type. That capability is required for its type only.

Files