How julienperret/mapmatcher works
1. Repository purpose
- This is a small Java library for map matching GPS traces onto a trail/road network.
- Its main job is to turn noisy GPS observations into a best-fit path using the Hidden Markov Model (HMM) map matching algorithm from Newson and Krumm.
2. Primary architectural shape
- The repo is not a full application; it is a library plus a thin command-line wrapper.
- The library is packaged as a single runnable JAR with dependencies, intended to be called externally rather than embedded in a larger Java app.
3. Core domain subsystem
- src/main/java/mapmatcher/HikingTrailMapMatcher.java is the likely core implementation class.
- Based on the README, this class is responsible for the actual matching logic: reading spatial data, running the HMM-based algorithm, and producing matched results.
4. Command-line / integration boundary
- src/main/java/mapmatcher/MatchHikingTrail.java is the entry point used from the shell and, indirectly, from R.
- It accepts file paths and tuning parameters, then invokes the core matcher. This is the boundary where external callers cross into the Java code.
5. Data flow through the system
- Input comes from two spatial datasets: a GPS file and a network file.
- The CLI passes those inputs plus algorithm parameters to the matcher.
- The matcher computes the aligned path and writes a tabular output file, which the caller can read back as a table.
6. Input/output contract
- The README shows inputs are expected as shapefiles for both GPS observations and the route network.
- Output is written as a CSV-like table that R reads using read.table(..., header=TRUE).
- So the architectural boundary is file-based rather than in-memory or service-based.
7. Algorithmic dependency
- The implementation relies on the GeOxygene library for the HMM map matching algorithm.
- That means the repository’s core logic is thin glue around a GIS/mapping library rather than a custom algorithm implementation from scratch.
8. Parameterization layer
- The exposed parameters in the README — sigmaZ, selection, beta, and distanceLimit — are tuning knobs for the HMM matcher.
- Architecturally, these parameters flow from the CLI/R wrapper into the matching engine and affect candidate selection and scoring.
9. R integration boundary
- The project is explicitly designed to be called from R.
- The README’s example wraps the Java CLI in an R function, showing the intended usage pattern: R orchestrates execution, Java performs matching, and R loads the output table.
10. Build and packaging subsystem
- The project uses Maven (pom.xml) to compile and package the library.
- The expected artifact is a “jar with dependencies”, which indicates a shaded/uber-JAR style distribution to simplify calling from R or the command line.
11. Operational/runtime model
- There is no server, database, or background worker in the repository.
- The runtime is a simple batch process: read files, match, write results, exit.
12. Tooling and CI
- .travis.yml and the README badge show the project is wired for Travis CI.
- This is a build verification layer only; it does not change runtime architecture, but it confirms the project is intended to be continuously built and tested.
13. External dependency boundaries
- The important external dependency is GeOxygene for GIS/map-matching capabilities.
- The repository also assumes the presence of standard Java build tooling and, for users, R as the downstream consumer.
14. How to draw the architecture
- A good diagram would show:
- R or shell caller on the left
- the CLI entrypoint as the boundary
- the core map-matching engine in the center
- GeOxygene as an internal third-party library beneath the core
- shapefile inputs entering the system and matched tabular output leaving it
- There are no additional subsystems such as persistence, networking, or UI to include.
Main entry points: HikingTrailMapMatcher.java HikingTrailMapMatcher · MatchHikingTrail.java MatchHikingTrail · pom.xml Maven build · .travis.yml Travis CI
Components 11
Runtime
Batch map-matching flow
- MatchHikingTrail · Thin command-line boundary that parses arguments and launches matching.
src/main/java/mapmatcher/MatchHikingTrail.java - HikingTrailMapMatcher · Core HMM map-matching implementation and file-based processing logic.
src/main/java/mapmatcher/HikingTrailMapMatcher.java - Tuning params · sigmaZ, selection, beta, and distanceLimit flow into the matcher.
Build & CI
Packaging and verification
- Maven build · Compiles and packages the runnable jar with dependencies.
pom.xml - Travis CI · Continuous integration configuration for build verification.
.travis.yml
External
Downstream and third-party boundaries
- R caller · R wraps the Java CLI and reads the tabular output back in.
- Shell user · Command-line entry point for running the matcher directly.
- GPS file · Observed GPS trace data provided as a file.
- Network file · Trail or road network used as the matching graph.
- Matched table · CSV-like results written for consumption by R or other callers.
- GeOxygene · External GIS library providing map-matching and spatial capabilities.
Connections 12
- R caller → MatchHikingTrail: invokes · R launches the Java CLI wrapper.
- Shell user → MatchHikingTrail: runs · The matcher can also be run directly from the shell.
- MatchHikingTrail → HikingTrailMapMatcher: delegates · CLI forwards the file paths and matching settings into the core engine.
- GPS file → HikingTrailMapMatcher: input · Observed GPS observations are consumed by the matcher.
- Network file → HikingTrailMapMatcher: input · Route or trail network is read by the matcher.
- Tuning params → HikingTrailMapMatcher: configures · HMM tuning values affect candidate selection and scoring.
- HikingTrailMapMatcher → GeOxygene: uses · Core matching logic relies on the GeOxygene GIS library.
- HikingTrailMapMatcher → Matched table: writes · Matched path results are emitted as a table-like file.
- R caller → Matched table: reads · R loads the produced table for downstream analysis.
- Maven build → MatchHikingTrail: builds · Maven compiles the CLI class into the packaged artifact.
- Maven build → HikingTrailMapMatcher: builds · Maven packages the core matcher into the runnable jar.
- Travis CI → Maven build: verifies · CI runs the Maven build to check the repository.