Skip to content

feat: on-device Meili map matching on Android (trace_attributes) + persistent actor + HTTP tile client#83

Open
matt-jsb wants to merge 1 commit into
Rallista:mainfrom
matt-jsb:feat/android-on-device-map-matching
Open

feat: on-device Meili map matching on Android (trace_attributes) + persistent actor + HTTP tile client#83
matt-jsb wants to merge 1 commit into
Rallista:mainfrom
matt-jsb:feat/android-on-device-map-matching

Conversation

@matt-jsb
Copy link
Copy Markdown

Summary

Three coherent additions to the Android side of the wrapper, all aimed at
enabling Valhalla as a navigation runtime rather than just a routing endpoint:

  1. On-device map matchingValhalla.traceAttributes(...) exposes
    Valhalla's trace_attributes action, backed by Meili's HMM matcher. Useful
    for off-route detection, lane reasoning, and any consumer that needs the
    matched road-graph edge for a sequence of GPS samples.

  2. Persistent JNI actor — resolves the existing
    // TODO: Android currently creates a new actor every time. Optimize to be like iOS later. Each Valhalla instance now owns one native
    ValhallaActor for its lifetime (mmap'd tile extract held open). Required
    for any production matching path; routing also benefits.

  3. OkHttp-backed ValhallaHttpClient — Android counterpart to the
    existing iOS ValhallaMobileHttpClient. Lets the wrapper pull tiles over
    HTTP when the tile extract isn't bundled locally; consumers pass in their
    own preconfigured OkHttpClient.

A small build-script portability fix (nproc not available on macOS) and an
optional Cloudsmith publishing target ride along — both opt-in and don't
change upstream behaviour by default.

API additions (Android)

Surface Purpose
Valhalla : Closeable Lifecycle now explicit. Old construction-without-tiles silently-succeeds-then-fails-per-call behaviour replaced by fail-fast at construction.
Valhalla.traceAttributes(request: TraceAttributesRequest): String Typed map-matching call. Returns raw JSON for parser flexibility.
Valhalla.traceAttributesRaw(json: String): String Escape hatch.
com.valhalla.valhalla.mapmatching.* TraceAttributesRequest, TracePoint, TraceFilters, TraceOptions, ShapeMatch, FilterAction.
OkHttpValhallaHttpClient Android HTTP tile client.

iOS is unchanged

All edits to src/wrapper/main.cpp are guarded by #ifdef __ANDROID__. The
#elif __APPLE__ block is byte-identical to main. iOS Swift / Obj-C++ APIs
are not touched.

Behaviour change (worth flagging)

Valhalla(context, badConfig) now throws ValhallaException.Internal at
construction time, carrying the original native error message. Previously,
construction succeeded and every subsequent route() returned an error JSON.
The new contract is fail-fast and matches what most Android consumers expect.
Existing tests were updated to match.

Documentation

  • android/valhalla/docs/MapMatching.md — request/response shape, off-route
    detection recipe, lifecycle notes.
  • android/valhalla/docs/Publishing.md — Cloudsmith publishing recipe (opt-in).

Test plan

  • ./gradlew :valhalla:connectedAndroidTest — all existing tests pass,
    plus new ValhallaTraceAttributesTest (smoke test against bundled
    Andorra fixture) and ValhallaHttpTileTest.
  • ./gradlew ktfmtCheck — clean.
  • Build for all four ABIs (./build.sh android) — clean.
  • iOS build untouched — ./build.sh ios still green.

What's not in this PR

  • The streaming MapMatcher::AppendMeasurements binding (Path B in the design
    doc) — only worthwhile if profiling shows batch trace_attributes is too
    expensive for live navigation. Deferred until there's evidence.
  • iOS bindings for trace_attributes — followable in a separate PR.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant