5. Offline Maps

Offline Maps

Language: English. Chinese version: 5. Offline Maps (中文)

Offline maps are core to TAK and offline operation. They give position, teammates, tracks, markers, and assembly points a local shared reference when there is no Internet.

But the map model here is not the same as a phone app that fetches tiles online and changes style at will. The current implementation favors a controlled, predictable tile system that runs well on constrained hardware for long periods.

What Is Supported And What Is Not

The device-side map renderer reads directory tiles, meaning a standard z/x/y folder structure. The current project behavior is explicit about the following:

• offline tiles are read from SD card
• OSM, Terrain, and Satellite base layers are supported
• contour overlay is supported
• zoom levels z=0..18 are supported
• mbtiles is not supported as a device-side map database

That last point matters because many map problems start with users preparing mbtiles or another packaged format and assuming the device will adapt automatically.

Directory Structure

Required base-map directories

Prepare at least one base source:

/
└── maps
    └── base
        ├── osm
        │   └── {z}/{x}/{y}.png
        ├── terrain
        │   └── {z}/{x}/{y}.png
        └── satellite
            └── {z}/{x}/{y}.jpg

Optional contour directories

/
└── maps
    └── contour
        ├── major-500
        │   └── {z}/{x}/{y}.png
        ├── major-200
        │   └── {z}/{x}/{y}.png
        ├── major-100
        │   └── {z}/{x}/{y}.png
        ├── major-50
        │   └── {z}/{x}/{y}.png
        └── major-25
            └── {z}/{x}/{y}.png

Related route and track directories

/
├── routes
│   └── *.kml
└── trackers
    └── *.gpx / *.csv / *.bin

• routes is used for route-mode KML loading
• trackers is used for track file reading and display

What Each Map Layer Is For

OSM

This is usually the best first layer to validate. The directory structure and suffixes are straightforward, so it is the easiest way to confirm the SD card, tile path, and map-page loading behavior.

Terrain

Terrain is more useful when landform matters. In mountain and backcountry use, it is often a better fit for Trail Mate’s scenario than a road-focused layer, especially when used together with contours.

Satellite

Satellite imagery is good for checking the actual surface appearance of the environment, but it typically costs more storage and is more sensitive to source and suffix mismatches. The device currently expects .jpg under the satellite path, not .png.

Contour

Contours are not a separate base map. They are an overlay layer. Their purpose is not to make the map look more advanced, but to provide direct terrain-shape information on a limited screen.

The current contour profile mapping by zoom level is:

• z <= 7: no contour draw
• z = 8: major-500
• z = 9: major-200
• z = 10: major-500
• z = 11: major-200
• z = 12..14: major-100
• z = 15..16: major-50
• z >= 17: major-25

Why The Map System Looks Like This

Trail Mate’s choice of directory tiles, north-up orientation, no rotation, and discrete zoom levels comes from three practical reasons.

First, the device map is not trying to replace a phone navigation app. It only needs to provide a stable, readable field reference on constrained hardware. More rotation, more animation, and more dynamic behavior increase both render cost and cognitive load.

Second, map resources in this project are real field input data, not decorative assets. They should be prepared, copied, checked, and debugged explicitly rather than hidden inside an opaque cache.

Third, offline maps and the companion desktop tool belong to one workflow. Trail Mate Center can handle caching, area selection, and export, while the device focuses on reading and rendering the agreed structure. That separation keeps the device runtime simpler and troubleshooting more predictable.

A Practical Map Preparation Flow

A stable workflow usually looks like this:

1. define the real area of operation first
2. prepare a minimal usable base map, usually OSM
3. verify on the device that path and layer loading work
4. expand with terrain, satellite, and contour layers only after the basics work
5. if you already have a route, place the KML file under /routes

This order makes it easier to tell whether a failure is caused by the device, the path layout, the suffixes, or the data itself.

The Role Of Trail Mate Center

Trail Mate Center is the companion desktop tool, not a separate unrelated project. Based on the current companion-repository README, it handles map-related tasks such as:

• viewing and selecting map regions on desktop
• caching OSM, Terrain, and Satellite layers
• building and filling offline cache regions
• exporting to USB media or SD card
• importing KML tracks and preparing route-based caches

Operationally, Center is the map preparation and troubleshooting workbench, while the handheld is the field terminal that consumes the prepared resources.

How To Verify Maps On The Device

The most effective first test is not filling the whole SD card. It is preparing a tiny tile block and checking it directly.

For example, a minimal OSM test block:

/
└── maps
    └── base
        └── osm
            └── 12
                └── 3340
                    ├── 1788.png
                    ├── 1789.png
                    └── 1790.png

Then on the device:

1. open the map page
2. select the OSM layer
3. move to the corresponding area
4. confirm that the tiles really render instead of reporting a missing layer

That is a much cleaner validation method than loading tens of gigabytes before the first test.

Common Display Problems

The map page opens, but the base map is blank

Check the directory and suffix before suspecting GPS. The most common causes are:

• the folder hierarchy is not standard z/x/y
• satellite tiles were stored as .png
• the folders exist but contain no real tile files
• the chosen device layer does not match the prepared layer

GPS works, but there is still no map

That usually means the GPS path is fine and the map resource path is not. Positioning and tile rendering are separate chains.

The route or track list is empty

Check the folder:

• KML files belong under /routes
• track files belong under /trackers

If the folders do not exist, the UI simply shows that no route or track input is available.

Why not mbtiles

Because the device-side implementation is currently designed around directory tiles. This is a project boundary, not a hidden toggle that is merely off by default.

Practical Advice On Zoom Levels

The current documentation confirms support for z=0..18, but it does not claim that one universal zoom strategy fits all use cases. That is reasonable because different activities trade coverage, detail, and storage very differently.

A better approach is:

• prepare the zoom levels you actually need for the real area
• validate loading speed and storage cost
• then decide whether higher resolution or more layers are worth adding

Detailed “best zoom level by activity type” guidance is still worth adding later, but should not be invented as a fixed rule yet.

Information Still Worth Expanding

Useful future expansions include:

• an illustrated Trail Mate Center export-to-SD workflow
• map-source and data-license boundaries
• tile-level recommendations for different activity types
• more detailed map-making toolchain examples

For now, this page focuses on the exact directory, format, and loading boundaries the device actually expects.