We’re often asked by customers how to create Fulcrum-compatible offline tile layers from existing map data. We have documentation on how to do this using TileMill, but it can be cumbersome and overwhelming to replicate the process for multiple tile layers and data files. TileMill is an amazing application, but it’s intended to design complete base maps, which means it has a lot of sophistication that’s not typically required when you only need a simple overlay.
To help simplify the process, I created a little project called Fulcrum Tiler that uses TileMill behind the scenes to automate the creation of offline raster tile layers from existing GIS data. It includes support for some basic styling parameters that are typically used when creating transparent layers for Fulcrum. The goal of this project is to go from raw GIS data files to ready-to-use MBTiles with minimal hassle, while offering some customization for the most common styling properties used on data overlays.
The basic features provided by Fulcrum Tiler are:
- Simple rendering of GIS data to styled .mbtiles ready for offline use
- Supports GeoJSON, Shapefile, and KML
- Automatic projection conversion so most input files should “just work”
- Automatic detection of the bounds of the data so the tile layer is exactly the right size
- Polygon labeling using a custom attribute
- Interactivity using custom data attributes
- Min/Max zoom control to set the level of detail
Fulcrum Tiler automatically handles some common problems when creating MBTiles files from existing GIS data. One common frustration is handling input data in different projections. This utility will automatically re-project the input file to the correct projection so that most input files should work without having to manipulate the file before converting it to MBTiles.
Another very useful MBTiles feature supported in Fulcrum is UTFGrid interactivity. With this utility it’s easy to specify the data attribute you want to display when tapping on the features by using the –text-name property. In addition to the label name, you can also specify a few basic styling properties like line widths and fill colors.
The input files can be anything generally supported by the GDAL/OGR project.
Getting Set Up
First things first, you’ll need a couple of things:
- Docker Desktop — you’ll need this installed and running for your platform to support and run containers.
- Python – The main CLI is a simple Python script so it’s compatible with Windows, macOS and Linux
- GitHub Desktop — or standard git, Desktop just makes it easier to clone and set up
Next you’ll want to clone the fulcrum-tiler repository, then open a command line prompt to that directory.
Running the Command
The basic command is:
python mbtiles.py –input stpete.geojson –output stpete.mbtiles
Here is the command with some additional parameters to set the colors, zoom, and data field to use as the label. Each parameter is a separate line so it’s easier to read in this post.
python mbtiles.py
–input ~/Documents/Voting_Precincts.shp
–max-zoom 18
–text-name precinctid
–polygon-opacity 0.3
–line-color ‘#333’
In the above example, my input is Voting_Precincts.shp, which is a Shapefile I downloaded from the Pinellas County GIS Portal. I know this Shapefile has a data attribute named precinctid that I want to use as the polygon label. And since I know this data completely covers the entire area, I’m going to use an opacity of 0.3 so that it’s easy to see the base map underneath the polygons. The application will automatically detect the extents of the data and only generate tiles for the minimum bounding area of the data. I’m also passing a maximum zoom of 18. The maximum zoom you use will depend on the extents of your data and desired output file size. You can play around with different values for your data to see what ends up with a reasonable file size. Once it finishes, the output file will be placed in an output directory names output.mbtiles. You can override the output filename with the –output parameter.
Using this script, you can pretty easily script out the creation of multiple data layers using the same set of rendering parameters without having to manually create many TileMill projects or open the files one by one. Here is the complete list of parameters supported:
–input # The input file
–min-zoom # The minimum zoom level
–max-zoom # The maximum zoom level
–line-width # Width in pixels of rendered lines
–line-color # Color of rendered lines (hex code)
–polygon-fill # Color of rendered polygons (hex code)
–polygon-opacity # Opacity of polygons
–text-name # Name of data attribute for rendered labels
–template-teaser # Template to use for the popup for the UTFGrid interactivity
–template-full # Template to use for the popup once it’s clicked
–output # The output file name
You can then upload the MBTiles file to Fulcrum for usage on the web app or mobile apps. You can also preview the MBTiles using MapTiler or QGIS.
Here is what the voting precincts look like on the web in Fulcrum. You can click on each polygon and it will display the precinct number in the popup.
The same MBTiles can now be downloaded in the mobile app and used offline:
Fulcrum Tiler is an open source project, so please feel free to file issues and make contributions.