This article summarizes the steps to generate XYZ tiles from IIIF Georeference Extension JSON, serve them with TileServer GL, and display them with MapLibre GL JS.

Bird’s-eye view map of the University of Tokyo overlaid on OSM

Overview

I┌││└┌││└┌││└┌││└I────────I─i(──m(──T(──M(─F─iX──bm──it──am──iY──-b──li──pa─G─fZ──ut──el──Lp─e─-──ti──Se──i─o─gt──il──e──bd─r│▼─ei─│▼─le─│▼─rs─│▼─ri─e─ol──s──ve──es─f─re────er──p─e─e──c──rv──Gl─r─fg──o──i──La─e─-e──n──Gn──y─n─tn──v──Lg──J)─c─ie──e──)──S─e─lr──r──────ea──s─────J─st──i─────S─i──o─────O─o──n─────N─n──)──────)───────────────┐││┘┐││┘┐││┘┐││┘

Prerequisites

  • Docker / Docker Compose
  • Python 3.x
  • GDAL (gdal_translate, gdalwarp, gdal2tiles.py)
  • Pillow (pip3 install pillow)
  • mb-util

Installing GDAL

#b#srumeUdawbocuOinaSntpsut(t/HaDiolenmlbseitbgaardnlealwl)gdal-binpython3-gdal

Installing mb-util

pip3installmbutil

1. Project Structure

w├├├├└t─────m─────s/ddsfdoatroctyockalnse/et/rse-/ncdo/mpose.yml###mCMbuatspitLloiembsrseftiyvllieeessweroptional)

2. Docker Compose Configuration

docker-compose.yml:

sertfvirilicproicprcemoooenmoooeesanr-lstanr-lssegttutegttut:reas"maneas"mav:i:8e/rd:i:8e/ren8sdst:n8sftrme8:at:ne8:r::ar8tygr9op_:alui_:nutn8:ennn8tnia0/slxa0ellm8d:e:m"neee0a/saedsr:"tssl::s/at-p/-twysiwusitltntstlmeoemresspsps-p-spetefheridradvloreenerst/-eengrnglvdi:enlrxa/thetsmtl:ro

3. Generating XYZ Tiles from IIIF Images

Use iiif-georef-tiles.

Both Canvas format and Manifest format are supported.

#gc#pidyCtGtliehocinonlieneofr3n-ategtsheecehortrXirteYpepfZtps-so:tt/s/iiii/llitgeeioissfrt_yh(gusebpo.ercceoifmf_/ytnoaa_ktaCimalunervsaa.1sp9y6f/o<irIimIiaIftF-_goGerEoOrMReaEfnF-i_tfUieRlsLet>s.fgoirotmuattpuUtR-Ld)ir/tiles_output

Example: Bird’s-eye View Map of the University of Tokyo

python3scripts/iiif_georef_to_tiles.pyhttps://nakamura196.github.io/iiif_geo/canvas.jsonoutput-dir/tiles_output

Both Canvas format and Manifest format are accepted as input. For Manifest format, the first Canvas is automatically extracted.

Processing flow:

  1. Fetch IIIF Georeference JSON (automatically extract Canvas for Manifest format)
  2. Download image from IIIF Image API (full/max to get maximum server size)
  3. Embed all GCPs (gdal_translate)
  4. Coordinate transformation (gdalwarp, polynomial order obtained from JSON)
  5. Generate XYZ tiles (gdal2tiles.py)

4. Converting XYZ Tiles to mbtiles

To serve with TileServer GL, convert XYZ tiles to mbtiles format.

Important: Specify the --scheme=xyz option. Without it, the Y coordinates will be inverted and tiles will be displayed in the southern hemisphere.

python3-c"frommbutilimportdisk_to_mbtiles;disk_to_mbtiles('tiles_output/tiles','data/tokyo_utokyo.mbtiles',image_format='png',scheme='xyz')"

Adding Metadata

The mbtiles generated by mb-util do not contain metadata, so add it manually:

sIIEqNNOlSSFiEEtRReTT3IIdNNaTTtOOa/mmteeottkaayddoaa_ttuaato((knnyaaomm.eem,,btvviaallleuusee))VVAA'LLEUUOEEFSS'''nfaomrem'a,t'',Bi'rpdn'g''s)-;eyeViewofTokyoImperialUniversity');

Note: Do not add metadata such as scheme=xyz. mb-util internally stores Y coordinates in TMS format, and TileServer GL recognizes them as TMS format by default. Adding scheme=xyz will cause coordinate conversion to be skipped, resulting in tiles not being displayed correctly.

5. Starting TileServer GL

dockercomposeup-d

Verification

TileServer GL top page

Data detail page (TileJSON information)

6. Displaying with MapLibre GL JS

Fetch tiles from TileServer GL and display them with MapLibre.

#b#srumeUdawbocuOinaSntpsut(t/HaDiolenmlbseitbgaardnlealwl)gdal-binpython3-gdal

0

Adjusting Opacity

By adjusting opacity with a slider, comparison with the base map becomes easier.

Opacity 100%Opacity 50%

Basic Commands

#b#srumeUdawbocuOinaSntpsut(t/HaDiolenmlbseitbgaardnlealwl)gdal-binpython3-gdal

1

Endpoints

URLDescription
http://localhost:8888/TileServer GL top page
http://localhost:8888/data.jsonData source list
http://localhost:8888/data/{name}.jsonTileJSON
http://localhost:8888/data/{name}/{z}/{x}/{y}.pngTile retrieval
http://localhost:8889/MapLibre viewer

References