borderpoi-rs

borderpoi-rs finds administrative border crossings along a GPX track.

It is designed for long-distance cycling, bikepacking and ultracycling.

The program reads a GPX track and a GeoJSON file containing administrative boundary polygons. It detects every county/district transition, preserves repeated visits, and adds a GPX waypoint for every border crossing.

Features

• GPX input
• GPX output
• stdin/stdout support
• GeoJSON boundary input
• R*-tree spatial index
• repeated county visits are preserved
• one GPX POI per border crossing
• no distance calculation
• no GDAL dependency
• no native GIS library dependency

Input boundary data

The boundary GeoJSON must contain Polygon or MultiPolygon features.

Coordinates must be WGS84 / EPSG:4326.

For BKG VG250 data, the relevant layer is normally:

VG250_KRS

The default properties expected by borderpoi-rs are:

GEN
AGS

GEN is used as the displayed county name.

AGS is used as the administrative identifier.

Usage

GPX file to GPX file

borderpoi-rs \
    --track route.gpx \
    --boundaries VG250_KRS.geojson \
    --output route-with-borders.gpx

stdin to stdout

cat route.gpx \
    | borderpoi-rs \
        --boundaries VG250_KRS.geojson \
    > route-with-borders.gpx

Explicit stdin/stdout

- can be used explicitly:

borderpoi-rs \
    --track - \
    --boundaries VG250_KRS.geojson \
    --output -

Unix pipeline

The program writes diagnostic information to stderr and GPX data to stdout.

Therefore this works:

borderpoi-rs \
    --boundaries VG250_KRS.geojson \
    < route.gpx \
    > route-with-borders.gpx

The county report can still be seen in the terminal.

Command line

Usage: borderpoi-rs [OPTIONS] --boundaries <BOUNDARIES>

Options:
  -t, --track <TRACK>
      Input GPX track. Reads from stdin when omitted or set to '-'.

  -b, --boundaries <BOUNDARIES>
      Boundary GeoJSON.

      The GeoJSON must contain Polygon/MultiPolygon geometries
      in WGS84 / EPSG:4326.

      Required.

  --name-field <NAME_FIELD>
      Property containing the county name.

      [default: GEN]

  --id-field <ID_FIELD>
      Property containing the administrative identifier.

      [default: AGS]

  -o, --output <OUTPUT>
      Output GPX. Writes to stdout when omitted or set to '-'.

  -h, --help
      Print help.

  -V, --version
      Print version.

County sequence

The output preserves the order in which counties are visited.

Repeated visits are intentionally preserved.

For example:

Roth
Neumarkt i.d.OPf.
Regensburg
Neumarkt i.d.OPf.
Roth

is reported as exactly that.

It is not reduced to:

Roth
Neumarkt i.d.OPf.
Regensburg

This is important for bikepacking and ultracycling routes that cross administrative boundaries multiple times.

Border POIs

For every transition, a waypoint is added to the output GPX.

Example:

Border 01: Landkreis Roth -> Landkreis Neumarkt i.d.OPf.
Border 02: Landkreis Neumarkt i.d.OPf. -> Landkreis Regensburg
Border 03: Landkreis Regensburg -> Landkreis Neumarkt i.d.OPf.
Border 04: Landkreis Neumarkt i.d.OPf. -> Landkreis Roth

Each waypoint contains:

• crossing number
• source county
• destination county
• source AGS
• destination AGS
• administrative_boundary as GPX waypoint type

Spatial index

All county geometries are inserted into an R*-tree.

For every GPX track segment the algorithm performs:

GPX segment
     |
     v
segment bounding box
     |
     v
R*-tree lookup
     |
     v
candidate county polygons
     |
     v
exact point-in-polygon test
     |
     v
county transition
     |
     v
exact boundary intersection
     |
     v
GPX waypoint

This avoids testing every GPX segment against every county polygon.

This is particularly useful for long GPX tracks.

Coordinate reference system

borderpoi-rs expects the boundary GeoJSON to use:

EPSG:4326 / WGS84

GPX coordinates are also WGS84.

No CRS transformation is performed inside the program.

This is intentional: it removes the GDAL dependency and keeps the application entirely Rust-native.

Why no GDAL?

The previous implementation used GDAL to read the BKG GeoPackage.

That caused the Rust build to depend on the system GDAL version.

For example:

gdal       0.19.0
gdal-sys   0.12.0
system     GDAL 3.13.2

and required generated GDAL bindings.

borderpoi-rs does not actually need GDAL for its runtime operation.

The recommended workflow is therefore:

BKG VG250
     |
     | one-time conversion
     v
WGS84 GeoJSON
     |
     v
borderpoi-rs

The conversion from the original BKG dataset can be performed with GDAL/QGIS once, but the resulting command line tool has no GDAL dependency.

Building with Nix

Enter the development environment:

nix develop

Then:

cargo build --release

Run:

cargo run --release -- \
    --boundaries VG250_KRS.geojson \
    < route.gpx \
    > route-with-borders.gpx

Building entirely with Nix

First generate the lock file:

cargo generate-lockfile

Then:

nix build

The resulting executable is:

./result/bin/borderpoi-rs

Example:

./result/bin/borderpoi-rs \
    --boundaries VG250_KRS.geojson \
    --track route.gpx \
    --output route-with-borders.gpx

Formatting and linting

Format:

cargo fmt

Check:

cargo check

Run Clippy:

cargo clippy --all-targets --all-features -- -D warnings

Input assumptions

The current implementation assumes:

1. GPX coordinates are WGS84.
2. Boundary coordinates are WGS84.
3. Boundary features are Polygon or MultiPolygon.
4. The GPX track normally lies inside a county polygon.
5. Administrative boundary geometries are topologically valid.

Tracks that run exactly along a county boundary are inherently ambiguous.

Such a section is deliberately not interpreted as a sequence of crossings.

Output contract

stdout:

output GPX only

stderr:

diagnostic messages
county sequence
border crossing report

This makes the program suitable for Unix pipelines.

Example:

borderpoi-rs \
    --boundaries counties.geojson \
    < route.gpx \
    > result.gpx

while the report remains visible on the terminal.

License

MIT