ZYRNTOPO Documentation

Complete reference for every feature in ZYRNTOPO — an offline-capable topographic mapping application for Android and Web. The core app is free with no account or subscription; ZYRNTOPO Pro is an optional one-time unlock for the power features. Your data stays on your device.

Installation

ZYRNTOPO runs on Android and the web. Choose the one that fits your device.

Android

1. Install from Google Play when available (search "ZYRNTOPO").
2. For sideload testing, download the current 1.10.7 beta APK from this site. Android may ask you to allow installs from your browser before opening the APK.
3. On first launch, the app shows a prominent disclosure and requests Location (for GPS position and track recording). The Microphone is requested only when you record a voice note. You can update these any time in Android Settings.
4. The app works immediately — no sign-in, no setup wizard.

Web / PWA

Open app.zyrntopo.com in any modern browser. For offline use, install it as a PWA: in Chrome/Edge click Install app in the address bar; in Firefox/Safari use Add to home screen.

First Launch

On first launch ZYRNTOPO shows a prominent disclosure, then requests Location using the native OS dialog (foreground only — never in the background). Location is used for map position, tracks, route following, and nearby field context; online weather, elevation, routing, or search features may send the needed coordinates or query to their provider. The Microphone permission is requested in-context the first time you record a voice note. On Web, the browser asks for Location when you first use GPS.

The default base layer on first launch is OpenFreeMap Liberty — a full-detail vector street map rendered via MapLibre GL. Your map starts centered at the contiguous US (z4) or at your last-saved position if you've used the app before.

After your first session, all key UI state is automatically persisted — base layer selection, map position and zoom, and hillshade opacity are restored exactly as you left them on every subsequent launch.

Basic Navigation

The interface has three main areas:

• Map canvas — the full-screen map. Pan with one finger (touch) or mouse drag. Pinch or scroll to zoom. Rotate with two fingers.
• Top bar — map title, layer switcher, GPS button, search, and the More drawer trigger.
• More drawer — opens from the hamburger menu: Map Objects, Folders, Operational Periods, Team Members, Team Sync, Gear, Settings, Offline Tiles, and Import/Export.

Long-press anywhere on the map to open the context menu: drop a marker here, start a line from here, or view point info.

Base Layers

Tap the layer icon (stack icon in top bar) to open the layer panel. The current basemap shows as a single compact row — tap it to open the base-layer picker, grouped by category with a thumbnail preview per layer. Twenty-one base layers are included — 14 raster layers organized into groups, plus seven no-key vector basemaps (five VersaTiles, two hand-built ZYRNTOPO styles) — plus a built-in browser for 1,345 additional worldwide imagery sources (OSM Editor Layer Index).

The Offline column reflects each provider's terms — ✓ = saveable with the Area Saver; Online only = view-only (terms forbid bulk/offline download, import a .pmtiles instead).

Topo & Terrain

Imagery

Water / Bathymetric

Street & General

Vector Basemaps

Ten no-key vector basemaps are available directly from the base-layer dropdown — no PMTiles import required — rendered by MapLibre GL JS. Five come from OpenFreeMap and five from VersaTiles. Both sets are free, require no API key, and overzoom cleanly (they stay sharp at any zoom). As of v0.3.16 their style, glyphs, and sprites are bundled in the app, so a vector map renders even from a cold offline start (only the tiles need a connection until you download an area).

Imagery Catalog (NEW in 0.2.5)

Beyond the 23 built-in layers, ZYRNTOPO ships with a filtered copy of the OSM Editor Layer Index — 1,345 worldwide imagery sources curated for OSM editing (regional aerials, government topo maps, historical photos, etc.). Tap Layers → Custom WMS / WMTS → Browse Imagery Catalog and filter by:

• Search — name, country code, description
• Type — XYZ (TMS) or WMS
• Category — aerial photo, map, historic photo, historic map, elevation, OSM-based, QA
• Country — ISO country code dropdown

One-tap Add converts the entry into a custom source (TMS templates have {zoom} rewritten to {z}; WMS endpoints have LAYERS and FORMAT auto-extracted) and persists it across sessions. Added sources appear in the dropdown alongside the built-in 23 layers.

The Offline column shows which bases ZYRNTOPO will pre-download into a local .pmtiles archive. This is gated by each provider's terms: USGS The National Map (US-government public domain, attribution requested) and the vector basemaps (OpenFreeMap / VersaTiles) are downloadable; Esri, OpenStreetMap, OpenTopoMap, and NatGeo stay online-only because their terms prohibit bulk/offline tile download. For those, import a provider-approved .pmtiles instead — see Offline Maps (PMTiles).

You can also add custom tile sources manually: tap Add WMS/WMTS Source at the bottom of the layer panel, enter a tile URL template (https://example.com/{z}/{x}/{y}.png), a name, and tap Add.

Overlays

Overlays layer on top of any base map. Multiple overlays can be active simultaneously, each with an adjustable opacity slider.

Terrain & Topography

• Slope Angle Shading (NEW in 0.5.0) — terrain coloured by steepness, computed on-device from the elevation (DEM) data — no external service. The avalanche-oriented ramp keeps gentle terrain clear and heats up through the critical band: 27–29° yellow, 30–34° orange, 35–45° red (where most slab avalanches release), 46–50° purple, 51–59° blue, 60°+ grey (cliffs). Toggle it under Layers → Conditions → Slope Angle with an opacity slider. Works online (Mapterhorn DEM) and offline once DEM tiles are cached or a terrain archive is imported. Renders from zoom 8 in.
• Slope Aspect (NEW in 0.9.0) — terrain coloured by the compass direction each slope faces, computed on-device from the same DEM as slope angle. An 8-sector colour rose (N, NE, E … NW) for planning sun exposure, snow loading, and avalanche aspect. Toggle it from the overlay picker with its own opacity slider; an on-map legend appears while it's active. Works online and offline (cached DEM / terrain archive).
• Hillshade — shaded relief from Esri's World_Hillshade service (DEM-derived). Pairs well with imagery and any topo layer.
• USGS Topo Overlay — overlays USGS Topo at adjustable opacity for blending with satellite imagery.
• USGS Hydrography — streams, rivers, water bodies from USGS National Map.

Reference

• Boundaries & Places — Esri labels overlay (great companion for satellite imagery).
• Transportation — Esri's roads/highways reference layer.

Route Discovery

• Hiking Trails — Waymarked Trails hiking-route overlay (display only — see CORS note).
• Cycling Routes — Waymarked Trails cycling network (display only).
• MTB Trails — Waymarked Trails mountain-bike network (display only).
• Public Lands (BLM) — US Bureau of Land Management ownership and surface management. Available at zoom 9+ (display only).
• OpenSeaMap — nautical seamarks for coastal/marine ops.
• OpenSnowMap pistes (NEW) — worldwide ski/snowboard pistes and lifts — great for winter SAR and backcountry skiing.
• OpenRailwayMap (NEW) — global rail infrastructure: tracks, stations, signals.
• OpenInfraMap power (NEW) — high-voltage transmission lines and substations from OSM data.
• Esri Reference Labels (NEW) — transparent label-only overlay; pairs with satellite/physical bases.

Weather & Hazards (NEW in 0.7.6)

• Weather Radar (NEXRAD) — near-real-time NEXRAD base-reflectivity mosaic (Iowa Environmental Mesonet), refreshed about every 5 minutes. Online-only — radar is time-sensitive and isn't cached for offline use.
• Active Wildfires (NIFC) — current US wildland-fire perimeters (over 100 acres) from the National Interagency Fire Center, drawn as vector polygons; tap a perimeter for the incident name, acreage, and discovery date. Loaded on demand and refreshed every few minutes.
• Avalanche Danger (NEW in 0.9.0) — US avalanche-forecast zones from avalanche.org, colour-coded by the current North American danger scale (1 Low → 5 Extreme). Tap a zone for its rating; an on-map legend appears while it's active. Online-only and refreshed periodically (off-season zones show with no active rating).

Field Data — US (NEW in 0.7.6)

• PLSS Survey Grid (BLM) — the Public Land Survey System township / section / intersected grid, shown as a reference overlay.
• USFS Motor Vehicle Use Map — legal motorized roads & trails on national-forest land (the authority for vehicle access while hunting and scouting).
• USFS Ownership (NEW in 0.9.0) — US Forest Service surface-ownership / administrative boundaries, for confirming you're on national-forest land vs. adjacent private or other-agency parcels.
• Wetlands (NWI) — USFWS National Wetlands Inventory polygons (waterfowl habitat and fishing / launch context).
• Tribal Lands / Reservations (NEW) — American Indian, Alaska Native, and Native Hawaiian areas from the US Census Bureau: Federal & State reservations, off-reservation trust lands, and Hawaiian home lands. Jurisdiction and access context in the backcountry. Toggle it from the overlay picker with its own opacity slider (display only, like the other field-data layers).
• USGS Contours — transparent topographic contour lines to drape over satellite imagery.
• Watersheds (USGS WBD) — HUC drainage-basin boundaries for hydrology and fishing.

These US field-data layers come from free, no-API-key ArcGIS map services via a generic dynamic-MapServer overlay type, so any number of them can be stacked at adjustable opacity.

3D Terrain View

Tap the 3D badge in the layer panel or the top bar to switch to 3D terrain mode, powered by MapLibre GL with WebGL rendering.

• Real DEM elevation data from Mapterhorn (Terrarium-encoded WebP)
• Drapes any base layer over the 3D terrain mesh
• Hillshade and sky atmosphere included
• Two-finger drag to pitch the view; two-finger rotate to spin
• Use the pitch slider to adjust terrain tilt
• Terrain exaggeration can be increased in Settings

Offline 3D Terrain (NEW in 0.2.5)

Previously, 3D mode required internet to fetch DEM tiles from Mapterhorn. Now you can save terrain data offline:

1. Pan/zoom to your AOI
2. Open Layers → Save Terrain
3. Confirm the tile count + size estimate; ZYRNTOPO downloads the Mapterhorn DEM tiles (z0–10 by default) and packs them into a .pmtiles archive tagged with kind: 'dem'
4. From then on, any 3D activation prefers the local DEM archive over the network — fully air-gapped 3D terrain

The DEM archive is independent from base-tile archives. Both can coexist; the 3D engine combines them via MapLibre's raster-dem source pointed at a pmtiles:// URL.

You can also bundle a starter DEM archive with the app by adding an entry to public/maps/manifest.json with "kind": "dem" — see Offline Maps.

Vector PMTiles

ZYRNTOPO can display vector PMTiles archives (OpenFreeMap exports, Protomaps Basemaps, tippecanoe output, etc.) — not just raster ones. The app uses MapLibre GL's addProtocol('pmtiles') to read tiles directly from the in-OPFS archive without any network round-trip.

• Import any .pmtiles file (raster or vector) via Layers → Offline Maps → Import .pmtiles.
• Activate a vector archive: tap Use (3D) in the offline maps list. The app enters 3D mode and switches to a MapLibre style.
• A default style is auto-generated from the archive's vector_layers metadata: every layer gets a fill, line, and circle entry filtered by geometry type, plus label symbols where the layer has a name field.
• Vector tiles drape over the DEM just like raster bases — so vector maps get real 3D terrain too.
• Raster + vector PMTiles can coexist; switch between them from the base-layer dropdown.

Controls & Compass

All map controls are accessible from the map canvas:

• Zoom buttons (+/−) — bottom-right corner
• Download map area — the offline-area button now lives in the top bar, to the right of Point Info (moved out of the bottom-right stack in 0.5.0 to declutter the main controls). Tap it to draw/drag a box and download that region. See Area Saver.
• Compass rose — tap to reset rotation to North-up; long-press to enable heading-up mode (map rotates with your bearing)
• Center crosshair — a fixed crosshair at the map center for precise location reading
• Context menu — long-press the map anywhere for: drop marker here, start line from here, view point info, navigate here

Night Mode

Tap the moon icon to cycle through three states: Off → Dim → Dark. Night mode applies a CSS filter to the map canvas to reduce brightness and blue light without affecting the UI. It works on all base layers and overlays and is preserved across sessions.

Coordinate Display

Your current GPS position is always shown in the bottom status bar. Choose your preferred format in Settings → Coordinate Format:

Tap any displayed coordinate to copy it to the clipboard.

UTM / MGRS grid overlay (NEW in 0.7.7)

Add the UTM / MGRS grid from the overlay picker (Layers → Add an overlay → Topographic / Reference) to draw a labelled military-style reference grid over any base map. The grid is computed in the view-centre UTM zone, redraws as you pan and zoom, and has its own opacity slider in the layer stack. Spacing scales with zoom (100 km → 10 km → 1 km) — the same grid lines underlie MGRS.

Markers & Waypoints

Drop a marker by long-pressing the map and selecting Drop Marker Here, or tap GPS marker to drop one at your current location. A details panel opens immediately.

Marker properties

• Name — any text label
• Notes — multi-line description or clue notes
• Icon — choose from 50+ typed icons: trailhead, summit, camp, water, warning, medical, wildlife, and more
• Color — full color picker with preset swatches
• Folder — assign to any existing folder
• SAR attributes — mark as clue, assign to operational period, set find status

Tap an existing marker to open its info card. From there: edit, delete, navigate to, copy coordinates, or zoom-in.

Averaged waypoint (NEW in 0.7.7)

For higher-accuracy waypoints, use Add → Average WP. Hold the device still over the point while it collects continuous GPS fixes; the dialog shows a live sample count, the running average position, and an estimated ± accuracy that tightens as samples accumulate (random error falls off as roughly √N). Tap Save waypoint to drop a marker at the averaged position, tagged with the sample count and accuracy.

Lines & Routes

Tap Draw in the top bar then select Line. Tap the map to place vertices. A live distance display shows the running total. When done, tap Finish.

• Each line segment shows distance in your preferred units
• Edit mode: drag existing vertices, insert new ones, or delete
• Assign name, color, and folder
• Free Draw (1.3.0) — open Tools → Free Draw and drag on the map to sketch. Each stroke saves immediately as a line you can rename, recolour, or move later. Works with touch or mouse; pinch-zoom still works mid-sketch. Press Escape to exit the tool.

Elevation profile (NEW in 0.7.7)

Open any line, track, or route and tap Elevation in its editor to see a CalTopo/Gaia-style elevation profile: the path is resampled evenly by distance, elevations are fetched, and a profile chart is drawn with total distance and gain / loss / min / max in your preferred units. Needs a connection to fetch elevation data.

Polygons & Areas

Select Polygon in the Draw menu. Tap to place polygon vertices; the shape closes automatically when you tap Finish. Area is calculated and shown in the info panel (acres, sq km, sq mi).

Buffer zones — tap an existing object and choose Buffer Zone to create a polygon offset by a specified distance.

Sectors / wedges — from the context menu choose Draw Sector to create a pie-wedge search area with configurable bearing and radius.

Highlight (NEW in 0.8.3) — select Highlight in the Draw menu to shade an area with a translucent fill (preset colours or a custom colour). Use it to mark a search segment, a hazard zone, a planned burn, or an area of interest without hiding the map underneath.

Circle (1.3.0) — open Tools → Circle, press at the centre point and drag outward. A live radius readout appears while you size it; release to name and save. Saved as a buffer-style polygon you can edit like any other shape.

Range Rings

Long-press a marker or tap More → Range Rings to draw concentric search rings around a point. Configure:

• Number of rings — 1 to 10
• Spacing — distance between each ring (meters or feet)
• Custom radii — override with specific values per ring
• Bearing offset — rotate the ring set for directional probability

Range rings are stored as a single object and can be edited or deleted from the Objects panel.

Folders & Organization

Open More → Folders to manage folders. Folders help group objects by purpose — e.g., "Day 1 Search", "Water Sources", "Hazards".

• Create folder with name and color
• Assign any marker, line, or polygon to a folder
• Toggle folder visibility — hides/shows all objects inside on the map
• Export a single folder as GeoJSON

Operational Periods

Open More → Operational Periods. Operational periods (OPs) are standard SAR planning containers — typically one per 12 or 24 hour shift.

• Create an OP with a name, start time, and active status
• Assign any map object to an OP
• Objects belonging to an inactive OP can be filtered out of view
• Export a single OP as GeoJSON

GPS Modes

The GPS button (bottom-right of map) cycles through three states:

1. Off — no GPS. Button is gray.
2. Follow — map re-centers on your position every few seconds. Button is blue.
3. Heading-up — map rotates to match your bearing AND follows your position. Button is blue with rotation indicator.

An accuracy circle is displayed around your position marker. In poor GPS conditions (dense canopy, canyon) the circle will be large — always verify position against known landmarks.

Track Recording

Tap the track icon (footprints, top bar) to start recording. A live track is drawn on the map in real time. The track bar shows live stats:

• Distance traveled
• Elevation gain (from GPS altitude)
• Elapsed time
• Average speed (mph or km/h) — NEW in 0.7.7

Tap Stop to end the recording. A trip summary (distance, elevation gain, duration, and max speed) is shown, and the track is saved as a line object in your map objects list — exportable as GPX or GeoJSON, and you can open its elevation profile from the editor.

Measurement Tools

Tap More → Measure to open the measure tool. Tap points on the map to build a measurement path:

• Point-to-point distance with running total
• Bearing between last two points
• Area measurement — close the shape to get area in acres or sq km
• Elevation profile — tap two points to see the elevation chart along the path
• Viewshed / line-of-sight (NEW in 0.9.0) — tap an observer point and the tool shades the terrain that's visible from it in green, computed on-device from the DEM. Set observer and target height, a maximum radius, and an optional radio (4/3-earth) mode that models radio-horizon bending for comms planning. Distances and areas report in your chosen units. Great for siting repeaters, lookouts, or signal mirrors.

Measurement results appear in a card directly on the map and stay visible while you keep working — you no longer need to reopen the Measure panel to read them. Tap the card's × to dismiss the result and clear the drawing.

Tap Clear to reset without saving the measurement.

Field Navigation Shortcuts

ZYRNTOPO includes a few quick actions for search and field coordination without adding military-specific marker sets or fire-planning workflows.

• Heading Line: open Tools → Heading Line while GPS/compass is active to create a bearing line from your current position and current heading. Choose a length such as 500 m, 1 km, 0.5 mi, or 1000 ft, then save or edit the line.
• Bearing Sight: open Tools → Sight for a fullscreen compass HUD. It shows the live azimuth your device is pointing — toggle between magnetic and true (local declination is applied), with mils, a rotating compass card, and a vertical inclination angle. Tap Shoot azimuth → map to drop a bearing line from your GPS fix (or the map centre). It runs entirely from the device's compass and accelerometer, so it works fully offline and needs no camera.
• Share Loc: open Tools → Share Loc to share your current GPS position, or the map center if GPS is off. The share card includes DD, DMS, UTM, MGRS coordinates, and a map link.
• Share point: long-press any location and choose Share point to send a clean coordinate card for that exact point.

Navigate to Point

Tap any marker and choose Navigate, or long-press the map and choose Navigate Here. A navigation bar appears at the top showing:

• Target name or coordinates
• Straight-line distance to target
• Bearing to target
• Arrow pointing toward target

Navigation updates every GPS fix. Tap the X to stop navigating.

Trail Routing & Off-Route Alerts (NEW in 0.9.0)

For a route that follows real trails instead of a straight line, open Tools → Route, tap waypoints along your intended path, and double-tap to finish. When you're online the route snaps to trails and paths via BRouter and reports total distance and elevation gain; offline it falls back to straight segments between waypoints. The finished route is saved as a normal line object you can navigate and use offline.

While you follow a route, off-route alerts warn you when your live GPS position strays beyond a set distance from the line — so you catch a wrong turn early. One-tap activity presets (Hike / Snow / SAR / Off-road) set up a matching base map and overlays before you start.

Search & Point Info

Place Name Search

Tap the search icon in the top bar. Type a place name, address, or coordinates. Results come from Nominatim (OpenStreetMap geocoding). Tap a result to jump to it on the map and optionally drop a marker.

You can also paste raw coordinates directly into the search bar in any supported format (DD, DMS, DDM, UTM, MGRS).

Point Info Panel

Long-press any map location and tap Point Info. The panel shows:

• Coordinates in your selected format
• Elevation from a point-elevation query (requires network)
• Weather (updated in 0.8.0) — a live conditions widget for the exact point you tapped: weather icon, temperature, condition, and wind, from the free Open-Meteo API (no key)
• Sun & daylight (NEW in 0.9.0) — sunrise / sunset, civil twilight, and daylight-remaining for that point, computed on-device so it works offline

Offline Maps (PMTiles)

The primary offline mechanism is a real .pmtiles archive stored as a single file in the device's Origin Private File System (OPFS). This replaces fragile per-tile browser caching with something that survives storage pressure, works across reloads, and can be transferred to teammates as a single file.

What you can save offline

ZYRNTOPO only pre-downloads tiles from sources whose terms permit offline storage. That's a deliberate choice — it keeps you compliant and avoids provider rate-limit / IP blocks. Here's exactly what the Area Saver (and Save Terrain) can save:

Why PMTiles instead of a tile cache?

• Single file — random-access via byte ranges. No millions of Cache API entries.
• Eviction-resistant — when the browser grants persistent storage, the saved file isn't dropped under storage pressure.
• Sneakernet-friendly — copy a 500 MB regional archive over USB, drop it via Reticulum, share over LAN.
• Same format used by Protomaps, OpenFreeMap, BBBike — bring your own archive from any of these sources.

What ships with the app

As of v0.3.0, no bundled starter archive is included. The app ships without any pre-packaged PMTiles files to keep the download lean. On first launch the default basemap is OpenFreeMap Liberty (hosted vector, requires network). To go offline, either use the Area Saver to build your own archive, or import any .pmtiles file you have.

Importing a PMTiles file

1. Open Settings → OFFLINE MAPS (.PMTILES).
2. Tap Import .pmtiles and pick a file from your device.
3. The bytes stream-copy into OPFS (multi-GB safe), the header is parsed, and the archive appears in your list with bounds, zoom range, and tile format.
4. Switch to it in the base-layer dropdown under My Maps (offline). Disable Wi-Fi to confirm — tiles render straight from the file.

Recommended sources: Protomaps, OpenFreeMap, BBBike Extract, or any tippecanoe / pmtiles convert output.

Area Saver — Build Your Own Archive

The Area Saver downloads tiles for the current viewport at any zoom range and packs them into a brand-new .pmtiles archive on your device. This is the answer to "all zoom levels for my area" — without trying to bundle the whole world.

How it works

1. Pan the map to your area of interest (a county, a search grid, a trail system).
2. Open Settings → OFFLINE MAPS → Select Area, or tap the offline-tiles button on the map toolbar. A green selection box appears on the map.
3. Drag the box to reposition and pull any corner to resize, then set the min and max zoom. A live estimate shows tile count + size.
4. Tap Download Area → confirm the download size → progress bar shows tiles downloaded and bytes written.
5. The archive lands in your My Maps list automatically, ready to use.

Select Area on Map (NEW in 0.3.16)

For a precise, Google-Maps-style selection, open Settings → OFFLINE MAPS → Select Area. A green box appears on the map — drag it to reposition and pull any corner to resize until it frames exactly the area you want. Pick the min/max zoom (the panel shows a live tile-count and size estimate), then tap Download Area. It downloads that exact rectangle of the current base map — raster or vector — into a .pmtiles archive via the same background, resumable engine.

Download by Region (NEW in 0.3.15)

Don't want to frame the viewport by hand? Open Settings → OFFLINE MAPS → Download Offline Map → Browse and tap Pick a region to download. Choose a preset continent, country, or mountain range, pick the zoom range with a live size estimate, and the current base map is saved for that whole area — no panning required. The same sheet also lists ready-made packages and accepts a direct .pmtiles / .mbtiles URL.

• Preset regions — continents, countries, and mountain ranges with one-tap download
• Per-download zoom — choose min/max zoom with a live tile-count & size estimate before you commit
• Background & resumable — downloads run in the background and resume automatically after an app restart, so a dropped connection or a closed app won't lose progress

Why it scales

• Streaming write — tiles go straight from the network to OPFS via the FileSystemWritableFileStream. The app never holds the whole archive in memory, so multi-GB regions are safe even on phones.
• SHA-1 deduplication — identical tiles (ocean, forest canopy, blank areas) are stored once. Typical savings: 30–50% on raster regions with lots of homogeneous terrain.
• Cancellable — tap Cancel and the partial OPFS file is removed cleanly.
• Polite — concurrency capped at 4 simultaneous fetches.

Realistic sizing

Online Tile Cache (Fallback)

For tiles you happen to view while online — outside any imported PMTiles archive — the service worker still caches them to Cache API storage as a stale-while-revalidate fallback. This is now a secondary mechanism; PMTiles archives are the canonical offline source. In 0.7.5, opportunistic caching was tightened so it feels more native without overwhelming low-end devices.

• All base layers and overlays cached independently while online
• Cached tiles continue to serve when the connection drops
• DEM terrain tiles (for 3D) cached alongside base layers
• Retina-aware: {r}=@2x URL substitution matches between cache write and live <img> request
• Viewport preloading warms nearby tiles and adjacent zoom levels, with deduped and bounded queues
• Cached parent tiles are used as fallback when exact tiles are unavailable, including opaque no-CORS tiles served back through the service worker
• When connectivity returns, visible tile layers redraw and run a light re-warm pass
• Subject to OS storage-pressure eviction (which is exactly why PMTiles archives are the canonical mechanism — they're not evicted)

Storage Management

Open Settings → OFFLINE MAPS for archive management, or scroll down for online-cache controls:

• My archive list — name, size, zoom range, and tile format per imported archive. Each row has Use / Remove buttons. Bundled archives are flagged.
• Tile cache size — total storage used by the online fallback cache
• Clear tile cache — removes only the online cache; PMTiles archives are unaffected
• Clear app cache — clears app-level cache (does not delete map objects or archives)

Team Sync — Overview

Team Sync lets multiple ZYRNTOPO users share a live map — markers, lines, and polygons propagate to all connected peers in real time, along with each user's GPS position. Open via More → Team Sync.

How it works

• Objects are synced with a last-write-wins CRDT — the most recent edit always wins
• GPS positions broadcast every 4 seconds; peers appear as colored circles on the map
• Peer identity is ephemeral per session (no accounts)
• Five transport modes are available depending on connectivity

Team Sync — P2P (Internet)

Uses Trystero over Nostr relays — serverless peer-to-peer WebRTC. No server infrastructure to maintain; peers discover each other via public Nostr relay nodes.

1. In Team Sync, enter your display name and role, pick a color.
2. Select Internet / P2P mode (default).
3. Enter or generate a 6-character session code and share it with teammates (QR code button or copy).
4. Tap Join Session. Teammates enter the same code.

Team Sync — LAN Hub

For use when all devices are on the same WiFi network — ideal for incident command posts and field ops with a local hotspot. Run relay.mjs on any Node.js device on the network:

node bridge/relay.mjs [port]
# Default port: 8080
# Example output:
#   URL:  ws://192.168.1.45:8080

In Team Sync, switch to Advanced → LAN Hub transport and enter ws://<relay-ip>:8080.

Bonus: relay.mjs automatically joins the ATAK CoT multicast group (239.2.3.1:6969). If soRD or any ATAK-compatible device is broadcasting detections on the same network, they flow to all connected ZYRNTOPO clients with no extra configuration.

Team Sync — Reticulum & LXMF

Reticulum is a cryptographic mesh networking stack supporting LoRa radios, WiFi, TCP/IP, and more. ZYRNTOPO bridges Reticulum to its WebSocket protocol via reticulum_bridge.py, and includes full LXMF support so you can exchange messages with Sideband and other LXMF-compatible apps.

pip install --user --break-system-packages rns lxmf websockets msgpack
python3 bridge/reticulum_bridge.py --port 4242

The bridge creates a persistent identity at ~/.zyrntopo/bridge.identity and announces it on the Reticulum mesh. In Team Sync, use Advanced → Reticulum transport and enter the bridge's WebSocket URL (default ws://localhost:4242, or its LAN IP).

LXMF address — your mesh identity

Once connected, the Team Sync drawer shows an LXMF Mesh Devices section with:

• Your LXMF address — a 32-character hex string, with Copy / Share / Announce / Refresh buttons
• Add a Device — paste another address (from a teammate or a Sideband contact) and tap Connect; the bridge requests a path on the mesh and registers the device as a known peer
• Connected Devices — every peer ever announced or added is listed with display name, online status (green dot), and last-seen time

Display names from Sideband peers are decoded from the announce app_data field (msgpack [name, stamp_cost] for LXMF ≥ 0.5, or legacy UTF-8). Bidirectional messaging works: when you send an LXMF message, the bridge picks DIRECT delivery and registers delivered/failed callbacks so you see status in the UI.

Over LoRa (e.g., RNode hardware), expect latency of 3–30 seconds — ideal for position sharing where timeliness is less critical than coverage.

Team Sync — Drone Telemetry (MAVLink)

Connect any MAVLink-compatible drone autopilot to ZYRNTOPO via WebSocket or, in compatible desktop browsers, directly over USB/serial. The app parses both MAVLink v1 and v2 binary frames and JSON bridges.

Supported messages

• GLOBAL_POSITION_INT (msgid 33) — lat/lon/alt/heading → drone marker on map
• HEARTBEAT (msgid 0) — armed status
• SYS_STATUS (msgid 1) — battery percentage

Compatible bridges

Wired MAVLink notes

• Desktop web: Chrome/Edge can use Web Serial. Plug in a USB-C/OTG serial adapter or telemetry radio, choose the baud rate (commonly 57600, 115200, or 921600), and tap Connect USB / Serial.
• Android app: the APK includes a native USB serial bridge for common FTDI, CP210x, CH340/CH341, PL2303, and CDC/ACM adapters. Plug in with USB-C/OTG, grant Android's USB permission prompt, leave the selector on Auto-detect port / baud, and tap Connect USB / Serial. ZYRNTOPO scans supported adapters across common MAVLink baud rates; manual baud selection remains available for known hardware.
• Flight controller ports: ArduPilot/PX4 telemetry ports must be configured for MAVLink output at the same baud rate as the adapter.

In Team Sync, expand Drone Telemetry (MAVLink), enter the WebSocket URL or use Connect USB / Serial with auto-detect or a manual baud rate. The drone appears on the map as a rotating 4-arm icon. The tooltip shows altitude, armed state, and battery level.

Team Sync — ATAK CoT / soRD Detections

ZYRNTOPO talks ATAK Cursor on Target (CoT) over UDP multicast both ways. Your team members appear on any ATAK device on the same LAN, and inbound detections from ATAK or the soRD SAR drone platform appear on your map as color-coded markers in real time.

Bidirectional behavior (since v0.2.4)

• Outbound: when ZYRNTOPO is connected to atak_bridge.py, every GPS update is converted to a CoT 2.0 PLI event of type a-f-G-U-C-I (friendly · ground · unit · civilian · individual) and broadcast to 239.2.3.1:6969. Each peer gets a stable UID (ZYRN.<peerId>) so ATAK updates the same marker rather than spawning new ones, with a 60-second stale attribute so dropped peers auto-clear.
• Inbound: incoming CoT events are parsed for position, callsign, remarks, thermal score (Thermal: 0.XX), ArcFace score (ArcFace: 0.XX), composite confidence (Conf: XX%), CoT type, color argb, and the original stale timestamp. All scores are displayed on the marker label and detection list. A sweeper auto-removes detections after their stale time elapses (default 120 s), matching ATAK's own behavior.

GeoChat & markers (NEW in 0.5.0)

• GeoChat bridging (both ways): messages you send in Team Chat are emitted as ATAK GeoChat (b-t-f) CoT, so they land in ATAK's chat window; inbound ATAK GeoChat appears in ZYRNTOPO chat tagged (ATAK). Works even in an ATAK-only session with no P2P/LAN room. Echo of your own messages is suppressed via a BAO.F.ZYRN. source tag.
• Affiliation classification: inbound events now carry an affiliation (friend / hostile / neutral / unknown) derived from the CoT type, so friendly units, neutral contacts and placed markers — not just hostile detections — are distinguished on the map.
• Outbound markers: the bridge accepts cot_marker frames and emits them as CoT marker events, so a ZYRNTOPO-placed point can be pushed to ATAK.
• TAK Protocol "Mesh SA" framing: the bridge unwraps the 0xbf TAK Protocol header. Version 0 (CoT XML) is decoded; version 1 (protobuf) is detected and skipped with a one-time notice — set ATAK to "CoT XML" output, or route protobuf mesh through a TAK server.

Detection confidence colors

• Red circle — High confidence ≥85% hostile (a-h-*) — auto-alert
• Orange circle — Review queue 60–85% hostile — manual verification needed
• Friendly circle — Friendly CoT type (a-f-*) — PLI / teammate position

Automatic connection

The app silently tries ws://localhost:4243 at startup; if the bridge is running on the same machine (or you enter its LAN address), it connects automatically and your team starts publishing CoT.

Manual setup

pip install --user --break-system-packages websockets
python3 bridge/atak_bridge.py --ws-port 4243 --mcast-group 239.2.3.1

In Team Sync, expand ATAK CoT Detections (soRD) and enter ws://<bridge-ip>:4243.

If you're using the LAN relay (relay.mjs) instead, CoT detections flow automatically as before — but outbound CoT requires atak_bridge.py.

Wired soRD / ATAK notes

• If the cable/adapters create a network interface (USB Ethernet, USB tethering, or a radio gateway with IP), keep using atak_bridge.py and enter the bridge address in ZYRN.
• If the private soRD stack emits CoT XML over raw serial, the Android APK can read it directly through ATAK detections (soRD) → Connect USB / Serial. Auto-detect scans supported adapters and common baud rates until valid CoT XML is seen; manual baud selection remains available.
• If the serial source uses TAK protobuf or a proprietary framing format, route it through a small adapter that emits standard CoT XML first.
• ZYRNTOPO does not need soRD internals. It only needs the resulting ATAK/CoT position, callsign, score, and remarks fields.

soRD platform overview (v5)

soRD is a compact SAR drone system. The v5 ground station adds a multimodal detection pipeline and per-mission folder management:

• AMG8833 thermal sensor → ESP32-S2 DAC → 5.8 GHz VTX video transmitter
• ROTG02 USB capture → YOLOv5n CPU inference → ArcFace identity verification
• Composite score (Conf: XX%), thermal score (Thermal: 0.XX), and ArcFace score (ArcFace: 0.XX) are all embedded in CoT remarks and displayed separately on ZYRNTOPO markers
• Scores ≥0.85 trigger automatic ATAK CoT broadcasts to 239.2.3.1:6969 with a 120 s stale window
• Scores 0.6–0.85 enter an operator review queue (also broadcast as CoT with lower score)
• Per-mission folders: detections, crops, and thermal frames are saved under a timestamped mission directory; the operator review dialog lets you accept/reject each detection
• WiFi latency ~260 ms; LoRa relay latency 3–30 s

Team Chat

Chat is available in any Team Sync session. Tap the chat bubble icon to open the chat panel. The input bar sits at the top of the panel so it remains visible when the keyboard is open on mobile.

• Text messages — sent to all peers in the session
• Voice messages — tap-and-hold the microphone button to record; release to send; tap to cancel
• Chat history is stored locally for the current session
• Unread message badge on the chat button
• ATAK GeoChat bridge (NEW in 0.5.0) — when the ATAK bridge is connected, text chat is mirrored to/from ATAK's GeoChat, so ZYRNTOPO and ATAK users share one conversation.

SAR — Operational Periods

Open More → Operational Periods. Each period represents a planning cycle (typically 12 or 24 hours) in a search operation. Assign map objects to periods to keep your map organized and filterable.

• Name, start date/time, and status (active/inactive)
• Toggle visibility of all objects in a period with one switch
• Export a period's objects as GeoJSON for incident documentation

SAR — Resources & Roles

Open More → Team Members. Each member has:

• Name and role (team leader, member, medical, air, K9, logistics, etc.)
• Contact info — radio channel, phone, callsign
• Assignment — linked to an operational period

Import/export team rosters as JSON or CSV for briefings and ICS documentation.

SAR — Gear / Pack List

Open More → Gear. Build a complete inventory of field equipment with:

• Item name, category, quantity, weight
• Total pack weight summary
• Category grouping (shelter, navigation, medical, comms, etc.)
• Export as JSON or CSV for logistics planning
• Import from a previous operation's export

SAR — Clue & Find Logging

Any marker can be flagged as a clue or find using its SAR properties panel:

• Type: Physical clue, track, trail, scent, shelter, victim found, deceased
• Description: Detailed notes
• Time found: Timestamp recorded automatically
• Assigned to OP: Links to an operational period
• Photo: Attach a camera photo directly to the clue marker

All clue markers are also exported in GeoJSON with full SAR metadata intact.

Import & Export — GeoJSON

GeoJSON is ZYRNTOPO's primary exchange format. All map objects are serialized to standard GeoJSON with ZYRNTOPO-specific properties in the properties object.

Export

Open More → Export → GeoJSON. Choose to export all objects, a specific folder, or a specific operational period. The file saves to the device's Downloads folder or triggers a browser download.

Import

Open More → Import and select a .geojson or .json file. Objects are merged into the current map — existing objects with the same ID are updated; new IDs are created. Drag-and-drop import is supported in the web app.

Import & Export — KML / KMZ

Export to KML for use in Google Earth, CalTopo, or other GIS tools. KMZ (zipped KML) is also supported for import. Exported KML includes point placemarks, line strings, and polygon features with names and color styling.

Import & Export — GPX

GPX export is ideal for loading routes onto dedicated GPS devices (Garmin, Suunto, etc.). Waypoints export as <wpt> elements; recorded tracks export as <trk>. GPX import reads both <wpt> and <trk>/<rte> elements.

Import & Export — CSV

CSV export writes all marker coordinates and properties to a spreadsheet-compatible file — useful for importing into ArcGIS, QGIS, or sharing data with agencies that use spreadsheet-based tools. Team member rosters and gear lists also export/import as CSV.

Print to PDF

Open More → Print. The current map viewport is rendered to a printable layout with:

• All visible map objects (markers, lines, polygons)
• Map title (from Settings → Map Title)
• Coordinate grid overlay (optional)
• Scale bar
• Date/time stamp

On Android, the system print dialog opens allowing PDF save or physical printing. In the web app, the browser print dialog is used — choose Save as PDF.

Bridge Tools — LAN Relay (relay.mjs)

The LAN relay is a lightweight Node.js WebSocket server for offline LAN-only Team Sync. It requires no internet connection — just Node.js installed on any device on the network.

# Start on default port 8080
node bridge/relay.mjs

# Custom port
node bridge/relay.mjs 9000

The relay prints its WebSocket URLs on startup. Share one with teammates for the LAN Hub URL field in Team Sync. The relay also automatically listens on UDP multicast 239.2.3.1:6969 for ATAK CoT detection events and forwards them to all connected clients — no separate bridge needed.

Bridge Tools — Reticulum / LXMF Bridge (reticulum_bridge.py)

Bridges the Reticulum mesh network to ZYRNTOPO's WebSocket protocol with full LXMF identity, addressing, and messaging — Sideband-compatible.

pip install --user --break-system-packages rns lxmf websockets msgpack
python3 bridge/reticulum_bridge.py --port 4242 [--channel zyrntopo]

Features:

• Persistent identity stored at ~/.zyrntopo/bridge.identity — destination hash stays consistent across restarts
• Auto re-announce every 60 s for both the ZYRNTOPO destination and the LXMF delivery destination
• RNS announce handler with aspect_filter='lxmf.delivery' picks up Sideband / other ZYRNTOPO bridges automatically and forwards them as lxmf_announce frames
• Persistent peer cache at ~/.zyrntopo/lxmf_peers.json — known devices survive restarts
• Display-name decoding: msgpack [name, stamp_cost] (LXMF ≥ 0.5) with UTF-8 fallback for legacy clients
• LXMF delivery callbacks → UI delivered/failed status

WebSocket protocol

The bridge exposes a JSON WS protocol on ws://0.0.0.0:4242 (configurable):

Bridge Tools — ATAK CoT Bridge (atak_bridge.py)

A bidirectional CoT ↔ ZYRNTOPO bridge. Receives ATAK / soRD detections from UDP multicast and forwards them as JSON to the WS client; in the other direction, it accepts position frames from ZYRNTOPO over WS and re-broadcasts them as proper CoT XML so any ATAK device on the LAN sees your team.

pip install --user --break-system-packages websockets
python3 bridge/atak_bridge.py [--ws-port 4243] [--mcast-group 239.2.3.1] [--mcast-port 6969]

ZYRNTOPO automatically tries ws://localhost:4243 at startup, so if the bridge is running on the same machine it connects automatically.

Outbound CoT (ZYRNTOPO → ATAK)

Position frames received from ZYRNTOPO — in either {t:'pos', d:{name, lat, lng, …}} or {type:'cot_pos', …} shape — are converted to a CoT 2.0 PLI event and sent to 239.2.3.1:6969:

<event version="2.0" uid="ZYRN.<peerId>" type="a-f-G-U-C-I"
       how="m-g" time="..." start="..." stale="+60s (peers)">
  <point lat="..." lon="..." hae="..." ce="9999999" le="9999999"/>
  <detail>
    <contact callsign="..."/>
    <__group name="Cyan" role="Team Member"/>
    <precisionlocation altsrc="GPS" geopointsrc="GPS"/>
    <remarks>ZYRNTOPO</remarks>
  </detail>
</event>

The stable per-peer UID prevents marker duplication on the ATAK side; the 60-second stale means peers auto-clear when they go offline. Echoes of our own outbound frames are filtered on the inbound listener.

Inbound CoT (ATAK → ZYRNTOPO)

Incoming CoT XML is parsed for:

• Event UID (prepended with soRD-) — stable across updates
• Position from <point lat lon hae />
• Callsign from <detail><contact callsign="…"/>
• Remarks text — full string forwarded to client
• Composite confidence from Conf: XX% in remarks
• thermal_score — parsed from Thermal: 0.XX in remarks
• rgb_score — parsed from ArcFace: 0.XX in remarks
• color — from <color argb="…"/> element
• cot_type, cot_time, stale, how — passed through to the client

The client honors the stale timestamp (soRD v5 detections use a 120 s window) and a sweeper auto-removes expired markers every 5 seconds. Marker icons use cot_type to set color: red/orange for hostile (a-h-*), blue for friendly (a-f-*).

Settings — Coordinate Formats

Open More → Settings → Coordinate Format and choose from DD, DMS, DDM, UTM, or MGRS. This affects all coordinate displays: status bar, point info panel, marker info, and CSV export.

Settings — Units & Display

• Distance — Imperial (miles, feet) or Metric (km, meters)
• Area — Acres or Hectares
• Elevation — Feet or Meters
• Speed — mph or km/h
• Map title — appears on PDF prints
• Default base layer — layer shown on first load (default: OpenFreeMap Liberty)
• Terrain exaggeration — 3D mesh vertical scale (1.0–3.0×)

Accessibility (NEW in 0.9.0)

• Glove mode — enlarges buttons and touch targets across the app for use with gloves or in motion.
• Colour-blind-safe palette — switches the computed terrain layers (slope angle / aspect) to a colour-blind-friendly ramp; legends update to match.
• Night mode — a separate 3-state map dimming / red-light cycle (see Night Mode).

Map display toggles (NEW in 0.9.1)

Declutter the map by hiding chrome you don't need — each is an independent on/off switch under Settings → Map display:

• Coordinates readout, live weather widget, scale bar, the on-map control buttons, and the Tools button can each be shown or hidden.

Automatic persistence

The following state is saved automatically and restored on every launch — no manual action required:

• Base layer selection — the active basemap (raster, vector, or imported archive) is remembered; the same layer loads on the next launch.
• Map position & zoom — the last map center and zoom level are saved (debounced 1.5 s after panning stops) and restored on launch.
• Hillshade opacity — the global relief opacity slider value is preserved across sessions.

Settings — Permissions

On first launch all permissions are requested via native dialogs. If you denied a permission and need to re-enable it:

• Android: Settings → Apps → ZYRNTOPO → Permissions
• Web / Chrome: Click the lock icon in the address bar → Permissions

Permissions used by the app:

Platforms — Android

Built with Capacitor 6. Minimum Android 7.0 (API 24). Tested on Android 13–15.

• Install via Google Play
• Current sideload build: Download Beta APK 1.10.7 (Build 160)
• Location is used in the foreground only — GPS tracking runs while the app is open (no background location)
• The keyboard uses adjustResize so the chat input bar stays visible when typing
• Production build hardening: app backup disabled and mixed content disabled; cleartext is intentionally allowed for operator-managed local ws:// field bridges such as LAN, Reticulum, MAVLink, and ATAK integrations
• Release builds are signed; debug builds use .debug app ID suffix

Platforms — Web / PWA

The web version runs in any modern browser (Chrome, Firefox, Edge, Safari) at app.zyrntopo.com. Install as a PWA for an app-like experience:

• Chrome / Edge: Click the install icon in the address bar
• Firefox: Menu → Install as App (Firefox 128+)
• iOS Safari: Share → Add to Home Screen

The PWA uses a Service Worker for offline-first operation — all app code and viewed tiles are cached automatically. No separate install or download manager needed.