You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
QGroundControl stores downloaded map tiles in an SQLite database located under the platform cache directory (for example `~/.cache/QGroundControl/QGCMapCache` on Linux). The file is named `qgcMapCache.db` and is created automatically the first time the QtLocation plugin runs.
4
+
5
+
## Schema version
6
+
7
+
The cache schema is versioned through `PRAGMA user_version`. QGroundControl v4.4 introduced schema version **2** (`kCurrentSchemaVersion` in `QGCTileCacheWorker`). On startup we verify the on-disk version and automatically rebuild the cache if it is missing or outdated. If you change the schema, update `kCurrentSchemaVersion`, describe the migration path in this document, and add a release note so that integrators know the cache will be rebuilt.
8
+
9
+
## Migration behaviour
10
+
11
+
* If the schema is missing or corrupted, `QGCTileCacheWorker::_verifyDatabaseVersion()` deletes the database and creates a fresh one.
12
+
* When importing a cache file, `_checkDatabaseVersion()` ensures the version matches `kCurrentSchemaVersion` and surfaces a user-facing error if it does not.
13
+
* Default tile sets are recreated on demand and always use map ID `UrlFactory::defaultSetMapId()`.
14
+
15
+
## Disabling caching
16
+
17
+
Two separate switches control caching:
18
+
19
+
*`setCachingPaused(true/false)` is used internally to stop saving tiles while maintenance tasks such as deletes and resets are in progress. Downloads are paused and resumed automatically.
20
+
*`MapsSettings.disableDefaultCache` exposes a user-facing “Default Cache” toggle. When disabled, tiles fetched during normal browsing are not persisted, but manually created offline sets continue to work.
21
+
22
+
When adding new features that manipulate the cache, prefer to go through `QGCMapEngineManager` so that pause/resume, download bookkeeping, and schema checks remain in sync.
Copy file name to clipboardExpand all lines: docs/en/qgc-user-guide/settings_view/offline_maps.md
+8Lines changed: 8 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -12,3 +12,11 @@ To create a new offline map set, click "Add new set". Which will take you to thi
12
12
From here you can name your set as well as specify the zoom levels you want to cache. Move the map to the position you want to cache and then set the zoom levels and click Download to cache the tiles.
13
13
14
14
To the left you can see previews of the min and max zoom levels you have chosen.
15
+
16
+
## Managing downloads
17
+
18
+
Each offline tile set shows live download statistics (pending, active, and error tiles) so you can see whether work is still in progress. You can pause an in-flight download, resume it later, or retry only the tiles that previously failed. Pausing keeps your place in the queue, which is especially useful when you need to temporarily disable connectivity or suspend caching from the main Map Settings page.
19
+
20
+
## Default cache toggle
21
+
22
+
The **Default Cache** switch near the top of the Offline Maps page controls whether QGroundControl stores tiles that are fetched during normal map browsing. Leave it enabled if you rely on the automatic cache for day-to-day flying, or disable it to save disk space and rely exclusively on the offline tile sets you create manually. The toggle simply affects the default/system cache—the user-defined offline sets continue to work normally.
text:qsTr("Too many tiles: %1 exceeds limit of %2").arg(QGroundControl.mapEngineManager.tileCountStr).arg(_settings ?_settings.maxTilesForDownload.valueString:"")
0 commit comments