Skip to content

Commit f25b8bd

Browse files
MathiasVDAMathiasVDA
authored
Merge pull request #4 from Matdata-eu/003-path-review-webapp
003 path review webapp
2 parents 47f9173 + c25b28c commit f25b8bd

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

57 files changed

+54521
-56
lines changed

‎.dockerignore‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,11 @@ target/
33
**/*.rs.bk
44
*.pdb
55

6+
# Secrets / environment
7+
.env
8+
.env.*
9+
!.env.example
10+
611
# Python
712
.venv/
813
__pycache__/

‎.github/agents/copilot-instructions.md‎

Lines changed: 31 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -1,29 +1,32 @@
1-
# tp-lib Development Guidelines
2-
3-
Auto-generated from all feature plans. Last updated: 2026-01-09
4-
5-
## Active Technologies
6-
7-
- Rust 1.75+ (edition 2021) (002-train-path-calculation)
8-
9-
## Project Structure
10-
11-
```text
1+
# tp-lib Development Guidelines
2+
3+
Auto-generated from all feature plans. Last updated: 2026-01-09
4+
5+
## Active Technologies
6+
- Rust 2021 edition, latest stable (1.80+) (003-path-review-webapp)
7+
- File-based (GeoJSON network, CSV train path, CSV GNSS positions) — no database (003-path-review-webapp)
8+
9+
- Rust 1.75+ (edition 2021) (002-train-path-calculation)
10+
11+
## Project Structure
12+
13+
```text
1214
src/
13-
tests/
14-
```
15-
16-
## Commands
17-
18-
cargo test; cargo clippy
19-
20-
## Code Style
21-
22-
Rust 1.75+ (edition 2021): Follow standard conventions
23-
24-
## Recent Changes
25-
26-
- 002-train-path-calculation: Added Rust 1.75+ (edition 2021)
27-
28-
<!-- MANUAL ADDITIONS START -->
29-
<!-- MANUAL ADDITIONS END -->
15+
tests/
16+
```
17+
18+
## Commands
19+
20+
cargo test; cargo clippy
21+
22+
## Code Style
23+
24+
Rust 1.75+ (edition 2021): Follow standard conventions
25+
26+
## Recent Changes
27+
- 003-path-review-webapp: Added Rust 2021 edition, latest stable (1.80+)
28+
29+
- 002-train-path-calculation: Added Rust 1.75+ (edition 2021)
30+
31+
<!-- MANUAL ADDITIONS START -->
32+
<!-- MANUAL ADDITIONS END -->

‎Cargo.toml‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@ members = [
33
"tp-core",
44
"tp-cli",
55
"tp-py",
6+
"tp-webapp",
67
]
78
resolver = "2"
89

@@ -56,6 +57,12 @@ pyo3 = { version = "0.21", features = ["extension-module"] }
5657
criterion = { version = "0.5", features = ["html_reports"] }
5758
quickcheck = "1.0"
5859

60+
# Web server
61+
axum = "0.8"
62+
tokio = { version = "1", features = ["full"] }
63+
rust-embed = { version = "8", features = ["debug-embed"] }
64+
open = "5"
65+
5966
[profile.dev]
6067
debug = 2
6168
opt-level = 0

‎README.md‎

Lines changed: 82 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@ Train positioning library excels in post-processing the GNSS positions of your m
1616
- 🚄 **High Performance**: R-tree spatial indexing for O(log n) nearest-track search
1717
- 📍 **Accurate Projection**: Haversine distance and geodesic calculations with geo-rs
1818
- 🛤️ **Train Path Calculation**: Probabilistic path calculation through rail networks using topology
19+
- 🗺️ **Interactive Path Review**: Browser-based map webapp to visually review and edit calculated paths before projection
1920
- 🌍 **CRS Aware**: Explicit coordinate reference system handling (EPSG codes)
2021
- ⏰ **Timezone Support**: RFC3339 timestamps with explicit timezone offsets; timezone-less ISO 8601 datetimes assumed UTC
2122
- 📊 **Multiple Formats**: CSV and GeoJSON input/output
@@ -47,6 +48,12 @@ tp-cli simple-projection --gnss positions.csv --network network.geojson --output
4748

4849
# Use pre-calculated path for projection
4950
tp-cli --gnss positions.csv --network network.geojson --train-path path.csv --output result.csv
51+
52+
# Review calculated path in browser before projection (integrated mode)
53+
tp-cli --gnss positions.csv --network network.geojson --output result.csv --review
54+
55+
# Launch standalone webapp to review/edit a path file
56+
tp-cli webapp --network network.geojson --train-path path.csv --output reviewed_path.csv
5057
```
5158

5259
### Debug Output
@@ -72,13 +79,70 @@ See **[DEBUG.md](DEBUG.md)** for a full description of the debug output files, t
7279
- **Scalability**: Sub-linear scaling with R-tree spatial indexing
7380
- **Memory**: Handles 10,000+ positions efficiently
7481

82+
## Train Path Review Webapp
83+
84+
The library ships a companion browser-based map webapp (`tp-webapp`) that lets you visually inspect and edit a calculated train path before using it for projection. No npm, no Node.js, no frontend build step required — the web assets are embedded in the binary at compile time using `rust-embed`.
85+
86+
### Modes
87+
88+
| Mode | Command | Use case |
89+
|------|---------|----------|
90+
| **Standalone** | `tp-cli webapp` | Review/edit an existing path file; save result to disk; server stays alive |
91+
| **Integrated** | `tp-cli … --review` | Pause the projection pipeline after path calculation; confirm or abort in the browser |
92+
93+
### What You Can Do in the Browser
94+
95+
- View all network segments on a Leaflet map (OpenStreetMap basemap, toggleable)
96+
- Path segments are highlighted with a colour-coded confidence scale
97+
- **Add** a netelement to the path by clicking it on the map — snapped to the correct topological position
98+
- **Remove** a path segment by clicking it — segment reverts to the default style
99+
- Sidebar shows an ordered list of segments with probability scores
100+
- **Dark mode** toggle (auto-activates from OS `prefers-color-scheme`)
101+
- **Close Tab** button for clean exit after the server shuts down
102+
103+
### Standalone Usage
104+
105+
```sh
106+
tp-cli webapp \
107+
--network network.geojson \
108+
--train-path path.csv \
109+
--output reviewed_path.csv
110+
```
111+
112+
A browser opens at `http://127.0.0.1:8765`. Click **Save** to write the reviewed path; the server stays alive for further edits. Press Ctrl+C when done.
113+
114+
The saved file is accepted directly by `--train-path`:
115+
116+
```sh
117+
tp-cli --gnss positions.csv --network network.geojson \
118+
--train-path reviewed_path.csv --output result.csv
119+
```
120+
121+
### Integrated Usage
122+
123+
```sh
124+
tp-cli --gnss positions.csv --network network.geojson \
125+
--output result.csv --review
126+
```
127+
128+
1. CLI calculates the train path
129+
2. Browser opens automatically — review and edit the path
130+
3. Click **Confirm** → path artifact saved as `result-path.csv`; projection continues
131+
4. Click **Abort** → CLI exits with non-zero code
132+
133+
### Build Without Web Server
134+
135+
```sh
136+
cargo build --package tp-cli --no-default-features
137+
```
138+
75139
## Project Structure
76140

77141
```
78142
tp-lib/ # Rust workspace root
79143
├── tp-core/ # Core Rust library
80144
│ ├── src/
81-
│ │ ├── models/ # Data models (GnssPosition, Netelement, ProjectedPosition)
145+
│ │ ├── models/ # Data models (GnssPosition, Netelement, ProjectedPosition, PathOrigin)
82146
│ │ ├── projection/ # Projection algorithms (geom, spatial indexing)
83147
│ │ ├── path/ # Train path calculation (candidate, probability, graph, viterbi)
84148
│ │ ├── io/ # Input/output (CSV, GeoJSON, Arrow)
@@ -90,6 +154,7 @@ tp-lib/ # Rust workspace root
90154
│ │ └── integration/ # Integration tests
91155
│ └── benches/ # Performance benchmarks
92156
├── tp-cli/ # Command-line interface
157+
├── tp-webapp/ # Interactive path review web server (axum + Leaflet.js)
93158
└── tp-py/ # Python bindings (PyO3)
94159
```
95160

@@ -383,13 +448,28 @@ xdg-open target/doc/index.html # Linux
383448

384449
### Specification Documents
385450

451+
**Feature 001 — GNSS Projection**
386452
- [Feature Specification](specs/001-gnss-projection/spec.md)
387453
- [Implementation Plan](specs/001-gnss-projection/plan.md)
388454
- [Data Model](specs/001-gnss-projection/data-model.md)
389455
- [CLI Contract](specs/001-gnss-projection/contracts/cli.md)
390-
- [API Contracts](specs/001-gnss-projection/contracts/)
391456
- [Tasks](specs/001-gnss-projection/tasks.md)
392457

458+
**Feature 002 — Train Path Calculation**
459+
- [Feature Specification](specs/002-train-path-calculation/spec.md)
460+
- [Implementation Plan](specs/002-train-path-calculation/plan.md)
461+
- [Data Model](specs/002-train-path-calculation/data-model.md)
462+
- [Tasks](specs/002-train-path-calculation/tasks.md)
463+
464+
**Feature 003 — Train Path Review Webapp**
465+
- [Feature Specification](specs/003-path-review-webapp/spec.md)
466+
- [Implementation Plan](specs/003-path-review-webapp/plan.md)
467+
- [Data Model](specs/003-path-review-webapp/data-model.md)
468+
- [REST API Contract](specs/003-path-review-webapp/contracts/api.md)
469+
- [CLI Contract](specs/003-path-review-webapp/contracts/cli.md)
470+
- [Quickstart](specs/003-path-review-webapp/quickstart.md)
471+
- [Tasks](specs/003-path-review-webapp/tasks.md)
472+
393473
### CI/CD & Workflows
394474

395475
This project uses automated workflows for continuous integration and deployment:

‎deny.toml‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -78,6 +78,12 @@ ignore = [
7878
# Updating to 0.24.1+ causes memory allocation issues during compilation
7979
# Will be resolved once polars supports newer pyo3 versions
8080
{ id = "RUSTSEC-2025-0020", reason = "pyo3 upgrade to 0.24.1+ blocked by polars dependency compatibility" },
81+
82+
# bytes 1.11.0 integer overflow in BytesMut::reserve; only exploitable with
83+
# intentional usize::MAX-sized allocations and overflow-wrapping builds.
84+
# Upgrade to bytes 1.10.1+ blocked by tokio/axum transitive constraint - will
85+
# be resolved when the dependency graph allows a compatible bytes upgrade.
86+
{ id = "RUSTSEC-2026-0007", reason = "bytes 1.11.0 integer overflow in BytesMut::reserve; transitive dependency via tokio/axum, upgrade tracked" },
8187
]
8288

8389
# This section is considered when running `cargo deny check licenses`

‎specs/003-path-review-webapp/checklists/requirements.md‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
# Specification Quality Checklist: Train Path Review Webapp
2+
3+
**Purpose**: Validate specification completeness and quality before proceeding to planning
4+
**Created**: March 21, 2026
5+
**Feature**: [spec.md](../spec.md)
6+
7+
## Content Quality
8+
9+
- [x] No implementation details (languages, frameworks, APIs)
10+
- [x] Focused on user value and business needs
11+
- [x] Written for non-technical stakeholders
12+
- [x] All mandatory sections completed
13+
14+
## Requirement Completeness
15+
16+
- [x] No [NEEDS CLARIFICATION] markers remain
17+
- [x] Requirements are testable and unambiguous
18+
- [x] Success criteria are measurable
19+
- [x] Success criteria are technology-agnostic (no implementation details)
20+
- [x] All acceptance scenarios are defined
21+
- [x] Edge cases are identified
22+
- [x] Scope is clearly bounded
23+
- [x] Dependencies and assumptions identified
24+
25+
## Feature Readiness
26+
27+
- [x] All functional requirements have clear acceptance criteria
28+
- [x] User scenarios cover primary flows
29+
- [x] Feature meets measurable outcomes defined in Success Criteria
30+
- [x] No implementation details leak into specification
31+
32+
## Notes
33+
34+
- All items pass. Spec is ready for `/speckit.clarify` or `/speckit.plan`.
35+
- Domain format terms (GeoJSON, CSV) are intentional — they refer to established contracts from prior features, not implementation choices.
36+
- CLI syntax in FR-015/FR-016 is required to specify the user interface contract; it does not prescribe implementation.

0 commit comments

Comments
 (0)