This article is a somewhat technical overview of how maps and map downloads work in Gaia GPS. Gaia GPS supports viewing multiple map types, both online and offline.
What type of maps are we talking about?
Maps in Gaia GPS come from a number of providers, and we also make some maps in-house.
Most of the maps in Gaia GPS are "raster" maps cut into "tiles." Raster means the map is made of pre-made images, often different images for different zoom levels. Tiled means the map is cut into many small squares (for performance reasons).
Map Sources
There are several pieces of information that go into a defining a map source:
- Minimum and maximum zoom levels that the map provides
- A bounding box for the region the map covers (defined by the Northeast and Southwest corners of a box that contains the entire map)
- A URL where the tiles live on the internet
- A name and description
- A unique identifier used in the App
How Map Downloads are Stored
Maps in Gaia GPS are stored in two different places in the app: the temporary cache folder and the Download Folder. Each Map Source has its own download folder and temporary cache folder. It's important that each Map Source has exactly one download folder. Multiple copies of the same tile are never stored in the download folder. As you browse the map, Gaia first checks if a tile is available in the download folder, then the temporary cache. If the tile is not available in either of those places, Gaia requests it from the internet. If the tile is successfully fetched from the internet it is stored in the temporary cache.
The temporary cache can grow quite large when panning around the map. The cache can be manually cleared from the app's Settings menu if you are running low on storage. When the app is launched it checks if the temporary cache contains more than 100,000 tiles. If it does, the 10,000 least recently used tiles are deleted.
Map Downloads
Gaia GPS supports downloading maps for offline use. Areas of the map that are frequently browsed will likely be in the temporary cache, but in order to guarantee that maps will be available offline they should be downloaded.
Each map download record contains several pieces of information:
- The map source the download refers to* The minimum zoom level to be downloaded* The maximum zoom level to be downloaded* The northeast and southwest corners of the region to be downloaded
- The number of tiles remaining to download.
- A name, date and description for the download.
Maps are downloaded by selecting a rectangular region on the map, and choosing one or more map sources to download. When the download is saved, a Map Download record is created for each Map Source selected. The Map Download record is then sent to the Map Downloader. The downloader calculates a list of all tiles within the selected region and iterates through them. If a tile does not already exists in the Download Folder, it is downloaded. The number of tiles remaining to be download is updated as this happens. If you download a Map Source for a region, then select the same Map Source and region to download again. No tiles will actually be downloaded, because they are already all stored on the device, but the app will still have to go through the list of all tiles for the map and check if they have been downloaded.
When a Map Download is deleted a similar process happens as when it was downloaded. A list of tiles is generated, then each tile on the list is checked to see if any other Map Downloads need it, and if they don’t it is deleted. If you have two downloads from the same Map Source and region, and delete one of them, no tiles will actually be deleted. When the remaining download is deleted all the tiles will be deleted.
Downloading Maps along a Track
In addition to downloading rectangular regions, Gaia GPS can also download all the maps needed for a track/route. This is similar to downloading maps for a rectangular region, except that instead of calculating the list of tiles based on a rectangular region when the map is downloaded or deleted, a list of tiles is calculated once, and stored on disk. The list is calculated going along the track and calculating what map tile each point is on, then that tile, and one tile in each direction is added to the list.
Syncing maps to gaiagps.com
Map Sources and Map Downloads can both be synced to gaiagps.com. When a Map Download is synced to gaiagps.com only the Metadata, location and zoom levels are sent, not the actual map tiles. When the app receives a Map Download record from syncing, the number of tiles downloaded is set to 0. This can be confusing, because it could be that all of the tiles are already downloaded because of another Map Download on the device, but the map will show as being 0% downloaded.
To correct this situation select “Resume Download” from the map details page. This will initiate the the Map Download procedure described above, but will not download tiles that are already on the device.
Auto-Resuming downloads
One of the options in the Map Downloads section of the Settings menu is “Auto-Resume”. With this enabled, the app will check for incomplete downloads at launch, and resume them. Disable auto-resume if you don't want the same maps saved to all your devices. When auto-resume is disabled, you have the option to manually choose which maps are downloaded to the device.
When using multiple devices this can be very handy. For example, you have an iPhone you use in the field for viewing maps and recording track and an iPad that you only ever use at home to view your tracks, you want the maps to be downloaded on the iPhone, but it would be a waste of space to have them all saved on the iPad.
Auto-resume is a per-device function. This setting does not carry over from one device to another.
Data Integrity Check
One of the more mysterious options in the Settings menu is the Data Integrity Check. This is a periodic check that is run to ensure that map downloads are not missing any tiles. It is a similar process to downloading a map. A list of tiles is generated for each map source, and each tile is checked to verify that it actually exists on disk. If any tiles are missing the download is marked as incomplete, and missing tiles will be downloaded if Auto-Resume is enabled.
This is mainly intended to protect against unexpected changes in the operations system, which may happen between releases of Gaia GPS, and also as an extra check when we send out updates.