DOCSEARCHbyAlgolia
Submit Docs

vector_map_tiles

repository·main·Indexed 41 days ago

https://github.com/greensopinion/flutter-vector-map-tiles

A plugin for flutter_map that enables high-performance vector tile rendering with hardware-accelerated GPU support via flutter_gpu. It supports loading map styles via StyleReader, custom themes, and multiple tile providers including NetworkVectorTileProvider, FileVectorTileProvider, and specialized formats like PMTiles and MBTiles. Version 10.0.0-beta introduces Flutter GPU Preview requiring the Flutter main channel.

Tokens
6.5K
Snippets
23
Records
27
Agent score
49%

What's inside vector_map_tiles

  1. Matching Themes and Tile Providers

    main

    Themes and tile providers must be matched correctly because themes reference specific layers and properties within the vector tiles.

    Tested Combinations:

    • Maptiler or Stadia Maps:
      • OSM Liberty
      • OSM Bright
      • Klokantech Basic
      • Dark Matter
    • Mapbox:
      • Mapbox Outdoors
      • Mapbox Streets
      • Mapbox Light
      • Mapbox Dark

    Mapbox Tile Offset: Some providers (like Mapbox) offer tiles at 512px instead of the default 256px. If using such providers, set VectorTileLayerOptions.tileOffset to ensure correct rendering.

  2. Set up API keys for vector map providers

    main

    To use vector tiles from providers like Stadia Maps, MapTiler, or Mapbox, you must obtain an API key from their respective services.

    In the example project, create a file at lib/local_api_key.dart and define the following constants with your credentials:

    const stadiaMapsApiKey = '<your_stadiamaps_api_key>';
const maptilerApiKey = '<your_maptiler_api_key>';
const mapboxApiKey = '<your_mapbox_api_key>';

  3. Run the vector_map_tiles example app

    main

    After obtaining your API keys and configuring lib/local_api_key.dart, follow these steps to run the example:

    1. Open example/main.dart.
    2. Update the map provider URL and the corresponding API key to match the service you selected (Stadia Maps, MapTiler, or Mapbox).
    3. Execute the application using the Flutter CLI.
    flutter run

  4. Setup vector_map_tiles version 10+ (Flutter GPU Preview)

    main

    Version 10.0.0-beta uses flutter_gpu for hardware-accelerated rendering. This requires the Flutter main channel and specific configuration:

    1. Switch Flutter Channel: Run flutter channel main && flutter upgrade.
    2. Enable Flutter GPU:
      • Via command line: use --enable-flutter-gpu.
      • Via Manifest (Android): Add io.flutter.embedding.android.EnableFlutterGPU set to true.
      • Via Manifest (iOS/MacOS): Add FLTEnableFlutterGPU set to true.
    3. Enable Impeller: Ensure Impeller is enabled in your Flutter project.
    4. Dependencies: If build errors occur, install cmake.

    Note: This version is in preview. For production, use version 8.0.0 or 9.0.0-beta.8.

    flutter channel main && flutter upgrade

  5. Unit Test Guidelines for flutter-vector-map-tiles

    main

    When writing unit tests for this project, follow these implementation and naming standards:

    Test Naming

    • Describe behavior as a requirement: Use concise descriptions of desired behavior (e.g., provides a tile for a given identity).
    • Avoid technical implementation details: Do not use terms like returns false or throws an exception in the name; focus on the business requirement.
    • Forbidden words: Do not use expected, handles, or correct.
    • Avoid redundancy: Do not use should, check, or verify in test names.

    Test Implementation

    • Assertions: Every test MUST include an assertion or an expect call that matches the claim in the test name. Assertions within helper methods are permitted.
    • Organization: Group related tests within a common describe section. Place test files in folders that mirror the lib/ directory structure (e.g., lib/src/feature.dart maps to test/src/feature_test.dart).
    • Initialization: Prefer initializing fields inline rather than using a setUp method.
    • Mocks: If a mock is required, extract it to a separate file to prevent duplication across tests.
    • Code Quality: Do not duplicate test code; extract common logic to helper functions only when necessary. Do not extend production code in tests unless absolutely required. Avoid adding comments; rely on readable code instead.
    • Constructors: Do not add tests for constructors unless they contain non-trivial logic.

  7. Customize iOS launch screen assets

    main

    To customize the iOS launch screen, replace the existing image files in the example/ios/Runner/Assets.xcassets/LaunchImage.imageset/ directory with your own assets.

    Alternatively, you can manage these assets through Xcode:

    1. Open the iOS project using open ios/Runner.xcworkspace.
    2. In the Xcode Project Navigator, select Runner/Assets.xcassets.
    3. Locate the LaunchImage asset set and drag/drop your desired images into it.
    open ios/Runner.xcworkspace

  9. How to produce gallery screenshots

    main

    To create screenshots for the project gallery, follow these steps:

    1. Start the iPhone 13 Simulator.
    2. Run the example in debug mode.
    3. Navigate to the specific view you wish to capture.
    4. Use the simulator's built-in screenshot function.
    5. Open the captured image in the Preview application.
    6. Go to Tools -> Adjust Size... and set the width to 585.
    7. Save the resized image to the Gallery folder.
    8. Update gallery.md with the new image reference.

  10. Basic Usage of VectorTileLayer

    main

    To use vector tiles in a flutter_map, replace the standard TileLayer with VectorTileLayer. You must first read a map style using StyleReader and then pass the resulting theme, sprites, and tileProviders to the layer.

    // 1. Read the style
Future<Style> _readStyle() => StyleReader(
          uri: 'https://tiles.stadiamaps.com/styles/osm_bright.json?api_key={key}',
          apiKey: stadiaMapsApiKey,
          logger: const Logger.console(),
        ).read();

// 2. Use in FlutterMap
FlutterMap(
    mapController: _controller,
    options: MapOptions(
        center: style.center ?? LatLng(49.246292, -123.116226),
        zoom: style.zoom ?? 10,
        maxZoom: 22,
        interactiveFlags: InteractiveFlag.drag | 
            InteractiveFlag.flingAnimation | 
            InteractiveFlag.pinchMove | 
            InteractiveFlag.pinchZoom | 
            InteractiveFlag.doubleTapZoom,
    ),
    children: [
      VectorTileLayer(
          theme: style.theme,
          sprites: style.sprites,
          tileProviders: style.providers,
      ),
    ],
  )
    FlutterMap(
    mapController: _controller,
    options: MapOptions(
        center: style.center ?? LatLng(49.246292, -123.116226),
        zoom: style.zoom ?? 10,
        maxZoom: 22,
        interactiveFlags: InteractiveFlag.drag | 
            InteractiveFlag.flingAnimation | 
            InteractiveFlag.pinchMove | 
            InteractiveFlag.pinchZoom | 
            InteractiveFlag.doubleTapZoom,
    ),
    children: [
      VectorTileLayer(
          theme: style.theme,
          sprites: style.sprites,
          tileProviders: style.providers,
      ),
    ],
  )

  11. Specify Alternate Tile Providers

    main

    You can load tiles from custom sources by providing a TileProviders object to the VectorTileLayer. Use NetworkVectorTileProvider to define a custom URL template.

    Note: The maximumZoom in the provider should represent the maximum zoom level of the provider itself, not the map's maximum zoom, as vector tiles are often rendered at larger sizes to support higher zoom levels.

    VectorTileLayer(
    tileProviders: TileProviders(
        {'openmaptiles': _tileProvider() },
        // ... other providers
    ),
)

VectorTileProvider _tileProvider() => NetworkVectorTileProvider(
            urlTemplate: 'https://tiles.example.com/openmaptiles/{z}/{x}/{y}.pbf?api_key=$myApiKey',
            maximumZoom: 14,
        );