Skip to main content

Vector Tile Providers

  • 6 minutes to read

Use a vector data tile source with the Map Control to optimize tile loading performance. When the control is bound to a vector provider, it only downloads shape definitions (geometries) and applies styles on the client. Raster providers require more bandwidth to download pre-rendered tiles. You can also use vector tile packages in offline environments where it is impossible to load tiles from online map providers.

Refer to the following sections for more information on supported vector tile sources and styles:

Connect to Mapbox Service

Mapbox Service provides vector tilesets. Each tileset consists of vector tiles in PBF format.

image

Important

Before you use the Mapbox Service, read the Invoices and billing and Terms of service pages.

You should register an access token to use this service. See the access token page for more information.

Use MapboxDataProvider to connect to Mapbox Tile Service and load the Mapbox Streets tileset to a map. To choose between available tilesets, use the MapboxDataProvider.Tileset property.

private void Form1_Load(object sender, EventArgs e) {
    ImageLayer layer = new ImageLayer();
    MapboxDataProvider dataProvider = new MapboxDataProvider();

    dataProvider.AccessToken = "Your_access_token_here";

    layer.DataProvider = dataProvider;
    mapControl1.Layers.Add(layer);
}

See the MapboxDataProvider page in the API Reference section for more information.

Load Data from an MbTiles File

Vector tiles can be stored as MbTiles files (wrapped SQLite databases). Use MbTilesDataProvider to load a MbTiles file stored locally or on a server.

private void Form1_Load(object sender, EventArgs e) {
    ImageLayer layer = new ImageLayer();
    MbTilesDataProvider dataProvider = new MbTilesDataProvider();
    dataProvider.FileUri = new Uri(@"D:\countries.mbtiles", UriKind.Absolute);
    layer.DataProvider = dataProvider;
    mapControl1.Layers.Add(layer);
}            

Note that you need to install the System.Data.SQLite.Core package to load MbTiles files to a map.

See the MbTilesDataProvider page in the API Reference section for more information.

Load Tiles in PBF and MVT Formats

To load vector tiles in .PBF or .MVT format, use UriBasedVectorTileDataProvider. Specify its UriBasedVectorTileDataProvider.TileUriTemplate property to set a template that the Map Control uses to obtain tiles.

ImageLayer layer = new ImageLayer();
UriBasedVectorTileDataProvider dataProvider = new UriBasedVectorTileDataProvider();            
dataProvider.TileUriTemplate = @"D:\PbfFiles\{x}-{y}-{level}.pbf";
layer.DataProvider = dataProvider;
mapControl1.Layers.Add(layer);

See the UriBasedVectorTileDataProvider page in the API Reference section for more information.

Load Data from a Custom Source

Follow the steps below to implement a provider that loads tiles from a custom source.

  • Create a provider class that implements VectorTileDataProviderBase.
  • Implement the VectorTileDataProviderBase.GetStream method so that it returns a tile as a sequence of bytes for specific coordinates in the tile grid at the specified zoom level.
  • Assign the provider to the ImageLayer.DataProvider property.

    View Example

    using DevExpress.XtraMap;
    using System.IO;
    using System.Windows.Forms;
    
    namespace WinFormsMap {
        public partial class Form1 : Form {
            public Form1() {
                InitializeComponent();
                var layer = new ImageLayer();
                var provider = new CustomVectorTileStreamProvider();
    
                layer.DataProvider = provider;
                mapControl1.Layers.Add(layer);
            }
        }
        public class CustomVectorTileStreamProvider : VectorTileDataProviderBase {
            public override Stream GetStream(long x, long y, long level) {
                string path = Path.GetFullPath("..\\..\\Data\\test.data");
                return File.OpenRead(path);
            }
        }
    }
    

Vector Tile Styles

If a default vector tile style does not meet your requirements, you can apply your style to vector tiles. Styles apply on the client before rendering the map.

A style must be a valid JSON file. The Map Control supports the following properties:

Property values can be set directly (for example, “text-size”: 10) or via an interpolation syntax (for example, “line-width”: {“base”: 1.2, “stops”: [[15, 1], [17, 4]]}).

The following color formats are supported: hsl, rgb, rgba, hsla, hex. You can use web color names, such as red or yellow.

Apply a Style

  1. The MapControl uses the Newtonsoft.Json library to parse style files. Install the Newtonsoft.Json package if your .NET Framework application does not reference this library. For .NET 6+ platforms, System.Text.Json is used. Set the DevExpress.Map.Native.VectorTileStyleParser.ProcessingLibrary property to NewtonsoftJson to use the Newtonsoft.Json library instead.
  2. Use the VectorTileDataProviderBase.StyleFileUri property to define a path to a style file.

The following code loads a style file from the project’s Data directory:

dataProvider.StyleFileUri = new Uri(GetRelativePath("style.json"), UriKind.Absolute);

public static string GetRelativePath(string name) {
    name = "Data\\" + name;
    DirectoryInfo dir = new DirectoryInfo(Application.StartupPath);
    while (dir != null) {
        string filePath = Path.Combine(dir.FullName, name);
        if (File.Exists(filePath))
            return filePath;
        dir = Directory.GetParent(dir.FullName);
    }
    return string.Empty;
}

Sample Style

The following code snippet contains a sample style file notation:

{
    "name": "style",
    "layers": [
        {
            "id": "background",
            "type": "background",
            "paint": {"background-color": "#ffffff"}
        },
        {
            "id": "osm_fill",
            "type": "fill",
            "source-layer": "osm",
            "paint": {"fill-color": "#00ff00"}
        },
        {
            "id": "osm_line",
            "type": "line",
            "source-layer": "osm",
            "paint": {
                "line-color": "#ff0000",
                "line-width": "1"
            }
        },
        {
            "id": "osm_symbols",
            "type": "symbol",
            "source-layer": "osm",
            "layout": {
                "text-field": "{name:be}",
                "text-size": "10"
            },
            "paint": {
                "text-color": "#0000ff"
            }
        }
    ]
}