natlabrockies/mappymatch

1. What the package is

- mappymatch is a pure-Python map-matching library whose core job is to take a GPS trace and align it to a road network.

- The architecture is centered on a small domain model, pluggable map backends, and multiple matcher implementations.

2. Core domain layer

- The constructs package defines the shared data model used by all matchers and maps: Coordinate, Trace, Geofence, Road, and Match.

- These objects are the main boundary between raw inputs, map data, and matcher outputs.

3. Trace ingestion and preprocessing

- Trace data is typically loaded from CSV or geospatial files into Trace objects.

- utils/process_trace.py and related helpers handle trace normalization and preparation steps such as coordinate handling, stationary-point logic, and geometric utilities.

- This layer is where raw GPS points become matcher-ready input.

4. Map abstraction layer

- maps/map_interface.py defines the common map contract.

- There are concrete map adapters for:

- maps/nx/NxMap for NetworkX-based road graphs

- maps/igraph/IGraphMap for igraph-based graphs

- This abstraction lets matchers work against a common map API instead of binding to one graph library.

5. OpenStreetMap acquisition

- maps/nx/readers/osm_readers.py is the OSM ingestion path for the NetworkX backend.

- The typical flow is: build a Geofence around a trace, query OSM data within that boundary, and construct an in-memory road network.

- In practice, the repository’s primary map source is OpenStreetMap.

6. Matcher subsystem

- matchers/matcher_interface.py defines the matcher boundary.

- The repo contains three matcher families:

- LCSSMatcher in matchers/lcss/

- OsrmMatcher

- ValhallaMatcher

- This is the main strategy layer: each matcher consumes the same trace/map abstractions but produces matches through a different algorithm or service.

7. LCSS matcher internals

- The lcss package is the most substantial in-repo algorithm implementation.

- It contains the algorithm, helper operations, and internal constructs used for segmentation/sequence alignment.

- This matcher is local and offline: it runs entirely in Python against the in-memory road graph, making it the repo’s most self-contained matching path.

8. External service-based matchers

- OsrmMatcher and ValhallaMatcher are thin clients over external routing/map-matching engines.

- They introduce a network boundary: trace data is serialized, sent to a running OSRM or Valhalla service, and the returned match result is converted back into the package’s internal Match representation.

- These matchers depend on service availability and remote API compatibility, unlike LCSS.

9. Match results

- matchers/match_result.py is the common output container for all matchers.

- It acts as the integration point for downstream analysis, including conversion to tabular form via pandas-like dataframe workflows.

- This keeps result consumption separate from algorithm execution.

10. Geometry, CRS, and geo utilities

- utils/crs.py, utils/geo.py, and utils/url.py support coordinate system handling, geometric calculations, and request construction.

- These utilities are shared infrastructure used by trace processing, geofence creation, map loading, and service-backed matchers.

11. Plotting and visualization

- utils/plot/ contains visualization helpers for maps, traces, geofences, paths, trajectory segments, and matches.

- This is a presentation layer, not part of the core matching pipeline, but it is important for debugging and explaining results.

12. Data and example assets

- resources/traces/ provides sample trace CSVs used in examples and tests.

- tests/test_assets/ includes OSM graph and geospatial fixtures, showing the intended offline testing path for map and trace behavior.

- These assets indicate the library is designed to be exercised both with real OSM-derived graphs and small reproducible fixtures.

13. Typical end-to-end flow

- The canonical architecture path is:

- load a Trace

- derive a Geofence

- build or load a map backend (NxMap or IGraphMap)

- run a matcher (LCSSMatcher, OSRM, or Valhalla)

- consume a MatchResult

- This is the key pipeline to show in an architecture diagram.

14. Repository boundary and delivery

- The project ships as a Python package with docs and automated testing.

- Documentation lives under docs/, and the test suite covers trace handling, geo logic, OSM integration, matchers, and result behavior.

- The package is therefore a library architecture, not a server or application architecture.