Virtual Tileset JSON for seamless blending of drone, aerial, and satellite imagery

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 to use it. Please note that Virtual Tileset JSON is not supported on MacOS!

Benefits of composing mosaic tilesets and color-toning multiple imagery

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.Implementing Virtual Tileset JSON 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 parameters such as attribution or title of the tileset. 

Adding new sources or making changes to the JSON file is now possible directly from the MapTiler Server’s Graphic User Interface with the newly added “Edit JSON” button.

How to create an image mosaic from a drone (UAV), aerial, or satellite imagery

In this example, we will use data from different sources to create an image mosaic using the 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. Put 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.

###
Admin panel

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

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

You can view your dataset by clicking on the detail button.

Example of the drone image dataset detail.

###
Create the virtual tileset JSON

Download sample JSON from: https://docs.maptiler.com/server/virtual-tileset-json/data/virtual-satellite.json. And use it to create your own virtual.satellite.json.

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 to the satellite imagery overlay

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.

Pixel operation

The pixel_operation attribute determines the values employed to perform color correction. The following table shows the options and their corresponding description.

Attribute

Type

Description

contrast

(Optional) Array of numbers

[contrast, bias]

• Contrast - default 0. <0 less contrast, >0 more contrast
• Bias - [0, 1], default 0.5

gamma

(Optional) Array of numbers

[R, G, B] gamma factors

Non-negative numbers, default 1

saturation

(Optional) Number

Non-negative number, default 1

###
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. The newly added “Edit JSON” button in the MapTiler Server’s graphic user interface now allows you to apply changes to the JSON file directly.

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 own drone 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 the 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.

Conclusion

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 enhances the user’s viewing experience. MapTiler Server can now work with mosaic tilesets and seamlessly blend satellite, aerial, or drone imagery into one layer, applying beautiful color toning. Virtual Tileset JSON also allows the storage of metadata, which was not previously possible with composite JSON.