Bulk Downloading

FMTC provides the ability to bulk download areas of maps in one-shot, known as 'regions'. There are multiple different types/shapes of regions available.

Before using FMTC, especially to bulk download or import/export, ensure you comply with the appropriate restrictions and terms of service set by your tile server. Failure to do so may lead to any punishment, at the tile server's discretion.

This library and/or the creator(s) are not responsible for any violations you make using this package.

For example, OpenStreetMap's tile server forbids bulk downloading: https://operations.osmfoundation.org/policies/tiles. And Mapbox has restrictions on importing/exporting from outside of the user's own device.

For testing purposes, check out the testing tile server included in the FMTC project: Testing Tile Server.

Downloading is extremely efficient and fast, and uses multiple threads and isolates to achieve write speeds of hundreds of tiles per second (if the network/server speed allows). After downloading, no extra setup is needed to use them in a map (other than the usual Integrating With A Map).

Walkthrough

Before you can get started, make sure you've initialised FMTC & created one or more Stores!

1

Define a region

A region represents a geographical area only, not any of the other information required to start a download.

All types of region inherit from BaseRegion.

Rectangle

RectangleRegions are defined by a LatLngBounds: two opposite LatLngs.

final region = RectangleRegion(
    LatLngBounds(LatLng(0, 0), LatLng(1, 1)),
);

Circle

(Poly)Line

Custom Polygon

Multi

BaseRegion class - flutter_map_tile_caching library - Dart APIpub.dev

It is also possible to reconstruct the region from a RecoveredRegion: RecoveredRegion.

2

Add information to make the region downloadable

BaseRegions must be converted to DownloadableRegions before they can be used to download tiles.

These contain the original BaseRegion, but also some other information necessary for downloading, such as zoom levels and URL templates.

final downloadableRegion = region.toDownloadable(
    minZoom: 1,
    maxZoom: 18,
    options: TileLayer(
        urlTemplate: '<your tile server>',
        userAgentPackageName: 'com.example.app',
    ),
),

toDownloadable method - BaseRegion class - flutter_map_tile_caching library - Dart APIpub.dev

The TileLayer passed to the options parameter must include both a urlTemplate (or WMS configuration) and a userAgentPackageName, unless it is only being used to check the number of tiles in the region.

3

(Optional) Count the number of tiles in the region

Before continuing to downloading the region, use countTiles() to count the number of tiles it will attempt to download. This is accessible through FMTCStore().download.

The method takes the DownloadableRegion generated above, and will return an int number of tiles. For larger regions, this may take a few seconds.

This figure will not take into account any skipped sea tiles or skipped existing tiles, as those are handled at the time of download.

4

Configure and start the download

To start the download, use the startForeground method on the existing store you wish to download to:

final (:downloadProgress, :tileEvents) =
  const FMTCStore('mapStore').download.startForeground(
    ...
  );

There are many options available to customize the download, which are described fully in the API reference:

startForeground method - StoreDownload class - flutter_map_tile_caching library - Dart APIpub.dev

The download starts as soon as the method is called; it does not wait for listeners.

5

Monitor the download outputs

Listening to the output streams of the download is something most apps will want to do, to display information to the user (unless operating in a headless mode or in the background).

There are two output streams returned as a record. One stream emits events that contain information about the download as a whole, whilst the other stream independently emits an event after the fetch/download of each tile in the region is attempted. See the API documentation for information on the exact emission frequencies of each stream. These are returned separately as the first stream emits events more frequently than the second, and this prevents tile events from needed to be repeated*.

DownloadProgress class - flutter_map_tile_caching library - Dart APIpub.dev

TileEvent class - flutter_map_tile_caching library - Dart APIpub.dev

An emitted TileEvent may refer to a tile for which an event has been emitted previously.

See the API documentation for more information.

6

(Optional) Control the download

Listening, pausing, resuming, or cancelling subscriptions to the output streams will not start, pause, resume, or cancel the download. It will only change whether the download emits updates.

Instead, there are methods available to control the download itself.

Pause/Resume

If your user needs to temporarily pause the download, with the ability to resume it at some point later (within the same app session), use pause and resume.

Pausing does not interrupt any tiles that are being downloaded when pause is invoked. Instead, the download will pause after the tile has been downloaded. pause's returned Future completes when the download has actually paused (or after resume is called whilst still pausing).

Pausing also does not cause the buffer to be flushed (if buffering is in use).

If listening to the DownloadProgress stream, an event will be emitted when pausing and resuming.

Use isPaused to check whether the download is currently paused.

Cancel

If your user needs to stop the download entirely, use cancel.

Cancelling does not interrupt any tiles that are being downloaded when cancel is invoked. The returned future completes when the download has stopped and been cleaned-up.

Any buffered tiles are written to the store before the future returned by cancel is completed.

It is safe to use cancel after pause without resumeing first.

Examples