Package-level declarations

Manage a valhalla configuration json file (valhalla.json). This is similar to operating valhalla on a server, but we generate the file from code to correctly specify paths relative to the app's filesystem.

Building a config

ValhallaConfigFactory starts from valhalla's own defaults and points them at your tiles. Each function mirrors an initializer on iOS's ValhallaConfig extension, so a config built here matches the config built there.

val tilesDir = appContext.getExternalFilesDir(null)
val tarFile = ValhallaFile(appContext, "valhalla_tiles.tar", tilesDir!!)

val config = ValhallaConfigFactory.usingTileExtract(tarFile.absolutePath())

For a directory of loose tiles rather than a tarball, and with elevation tiles so the height action returns something:

val config = ValhallaConfigFactory.usingTilesDir(
    tilesDir = tilesDirectory.absolutePath,
    elevationDir = elevationDirectory.absolutePath,
)

To download tiles on demand and cache them on the device:

val config = ValhallaConfigFactory.usingTileUrl(
    tilesUrl = "https://your.tileserver/{tilePath}",
    tilesDir = tilesDirectory.absolutePath,
)

Valhalla fills the {tilePath} portion in with the tile it wants. tilesAreGzFiles decides whether downloaded tiles are stored gzip-compressed or raw, whatever the server sends. It is ignored for a tar URL.

Fetching goes through java.net.HttpURLConnection, so this adds no networking dependency to your app. Three things to know:

• The consuming app must declare <uses-permission android:name="android.permission.INTERNET" />. This library does not declare it, so that offline-only consumers do not inherit it. Without it every fetch fails.

• Fetches are synchronous, on whichever thread ran the routing action. Do not route on the main thread with a config built this way.

• This turns Loki's connectivity map off. It is built from the tiles that are present, so it cannot answer for tiles that have not been downloaded yet.

A config built for offline use — usingTileExtract or usingTilesDir — carries no tile URL, and no fetching is attempted.

A config that already exists as JSON can be read back with ValhallaConfigFactory.fromJson or fromFile, and ValhallaConfigFactory.default() hands you valhalla's defaults to adjust yourself. Every function returns an immutable ValhallaConfig, so copy it for anything the factory does not cover.

Where the defaults come from

default() reads a bundled default.json that is generated by valhalla's own scripts/valhalla_build_config from the version of valhalla this library is built against, and iOS bundles the identical bytes. That is deliberate: it keeps the two platforms' defaults from drifting apart, and it sidesteps the defaults baked into the generated model classes, several of which do not match valhalla's.

Writing it out

ValhallaConfigManager writes a ValhallaConfig to disk, which is what Valhalla does for you when you hand it a config. It defaults to one fixed valhalla.json, so give each instance its own ValhallaFile when more than one is alive at a time:

val manager = ValhallaConfigManager(appContext, ValhallaFile(appContext, "valhalla-region-a.json"))
val valhalla = Valhalla(appContext, config, manager)

If the app ships or downloads a complete valhalla.json already, skip all of this and point Valhalla straight at it with Valhalla(configPath). The tile paths inside must be absolute and correct for the device; nothing rewrites them.