Support for Offline Maps

[stevecassidy]

Support for Offline Maps

JIRA Ticket

BSS-143
BSS-630

Description

We need to support offline data collection with maps. This PR adds support for pre-loading
and using map tiles to display maps rather than requiring an online connection.

Proposed Changes

• Add a custom tile source that can cache tiles once downloaded
• Add methods to download a given region of the map for offline use
• Add methods to monitor and manage the storage space used by maps
• Add a user interface to view stored maps and select regions to download

This has been a journey, and I don't think it's finished. Current state is close to being usable but
will likely need more work before it is field ready.

OSM as a tile source does not allow bulk downloads so we switch to a commercial provider (MapTiler).

How to Test

Configuration needed, ask @stevecassidy for a maptiler key or make your own free account.

# Set to one of 'osm', 'maptiler', defaults to 'osm'
VITE_MAP_SOURCE=maptiler
# Optional key for the map tile service, eg. maptiler
VITE_MAP_SOURCE_KEY=<your api key>
# Set to true to enable offline map downloads
# note that some services, notably OSM, don't allow map tile downloads
VITE_OFFLINE_MAPS=true

In the app, go to the hamburger menu and select "Offline Maps" This provides the interface
to download regions for offline use. Pan/Zoom the map to a region of interest and click
Download. Note the Estimate Size button, suggest you test with very small areas so the
download isn't too big.

Downloaded regions are listed below the form and will update as tiles are downloaded.
You should be able to leave the page and return and see the download continue.

Click on "Show Download Area" for a region to jump to it.

Go offline (browser tools > Network) and you should still be able to zoom to your downloaded
area and see the map up to a max zoom level of 20.

Now go to a survey and view a map field (it will need to be centered close to the map you downloaded). You should
be able to browse the map that was downloaded while offline.

Checklist

• I have confirmed all commits have been signed.
• I have added JSDoc style comments to any new functions or classes.
• Relevant documentation such as READMEs, guides, and class comments are updated.

[PeterBaker0]

As discussed, it seems this needs more thought. I did manage to accelerate the download initially using a pool of promises which work concurrently, but the API throttles your downloads after around 10-20MB.

Even after downloading the region, the UX is a bit tricky and would need more thought since you can end up in positions where you can't find your way to a downloaded area, and it's unclear which regions are/aren't downloaded. I understand this was a technical PoC so not knocking that just noting it's not ready for the big time yet.

I think we'll need to consider a vector based approach, and maybe use some sort of pre-packaged single files for regions rather than spamming an API for thousands of tiles. Then have an intelligent handler in the form which tries to do a nice job of selecting which downloaded region the user is closest to/in when offline, then use online tiles when online.