Add to the layer gallery

Edit scripts/layer_gallery/config.py. This is the only file you need to touch.

The gallery dict is structured as gallery[category][layer_id] = LayerEntry(...). Category keys become the tab labels in the gallery UI.

If your layer is in the xyzservices catalog

Use XYZServicesRef to point at an existing entry in the xyzservices catalog:

from models import LayerEntry, ThumbnailConfig, XYZServicesRef

gallery = {
    ...
    "OpenStreetMap": {
        ...
        "MyNewLayer": LayerEntry(
            name="OpenStreetMap.MyNewLayer",
            layer_type="RasterLayer",
            source_type="RasterSource",
            xyzservices=XYZServicesRef(provider="OpenStreetMap", layer="MyNewLayer"),
            thumbnail=ThumbnailConfig(lat=47.04, lng=1.30, zoom=5),
        ),
    },
}

The layer gallery generator script (/scripts/layer_gallery/) fills in the URL, attribution, and zoom levels from xyzservices at build time.

If your layer is not in the xyzservices catalog

Use TileProvider from the xyzservices library to specify parameters directly:

from xyzservices import TileProvider
from models import LayerEntry, ThumbnailConfig

gallery = {
    ...
    "MyProvider": {
        "MyLayer": LayerEntry(
            name="MyProvider.MyLayer",
            layer_type="RasterLayer",
            source_type="RasterSource",
            tile_provider=TileProvider(
                name="MyProvider.MyLayer",
                url="https://tiles.example.com/{z}/{x}/{y}.png",
                attribution="© My Provider",
                max_zoom=18,
            ),
            thumbnail=ThumbnailConfig(lat=47.04, lng=1.30, zoom=5),
        ),
    },
}

For URLs with template variables beyond {z}/{x}/{y} (e.g. {variant}), add them as extra kwargs to TileProvider. They become urlParameters in the output JSON.

Specify a layer and source type

The layer and source types that JupyterGIS will use to add these layers to the map.

For raster tile layers, use layer_type="RasterLayer" and source_type="RasterSource".

For vector tile layers, use layer_type="VectorTileLayer" and source_type="VectorTileSource".

Add a thumbnail

Thumbnails live in packages/base/layer_gallery_thumbnails/ and are committed to the repo.

Generate automatically (raster tile layers)

python scripts/layer_gallery/generate.py --thumbnails

This fetches tiles, stitches a 256×256 PNG, and optimizes it. Commit the result.

Create manually (GeoJSON / vector layers, or custom screenshots)

Save a 256×256 PNG to:

packages/base/layer_gallery_thumbnails/<Name>.png

where <Name> is entry.name with the first . replaced by -. For example, NaturalEarth.Coastlines110m → NaturalEarth-Coastlines110m.png.

Optimize this png with optipng.

Commit the file.

Verify

python scripts/layer_gallery/generate.py

This runs automatically at build time. It fails with a listing of missing thumbnail paths, and does not write packages/base/_generated/layer_gallery.json until all thumbnails are present.