MapLibre Composition

deckgl_marimo.maplibre.MapLibreConfig

Composed basemap configuration: a base style plus extra sources/layers.

Pass to Map(basemap=config). The frontend loads the base style and then applies the additional sources and MapLibre layers on top — without hand-writing a full style JSON document.

Examples:

WMS raster over a named basemap::

from deckgl_marimo.maplibre import MapLibreConfig, RasterSource, RasterLayer

config = MapLibreConfig(
    style="positron",
    sources={"wms": RasterSource.from_wms(
        "https://ows.terrestris.de/osm/service", layers="TOPO-WMS",
    )},
    map_layers=[RasterLayer(id="wms-topo", source="wms", raster_opacity=0.7)],
)
m = dgl.Map(basemap=config, layers=[...])

Custom vector tiles::

config = MapLibreConfig(
    style="dark-matter",
    sources={"custom": VectorSource(tiles=["https://example.com/{z}/{x}/{y}.pbf"])},
    map_layers=[FillLayer(id="custom-fill", source="custom", source_layer="buildings")],
)

Parameters:

Name	Type	Description	Default
`style`	`str \| dict[str, Any]`	Basemap alias (`"positron"`), MapLibre style URL, or inline style spec dict. Use :func:`empty_style` for WMS-only maps.	`'dark-matter'`
`sources`	`dict[str, Any] \| None`	Extra sources keyed by source id — values may be Source objects (:class:`RasterSource`, :class:`VectorSource`, :class:`GeoJSONSource`) or raw spec dicts.	`None`
`map_layers`	`list[Any] \| None`	Extra MapLibre style layers — Layer objects (:class:`RasterLayer`, :class:`FillLayer`, ...) or raw spec dicts. Applied in order after the base style loads.	`None`
`map_options`	`dict[str, Any] \| None`	Additional options merged into the MapLibre `Map` constructor.	`None`

to_dict

to_dict()

Convert to the dict shape the widget's maplibre_config traitlet carries.

deckgl_marimo.maplibre.empty_style

empty_style()

An empty MapLibre style spec — for WMS-only / layers-only maps.

Sources

deckgl_marimo.maplibre.RasterSource

MapLibre raster tile source.

Used for XYZ tile servers, WMS, WMTS, or any raster tile endpoint — the primary building block for composing WMS base layers, which is this library's headline MapLibre use case.

Examples:

XYZ tiles::

RasterSource(tiles=["https://tile.openstreetmap.org/{z}/{x}/{y}.png"])

WMS::

RasterSource.from_wms(
    base_url="https://ows.terrestris.de/osm/service",
    layers="TOPO-WMS",
)

Parameters:

Name	Type	Description	Default
`tiles`	`list[str] \| None`	Tile URL templates with `{z}`, `{x}`, `{y}` placeholders.	`None`
`tile_size`	`int`	Tile size in pixels.	`256`
`min_zoom`	`int`	Zoom range at which tiles are requested.	`0`
`max_zoom`	`int`	Zoom range at which tiles are requested.	`0`
`bounds`	`list[float] \| None`	Bounding box `[west, south, east, north]` in WGS84.	`None`
`attribution`	`str \| None`	Attribution string for the source.	`None`
`scheme`	`str`	Tile scheme: `"xyz"` (default) or `"tms"`.	`'xyz'`

from_wms `classmethod`

from_wms(base_url, layers, tile_size=256, format='image/png', transparent=True, version='1.1.1', crs='EPSG:3857', styles='', extra_params=None, **kwargs)

Create a raster source from a WMS endpoint.

Builds a GetMap tile-URL template with MapLibre's {bbox-epsg-3857} placeholder.

Parameters:

Name	Type	Description	Default
`base_url`	`str`	WMS service base URL (query parameters are merged if present).	required
`layers`	`str`	WMS layer name(s); comma-separate multiple layers.	required
`tile_size`	`int`	Tile size in pixels (also sent as WIDTH/HEIGHT).	`256`
`format`	`str`	Image format, e.g. `"image/png"`.	`'image/png'`
`transparent`	`bool`	Request a transparent background.	`True`
`version`	`str`	WMS version; 1.3.x switches SRS -> CRS automatically.	`'1.1.1'`
`crs`	`str`	Coordinate reference system (Web Mercator by default).	`'EPSG:3857'`
`styles`	`str`	WMS STYLES parameter.	`''`
`extra_params`	`dict[str, str] \| None`	Additional WMS query parameters.	`None`
`**kwargs`	`Any`	Forwarded to :class:`RasterSource` (bounds, attribution, ...).	`{}`

to_dict

to_dict()

Convert to a MapLibre source spec dict.

deckgl_marimo.maplibre.VectorSource

MapLibre vector tile source for PBF/MVT tiles.

Examples:

::

VectorSource(tiles=["https://example.com/{z}/{x}/{y}.pbf"])
VectorSource(url="https://example.com/tiles.json")   # TileJSON

Parameters:

Name	Type	Description	Default
`tiles`	`list[str] \| None`	Tile URL templates (alternative to `url`).	`None`
`url`	`str \| None`	TileJSON URL (alternative to `tiles`).	`None`
`min_zoom`	`int`	Zoom range at which tiles are requested.	`0`
`max_zoom`	`int`	Zoom range at which tiles are requested.	`0`
`bounds`	`list[float] \| None`	Bounding box `[west, south, east, north]` in WGS84.	`None`
`attribution`	`str \| None`	Attribution string.	`None`
`scheme`	`str`	`"xyz"` (default) or `"tms"`.	`'xyz'`
`promote_id`	`str \| dict[str, str] \| None`	Property to use as feature ID — a string applied to all layers, or a dict mapping source-layer names to properties.	`None`

to_dict

to_dict()

Convert to a MapLibre source spec dict.

deckgl_marimo.maplibre.GeoJSONSource

MapLibre GeoJSON source for inline or remote GeoJSON data.

Examples:

::

GeoJSONSource(data={"type": "FeatureCollection", "features": [...]})
GeoJSONSource(data="https://example.com/data.geojson")

Parameters:

Name	Type	Description	Default
`data`	`str \| dict[str, Any]`	GeoJSON dict or URL string.	required
`cluster`	`bool`	Enable point clustering.	`False`
`cluster_radius`	`int`	Cluster radius in pixels.	`50`
`cluster_max_zoom`	`int \| None`	Max zoom to cluster points.	`None`
`cluster_min_points`	`int`	Minimum points to form a cluster.	`2`
`cluster_properties`	`dict[str, Any] \| None`	Custom aggregation expressions for clusters.	`None`
`line_metrics`	`bool`	Calculate line distance metrics (needed for line-gradient).	`False`
`tolerance`	`float`	Douglas-Peucker simplification tolerance.	`0.375`
`buffer`	`int`	Tile buffer size.	`128`
`max_zoom`	`int`	Maximum zoom level to generate tiles for.	`18`
`attribution`	`str \| None`	Attribution string.	`None`
`promote_id`	`str \| None`	Property to use as feature ID.	`None`
`generate_id`	`bool`	Auto-generate feature IDs.	`False`

to_dict

to_dict()

Convert to a MapLibre source spec dict.

Style layers

deckgl_marimo.maplibre.BaseMapLibreLayer

Base class for MapLibre style layers.

Parameters:

Name	Type	Description	Default
`id`	`str`	Unique layer ID within the style.	required
`source`	`str`	Source ID this layer draws from.	required
`source_layer`	`str \| None`	Source layer name (required for vector tile sources).	`None`
`min_zoom`	`float \| None`	Zoom range for layer visibility (MapLibre `minzoom`/`maxzoom`).	`None`
`max_zoom`	`float \| None`	Zoom range for layer visibility (MapLibre `minzoom`/`maxzoom`).	`None`
`filter`	`Expression \| None`	MapLibre filter expression.	`None`
`layout`	`dict[str, PropertyValue] \| None`	Raw layout properties (kebab-case keys) merged after convenience kwargs.	`None`
`paint`	`dict[str, PropertyValue] \| None`	Raw paint properties (kebab-case keys) merged after convenience kwargs.	`None`
`metadata`	`dict[str, Any] \| None`	Arbitrary metadata dict.	`None`

to_dict

to_dict()

Convert to a MapLibre layer spec dict.

deckgl_marimo.maplibre.FillLayer

Bases: BaseMapLibreLayer

MapLibre fill layer — filled polygons.

Example

::

FillLayer(
    id="buildings", source="vector-tiles", source_layer="building",
    fill_color="#ff0000", fill_opacity=0.5,
)

deckgl_marimo.maplibre.LineLayer

Bases: BaseMapLibreLayer

MapLibre line layer — lines and polygon outlines.

Example

::

LineLayer(
    id="roads", source="vector-tiles", source_layer="road",
    line_color="#000000", line_width=2,
)

deckgl_marimo.maplibre.RasterLayer

Bases: BaseMapLibreLayer

MapLibre raster layer — renders a raster (XYZ/WMS) source.

Example

::

RasterLayer(id="wms-topo", source="wms", raster_opacity=0.8)

deckgl_marimo.maplibre.CircleLayer

Bases: BaseMapLibreLayer

MapLibre circle layer — points as circles.

Example

::

CircleLayer(
    id="points", source="geojson-points",
    circle_radius=6, circle_color="#007cbf",
)

deckgl_marimo.maplibre.SymbolLayer

Bases: BaseMapLibreLayer

MapLibre symbol layer — text labels and icons.

Example

::

SymbolLayer(
    id="labels", source="places",
    text_field=["get", "name"], text_size=12, text_color="#000000",
)

deckgl_marimo.maplibre.FillExtrusionLayer

Bases: BaseMapLibreLayer

MapLibre fill-extrusion layer — 3D extruded polygons.

Example

::

FillExtrusionLayer(
    id="buildings-3d", source="vector-tiles", source_layer="building",
    fill_extrusion_color="#aaa",
    fill_extrusion_height=["get", "height"],
    fill_extrusion_opacity=0.6,
)

MapLibre Composition

deckgl_marimo.maplibre.MapLibreConfig

to_dict

deckgl_marimo.maplibre.empty_style

Sources

deckgl_marimo.maplibre.RasterSource

from_wms classmethod

to_dict

deckgl_marimo.maplibre.VectorSource

to_dict

deckgl_marimo.maplibre.GeoJSONSource

to_dict

Style layers

deckgl_marimo.maplibre.BaseMapLibreLayer

to_dict

deckgl_marimo.maplibre.FillLayer

deckgl_marimo.maplibre.LineLayer

deckgl_marimo.maplibre.RasterLayer

deckgl_marimo.maplibre.CircleLayer

deckgl_marimo.maplibre.SymbolLayer

deckgl_marimo.maplibre.FillExtrusionLayer

from_wms `classmethod`