🕌IIIF Georeference to XYZ Tiles

A tool for generating XYZ tiles from IIIF Georeference Extension JSON and displaying them with MapLibre GL JS.

• Repository: https://github.com/nakamura196/iiif-georef-tiles
• GitHub Pages: https://nakamura196.github.io/iiif-georef-tiles/

Requirements

• Python 3.x
• GDAL (gdal_translate, gdalwarp, gdal2tiles.py)

Installing GDAL

# macOS (Homebrew)
brew install gdal

# Ubuntu/Debian
sudo apt install gdal-bin python3-gdal

Usage

python3 scripts/iiif_georef_to_tiles.py <IIIF_GEOREF_JSON_URL>

Example

python3 scripts/iiif_georef_to_tiles.py https://nakamura196.github.io/iiif_geo/canvas.json

Options

Option	Default	Description
--scale	0.25	Image scale factor
--zoom	14-18	Tile zoom level range
--output-dir	docs	Output directory
--name	tiles	Tile folder name
--work-dir	work	Working directory
--keep-work	-	Do not delete working files

Processing Flow

IIIF Georeference JSON
        │
        ▼
┌───────────────────────┐
│ 1. Fetch JSON         │
│    (fetch from URL)   │
└───────────────────────┘
        │
        ▼
┌───────────────────────┐
│ 2. Download image     │
│    (IIIF Image API)   │
└───────────────────────┘
        │
        ▼
┌───────────────────────┐
│ 3. Embed GCPs         │
│    (gdal_translate)   │
└───────────────────────┘
        │
        ▼
┌───────────────────────┐
│ 4. Coordinate         │
│    transformation     │
│    (gdalwarp)         │
└───────────────────────┘
        │
        ▼
┌───────────────────────┐
│ 5. Generate tiles     │
│    (gdal2tiles.py)    │
└───────────────────────┘
        │
        ▼
┌───────────────────────┐
│ 6. Generate HTML      │
│    viewer             │
│    (MapLibre GL JS)   │
└───────────────────────┘

Conversion Results

Original image	After georeferencing

Output Files

docs/
├── index.html    # MapLibre GL JS viewer
├── source.json   # Original IIIF Georeference JSON
└── tiles/        # XYZ tiles
    ├── 14/
    ├── 15/
    ├── 16/
    ├── 17/
    └── 18/

Local Preview

cd docs && python3 -m http.server 8000
# Open http://localhost:8000/

IIIF Georeference Extension

The IIIF Georeference Extension is an extension specification for adding georeference information to IIIF images.

• IIIF Georeference Extension Specification

JSON Structure

{
  "@context": [
    "http://iiif.io/api/extension/georef/1/context.json",
    "http://iiif.io/api/presentation/3/context.json"
  ],
  "type": "Canvas",
  "width": 18415,
  "height": 12911,
  "items": [...],
  "annotations": [
    {
      "type": "AnnotationPage",
      "items": [
        {
          "type": "Annotation",
          "motivation": "georeferencing",
          "body": {
            "type": "FeatureCollection",
            "transformation": {
              "type": "polynomial",
              "options": { "order": 1 }
            },
            "features": [
              {
                "type": "Feature",
                "properties": {
                  "resourceCoords": [6690, 7517]
                },
                "geometry": {
                  "type": "Point",
                  "coordinates": [139.7623182, 35.7151233]
                }
              }
            ]
          }
        }
      ]
    }
  ]
}

Sample Data Source

The image used in the demo is obtained from:

• Bird's-eye View of the University of Tokyo Main Campus and Faculty of Agriculture Buildings
  • Source: University of Tokyo Digital Archive Portal

References

• IIIF Presentation API 3.0
• IIIF Image API 3.0
• IIIF Georeference Extension
• Allmaps - Georeferencing tool for IIIF images
• GDAL Documentation
• MapLibre GL JS