track2corridor-geo

Build an auditable centerline and corridor from ground mobile laser-scanning (MLS) trajectory points.

Here, a noisy track means ordered trajectory coordinates with positional scatter, short side deviations, or gaps around the route actually travelled. It does not mean the complete laser point cloud. track2corridor converts those ordered trajectory points into a buffered footprint, raster skeleton, NetworkX graph, centerline, and fixed-width corridor. It exposes every intermediate geometry and a diagnostics report instead of hiding algorithmic warnings behind a single polygon.

Quick start

python -m pip install track2corridor-geo
track2corridor build track.laz \
  --footprint-width 20 \
  --corridor-width 8 \
  --output corridor.gpkg

CSV input must contain x,y columns and needs an explicit projected CRS:

track2corridor build track.csv --crs EPSG:32637 --output corridor.gpkg

Reproducible example

Generate and process three deterministic trajectory scenarios plus equivalent CSV, LAZ, and GeoPackage inputs:

python examples/run_examples.py

Generated inputs, outputs, and diagnostics are placed under examples/generated/. To run the standard case through the CLI:

track2corridor build examples/generated/mls-s-track.csv \
  --crs EPSG:32637 \
  --time-field sequence \
  --footprint-width 14 \
  --corridor-width 6 \
  --cell-size 1 \
  --min-branch-length 4 \
  --output examples/generated/mls-s-track-cli.gpkg \
  --diagnostics examples/generated/mls-s-track-cli.json

The GeoPackage contains three inspectable layers:

The JSON report records input point count, raster dimensions and cell count, skeleton pixels, graph nodes and edges, connected components, pruned nodes, extended endpoints, and centerline part count.

Parameters

Python API

from track2corridor import CorridorOptions, CorridorResult, build_corridor

result: CorridorResult = build_corridor(
    points,
    "EPSG:32637",
    CorridorOptions(footprint_width=14, corridor_width=6, cell_size=1),
)
print(result.diagnostics.to_dict())

Input behavior

• LAS/LAZ uses gps_time for stable ordering when that dimension exists.
• CSV uses source order unless --time-field is supplied.
• Other vector formats must contain only Point geometries and retain their CRS.
• An explicit --crs must match embedded CRS metadata; reprojection is never performed automatically.

Limits

• Coordinates must use a projected CRS with horizontal units in metres.
• The method derives a skeleton from point buffers; it is not a map-matching or trajectory-inference algorithm.
• Disconnected point clusters produce multiple centerline components.
• Dense data, a very small cell size, or a very large extent can create expensive rasters; --max-cells provides a hard safety limit.
• Results should be visually reviewed when the footprint contains loops, wide junctions, or sparse gaps.

Run track2corridor --help for all options. Exit code 0 means success and 2 means invalid input or a processing failure.

The pre-release and launch checks are listed in docs/release-checklist.md.

Development

python -m pip install -e ".[test]"
python -m ruff check .
python -m ruff format --check .
python -m pytest

Copyright 2026 Alena Nikitina. Licensed under the Apache License 2.0.