environmentaltools.spatial.continuous_line

environmentaltools.spatial.continuous_line(data: DataFrame, limiting_distance: float = 1000000000.0)[source]

Create continuous line from scattered points by connecting nearest neighbors.

Constructs an ordered sequence of points forming a continuous line by iteratively connecting each point to its nearest unconnected neighbor. Algorithm starts from the leftmost point (minimum x coordinate) and proceeds by selecting the closest remaining point at each step.

Parameters:

data (pd.DataFrame) – Scattered point data containing at least ‘x’ and ‘y’ coordinate columns. Additional columns are preserved in the output.
limiting_distance (float, optional) – Maximum allowed distance between consecutive points. If the nearest remaining point exceeds this distance, the algorithm terminates. Default is 1e9 (effectively unlimited). Units match input coordinates.

Returns:

Ordered points forming a continuous line. Points are sorted by connection order starting from the leftmost point. Contains same columns as input data. Points that couldn’t be connected within the limiting distance are excluded.

Return type:

pd.DataFrame

Notes

This greedy nearest-neighbor algorithm works well for creating ordered lines from scattered data along approximately linear features (coastlines, transects, etc.). For complex or branching geometries, results may not be optimal.

The algorithm modifies the input DataFrame in place (removes points as they are processed).

Examples

>>> import pandas as pd
>>> import numpy as np
>>> # Create scattered points along a curve
>>> data = pd.DataFrame({
...     'x': [0, 2, 1, 3, 4],
...     'y': [0, 1, 0.5, 2, 3]
... })
>>> line = continuous_line(data.copy(), limiting_distance=2.0)
>>> print(line[['x', 'y']])