In this blog post we are going to show you how to use the free mapping files, available for download from various resources and convert them to image files so they can be rendered through the URL http://your_website/files_location/{z}/{x}/{y}.png You will get acquainted with various sources of map data files, different tools to convert and export the files into raster images. Finally, you will use MindFusion’s JS Mapping library to create a map that uses the image files, you have prepared and uploaded on your own server.
I. Mapping Data Resources: TileMill, Natural Earth and More
The first step in creating your own interactive map is getting geo, GPS, satellite or other data. We list here resources, who offer free downloadable files. We will list a couple of free, open source tools for converting between the file formats, so in general, you can start with any data, no matter the format it is offered in.
*.mbtiles files with data for the planet or per continent are available from this link:
https://www.reddit.com/r/openstreetmap/comments/v9yoed/downloadable_planet_europe_and_netherlands/
The files are very large and converted to raster files the whole data would be in the amount of tens of gigabytes – suitable for serious, detailed projects.
TileMill is a map design studio, which is open source and available from git hub here: https://github.com/tilemill-project/tilemill
TileMill runs under Unix-like machines (Linux, MacOS) and uses the browser as UI interface. The readme notes list the row of commands to run to install the application. It runs on your local machine at http://localhost:20009/
TileMill offers a set of predefined projects with maps and one of them is a beautiful political map of the world, which can be exported to a variety of file formats, including .mbtiles
If you are on the hunt for terrain data, the Natural Earth project lists TIF files that can be converted to *.mbtiles with tools listed below. The files are in several sizes and you can download the one that suits your needs. Here is the link:
https://www.naturalearthdata.com/downloads/10m-raster-data/10m-natural-earth-1/
II. Converting Data Files to the *.mbtiles Format
Whatever the initial mapping data file, we must provide an *.mbtiles file to the MBUtil tool, which we will use to prepare the PNG files used by MindFusion’s Mapping library.
The first way to create the *.mbtiles file is to export it from TileMill. TileMill supports various export options and you can play with the settings and see how they affect the output file size. You can create your own map projects, load additional layers from various files like *shp, TIF, etc. and export the final map.
Another option to create an *.mbtiles file is to use the GDAL tool. This is a very powerful tool, which, in contrast to TileMill is in active development. You can read how to install it from the following links:
https://discussions.apple.com/thread/254510018?sortBy=best
and
https://mits003.github.io/studio_null/2021/07/install-gdal-on-macos/
Detailed GDAL documentation is available at
https://gdal.org/programs/index.html
Once you have installed GDAL, you can use the GDAL translate utility to convert between files. For example, in order to convert a TIF file into an *.mbtiles file, you need to run something like that:
gdal_translate -oo ZOOM_LEVEL=10 -of mbtiles /Users/the_user/Downloads/NE1_HR_LC_SR_W/NE1_HR_LC_SR_W.tif /Users/the_user/Downloads/NE1_HR_LC_SR_W/terrain_map.mbtiles
This is the command that converts the specified TIF file into a new *.mbtiles file using the specified zoom level. By default, the GDAL utility will choose the maximum possible zoom level when converting, but you can opt for a lower level with the -oo ZOOM_LEVEL=XXX option.
A good explanation of the GDAL translate tool and the options when converting between files is found here:
https://gist.github.com/jbaranski/0073f7b98bdf1f64f49988853daed67b
and here
https://www.geos.ed.ac.uk/~smudd/TopoTutorials/html/tutorial_raster_conversion.html
III. Prepare the Raster Files
Once the *.mbtiles is ready, it is tile to install MBUtil. You can read about the project, download it and read the installation instructions from here:
https://github.com/mapbox/mbutil
When you are ready with the installation, the command to convert the *.mbtiles file to image files is this:
./mb-util world.mbtiles tiles
Depending on your machine, you might drop the first two characters that define the current directory and run:
mb-util world.mbtiles tiles
This converts a world.mbtiles file to image tiles located into the tiles directory. Note that the MBUtil tool supports various options, among which is to specify the format of the images. We go for PNG, which is the default.
Once the images are ready, you can upload them to your server. Check your hosting plan for the quota not only for disk space but also number of files. When your tiles are on the server, you can build your map.
IV. Build The Map
Create an empty folder, where we will store the project. Let’s name it my_map. Navigate to it in terminal and run
First, create a new npm project:
npm init
Follow the steps to create a new project. We have named ours my_map and specified the start file will be index.js Now it’s time to add the mapping library. Mapping is part of MindFusion Pack for JavaScript, so the easiest way to get the library files is to install the pack from npm:
npm i @mindfusion/pack
Run the command from the directory where you have created your project. All JavaScript files for all libraries in the pack are downloaded in the directory node-modules. For the map, we need drawing, controls, common, common-collections and mapping. We create an empty HTML page and reference them from the respective directories.
<script src="node_modules/@mindfusion/drawing/dist/umd/drawing.js" type="text/javascript"></script> <script src="node_modules/@mindfusion/controls/dist/umd/controls.js" type="text/javascript"></script> <script src="node_modules/@mindfusion/common/dist/umd/common.js" type="text/javascript"></script> <script src="node_modules/@mindfusion/common-collections/dist/umd/common-collections.js" type="text/javascript"></script> <script src="node_modules/@mindfusion/mapping/dist/umd/mapping.js" type="text/javascript"></script> <script src="index.js" type="text/javascript"></script>
Finally, we reference the index.js code-behind file, which we have created. This is an empty file, for now. In the web page we need to create a DIV element, where the map will render:
<div style="top: 10px; bottom: 24px;"> <div style="position: absolute; width: 100%; height: 100%;"> <div id="mapView" style="height: 100%; width: 100%;"> </div> </div> </div>
The map will be the size and location of the DIV we have designated for it. This is all for the web page, let’s edit the JavaScript code-behind file:
var m = MindFusion.Mapping;
// create a new instance of the mapView
view = new m.MapView(document.getElementById("mapView"));
var l = new m.MapLayer();
l.urlTemplate = "https://ubydesign.net/maps/meta_data2/{z}/{x}/{y}.png";
view.layers.add(l);
We create a namespace mapping and use the DIV element, whom we’ve given an ID, to create a new MapView instance. This is the class that renders the maps. We also create a new MapLayer. A MapView by default does not render anything – we need to add MapLayer-s to it. The layers can be for decorations, locations, labels, but most important – we need a layer with terrain, street or other data to specify the raster tiles. The urlTemplate property must point to the location of the tiles. In our case, we have uploaded the directory with the raster tiles at https://ubydesign.net/maps/meta_data2/. Change the URL with the location of your tiles at your server. Finally, we add the layer to the layers collection of the mapView.
In order to show the map, you need to call the —load method. It requires the location of a point to load in the center of the map and a zoom factor.
view.load(new m.LatLong(51.505, -0.09), 4);
For our map, we have also added a location marker.
var mark = new m.Marker(); mark.location = new m.LatLong(51.505, -0.09); view.decorations.add(mark);
Note: all code regarding map decoration, layers, info bubbles etc. must be called before mapView.load.
Loading the view should be the last line of code regarding the map initialization.
And now, if you double click the index.html file it will open in your default browser and you should be able to see your map.
Congratulations! You’ve just created a map that loads its own data from your own server using raster images you have prepared yourself. The whole process uses free open-source tools and data and provides you a way to host and serve your own maps without relying on a 3rd part TMS (tile map server) service. Enjoy!
You can download the source code of the project from this link:
Download the Mapping Sample Source Code
run “npm install” in the directory, where you have extracted the archive and open the index.html file in the browser.
Learn more about MindFusion.Mapping and MindFusion Pack for JavaScript at their respective pages. Technical support is available at MindFusion’s forum.