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

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

OptionDefaultDescription
--scale0.25Image scale factor
--zoom14-18Tile zoom level range
--output-dirdocsOutput directory
--nametilesTile folder name
--work-dirworkWorking 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 imageAfter 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.

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:

References