feat(vmt-pmtiles): add protomap themes, update docs and example (#24)

* added protomap themes and changed the vector_map_tiles_pmtiles to use it, fixing #17

* add all protomaps themes, update example app

* add `silenceTileNotFound` parameter

* update docs

* change image urls to absolute paths

otherwise they won't visible on pub.dev

* Update pubspec.yaml

* Revert "Update pubspec.yaml"

This reverts commit a41cebd.

* add more instrutions for a custom style to the readme

* Update CHANGELOG.md

---------

Co-authored-by: Joscha <[email protected]>

example/lib/common/attribution_widget.dart

@@ -0,0 +1,15 @@
+import 'package:flutter/material.dart';
+import 'package:flutter_map/flutter_map.dart';
+import 'package:url_launcher/url_launcher_string.dart';
+
+class OsmAttributionWidget extends StatelessWidget {
+  const OsmAttributionWidget({super.key});
+
+  @override
+  Widget build(BuildContext context) {
+    return SimpleAttributionWidget(
+      onTap: () => launchUrlString('https://openstreetmap.org/copyright'),
+      source: const Text('OpenStreetMap contributors'),
+    );
+  }
+}

example/lib/flutter_map_cache/page.dart

@@ -6,6 +6,7 @@ import 'package:flutter/foundation.dart';
 import 'package:flutter/material.dart';
 import 'package:flutter_map/flutter_map.dart';
 import 'package:flutter_map_cache/flutter_map_cache.dart';
+import 'package:flutter_map_plugins_example/common/attribution_widget.dart';
 import 'package:flutter_map_plugins_example/flutter_map_cache/cache_store_types.dart';
 import 'package:flutter_map_plugins_example/flutter_map_cache/connectivity_icon.dart';
 import 'package:latlong2/latlong.dart';
@@ -59,6 +60,7 @@ class _FlutterMapCachePageState extends State<FlutterMapCachePage> {
                   ),
                   userAgentPackageName: 'com.github.josxha/flutter_map_plugins',
                 ),
+                const OsmAttributionWidget(),
               ],
             ),
           ),

example/lib/flutter_map_compass/page.dart

@@ -1,6 +1,7 @@
 import 'package:flutter/material.dart';
 import 'package:flutter_map/flutter_map.dart';
 import 'package:flutter_map_compass/flutter_map_compass.dart';
+import 'package:flutter_map_plugins_example/common/attribution_widget.dart';
 import 'package:latlong2/latlong.dart';
 
 class FlutterMapCompassPage extends StatefulWidget {
@@ -36,6 +37,7 @@ class _FlutterMapCompassPageState extends State<FlutterMapCompassPage> {
             onPressed: () => rotateMap(90),
             icon: const Icon(Icons.rotate_right),
           ),
+          const SizedBox(height: 24),
         ],
       ),
       body: FlutterMap(
@@ -50,6 +52,7 @@ class _FlutterMapCompassPageState extends State<FlutterMapCompassPage> {
             urlTemplate: 'https://tile.openstreetmap.org/{z}/{x}/{y}.png',
           ),
           const MapCompass.cupertino(),
+          const OsmAttributionWidget(),
         ],
       ),
     );

example/lib/flutter_map_pmtiles/page.dart

@@ -1,5 +1,6 @@
 import 'package:flutter/material.dart';
 import 'package:flutter_map/flutter_map.dart';
+import 'package:flutter_map_plugins_example/common/attribution_widget.dart';
 import 'package:flutter_map_pmtiles/flutter_map_pmtiles.dart';
 import 'package:latlong2/latlong.dart';
 
@@ -11,12 +12,13 @@ class FlutterMapPmTilesPage extends StatefulWidget {
 }
 
 // TODO: use your own tile source https://docs.protomaps.com/pmtiles/cloud-storage
-const tileSource =
+/// This can be a hosted file or local file in your file system,
+/// However, flutter assets are not supported.
+const String tileSource =
     'https://raw.githubusercontent.com/protomaps/PMTiles/main/spec/v3/stamen_toner(raster)CC-BY%2BODbL_z3.pmtiles';
 
 class _FlutterMapPmTilesPageState extends State<FlutterMapPmTilesPage> {
-  final Future<PmTilesTileProvider> _futureTileProvider =
-      PmTilesTileProvider.fromSource(tileSource);
+  final _futureTileProvider = PmTilesTileProvider.fromSource(tileSource);
 
   @override
   Widget build(BuildContext context) {
@@ -38,6 +40,7 @@ class _FlutterMapPmTilesPageState extends State<FlutterMapPmTilesPage> {
               ),
               children: [
                 TileLayer(tileProvider: tileProvider),
+                const OsmAttributionWidget(),
               ],
             );
           }

example/lib/vector_map_tiles_pmtiles/page.dart

@@ -1,18 +1,31 @@
+import 'package:flutter/foundation.dart';
 import 'package:flutter/material.dart';
 import 'package:flutter_map/flutter_map.dart';
+import 'package:flutter_map_plugins_example/common/attribution_widget.dart';
 import 'package:latlong2/latlong.dart';
 import 'package:vector_map_tiles/vector_map_tiles.dart';
 import 'package:vector_map_tiles_pmtiles/vector_map_tiles_pmtiles.dart';
-import 'package:vector_tile_renderer/vector_tile_renderer.dart';
+import 'package:vector_tile_renderer/vector_tile_renderer.dart' as vtr;
 
-// It could be that the hosted PMTiles file is no longer available.
-// Check https://maps.protomaps.com/builds/ to get an up to date build.
-// TODO: use your own tile source https://docs.protomaps.com/pmtiles/cloud-storage
-const tileSource = 'https://build.protomaps.com/20240128.pmtiles';
+/// TODO: use your own tile source https://docs.protomaps.com/pmtiles/cloud-storage
+/// This can be a hosted file or local file in your file system,
+/// However, flutter assets are not supported.
+const String tileSource =
+    'https://raw.githubusercontent.com/protomaps/PMTiles/main/spec/v3/protomaps(vector)ODbL_firenze.pmtiles';
 
 class VectorMapTilesPmTilesPage extends StatelessWidget {
-  final Future<PmTilesVectorTileProvider> _futureTileProvider =
-      PmTilesVectorTileProvider.fromSource(tileSource);
+  /// The theme specifies the look of the rendered map.
+  ///
+  /// Note: Styles from Mapbox, OpenMapTiles and others and not compatible
+  /// with Protomaps styles.
+  final vtr.Theme mapTheme = ProtomapsThemes.light(
+    logger: kDebugMode ? const vtr.Logger.console() : null,
+  );
+
+  final _futureTileProvider = PmTilesVectorTileProvider.fromSource(
+    tileSource,
+    silenceTileNotFound: true,
+  );
 
   VectorMapTilesPmTilesPage({super.key});
 
@@ -30,17 +43,20 @@ class VectorMapTilesPmTilesPage extends StatelessWidget {
             final tileProvider = snapshot.data!;
             return FlutterMap(
               options: const MapOptions(
-                initialZoom: 1,
-                initialCenter: LatLng(0, 0),
-                maxZoom: 3.49,
+                initialCenter: LatLng(43.787942, 11.237517), // firenze
+                maxZoom: 18,
+                minZoom: 0,
               ),
               children: [
                 VectorTileLayer(
-                  theme: ProvidedThemes.lightTheme(),
+                  // disable the file cache when you change the PMTiles source
+                  fileCacheTtl: Duration.zero,
+                  theme: mapTheme,
                   tileProviders: TileProviders({
-                    'openmaptiles': tileProvider,
+                    'protomaps': tileProvider,
                   }),
                 ),
+                const OsmAttributionWidget(),
               ],
             );
           }

flutter_map_pmtiles/example/example.md

@@ -2,8 +2,8 @@
 
 ```dart
 // initiate your tile provider
-final Future<PmTilesTileProvider> _futureTileProvider = PmTilesTileProvider
-        .fromSource('eitherAnUrlOrFileSystemPath');
+final _futureTileProvider = PmTilesTileProvider
+    .fromSource('eitherAnUrlOrFileSystemPath');
 
 @override
 Widget build(BuildContext context) {

vector_map_tiles_pmtiles/CHANGELOG.md

@@ -1,3 +1,10 @@
+## [1.1.0] 2024-02-10
+
+- Add `ProtomapsThemes` with all Protomaps basemap themes.
+- Add the parameter `bool silenceTileNotFound` to silence "tile not found"
+  exceptions (`TileNotFoundException`).
+- Update example and docs
+
 ## [1.0.1] 2024-01-30
 
 - Improve documentation

vector_map_tiles_pmtiles/README.md

@@ -1,6 +1,9 @@
 # vector_map_tiles_pmtiles
 
-A TileProvider for flutter_map that adds support for PMTiles.
+A tile provider
+for [vector_map_tiles](https://pub.dev/packages/vector_map_tiles) that adds
+support
+for PMTiles.
 
 [![Pub Version](https://img.shields.io/pub/v/vector_map_tiles_pmtiles)](https://pub.dev/packages/vector_map_tiles_pmtiles)
 [![likes](https://img.shields.io/pub/likes/vector_map_tiles_pmtiles?logo=flutter)](https://pub.dev/packages/vector_map_tiles_pmtiles)
@@ -12,14 +15,38 @@ A TileProvider for flutter_map that adds support for PMTiles.
 [![GitHub issues](https://img.shields.io/github/issues/josxha/flutter_map_plugins)](https://github.com/josxha/flutter_map_plugins/issues)
 [![codecov](https://codecov.io/gh/josxha/flutter_map_plugins/graph/badge.svg?token=5045489G7X)](https://codecov.io/gh/josxha/flutter_map_plugins)
 
+<table>
+<tr>
+<th>light</th>
+<th>white</th>
+<th>grayscale</th>
+</tr>
+<tr>
+<td style="width: 33%"><img src="https://raw.githubusercontent.com/josxha/flutter_map_plugins/main/vector_map_tiles_pmtiles/images/screenshot-light.jpg" alt="Example screenshot"></td>
+<td style="width: 33%"><img src="https://raw.githubusercontent.com/josxha/flutter_map_plugins/main/vector_map_tiles_pmtiles/images/screenshot-white.jpg" alt="Example screenshot"></td>
+<td style="width: 33%"><img src="https://raw.githubusercontent.com/josxha/flutter_map_plugins/main/vector_map_tiles_pmtiles/images/screenshot-grayscale.jpg" alt="Example screenshot"></td>
+</tr>
+</table>
+
+<table style="width: 66%">
+<tr>
+<th>dark</th>
+<th>black</th>
+</tr>
+<tr>
+<td style="width: 33%"><img src="https://raw.githubusercontent.com/josxha/flutter_map_plugins/main/vector_map_tiles_pmtiles/images/screenshot-dark.jpg" alt="Example screenshot"></td>
+<td style="width: 33%"><img src="https://raw.githubusercontent.com/josxha/flutter_map_plugins/main/vector_map_tiles_pmtiles/images/screenshot-black.jpg" alt="Example screenshot"></td>
+</tr>
+</table>
+
 ## Getting started
 
 Add the following packages to your `pubspec.yaml` file:
 
 ```yaml
 dependencies:
-  flutter_map: ^6.0.0         # in case you don't have it yet 
-  vector_map_tiles_pmtiles: ^1.0.0 # this package
+  flutter_map: ^6.0.0              # in case you don't have it yet 
+  vector_map_tiles_pmtiles: ^1.1.0 # this package
 ```
 
 ## Usage
@@ -28,23 +55,32 @@ dependencies:
 
 ```dart
 // ...from an URL
-final Future<
-    PmTilesVectorTileProvider> _futureTileProvider = PmTilesVectorTileProvider
+final _futureTileProvider = PmTilesVectorTileProvider
     .fromSource('https://example.com/useYourOwnHostedPMTilesFile.pmtiles');
 // ...from an local file on the file system
-final Future<
-    PmTilesVectorTileProvider> _futureTileProvider = PmTilesVectorTileProvider
+final _futureTileProvider = PmTilesVectorTileProvider
     .fromSource('some/file/system/path.pmtiles');
 // ...or provide a PmTilesArchive directly 
-// (you'll need to add pmtiles as direct dependency to your project)
-final Future<
-    PmTilesVectorTileProvider> _futureTileProvider = PmTilesVectorTileProvider
+// (you'll have to add pmtiles as direct dependency to your project)
+final _futureTileProvider = PmTilesVectorTileProvider
     .fromArchive(somePmTilesArchive);
 ```
 
-2. Await the response of the future, e.g. by using a `FutureBuilder`.
+2. Create your map theme
+
+The theme specifies the look of the rendered map.
+
+- You can use one of the default Protomaps basemap
+  themes, for example the light theme: `ProtomapsThemes.light()`.
+- or provide your own style with: `ThemeReader().read(myStyleJson)`.
+
+Note: Styles from Mapbox, OpenMapTiles and others and not compatible
+with Protomaps styles.
 
-3. Provide your `PmTilesVectorTileProvider` to your `TileLayer`
+3. Await the future, e.g. by using a `FutureBuilder`.
+
+4. Provide your `PmTilesVectorTileProvider` and your map theme to
+   your `TileLayer`.
 
 ```dart
 @override
@@ -53,16 +89,49 @@ Widget build(BuildContext context) {
     options: MapOptions(),
     children: [
       VectorTileLayer(
-        theme: ProvidedThemes.lightTheme(),
+        // the map theme
+        theme: mapTheme,
+
         tileProviders: TileProviders({
-          'openmaptiles': tileProvider,
+          // the awaited vector tile provider
+          'protomaps': tileProvider,
         }),
+
+        // disable the file cache when you change the PMTiles source
+        // fileCacheTtl: Duration.zero,
       ),
     ],
   );
 }
 ```
 
+## Frequent questions
+
+<details>
+
+<summary>Where do I get PMTiles files from?</summary>
+
+Visit
+the [Getting Started](https://docs.protomaps.com/guide/getting-started) guide on
+protomaps.com.
+
+</details>
+
+<details>
+
+<summary>Can I use a custom style?</summary>
+
+Yes that's possible. Start with one of the basemap themes and make the changes
+you want. Then use `ThemeReader().read(style)` to use your theme.
+
+Maputnik has currently no built-in support for
+PMTiles ([open issue here](https://github.com/maplibre/maputnik/issues/807)).
+But you can use the
+fork [maputnik-with-pmtiles](https://github.com/a-nyx/maputnik-with-pmtiles) in
+the meantime.
+
+</details>
+
 ## Additional information
 
 If you need help you

vector_map_tiles_pmtiles/example/example.md

@@ -1,20 +1,33 @@
 ### Basic usage
 
 ```dart
-// initiate your tile provider
-final Future<
-        PmTilesVectorTileProvider> _futureTileProvider = PmTilesVectorTileProvider
-        .fromSource('eitherAnUrlOrFileSystemPath');
+/// Initiate your tile provider.
+/// The source can be a PMTiles file that is either hosted or local on 
+/// your file system. flutter assets however are not supported.
+final _futureTileProvider = PmTilesVectorTileProvider
+    .fromSource('eitherAnUrlOrFileSystemPath');
+
+/// The theme specifies the look of the rendered map.
+/// Note: Styles from Mapbox, OpenMapTiles and others and not compatible
+/// with Protomaps styles.
+final mapTheme = ProtomapsThemes.light();
 
 @override
 Widget build(BuildContext context) {
   return FlutterMap(
     options: MapOptions(),
     children: [
-      TileLayer(
-        urlTemplate: 'https://tile.openstreetmap.org/{z}/{x}/{y}.png',
-        // use your awaited PmTilesVectorTileProvider
-        tileProvider: tileProvider,
+      VectorTileLayer(
+        // the map theme
+        theme: mapTheme,
+
+        tileProviders: TileProviders({
+          // the awaited vector tile provider
+          'protomaps': tileProvider,
+        }),
+
+        // disable the file cache when you change the PMTiles source
+        // fileCacheTtl: Duration.zero,
       ),
     ],
   );