With MapTiler Server 4.5 (released 02.2024) we replaced the Composite JSON file with the Virtual Tileset JSON file. This article focuses on the benefits of that change, instructions on where to find it, and how it can be used. Please note that Virtual Tileset JSON is not supported on MacOS!
The main benefit of Virtual Tileset JSON is the possibility of creating mosaic tilesets (combining multiple data into one tileset and color-toning it together). This is very useful, especially for Satellite or Terrain RGB data, where global low-res datasets can be blended with local high-res datasets. Please take a look at the example to find out more.
With the implementation of Virtual Tileset JSON, we improved the general performance of that solution, which can be noticeable with faster map loading.
Another important benefit is the presence of the Metadata (non-existing in Composite JSON). With that, it's possible to affect such parameters as attribution or title of the tileset.
Adding new sources or applying any changes to the JSON file is now possible directly from the Graphical User Interface of MapTiler Server with the newly added "Edit JSON" button.
In this example, we will use data from different sources to create a virtual tileset. We will combine medium-resolution satellite images, high-resolution satellite images of the Zurich area, and a drone (UAV) image. We will also adjust the color tones of the Zurich and drone images to match the colors of the medium-resolution satellite image.
In the following video, you can see the result of combining different datasets (on the left are the images without color adjustments, and on the right are the images with the same color tone thanks to the color adjustment).
Download the virtual and data tilesets
To download Virtual Tileset JSON (with already filled sources) and medium and high-resolution satellite images, you can visit the MapTiler Data download page, where you will find different datasets, high-quality data from around the world, and free example datasets from some areas. You can read the How to try MapTiler Server using free MapTiler Data to learn more.
Download the maptiler-server-map-styles-3.14.1.zip and the maptiler-aerial-zurich.mbtiles. Extract maptiler-satellite-mediumres-2021.mbtiles from maptiler-server-map-styles-3.14.zip and place it in your maptiler server data directory. By default, it is the installation directory, and also put in the file maptiler-aerial-zurich.mbtiles in the same directory.
We downloaded the drone image from OpenAerialMap and created a mbtiles using the MapTiler Engine. If you want to use your image, consult the article How to overlay an image over a map to learn how to generate a .mbtiles. Download the drone image mbtiles and place it in your MapTiler Server data directory.
Start the MapTiler Server and open the administration panel (http://localhost:3650/admin/login); you should see your tileset in the tiles tab.
You can view your dataset by clicking on the detail button.
Example of the drone image dataset detail.
Create the virtual tileset JSON
Download the sample JSON for a virtual tileset called virtual-satellite.json (without any sources filled in) inside your MapTiler Server data folder.
You can open the virtual-satellite.json file in your favorite text editor and scroll to the end of the file until you find the virtual_sources property. In this array (now empty), you must define the tilesets that will be part of the virtual tileset.
Next, we will add the tileset of the medium-resolution satellite image and the aerial image of the Zurich area into the virtual_sources array. Copy the following code into your virtual-satellite.json file:
Save the file and click the re-scan button to apply the changes.
Click on the Details button to examine an individual data set.
Click the View fullscreen button to view your tileset. To zoom to a specific area, you can move on the map or modify the URL's Fragment (# hash) with the coordinates and zoom level. To zoom in on the Zurich area, you can copy the following in the URL's Fragment: #11.1/47.3894/8.5978
Color-toning aerial image
One of the benefits of virtual mosaics is that it allows us to adjust the color of the data sources to unify and homogenize the appearance of our map.
As we can see on our map, there is quite a difference in color tones between the satellite and aerial images. We will apply the color adjustment to the aerial image layer to unify the appearance of the two data sources.
Update the Zurich aerial image definition and add the pixel_operation property with the following values:
Save the file and click the re-scan button to apply the changes.
Refresh the page to see the changes.
Add transparency to the aerial image
We have already adjusted the color of the image. Now, we will adjust the image's opacity based on the zoom level to get a smoother transition in the display of the images.
We will use the MapTiler Server's built-in JSON editor to do this. Applying any changes to the JSON file is now possible directly from the Graphical User Interface of MapTiler Server with the newly added "Edit JSON" button.
Click the Details button to view the details of the virtual-satellite.json. On the details screen, press the Edit JSON button.
A text editor will open where you can edit the virtual tileset file. Scroll to the end of the file, add the following lines to the aerial image, and save the changes. (The changes are applied automatically, and there is no need to press the Re-scan button).
With this, the image's opacity gradually increases from 0 (completely transparent) at zoom level 12 to 1 (completely opaque) at level 16. Now, if we zoom in on the Zurich area, we will see that the transition between the two images is progressive.
Adding your data
Next, we will add the image taken with a drone to our virtual tileset. Open the built-in JSON editor and scroll to the end of the file. Add a new entry in the virtual_sources array, and write the following:
(Read how to obtain and define the tileset bound).
Save and zoom into the drone image area. Copy the following in the URL's Fragment: #17/47.3515714/8.5217461
Image without color adjustment.
Finally, we will adjust the drone image color to fit the tones of the map. Add these color adjustments using the pixel_operation property:
You can refresh the map viewer page to see the drone image changes. It now has a similar color tone to the rest of the map.
Image with color adjustments.
How to obtain and define the tileset bounds
You can check the bounds of the Tileset in the Metadata section in its details.
The coordinates of the bounds in the Tileset JSON must be defined in the same projection (spatial_ref_sys) as the tile_matrix_set; in this case, it is Spherical Mercator (ESPG:3857).
As we can see in the previous image, the coordinates of our Tileset are in the WGS84 projection (ESPG:4326); therefore, we must do a coordinate transformation to have the coordinates in Spherical Mercator (ESPG:3857).
To obtain the bounds in the Spherical Mercator, we will use the MapTiler coordinates API that performs coordinate transformations.
The coordinates API accepts a List of coordinate pairs separated by ";" (semicolon) delimiter (Max 50 pairs).
In our case, the coordinates of our bounds will be 8.519759,47.350850;8.522758,47.352281
With this pair of coordinates, we can call the coordinate transformation API. For example: https://api.maptiler.com/coordinates/transform/8.519759,47.350850;8.522758,47.352281.json?t_srs=3857&key=YOUR_MAPTILER_API_KEY_HERE
Coordinate API response JSON.
With the coordinates of the response, we can now define our bounds as follows:
Here, you can download the virtual-satellite.json (without any sources filled in) file with all the changes made in the example.
MapTiler Server is now supporting the Virtual Tileset JSON format for serving offline maps. The virtual tileset JSON replaces the older composite JSON data format, and it enhances the serving viewing experience for the user. MapTiler Server can now work with mosaic tilesets and also seamlessly blend satellite, aerial, or drone imagery into one layer, applying beautiful color toning. Virtual Tileset JSON also brings the ability to store metadata, which was not previously possible with the composite JSON.