In a one word answer: Yes.

FMTC aims to provide all the functionality you will need for advanced offline mapping in your app, and the unique features that will help set your app apart from the competition, in a way that requires little knowledge of the internals of 'flutter_map' and other caching fundamentals, and little effort from you (for most setups).

However, this doesn't mean there aren't any other options to consider! The flutter_map documentation gives a good overview of the different types of caching.

In general, there's a few reasons why I wouldn't necessarily recommend using FMTC:

• You're not planning to make use of bulk downloading or import/export functionality

• You don't need the fine grained control of stores (and their many-to-many relationship with tiles that keeps duplication minimal across them)

• You want to ship every user a standardized tileset, and you don't really need other functionality after that point

Although FMTC will still handle all these situations comfortably, other options may be better suited, and/or more lightweight.

FMTC is an all-in-one solution. It specialises in the functionalities which are difficult and time-consuming to get right (such as bulk downloading), and their integration with the essential function of browse caching, through a clean, unified API, and a clean, decluttered, and fast backend.

I am not a lawyer, and this information is to the best of my understanding only. You are urged to read the license yourself for a thorough understanding.

Permissions of this strong copyleft license are conditioned on making available complete source code of licensed works and modifications, which include larger works using a licensed work, under the same license. Copyright and license notices must be preserved. Contributors provide an express grant of patent rights.

Essentially, whilst you can use this code within commercial projects, they must not be proprietary - they incorporate this 'licensed work' so they must be available under the same license. You must distribute your source code (at least on request) (under the same GPL v3 license) to anyone who uses your program.

I learnt (and am still learning) to code with free, open-source software due to my age and lack of money, and for that reason, I believe in promoting open-source wherever possible to give equal opportunities to everybody, no matter their age, financial position, or any other characteristic. I'm not sure it's fair for commercial & proprietary applications to use software made by people for free out of generosity without giving back to the ecosystem or maintainer(s). On the other hand, I recognise that commercial businesses may want to use my projects for their own proprietary applications, and are happy to support me, and I am also trying to make a small amount of money from my projects, by donations and by selling licenses!

This page guides you through a simple, fast setup of FMTC that just enables basic browse caching, without any of the cool features that you can discover throughout the rest of this documentation.

Depend on the latest version of the package from pub.dev, then import it into the appropriate files of your project.

flutter pub add flutter_map_tile_caching

import 'package:flutter_map_tile_caching/flutter_map_tile_caching.dart';

Perform the startup procedure to allow usage of FMTC's APIs and allow FMTC to spin-up the underlying connections & systems.

import 'package:flutter/widgets.dart';
import 'package:flutter_map_tile_caching/flutter_map_tile_caching.dart';

Future<void> main() async {
    WidgetsFlutterBinding.ensureInitialized();
    
    await FMTCObjectBoxBackend().initialise(...);
    
    // ...
    
    runApp(MyApp());
}

Create a container that is capable of storing tiles, and can be used to browse cache and bulk download.

Here, we'll create one called 'mapStore', directly after initialisation. Any number of stores can be created, at any point!

    // ...
    
    await FMTCStore('mapStore').manage.create();
    
    // ...

Add FMTC's specialised TileProvider to the TileLayer, to enable browse caching, and retrieval of tiles from the specified store.

import 'package:flutter_map/flutter_map.dart';
import 'package:flutter_map_tile_caching/flutter_map_tile_caching.dart';

TileLayer(
    urlTemplate: 'https://tile.openstreetmap.org/{z}/{x}/{y}.png',
    userAgentPackageName: 'com.example.app',
    tileProvider: FMTCStore('mapStore').getTileProvider(),
    // Other parameters as normal
),

5. Wow! Look at that caching...

This package contains a full example application - prebuilt for Android and Windows by GitHub Actions - showcasing the most important features of this package and its modules.

Prebuilt Artifacts

If you can't build from source for your platform, our GitHub Actions CI system compiles the example app to artifacts for Windows and Android, which just require unzipping and installing the .exe or .apk found inside.

Build From Source

If you need to use the example app on another platform, you can build from source, using the 'example' directory of the repository.

These migration instructions will not cover every scenario, because the number of breaking changes is so high. I've done my best to organise them into categories.

Universal

// Get a store directory
final StoreDirectory oldStore = FlutterMapTileCaching.instance('storeName'); // (or `FMTC.`)

// Access the root statistics
final RootDirectory oldRoot = FlutterMapTileCaching.instance.rootDirectory; // (or `FMTC.`)
final RootStats oldRootStats = oldRoot.stats;

// Get a store
final FMTCStore newStore = FMTCStore('storeName');

// Access the root statistics
final RootStats newRootStats = FMTCRoot.stats;
// `FMTCRoot` must now be used immediately, because it is not an object instance

await FlutterMapTileCaching.initialise(
    errorHandler: (FMTCInitialisationException e) {},
);

try {
    await FMTCObjectBoxBackend().initialise();
} catch (error, stackTrace) {
    // Improved error handling
}

Bulk Downloading

Plugins

Statistics

Miscellaneous

Initialisation

Initialisation should be performed before any other FMTC or backend methods are used, and so it is usually placed just before runApp, in the main method. This shouldn't have any significant effect on application startup time.

import 'package:flutter/widgets.dart';
import 'package:flutter_map_tile_caching/flutter_map_tile_caching.dart';

Future<void> main() async {
    WidgetsFlutterBinding.ensureInitialized();   
    
    try {
        await FMTCObjectBoxBackend().initialise(...); // The default/built-in backend
    } catch (error, stackTrace) {
        // See below for error/exception handling
    }
    
    // ...
    
    runApp(MyApp());
}

Uninitialisation

It is also possible to un-initialise FMTC and the current backend. This should be rarely required, but can be performed through the uninitialise method of the backend if required. Initialisation is possible after manual uninitialisation.

Depend On

This is the recommended method of installing this package as it ensures you only receive the latest stable versions, and you can be sure pub.dev is reliable.

Just import the package as you would normally, from the command line:

If you urgently need the latest version, a specific branch, or a specific fork, you can use this method.

Import

After installing the package, import it into the necessary files in your project:

Highlights

Trusted by many

How can FMTC elevate my app to the next level?

Supporting Me

This project is wholly open source and funded by generous supporters like you! Any amount you can spare that you think FMTC deserves is hugely appriciated, and means a lot to me.

(Proprietary) Licensing

Get Help

Not quite sure about something? No problem, I'm happy to help!

Please get in touch via the correct method below for your issue, and I'll be there to help ASAP!

StoreManagement, accessed via FMTCStore().manage, allows control over the store and its contents.

final mgmt = FMTCStore('storeName').manage;

await mgmt.ready; // Check whether the store exists
await mgmt.create(); // Create the store
await mgmt.delete(); // Empty tiles from the store, and delete it
await mgmt.reset(); // Empty tiles from the store, and reset hits & misses
await mgmt.rename('newStoreName'); // Change the name of the store
await mgmt.removeTilesOlderThan(DateTime.timestamp()); // Empty all tiles last modified before the specified timestamp

RootStats, accessed via FMTCRoot.stats, allows access to cached statistics, as well as listing of all existing stores, and the watching over changes in multiple/all stores and the bulk download recovery system.

final stats = FMTCRoot.stats;

await stats.storesAvailable; // List all the available/existing stores
await stats.realSize; // Retrieve the actual total size of the database in KiBs
await stats.size; // Retrieve the total number of KiBs of all tiles' bytes (not 'real total' size) from all stores
await stats.length; // Retrieve the total number of tiles in all stores
await stats.watchRecovery(); // Watch for changes to the recovery system
await stats.watchStores(); // Watch for changes in the specified (or all) stores

Supporting Me

Hi there 👋 My name is Luka, but I go by JaffaKetchup!

I'm currently in full-time education in the UK studying Computer Science, Geography, and Mathematics, and have been building my software development skills alongside my education for many years. I specialise in the Flutter and Dart technologies to build cross-platform applications, and have over 4 years of experience both from a hobby and commercial standpoint.

I've worked as a senior developer with a small team at WatchEnterprise to develop their Flutter-based WatchCrunch social media app for Android & iOS.

I'm one of a small team of maintainers for Flutter's №1 non-commercially aimed mapping library 'flutter_map', for which we make internal contributions, regulate and collaborate with external contributors, and offer support to a large community. I also personally develop a multitude of extension libraries, such as 'flutter_map_tile_caching'. In addition, I regularly contribute to OpenStreetMap, and continously improve my skills with personal experimental projects.

I'm eager to earn other languages, and more than happy to talk about anything software development related!

Sponsorships & donations allow me to further my education, whilst spening even more time developing the open-source projects that you use & love. I'm grateful for any amount you can spare, all support means a lot to me :) If you can't support me financially, please consider leaving a star and a like on projects that worked well for you.

I'm extremely greatful for any amount you can spare!

Supporters

Many thanks to all my supporters, donations of all sizes mean a lot to me, and encourage and enable me to continue my work on FMTC and other open-source projects.

In no particular order:

• + more anonymous or private donors

And also a thank you to the businesses listed in Trusted by many, and more, for abiding by the GPL license of this repository.

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 flutter_map Integration).

It is also simple to understand and implement:

RootRecovery, accessed via FMTCRoot.recovery, allows access to the bulk download recovery system, which is designed to allow rescue (salvation and restarting) of failed downloads when they crashed due to an unexpected event.

final rec = FMTCRoot.recovery;

await rec.recoverableRegions; // List all recoverable regions, and whether each one has failed
await rec.recoverableRegions.failedOnly; // List all failed downloads
await stats.getRecoverableRegion(); // Retrieve a specific recoverable region by ID
await stats.cancel(); // Safely remove the specified recoverable region

Restoring Usable Regions

Once a RecoveredRegion has been retreived, it can be converted to a standard region:

• either a DownloadableRegion, using toDownloadable The start tile will be adjusted from the original to reflect the progress of the download before it failed, meaning that tiles already successfully cached (excluding buffered) will not be downloaded again, saving time and data! The end tile will be either the original, or the maximum number of tiles normally in the region (which will have no resulting difference than null, but allows for a quick estimate of the number of remaining tiles to be made without needing to recheck the entire region).

• or a BaseRegion (with the correct subtype), using toRegion

Because FMTC has complex internals that rely heavily on external factors and preconditions being met, it is important to properly anticipate, catch, and handle errors & exceptions.

Errors & exceptions in FMTC come in two primary forms:

• Errors: usually generated by FMTC & descended from FMTCBackendError These indicate incorrect usage on the user's part - for example, an incorrect assumption such as usage of a method on a store before initialisation. These may also be non-specfic types, such as ArgumentError.

• Exceptions: usually generated by the depdenencies of backends, such as databases These indicate some sort of unexpected failure, such as a database reaching its maximum size limit during a write operation. These are usually not generated/typed by FMTC, and so are often of types from other libraries, such as ObjectBox when using the default FMTCObjectBoxBackend.

Exceptions may be caught using standard try/catch blocks (it's not usually recommended to catch FMTCBackendErrors).

FMTC automatically adjusts and changes the thrown StackTrace to include useful additional info, and ensures that the trace is followed across the many isolates and asynchronous gaps (eg. streams) of the FMTC internals. When creating a bug report, please include the full trace, including debug info at the end, if any is available.

It can usually be assumed that the requested operation did not & will not complete when an exception is thrown from it.

During Initialisation

One particular place where exceptions can occur more frequently is during initialisation. The code sample above includes a try/catch block to catch these errors. If an exception occurs at this point, it's likely unrecoverable (for example, it might indicate that the underlying database has been corrupted), and the best course of action is often to manually delete the FMTC root directory from the filesystem.

The default directory can be found and deleted with the following snippet (which requires 'package:path' and 'package:path_provider':

FMTC uses a root and stores to structure its data.

Stores contain any metadata associated with them, cached statistics, and maintain a reference to all the tiles that belong to it.

They are referenced by name, the single argument of FMTCStore.

Construction of an FMTCStore object does not imply/infer that the underlying store has been created and is ready for use. Therefore, a store will require creation via its StoreManagement object (accessed via FMTCStore.manage) before it can be used.

After a store reference is constructed, the following actions can be performed with it:

Stores also have the method getTileProvider(). This is the point of integration with flutter_map, providing browse caching through a custom image provider. This TileProvider can then be passed to the TileLayer.tileProvider parameter.

import 'package:flutter_map/flutter_map.dart';

class MapView extends StatefulWidget {
    late final tileProvider = FMTCStore('storeName').getTileProvider();
    
    Widget build(BuildContext context) {
        return FlutterMap(
            // options: MapOptions(),
            children: [
                TileLayer(
                    // Other config parameters
                    tileProvider: tileProvider,
                ),
            ],
        );
    }
}

Tile Provider Settings

This method (and others) optionally take a FMTCTileProviderSettings. These configure the behaviour of the tile provider. Defaults to the settings specified in the , or the package default (see table below) if that is not specified.

FMTCTileProviderSettings can take the following arguments:

Cache Behavior

This enumerable contains 3 values, which are used to dictate which logic should be used to store and retrieve tiles from the store.

Obscuring Query Parameters

If the URL's query parameters (the key-value pairs list found after the '?') contains a value that may change between fetches, such as an API key, use obscuredQueryParams.

This method strips specified keys and values from the query parameters, and avoids storing them in the database.

Pass it the list of query keys who's values need to be omitted from storage. For example, 'api_key' would remove the 'api_key', and any other characters until the next key-value pair, or the end of the URL, as seen below:

https://tile.myserver.com/{z}/{x}/{y}?api_key=001239876&mode=dark
https://tile.myserver.com/{z}/{x}/{y}?&mode=dark

Check If A Tile Is Cached

StoreStats, accessed via FMTCStore().stats, allows access to cached statistics, as well as retrieval of a recent tile (as an image), and the watching over changes in the store.

final stats = FMTCStore('storeName').stats;

await stats.all; // Retrieve the size, length, hits, and misses of this store
await stats.size; // Retrieve the total number of KiBs of all tiles' bytes (not 'real total' size)
await stats.length; // Retrieve the number of tiles belonging to this store
await stats.hits; // Retrieve the number of successful tile retrievals when browsing
await stats.misses; // Retrieve number of unsuccessful tile retrievals when browsing
await stats.tileImage(); // Retrieve the tile most recently modified in the specified store
await stats.watchChanges(); // Watch for changes to statistics (including tile events) and metadata

FMTC supports attachment of any custom storage mechanism, through an FMTCBackend. This allows users to pick their favourite database engine, or conduct in-memory testing.

More info coming soon...

Regions (BaseRegions) are geographical areas that do not yet have any of the necessary extra information to start a download (this is the responsibility ofDownloadableRegion).

There are 4 types of BaseRegion:

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

Checking Number Of Tiles

Before continuing to downloading the region, you can use check() 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.

Data is interpreted in key-value pair form, where both the key and value are Strings. Internally, the default backend stores it as a flat JSON structure. The metadata is stored directly on the store: if the store is deleted, it is deleted, and an exported store will retain its metadata. More advanced requirements will require use of a seperate persistance mechanism.

final md = FMTCStore('storeName').metadata;

await md.read; // Retrieve (all) the stored metadata
await md.set(); // Set a single key-value pair (overwriting any existing value for the key)
await md.setBulk(); // Set multiple key-value pairs (overwriting any existing value for each key)
await md.remove(); // Remove the specified key (and corresponding value)
await md.reset(); // Remove all keys (and values)

Now that you have constructed a DownloadableRegion, you're almost ready to go.

Customization Options

Before you call startForeground (via FMTCStore().download) to start the download, check out the customization parameters:

• parallelThreads (defaults to 5) The number of simultaneous download threads to run

• maxBufferLength (defaults to 200) The number of tiles to temporarily persist in memory before writing to the cache

• skipExistingTiles (defaults to false) Whether to avoid re-downloading tiles that have already been cached

• skipSeaTiles (defaults to true) Whether to avoid caching tiles that are entirely sea (based on whether they have the same pixels as the tile at z17, x0, y0, which is assumed to be sea)

• rateLimit The maximum number of tiles that can be attempted per second

• maxReportInterval (defaults to 1 second) The duration in which to emit at least one DownloadProgress event

• disableRecovery (defaults to false) Whether to avoid registering this download with the Recovery system for safe recovery if the download fails

Start Download

final progressStream = FMTCStore('storeName').download.startForeground(
    region: downloadableRegion,
    // other options...
);

Listen For Progress

The startForeground method returns a (non-broadcast) Stream of DownloadProgress events, which contain information about the overall progress of the download, as well as the state of the latest tile attempt.

To reflect the information from a single event back to the user, use a StreamBuilder, and build the UI dependent on the 'snapshots' of the stream. If you need to keep track of information from across multiple events, see Keeping Track Across Events below.

Keeping Track Across Events

In addition to display each individual event to your user, you may also need to keep track of information from across multiple DownloadProgress events. In this case, you'll likely need to use the latestTileEvent getter to access the latest TileEvent object, and keep track of its properties.

For example, you may wish to keep a list of all the failed tiles' URLs.

However, there are 3 important things to keep in mind when doing this:

A miniature tile server, intended to test and calibrate FMTC, has been included in the project.

For internal testing and development purposes, it also doubles down as a handy way to test your application without making too many costly and slow requests to your chosen tile server. When in use with the example application, it can handle over 2000 tiles/second.

It is a very simple web HTTP server written in Dart, that responds to all* requests with a tile. There is a theoretically 90% chance that this tile will be a specific land tile, and a 10% chance that it will be a sea tile - designed to test the sea tile skipping functionality. There are only these two tiles - it is not a full tile server.

To use this tile server:

1. Download/compile & start the tile server (no permanent installation required)
2. Use the following URL to connect to it

   • From the local device: http://localhost:7070/{z}/{x}/{y}.png
3. Control the tile server using keyboard key presses in the console window

   • q: Release port 7070 and quit the executable

   • UP arrow: Increase the artificial delay between request and response by 2ms

   • DOWN arrow: Decrease the artificial delay between request and response by 2ms

There are 3 methods available to control a download, and 1 method to check the download's current state.

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.

pause allows all threads to finish the tile they're currently downloading, then forces them to wait for a signal sent by resume before they can download their next tile. It does not write any buffered tiles to the store.

Use isPaused to check whether the download is currently paused.

Cancel

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

cancel allows all threads to finish the tile they're currently downloading, then forces them to cleanup and 'kill' themselves. 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.

The export() method copies the stores, along with all necessary tiles, to a seperate archive at the specified location (creating it if non-existent, overwriting it otherwise), in the FMTC (.fmtc) format.

await FMTCRoot.external('~/path/to/file.fmtc').export(['storeName']);

For example, this can be used to create backup systems to allow user's to store maps for later off-device, sharing/distribution systems, or to distribute a preset package of tiles to all users without worrying about managing IO or managing assets, and still allowing users to update their cache afterward!

External functionality is accessed via FMTCRoot.external('~/path/to/file.fmtc').

All functionalities require the path to an archive file. The file may not necessarily exist: for the export method only, the file will be created if it does not exist, and overwritten if it does. Other methods require the file to exist, and be in a valid format.

The import() method copies the specified archive to a temporary location, then opens it and extracts the specified stores (or all stores if none are specified) & all necessary tiles, merging them into the in-use database. The specified archive must exist, must be valid, and should contain all the specified stores, if applicable.

There is no support for directly overwriting the in-use database with the archived database, but this may be performed manually while FMTC is uninitialised.

final importResult =
    await FMTCRoot.external('~/path/to/file.fmtc').import(['storeName']);

The returned value is complex. See the API documentation for more details:

Conflict Resolution Strategies

If an importing store has the same name as an existing store, a conflict has occurred, because stores must have unique names. FMTC provides 4 resolution strategies:

• skip Skips importing the store

• replace Deletes the existing store, replacing it entirely with the importing store

• rename Appends the current date and time to the name of the importing store, to make it unique

• merge Merges the two stores' tiles and metadata together

In any case, a conflict between tiles will result in the newer (most recently modified) tile winning (it is assumed it is more up-to-date).

List Stores

If the user must be given a choice as to which stores to import (or it is helpful to know), and it is unknown what the stores within the archive are, the listStores getter will list the available store names without performing an import.

Roots contain cached statistics and recovery information.

Because there is only a single root at any time, the root is not named. Instead, it is accessed via FMTCRoot - and all members are static.

// final root = FMTCRoot;
final size = await FMTCRoot.stats.realSize;

After the root reference is constructed, the following actions can be performed with it: