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.

Other libraries or DIY solutions may not be all-in-one, but they may be all that's required for your app. Caching alone is not difficult or time consuming to setup yourself, either through a custom TileProvider backed by a non-specialised image caching provider such as '', or the other browse-caching-only flutter_map plugin '' if you need to save even more time at the expense of more external dependencies.

If you're still not sure, please get in touch: ! I'm always happy to offer honest guidance :)

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.

This project is released under GPL v3. For detailed information about this license, see https://www.gnu.org/licenses/gpl-3.0.en.html. choosealicense.com summarises the license with the following paragraph:

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!

Therefore, if you would like a license to use this software within a proprietary application, I am willing to sell a (preferably yearly) license. If this seems like what you'd be interested in, please do not hesitate to get in touch at . Please include details of your project if you can, and the approximate scale/audience for your app; I try to find something that works for everyone, and I'm happy to negotiate! If you're a non-profit organization, I'm happy to also offer an alternative license for free*!

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:

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.

First, add the normal dependency following the instructions. Then, add the following lines to your pubspec.yaml file under the dependencies_override section:

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

FMTC uses a root and stores to structure its data.

There is generally a single root (which generally corresponds to a single backend), which contains multiple stores. Cached tiles can belong to multiple stores, which keeps duplication minimized.

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.

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

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.

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.

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

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

It is also simple to understand and implement:

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.

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.

FMTC relies on a self-contained 'environment', called a backend, that requires initialisation (and configuration) before it can be used. This allows the backend to start any necessary seperate threads/isolates, load any prerequisites, and open and maintain a connection to a database. This environment/backend is then accessible internally through a(*) singleton, so initialisation is not required again.

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.

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.

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.

1.

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';

2.

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

Here, we'll use the built-in, default 'backend' storage, which uses ObjectBox. We'll perform the intialisation just before the app starts, so we can be sure that it will be ready and accessible throughout the app, at any time.

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());
}

3.

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!

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

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

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

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.

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.

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.

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',
    ),
),

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.

StoreMetadata, accessed via FMTCStore().metadata, allows access and control over a simple peristent storage mechanism, designed for use with custom data/properties/fields tied to the store (such as a CacheBehavior or URL template).

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)

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:

FMTC allows stores (including all necessary tiles and metadata) to be exported to an 'archive'/a standalone file, then imported on the same or a different device!

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 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']);

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:

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:

Highlights

Trusted by many

In addition to our generous supporters, FMTC is also trusted and used by businesses all around the world:

Too easy 😄! Take a look at Google Maps, or Strava, or whichever other app of your choice.

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.

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!

• For bug reports & feature requests:

• For implementation/general support: The #plugin channel on the

• For other inquiries and licensing:

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.

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:

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

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:

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

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