How to create a virtual tileset JSON to combine multiple tilesets

The virtual tileset combines multiple tilesets with extra parameters defining how these tilesets are combined to create a single virtual tileset. The virtual tileset itself does not have any tile container. All the sources need to be in the same projection and compatible tile grid (identical to the one defined in the tileset chunk).

Combined in the given order – the first item is drawn first, and the last item is “on the top.”
The sources are always “overzoomed” but never “underzoomed”. E.g. source with maxzoom 18 will still be used at 19+. Or a source with minzoom 6 will not be used at zoom 5- (it would be expensive to combine so many tiles in production env). The minzoom and maxzoom are used to denote the data availability/existence, to control how they are visualized (e.g. stop using a source after a specific zoom), use opacity.

The virtual tileset file must be a JSON file. The file name in the working directory cannot contain word config, and cannot end with .composite.json. It must have the .json extension.

Virtual tileset type is introduced in MapTiler Server 4.5.0 it permanently replaces composite tileset type.

  Installation ————

To create a virtual tileset, it is necessary to install MapTiler Server version 4.5.0 or higher. 

MapTiler Server runs on different operating systems: Linux, Windows, macOS, Docker, etc. You can check out the installation and setup section to learn how to run it on your preferred system. 

Download the data tilesets

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.

To download medium and high-resolution satellite images, you can visit the MapTiler Data download page, where you will find different data sets, high-quality data from around the world, and free example data sets from some areas. Read the How to try MapTiler Server using free MapTiler Data.

data.maptiler.com_maps_.png

  • Download the maptiler-server-map-styles-3.14.zip and maptiler-aerial-zurich.mbtiles.
  • Extract maptiler-satellite-mediumres-2021.mbtiles from maptiler-server-map-styles-3.14.zip
  • Put it in your MapSiler Server data directory. (by default it is the installation dir).
  • Put the file maptiler-aerial-zurich.mbtiles in the same directory.

We downloaded the drone image from OpenAerialMap and created mbtiles using the MapTiler Engine. If you want to use your own image, see How to overlay an image over a map to learn how to generate MBTiles.

Admin panel

Start the MapTiler Server and open the administration panel http://localhost:3650/admin/login,
you should now see your tileset in the tiles tab.

localhost_3650_admin_tiles(screen capture).png

Paste your geodata (in MBTiles or tiled GeoPackage format) into the MapTiler server predefined data folder, click the Re\-Scan button, and all datasets will be visible in the administration panel.

Create the virtual tileset JSON

Download the sample JSON for a virtual tileset called virtual-satellite.json inside your MapTiler Server data folder. 

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 (which is now empty), you have to define the tilesets that are going to 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:

"virtual_sources": [
  {
    "url": "maptiler-satellite-mediumres-2021",
    "bounds": [
      -20037508.342789244,
      -13149614.7081853,
      20037508.342789244,
      17689362.572804667
    ],
    "minzoom": 0,
    "maxzoom": 13,
    "_name": "satellite-mediumres-2021"
  },
  {
    "url": "maptiler-aerial-2021-01-01-switzerland-zurich",
    "bounds": [
      932875.7117,
      5992032.4121,
      967941.1984,
      6012785.0653
    ],
    "minzoom": 10,
    "maxzoom": 19,
    "_name": "maptiler-aerial-switzerland-zurich"
  }
],

Save the file and click the re-scan button to apply the changes.

Click on the Details button if you want to take a closer look at an individual data set.

Click the View fullscreen button to view your tileset. Zoom to Zurich area http://localhost:3650/api/tiles/virtual-satelite#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 aeria mage definition and add the pixel_operation property with the following values:

{
  "url": "maptiler-aerial-2021-01-01-switzerland-zurich",
  "bounds": [
    932875.7117,
    5992032.4121,
    967941.1984,
    6012785.0653
  ],
  "minzoom": 10,
  "maxzoom": 19,
  "pixel_operation": {
    "gamma": [
      1.17,
      1.07,
      1.13
    ]
  },
  "_name": "maptiler-aerial-switzerland-zurich"
}

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.

localhost_3650_admin_tiles_640d6ebc-b699-457d-91ad-6efb205555a3(screen capture).png

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)

"opacity": [
    [
        12,
        0
    ],
    [
        16,
        1
    ]
],

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.

localhost_3650_admin_tiles_640d6ebc-b699-457d-91ad-6efb205555a3(screen capture) (1).png

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:

,
{
  "url": "drone",
  "bounds": [
    948415.2335614098,
    5999530.9383694185,
    948749.0807142986,
    5999766.065551735
  ],
  "minzoom": 16,
  "maxzoom": 21,
  "opacity": [
    [
      16,
      0
    ],
    [
      19,
      1
    ]
  ],
  "_name": "aerial-drone"
}

Save and zoom into the drone image: http://localhost:3650/api/tiles/virtual-satelite#17/47.3515714/8.5217461.

Finally, we will adjust the drone image color to fit the tones of the map. Add these color adjustments using the pixel_operation property:

"pixel_operation": {
  "contrast": [
    0,
    0.5
  ],
  "gamma": [
    1.85,
    1.73,
    1.57
  ],
  "saturation": 1
},

Refresh the map viewer page to see the drone image changes. It now has a similar color tone to the rest of the map.

localhost_3650_api_tiles_virtual-satellite(screen capture) (3).png

Conclusion

The virtual_satellite.json file that was used in this example is available for download here.