Map, Layer and Feature¶

The GeoLibre Jupyter widget and its leafmap-style Python API.

Map ¶

Map(center: list[float] | tuple[float, float] | None = None, zoom: float | None = None, *, basemap: str | None = None, renderer: str = 'maplibre', height: str = '800px', app_layout: str | None = None, layout: Any = None, theme: str = 'light', server_proxy: bool | str = 'auto', **kwargs: Any)

Bases: AnyWidget

An interactive GeoLibre map for Jupyter notebooks.

The widget embeds the full GeoLibre GIS app (menus, panels, processing tools) and exposes a small Python API to add data and drive the view. State is synchronized both ways through a single .geolibre.json project, so edits made in the UI are readable from Python via to_project.

Example

from geolibre import Map m = Map(center=(-100, 40), zoom=4) m.add_geojson("https://example.com/data.geojson", name="Data") m

Create a GeoLibre map.

Parameters:

Name	Type	Description	Default
`center`	`list[float] \| tuple[float, float] \| None`	Initial `[lng, lat]` map center.	`None`
`zoom`	`float \| None`	Initial zoom level.	`None`
`basemap`	`str \| None`	A basemap name or MapLibre style URL for the background.	`None`
`renderer`	`str`	`"maplibre"` (default), `"cesium"`, `"mapbox"`, or `"arcgis"`.	`'maplibre'`
`height`	`str`	CSS height of the widget (e.g. `"800px"`).	`'800px'`
`app_layout`	`str \| None`	`"embed"` (compact UI, the default), `"full"` (full desktop UI), or `"maponly"` (map without chrome).	`None`
`layout`	`Any`	An `ipywidgets.Layout` for the widget, as on any other ipywidgets widget. Its `height` overrides `height`. Passing an `app_layout` string here is deprecated.	`None`
`theme`	`str`	`"light"` or `"dark"`.	`'light'`
`server_proxy`	`bool \| str`	How the browser reaches the bundled app. `"auto"` (default) serves the app directly from localhost for local Jupyter and VS Code, and switches to a remote-aware path when running under JupyterHub (detected via `JUPYTERHUB_SERVICE_PREFIX`). On that path the front-end probes two same-origin routes and uses whichever is live: the bundled GeoLibre Jupyter Server extension at `{base_url}geolibre/app/` (needs no `jupyter-server-proxy` but only registers after the Jupyter Server restarts) and `jupyter-server-proxy` at `{base_url}proxy/{port}/` (works in the running server without a restart). Pass `True` to force the remote path on any other remote server (Binder, remote JupyterLab), or `False` to force the direct localhost path. Google Colab is detected separately and always uses its own port proxy.	`'auto'`
`**kwargs`	`Any`	Forwarded to `anywidget.AnyWidget`.	`{}`

user_rois `property` ¶

user_rois: dict[str, Any]

The user-drawn regions of interest as a GeoJSON FeatureCollection.

A leafmap-style accessor over get_drawn_features; reading it round-trips to the running app, so display the map first.

layers `property` ¶

layers: list[Layer]

The current layers as Layer objects, in draw order.

layer_names `property` ¶

layer_names: list[str]

Return layer display names in map order.

center `property` ¶

center: tuple[float, float]

The persisted (longitude, latitude) camera center.

zoom `property` ¶

zoom: float

The persisted camera zoom.

bearing `property` ¶

bearing: float

The persisted clockwise camera bearing in degrees.

pitch `property` ¶

pitch: float

The persisted camera pitch in degrees.

basemap `property` ¶

basemap: str | None

The current basemap style URL, embedded credentials redacted.

MapTiler, Stadia and others put an API key in the style URL itself, so this is swept like Layer.source rather than printed into a notebook cell. Read project for the URL exactly as stored.

name `property` `writable` ¶

name: str

The project name.

projection `property` ¶

projection: str

The persisted map projection, "globe" or "mercator".

close ¶

close() -> None

Close the widget and remove rasters materialized from xarray data.

request ¶

request(method: str, params: dict[str, Any] | None = None, *, timeout: float = 10.0) -> Any

Send a command to the running app and block for its reply.

This is the low-level primitive behind the query/processing methods; call it directly to reach a command without a dedicated wrapper.

Parameters:

Name	Type	Description	Default
`method`	`str`	The command name (e.g. `"getCenter"`).	required
`params`	`dict[str, Any] \| None`	Command parameters.	`None`
`timeout`	`float`	Seconds to wait for the reply.	`10.0`

Returns:

Type	Description
`Any`	The command's result value.

Raises:

Type	Description
`TimeoutError`	If the app does not reply in time.
`RuntimeError`	If the app reports the command failed.

request_async `async` ¶

request_async(method: str, params: dict[str, Any] | None = None, *, timeout: float = 10.0) -> Any

Send a command to the running app and asynchronously await its reply.

Async counterpart of request, with the same command set, arguments, return value, and errors. Because awaiting suspends the coroutine instead of blocking a thread, this works on the thread running the asyncio event loop that delivers the reply -- e.g. directly inside an async Shiny for Python observer or reactive.extended_task, with no worker thread and no jupyter_ui_poll pumping. It also works with top-level await in Jupyter.

Parameters:

Name	Type	Description	Default
`method`	`str`	The command name (e.g. `"getCenter"`).	required
`params`	`dict[str, Any] \| None`	Command parameters.	`None`
`timeout`	`float`	Seconds to wait for the reply.	`10.0`

Returns:

Type	Description
`Any`	The command's result value.

Raises:

Type	Description
`TimeoutError`	If the app does not reply in time.
`RuntimeError`	If the app reports the command failed.

on ¶

on(event: str, callback: Callable[[Any], None]) -> Callable[[], None]

Register a callback for an app event.

Events are delivered when the map is displayed and the user interacts with it. The known events are "click" (payload {"lngLat": [lng, lat], "features": [...]}), "selection-change" ({"layerId", "featureId"}), and "layer-change" ({"layerIds": [...]}).

Parameters:

Name	Type	Description	Default
`event`	`str`	The event name.	required
`callback`	`Callable[[Any], None]`	Called with the event payload.	required

Returns:

Type	Description
`Callable[[], None]`	A function that unregisters this callback.

on_click ¶

on_click(callback: Callable[[Any], None]) -> Callable[[], None]

Register a callback fired when the user clicks the map.

on_selection_change ¶

on_selection_change(callback: Callable[[Any], None]) -> Callable[[], None]

Register a callback fired when the selected layer/feature changes.

on_layer_change ¶

on_layer_change(callback: Callable[[Any], None]) -> Callable[[], None]

Register a callback fired when layers are added or removed.

get_view ¶

get_view(*, timeout: float = 10.0) -> dict[str, Any]

Return the live camera {center, zoom, bearing, pitch, bbox}.

get_view_async `async` ¶

get_view_async(*, timeout: float = 10.0) -> dict[str, Any]

Async variant of get_view; see request_async.

get_center ¶

get_center(*, timeout: float = 10.0) -> list[float]

Return the live map center as [lng, lat].

get_center_async `async` ¶

get_center_async(*, timeout: float = 10.0) -> list[float]

Async variant of get_center; see request_async.

get_bounds ¶

get_bounds(*, timeout: float = 10.0) -> list[float]

Return the live viewport bounds as [west, south, east, north].

get_bounds_async `async` ¶

get_bounds_async(*, timeout: float = 10.0) -> list[float]

Async variant of get_bounds; see request_async.

fly_to ¶

fly_to(lng: float | None = None, lat: float | None = None, *, zoom: float | None = None, bearing: float | None = None, pitch: float | None = None, duration: float | None = None, timeout: float = 10.0) -> None

Animate the camera. Only the provided fields change.

Parameters:

Name	Type	Description	Default
`lng`	`float \| None`	Target longitude (pass with `lat` to recenter).	`None`
`lat`	`float \| None`	Target latitude.	`None`
`zoom`	`float \| None`	Target zoom level.	`None`
`bearing`	`float \| None`	Target bearing in degrees.	`None`
`pitch`	`float \| None`	Target pitch in degrees.	`None`
`duration`	`float \| None`	Animation duration in milliseconds.	`None`
`timeout`	`float`	Seconds to wait for acknowledgement.	`10.0`

fly_to_async `async` ¶

fly_to_async(lng: float | None = None, lat: float | None = None, *, zoom: float | None = None, bearing: float | None = None, pitch: float | None = None, duration: float | None = None, timeout: float = 10.0) -> None

Async variant of fly_to; see request_async.

fit_bounds ¶

fit_bounds(bounds: list[float] | tuple[float, float, float, float], *, timeout: float = 10.0) -> None

Fit the camera to [west, south, east, north].

fit_bounds_async `async` ¶

fit_bounds_async(bounds: list[float] | tuple[float, float, float, float], *, timeout: float = 10.0) -> None

Async variant of fit_bounds; see request_async.

zoom_to_bounds ¶

zoom_to_bounds(bounds: list[float] | tuple[float, float, float, float], *, timeout: float = 10.0) -> None

Fit the map to bounds (leafmap-style alias of fit_bounds).

zoom_to_bounds_async `async` ¶

zoom_to_bounds_async(bounds: list[float] | tuple[float, float, float, float], *, timeout: float = 10.0) -> None

Async variant of zoom_to_bounds; see request_async.

zoom_to_layer ¶

zoom_to_layer(layer: str | Layer, *, timeout: float = 10.0) -> None

Fit the map to a layer, addressed by id, name, or layer handle.

zoom_to_layer_async `async` ¶

zoom_to_layer_async(layer: str | Layer, *, timeout: float = 10.0) -> None

Async variant of zoom_to_layer; see request_async.

identify ¶

identify(lng: float, lat: float, *, layer_id: str | None = None, timeout: float = 10.0) -> list[dict[str, Any]]

Query rendered features at a geographic point (like clicking it).

Parameters:

Name	Type	Description	Default
`lng`	`float`	Longitude of the query point.	required
`lat`	`float`	Latitude of the query point.	required
`layer_id`	`str \| None`	Restrict the query to one layer; omit to query all layers.	`None`
`timeout`	`float`	Seconds to wait for the reply.	`10.0`

Returns:

Type	Description
`list[dict[str, Any]]`	One `{"layerId", "featureId", "properties", "geometry"}` dict per
`list[dict[str, Any]]`	matched feature, topmost first.

identify_async `async` ¶

identify_async(lng: float, lat: float, *, layer_id: str | None = None, timeout: float = 10.0) -> list[dict[str, Any]]

Async variant of identify; see request_async.

get_features ¶

get_features(layer_id: str, *, timeout: float = 10.0) -> list[Feature]

Return a layer's features as Feature (GeoJSON) objects.

Reads the live store, so features added or edited in the UI are included. Only vector (GeoJSON) layers carry inline features; a tiled or remote layer returns an empty list — use identify for those.

Parameters:

Name	Type	Description	Default
`layer_id`	`str`	The layer id.	required
`timeout`	`float`	Seconds to wait for the reply.	`10.0`

Returns:

Type	Description
`list[Feature]`	A list of `Feature` objects (each also a plain GeoJSON dict).

get_features_async `async` ¶

get_features_async(layer_id: str, *, timeout: float = 10.0) -> list[Feature]

Async variant of get_features; see request_async.

get_selected_features ¶

get_selected_features(*, as_gdf: bool = False, timeout: float = 10.0) -> list[Feature] | Any

Return the features currently selected in the app.

Reads the live selection (the layer/feature highlighted by clicking a feature in the UI). Selection is a single feature, so the result is a list of zero or one Feature; the list shape leaves room for future multi-select.

Parameters:

Name	Type	Description	Default
`as_gdf`	`bool`	Return a `geopandas.GeoDataFrame` instead of a list of `Feature` objects (requires GeoPandas).	`False`
`timeout`	`float`	Seconds to wait for the reply.	`10.0`

Returns:

Type	Description
`list[Feature] \| Any`	A list of `Feature` objects, or a `GeoDataFrame` when
`list[Feature] \| Any`	`as_gdf` is true.

Note

Only features in vector (GeoJSON) layers can be read back. A feature selected in a tile or service layer carries no inline geometry, so the result is an empty list; use identify for those layers.

get_selected_features_async `async` ¶

get_selected_features_async(*, as_gdf: bool = False, timeout: float = 10.0) -> list[Feature] | Any

Async variant of get_selected_features; see request_async.

get_drawn_features ¶

get_drawn_features(*, as_gdf: bool = False, timeout: float = 10.0) -> list[Feature] | Any

Return the features the user drew with the Geo Editor.

Gathers the features from the app's "Sketches" layer(s) (the regions of interest drawn with the drawing tools), so a notebook can read back what was sketched on the map without knowing which layer it landed in.

Parameters:

Name	Type	Description	Default
`as_gdf`	`bool`	Return a `geopandas.GeoDataFrame` instead of a list of `Feature` objects (requires GeoPandas).	`False`
`timeout`	`float`	Seconds to wait for the reply.	`10.0`

Returns:

Type	Description
`list[Feature] \| Any`	A list of `Feature` objects, or a `GeoDataFrame` when
`list[Feature] \| Any`	`as_gdf` is true.

get_drawn_features_async `async` ¶

get_drawn_features_async(*, as_gdf: bool = False, timeout: float = 10.0) -> list[Feature] | Any

Async variant of get_drawn_features; see request_async.

list_algorithms ¶

list_algorithms(*, timeout: float = 10.0) -> list[dict[str, Any]]

List the available client-side processing algorithms.

Returns:

Type	Description
`list[dict[str, Any]]`	One `{"id", "name", "group", "description", "parameters"}` dict per
`list[dict[str, Any]]`	algorithm, suitable for discovering ids and parameters to pass to
`list[dict[str, Any]]`	`run_algorithm`.

list_algorithms_async `async` ¶

list_algorithms_async(*, timeout: float = 10.0) -> list[dict[str, Any]]

Async variant of list_algorithms; see request_async.

run_algorithm ¶

run_algorithm(algorithm_id: str, parameters: dict[str, Any] | None = None, *, timeout: float = 120.0) -> dict[str, Any]

Run a processing algorithm in the app and add its result layers.

Parameters:

Name	Type	Description	Default
`algorithm_id`	`str`	An id from `list_algorithms` (e.g. `"buffer"`).	required
`parameters`	`dict[str, Any] \| None`	The algorithm's parameters (see its `parameters` from `list_algorithms`). Layer parameters take a layer id.	`None`
`timeout`	`float`	Seconds to wait; raise this for large inputs.	`120.0`

Returns:

Type	Description
`dict[str, Any]`	`{"logs": [...], "resultLayerIds": [...]}` — the algorithm's log
`dict[str, Any]`	lines and the ids of any layers it added to the map.

run_algorithm_async `async` ¶

run_algorithm_async(algorithm_id: str, parameters: dict[str, Any] | None = None, *, timeout: float = 120.0) -> dict[str, Any]

Async variant of run_algorithm; see request_async.

run_model_builder ¶

run_model_builder(graph: dict[str, Any], *, timeout: float = 600.0) -> dict[str, Any]

Run a serialized GeoLibre Model Builder graph in the displayed app.

Sending the complete graph in one request also makes copied Model Builder scripts portable to JupyterLite, whose browser kernel cannot synchronously retrieve each intermediate layer id.

run_model_builder_async `async` ¶

run_model_builder_async(graph: dict[str, Any], *, timeout: float = 600.0) -> dict[str, Any]

Async variant of run_model_builder; see request_async.

list_whitebox_tools ¶

list_whitebox_tools(*, timeout: float = 30.0) -> list[dict[str, Any]]

List the bundled Whitebox/GeoLibre WASM tools and their parameters.

The catalog is resolved by the displayed app because the same browser runtime executes the tools. Display the map before calling this method.

list_whitebox_tools_async `async` ¶

list_whitebox_tools_async(*, timeout: float = 30.0) -> list[dict[str, Any]]

Async variant of list_whitebox_tools; see request_async.

run_whitebox_tool ¶

run_whitebox_tool(tool_id: str, parameters: dict[str, Any] | None = None, *, timeout: float = 300.0) -> dict[str, Any]

Run a bundled Whitebox tool locally in the browser via WASM.

Dataset parameters may be layer ids or Layer handles. Vector and raster outputs are added to the map automatically; a tool that writes a plain file instead (a CSV, GeoParquet, PMTiles, …) reports it in logs, since only the Processing panel can download one.

Parameters:

Name	Type	Description	Default
`tool_id`	`str`	An id from `list_whitebox_tools`, such as `"slope"`.	required
`parameters`	`dict[str, Any] \| None`	Tool parameters. Pass a `Layer` handle for an input-layer parameter, or its id as a string.	`None`
`timeout`	`float`	Seconds to wait; terrain and LiDAR tools may need several minutes for large inputs.	`300.0`

Returns:

Type	Description
`dict[str, Any]`	`{"logs": [...], "resultLayerIds": [...]}`.

run_whitebox_tool_async `async` ¶

run_whitebox_tool_async(tool_id: str, parameters: dict[str, Any] | None = None, *, timeout: float = 300.0) -> dict[str, Any]

Async variant of run_whitebox_tool; see request_async.

to_image ¶

to_image(path: str | None = None, *, timeout: float = 30.0) -> bytes | None

Capture the current map view as a PNG.

Parameters:

Name	Type	Description	Default
`path`	`str \| None`	If given, write the PNG here (parent dirs are created) and return `None`. Otherwise return the PNG bytes.	`None`
`timeout`	`float`	Seconds to wait for the capture.	`30.0`

Returns:

Type	Description
`bytes \| None`	The PNG bytes, or `None` when written to `path`.

to_image_async `async` ¶

to_image_async(path: str | None = None, *, timeout: float = 30.0) -> bytes | None

Async variant of to_image; see request_async.

to_html ¶

to_html(path: str | None = None, *, title: str = 'GeoLibre Map', width: str = '100%', height: str | None = None, app_url: str | None = None) -> str | None

Export the current map as a standalone HTML page.

The page embeds the GeoLibre app in an <iframe> and injects the current project into it over the same postMessage bridge the widget uses, so it renders the map exactly as configured here, in this map's app_layout and theme. Unlike to_image this needs no running kernel to view; by default it loads the hosted GeoLibre app over the network so the file stays portable.

Parameters:

Name	Type	Description	Default
`path`	`str \| None`	If given, write the HTML here (parent dirs are created) and return `None`. Otherwise return the HTML string.	`None`
`title`	`str`	The exported page's `<title>`.	`'GeoLibre Map'`
`width`	`str`	CSS width of the embedded map (e.g. `"100%"` or `"800px"`).	`'100%'`
`height`	`str \| None`	CSS height of the embedded map; defaults to this map's `height`.	`None`
`app_url`	`str \| None`	Base URL of the GeoLibre app to embed. Defaults to the hosted viewer so the export is portable. Pass a self-hosted deployment URL to pin a specific version, or this map's live `_app_url` to embed the session-bound localhost bundle.	`None`

Returns:

Type	Description
`str \| None`	The HTML string, or `None` when written to `path`.

Note

Layers backed by kernel-side local files (e.g. a local GeoTIFF added via add_cog) are served only for this kernel session, so the exported page cannot reach them once the kernel stops. Use hosted URLs or tile sources for a fully self-contained export.

get_layer ¶

get_layer(layer_id: str) -> Layer

Return a Layer handle for layer_id.

Raises:

Type	Description
`ValueError`	If no layer with that id exists.

find_layer ¶

find_layer(name: str) -> Layer | None

Return the first layer named name, or None when absent.

find_layer_index ¶

find_layer_index(name: str) -> int

Return the index of the first layer named name, or -1.

set_layer_visibility ¶

set_layer_visibility(layer: str | Layer, visible: bool = True) -> None

Show or hide a layer addressed by id, name, or layer handle.

set_layer_opacity ¶

set_layer_opacity(layer: str | Layer, opacity: float) -> None

Set a layer's opacity in [0, 1].

set_popup ¶

set_popup(layer: str | Layer, fields: Any = None, *, click: bool | None = None, hover: bool | None = None, title: str | None = None, title_expression: str | None = None, body_expression: str | None = None, show_feature_id: bool | None = None, max_width: int | None = None, image_height: int | None = None, tooltip: Any = None, merge: bool = False) -> dict[str, Any]

Configure a layer's click popup (and, with tooltip, its hover tip).

Without a config a layer shows its name and every visible property; a config narrows, orders, relabels and formats those rows.

Parameters:

Name	Type	Description	Default
`layer`	`str \| Layer`	The layer, by id, name, or handle.	required
`fields`	`Any`	Property names and/or field mappings, in display order. A mapping takes `field` plus any of `label`, `kind` (`"auto"`, `"text"`, `"number"`, `"date"`, `"link"`, `"image"`), `hover`, `decimals`, `thousands`, `date_format`, `prefix`, `suffix`, and `link_label`.	`None`
`click`	`bool \| None`	`False` suppresses the click popup.	`None`
`hover`	`bool \| None`	`True` shows a hover tooltip built from the `hover` fields.	`None`
`title`	`str \| None`	Property whose value titles the popup.	`None`
`title_expression`	`str \| None`	MapLibre expression source producing the title.	`None`
`body_expression`	`str \| None`	MapLibre expression source producing the body text.	`None`
`show_feature_id`	`bool \| None`	`False` drops the synthetic `id` row.	`None`
`max_width`	`int \| None`	Widest the click popup may draw, in CSS pixels (288 to 1200). The viewport still caps it.	`None`
`image_height`	`int \| None`	Tallest an `"image"` field's thumbnail may draw inside the popup, in CSS pixels (40 to 1200). A thumbnail keeps its aspect ratio, so raise `max_width` too for a landscape photo to use the extra height.	`None`
`tooltip`	`Any`	Hover shorthand -- a property name, a sequence of names, `True` to flag every configured field, or `False` to turn the tooltip off. The tooltip and the click popup share one field list, so naming a tooltip field on a popup that had none also narrows the click popup to it; pass `fields` too to keep the click popup full.	`None`
`merge`	`bool`	Merge into the layer's existing popup config rather than replacing it.	`False`

Returns:

Type	Description
`dict[str, Any]`	The layer's popup config after the change.

Example

m.set_popup( ... "Sites", ... [ ... {"field": "name", "label": "Site"}, ... {"field": "photo", "kind": "image", "label": "Photo"}, ... {"field": "url", "kind": "link", "link_label": "Details"}, ... {"field": "pop", "kind": "number", "thousands": True}, ... ], ... title="name", ... tooltip="name", ... max_width=480, ... image_height=320, ... )

set_tooltip ¶

set_tooltip(layer: str | Layer, fields: Any = True) -> dict[str, Any]

Show a hover tooltip on a layer, built from fields.

Parameters:

Name	Type	Description	Default
`layer`	`str \| Layer`	The layer, by id, name, or handle.	required
`fields`	`Any`	A property name, a sequence of names, `True` to use every field the layer's popup already configures, or `False` to turn the tooltip off. On a layer whose popup configures no fields, naming one here also narrows the click popup to it -- see `set_popup`.	`True`

Returns:

Type	Description
`dict[str, Any]`	The layer's popup config after the change.

clear_popup ¶

clear_popup(layer: str | Layer) -> None

Drop a layer's popup config, restoring the default popup.

set_layer_metadata ¶

set_layer_metadata(layer: str | Layer, *, merge: bool = False, **fields: Any) -> dict[str, Any] | None

Set a layer's descriptive (catalog) metadata.

The app shows and edits it in the layer's Metadata dialog, exports it as a STAC Item, and writes it into GeoParquet exports.

Parameters:

Name	Type	Description	Default
`layer`	`str \| Layer`	The layer, by id, name, or handle.	required
`merge`	`bool`	Keep existing fields that `fields` does not name.	`False`
`**fields`	`Any`	Any of `title`, `abstract`, `keywords` (list or comma-separated string), `license` (SPDX id or free text), `attribution`, `contact` (mapping with `name`, `email`, `organization`), `lineage`, `temporal_extent` (`(start, end)` ISO 8601 dates), and `links` (URLs or mappings with `href`, `rel`, `title`).	`{}`

Returns:

Type	Description
`dict[str, Any] \| None`	The layer's metadata block after the change, or `None` when empty.

Raises:

Type	Description
`ValueError`	If a value fails validation (email, dates, URLs).

Example

m.set_layer_metadata( ... "Rivers", ... title="Rivers of Tennessee", ... keywords=["hydrology", "rivers"], ... license="CC-BY-4.0", ... contact={"name": "Ada", "email": "[email protected]"}, ... temporal_extent=("2019-01-01", "2019-12-31"), ... )

clear_layer_metadata ¶

clear_layer_metadata(layer: str | Layer) -> None

Drop a layer's descriptive metadata.

set_layer_filter ¶

set_layer_filter(layer: str | Layer, expression: Any) -> None

Hide a layer's features that do not match a boolean expression.

Writes the layer's saved filterExpression -- the same filter the app's Select by Expression -> Filter layer creates. The data is untouched; non-matching features are just not drawn.

Parameters:

Name	Type	Description	Default
`layer`	`str \| Layer`	The layer, by id, name, or handle.	required
`expression`	`Any`	A boolean MapLibre expression, as a list or a JSON string, e.g. `[">=", ["get", "population"], 100000]`. `None` clears the filter.	required

Example

m.set_layer_filter("Cities", ["==", ["get", "state"], "TN"])

set_floor_picker ¶

set_floor_picker(layer: str | Layer, field: str | None = 'level', level: Any = None, *, mode: str | None = None) -> None

Link a multi-floor layer to the app's on-map floor picker.

The picker lists the floors in field across every linked layer and draws one floor, or a floor and the ones below it. It reads OpenStreetMap level values ("0", "0;1", "-1-0"), numbers and IMDF ordinals. Combine it with an extrusion base from the same field to stack the floors in 3D.

Parameters:

Name	Type	Description	Default
`layer`	`str \| Layer`	The layer, by id, name, or handle.	required
`field`	`str \| None`	The property holding the floor; `None` unlinks the layer.	`'level'`
`level`	`Any`	The floor to show, e.g. `"0"` or `-1`. Applies to every linked layer. `None` keeps the floor already shown; pass `mode="all"` to show every floor.	`None`
`mode`	`str \| None`	`"only"` (the default for a level), `"below"` to also show the floors under it, or `"all"`.	`None`

Example

m.set_floor_picker("Rooms", "level", "0", mode="below")

set_labels ¶

set_labels(layer: str | Layer, field: str | None = None, *, expression: Any = None, enabled: bool | None = None, **options: Any) -> dict[str, Any]

Label a vector layer's features from an attribute or an expression.

Options left out keep the layer's current label settings.

Parameters:

Name	Type	Description	Default
`layer`	`str \| Layer`	The layer, by id, name, or handle.	required
`field`	`str \| None`	Property whose value becomes the label text.	`None`
`expression`	`Any`	MapLibre expression for the label text, overriding `field` (e.g. `["concat", ["get", "name"], " ", ["get", "pop"]]`).	`None`
`enabled`	`bool \| None`	`False` hides the labels but keeps their settings; omitted, they keep their current state (on for a new layer).	`None`
`**options`	`Any`	`placement` (`"point"`/`"line"`), `size`, `color`, `halo_color`, `halo_width`, `min_zoom`, `max_zoom`, `allow_overlap`, `anchor`, `offset_x`, `offset_y`, `rotation`, `max_width`, `transform` (`"none"`/`"uppercase"`/`"lowercase"`), `number_format`, `number_decimals`, `number_locale`, `dedupe` (`"off"`/`"unique"`/`"concatenate"`), and the data-defined `size_expression`, `color_expression`, `opacity_expression`, `visibility_expression`, `priority_expression`.	`{}`

Returns:

Type	Description
`dict[str, Any]`	The layer's labels object after the change.

Example

m.set_labels("Cities", "name", size=14, halo_width=2, anchor="top")

set_plugin_state ¶

set_plugin_state(plugin_id: str, state: Any = None, *, position: str | None = None, activate: bool = True, allow_unknown: bool = False, clear: bool = False) -> dict[str, Any]

Store a plugin's saved state in the project, as the app saves it.

Each plugin reads its own state shape when the project opens (the Time Slider's timeline config, a grid plugin's resolution, ...). Use add_swipe, add_legend, and add_colorbar for those controls; they build validated state.

Parameters:

Name	Type	Description	Default
`plugin_id`	`str`	A built-in plugin id from `geolibre.project.PLUGIN_STATE_IDS`, or an external plugin's id with `allow_unknown=True`.	required
`state`	`Any`	The plugin's settings, as plain JSON. `None` keeps the stored settings (to change only `position`/`activate`).	`None`
`position`	`str \| None`	Optional control corner (`"top-left"`, ...).	`None`
`activate`	`bool`	Start the plugin active when the project opens.	`True`
`allow_unknown`	`bool`	Accept an id that is not a built-in plugin.	`False`
`clear`	`bool`	Remove the stored settings only, leaving activation and position as they were.	`False`

Returns:

Type	Description
`dict[str, Any]`	`{"pluginId", "active", "position", "state"}` as stored.

set_story_map ¶

set_story_map(**settings: Any) -> dict[str, Any]

Set the story map's title block and presentation settings.

Parameters:

Name	Type	Description	Default
`**settings`	`Any`	`title`, `subtitle`, `byline`, `footer`, `theme` (`"light"`/`"dark"`), `show_markers`, `marker_color`, `inset`, `inset_position`, `hide_chapter_nav`, `start_slide` and `end_slide` (`"none"`, `"blank"`, `"black"`, `"global"`, `"adjacent"`).	`{}`

Returns:

Type	Description
`dict[str, Any]`	The story settings with each chapter's id and title.

add_story_chapter ¶

add_story_chapter(title: str, *, description: str = '', center: tuple[float, float] | None = None, zoom: float | None = None, pitch: float | None = None, bearing: float | None = None, image: str | None = None, alignment: str = 'left', hidden: bool = False, map_animation: str = 'flyTo', rotate_animation: bool = False, on_enter: list[dict[str, Any]] | None = None, on_exit: list[dict[str, Any]] | None = None, index: int | None = None) -> dict[str, Any]

Add a chapter to the map's story (Project -> Story Map).

A camera value left out is taken from the map's current saved view.

Parameters:

Name	Type	Description	Default
`title`	`str`	Chapter heading.	required
`description`	`str`	Chapter body text.	`''`
`center`	`tuple[float, float] \| None`	Camera target `(lng, lat)`.	`None`
`zoom`	`float \| None`	Camera zoom, 0-24.	`None`
`pitch`	`float \| None`	Camera tilt in degrees, 0-85.	`None`
`bearing`	`float \| None`	Camera rotation in degrees.	`None`
`image`	`str \| None`	Optional image URL shown in the chapter panel.	`None`
`alignment`	`str`	`"left"`, `"center"`, `"right"`, or `"full"`.	`'left'`
`hidden`	`bool`	Hide the text panel while still moving the map.	`False`
`map_animation`	`str`	`"flyTo"`, `"easeTo"`, or `"jumpTo"`.	`'flyTo'`
`rotate_animation`	`bool`	Slowly rotate the camera once the move settles.	`False`
`on_enter`	`list[dict[str, Any]] \| None`	Layer opacity changes on entering the chapter, as `{"layer": <id, name or Layer>, "opacity": 0-1, "duration": ms}` entries.	`None`
`on_exit`	`list[dict[str, Any]] \| None`	Layer opacity changes on leaving, in the same form.	`None`
`index`	`int \| None`	Position to insert at; appended when omitted.	`None`

Returns:

Type	Description
`dict[str, Any]`	The chapter that was added, including its `id`.

Example

m.add_story_chapter("Downtown", center=(-83.92, 35.96), zoom=14, ... description="Where it started.")

remove_story_chapter ¶

remove_story_chapter(chapter: str | int) -> None

Remove a story chapter by id, title, or 0-based index.

move_story_chapter ¶

move_story_chapter(chapter: str | int, index: int) -> None

Move a story chapter (by id, title, or index) to a new position.

add_bookmark ¶

add_bookmark(name: str, *, center: tuple[float, float] | None = None, zoom: float | None = None, pitch: float | None = None, bearing: float | None = None, folder: str | None = None, visible_layers: list[str | Layer] | None = None) -> dict[str, Any]

Add a saved map view to the Bookmarks panel (Controls -> Bookmarks).

Bookmarks are saved in the project, so they travel with the file. A camera value left out is taken from the map's current saved view.

Parameters:

Name	Type	Description	Default
`name`	`str`	Bookmark name.	required
`center`	`tuple[float, float] \| None`	Camera target `(lng, lat)`.	`None`
`zoom`	`float \| None`	Camera zoom, 0-24.	`None`
`pitch`	`float \| None`	Camera tilt in degrees, 0-85.	`None`
`bearing`	`float \| None`	Camera rotation in degrees.	`None`
`folder`	`str \| None`	A folder id or name to file it under; a new name creates the folder.	`None`
`visible_layers`	`list[str \| Layer] \| None`	Layers (ids, names, or handles) to show when the bookmark is opened; the others are hidden. Omit to leave layer visibility alone.	`None`

Returns:

Type	Description
`dict[str, Any]`	The bookmark that was added, including its `id`.

Example

m.add_bookmark("Downtown", center=(-83.92, 35.96), zoom=14, ... folder="Neighborhoods")

remove_bookmark ¶

remove_bookmark(bookmark: str | int) -> None

Remove a bookmark by id, name, or 0-based index.

rename_layer ¶

rename_layer(layer: str | Layer, name: str) -> None

Rename a layer addressed by id, name, or handle.

Parameters:

Name	Type	Description	Default
`layer`	`str \| Layer`	The layer to rename, by id, name, or handle.	required
`name`	`str`	The new display name, surrounding whitespace stripped.	required

Raises:

Type	Description
`ValueError`	If `name` is blank or the reserved basemap pseudo-id.

move_layer ¶

move_layer(layer: str | Layer, index: int) -> None

Move a layer to index in the project's draw order.

Negative indices count from the end the way sequence indexing does, so -1 moves the layer to the last position (not list.insert(-1, ...), which would leave it second to last). Out-of-range indices are clamped.

duplicate_layer ¶

duplicate_layer(layer: str | Layer, *, name: str | None = None) -> str

Duplicate a layer, returning the new layer id.

The copy is appended to the draw order (drawn on top), the same place a newly added layer lands, rather than next to its source. Use move_layer to put it elsewhere.

Parameters:

Name	Type	Description	Default
`layer`	`str \| Layer`	The layer to copy, by id, name, or handle.	required
`name`	`str \| None`	Name for the copy, surrounding whitespace stripped; defaults to the source name plus `copy`.	`None`

Raises:

Type	Description
`ValueError`	If `name` is blank or the reserved basemap pseudo-id.

show_layer ¶

show_layer(layer: str | Layer) -> None

Show a layer.

hide_layer ¶

hide_layer(layer: str | Layer) -> None

Hide a layer.

layer_properties ¶

layer_properties(layer: str | Layer) -> dict[str, list[Any]]

Return sampled property values for an inlined GeoJSON layer.

column_values ¶

column_values(layer: str | Layer, column: str) -> list[Any]

Return one property column from an inlined GeoJSON layer.

describe ¶

describe() -> dict[str, Any]

Return a compact, JSON-serializable project summary.

add_geojson ¶

add_geojson(data: Any, name: str = 'GeoJSON', **style: Any) -> str

Add a GeoJSON layer.

Parameters:

Name	Type	Description	Default
`data`	`Any`	A FeatureCollection/Feature/geometry dict, a file path or URL to a GeoJSON file, a JSON string, or any object with a `__geo_interface__` (e.g. a GeoDataFrame).	required
`name`	`str`	Layer display name.	`'GeoJSON'`
`**style`	`Any`	Style overrides (e.g. `fillColor="#ff0000"`).	`{}`

Returns:

Type	Description
`str`	The id of the added layer.

Note

File and URL sources are fetched and inlined into the project (up to the 50 MB GeoJSON limit), so a large dataset is carried in memory and re-synced over the widget bus on every subsequent project update. For very large layers, prefer a tile/COG source the app fetches directly.

add_gdf ¶

add_gdf(gdf: Any, name: str = 'GeoDataFrame', *, column: str | None = None, **style: Any) -> str

Add a GeoDataFrame, optionally styled by a numeric column.

add_kml ¶

add_kml(data: Any, name: str = 'KML', **style: Any) -> str

Add a local or remote KML/KMZ dataset.

add_gpkg ¶

add_gpkg(data: Any, name: str = 'GeoPackage', *, layer: str | None = None, **style: Any) -> str

Add a local or remote GeoPackage, optionally selecting a table.

add_polyline ¶

add_polyline(polyline: str | Sequence[str], name: str = 'Polyline', *, precision: int = 5, unescape: bool = False, **style: Any) -> str

Add an Encoded Polyline layer.

Parameters:

Name	Type	Description	Default
`polyline`	`str \| Sequence[str]`	A single polyline string (e.g. Google or Valhalla encoded) or a list of polyline strings.	required
`name`	`str`	Layer display name.	`'Polyline'`
`precision`	`int`	Decimal digits of precision (5 for Google/OSRM, 6 for Valhalla/Mapbox).	`5`
`unescape`	`bool`	Whether to unescape double-escaped backslashes before decoding.	`False`
`**style`	`Any`	Style overrides (e.g. `lineColor="#ff0000"`, `lineWidth=3`).	`{}`

Returns:

Type	Description
`str`	The id of the added layer.

add_marker ¶

add_marker(lng: float, lat: float, name: str = 'Marker', *, properties: dict[str, Any] | None = None, color: str | None = None, opacity: float | None = None, radius: float | None = None, stroke_color: str | None = None, stroke_width: float | None = None, shape: str | None = None, size: float | None = None, icon: str | None = None, **style: Any) -> str

Add a single point marker at [lng, lat].

The marker is a GeoJSON point layer; its properties are shown in a popup when the point is clicked while Identify is armed (see set_identify). See add_markers for the symbology and popup arguments, which behave identically here.

Parameters:

Name	Type	Description	Default
`lng`	`float`	Marker longitude.	required
`lat`	`float`	Marker latitude.	required
`name`	`str`	Layer display name.	`'Marker'`
`properties`	`dict[str, Any] \| None`	Optional feature properties (shown in the Identify popup).	`None`
`color`	`str \| None`	Marker color.	`None`
`opacity`	`float \| None`	Fill opacity in `[0, 1]`.	`None`
`radius`	`float \| None`	Circle radius in pixels.	`None`
`stroke_color`	`str \| None`	Outline color.	`None`
`stroke_width`	`float \| None`	Outline width in pixels.	`None`
`shape`	`str \| None`	Marker shape; switches to sprite rendering.	`None`
`size`	`float \| None`	Sprite size in pixels; switches to sprite rendering.	`None`
`icon`	`str \| None`	SVG markup or data URL for a custom sprite.	`None`
`**style`	`Any`	Further style overrides, plus `popup=`/`tooltip=` and the `popup_max_width=`/`popup_image_height=` size shorthands (see `add_markers`).	`{}`

Returns:

Type	Description
`str`	The id of the added layer.

add_markers ¶

add_markers(points: Any, name: str = 'Markers', *, color: str | None = None, opacity: float | None = None, radius: float | None = None, stroke_color: str | None = None, stroke_width: float | None = None, shape: str | None = None, size: float | None = None, icon: str | None = None, **style: Any) -> str

Add point markers from a collection of points.

Markers draw as MapLibre circles by default, sized by radius. Passing shape, size or icon switches the layer to a marker sprite instead, sized by size; radius no longer applies to it, and color must then be a hex color because that is all the sprite baker accepts.

Parameters:

Name	Type	Description	Default
`points`	`Any`	A sequence of `(lng, lat)` pairs or `{"lng"/"lon"/"x", "lat"/"y", **properties}` mappings, a GeoJSON point FeatureCollection/Feature/geometry, a GeoJSON string, or a `__geo_interface__` object (e.g. a point GeoDataFrame).	required
`name`	`str`	Layer display name.	`'Markers'`
`color`	`str \| None`	Marker color, e.g. `"#e11d48"`.	`None`
`opacity`	`float \| None`	Fill opacity in `[0, 1]`.	`None`
`radius`	`float \| None`	Circle radius in pixels (circle rendering only).	`None`
`stroke_color`	`str \| None`	Outline color.	`None`
`stroke_width`	`float \| None`	Outline width in pixels.	`None`
`shape`	`str \| None`	One of `"circle"`, `"square"`, `"triangle"`, `"diamond"`, `"star"`, `"cross"`, `"pin"`, or `"custom"` (which needs `icon`).	`None`
`size`	`float \| None`	Sprite size in pixels.	`None`
`icon`	`str \| None`	Raw SVG markup or a data URL drawn as a custom sprite.	`None`
`**style`	`Any`	Further style overrides, plus `popup=` and `tooltip=` to configure what a click and a hover show. `popup` takes a property name, a list of names or field mappings, or a config mapping; see `set_popup`. `popup_max_width=` and `popup_image_height=` size the popup and its pictures, in CSS pixels, without spelling out the rest of a config mapping.	`{}`

Returns:

Type	Description
`str`	The id of the added layer.

Example

m.add_markers( ... [{"lon": -122.9, "lat": 47.0, "name": "Olympia", "photo": url}], ... shape="pin", ... color="#e11d48", ... size=32, ... popup=["name", {"field": "photo", "kind": "image"}], ... tooltip="name", ... popup_max_width=480, ... popup_image_height=320, ... )

add_circle_markers ¶

add_circle_markers(points: Any, name: str = 'Circle Markers', *, radius: float | None = None, **style: Any) -> str

Add circle markers (point markers with an explicit radius).

Convenience over add_markers that surfaces radius as a named argument; everything else behaves the same.

Parameters:

Name	Type	Description	Default
`points`	`Any`	Points in any form accepted by `add_markers`.	required
`name`	`str`	Layer display name.	`'Circle Markers'`
`radius`	`float \| None`	Optional circle radius in pixels (sets `circleRadius`).	`None`
`**style`	`Any`	Additional style overrides.	`{}`

Returns:

Type	Description
`str`	The id of the added layer.

add_marker_cluster ¶

add_marker_cluster(points: Any, name: str = 'Marker Cluster', *, cluster_radius: int = 50, cluster_max_zoom: int = 14, **style: Any) -> str

Add clustered point markers.

Builds a GeoJSON point layer with the cluster renderer enabled, so nearby points collapse into count bubbles that split apart as you zoom in (the same clustering the UI's point renderer offers).

Parameters:

Name	Type	Description	Default
`points`	`Any`	Points in any form accepted by `add_markers`.	required
`name`	`str`	Layer display name.	`'Marker Cluster'`
`cluster_radius`	`int`	Cluster radius in pixels.	`50`
`cluster_max_zoom`	`int`	Zoom level beyond which points are no longer clustered.	`14`
`**style`	`Any`	Additional style overrides.	`{}`

Returns:

Type	Description
`str`	The id of the added layer.

add_heatmap ¶

add_heatmap(points: Any, name: str = 'Heatmap', *, radius: float = 30, intensity: float = 1, color_ramp: str = 'turbo', weight_field: str = '', **style: Any) -> str

Add point data using GeoLibre's density heatmap renderer.

Parameters:

Name	Type	Description	Default
`points`	`Any`	Points in any form accepted by `add_markers`.	required
`name`	`str`	Layer display name.	`'Heatmap'`
`radius`	`float`	Heatmap radius in pixels.	`30`
`intensity`	`float`	Heatmap intensity multiplier.	`1`
`color_ramp`	`str`	Name of the built-in heatmap color ramp.	`'turbo'`
`weight_field`	`str`	Numeric property used to weight each point, or an empty string to give every point equal weight.	`''`
`**style`	`Any`	Additional style overrides.	`{}`

Returns:

Type	Description
`str`	The id of the added layer.

add_xy_data ¶

add_xy_data(data: Any, x: str = 'longitude', y: str = 'latitude', name: str = 'XY Data', **style: Any) -> str

Add points from a DataFrame, CSV path/URL/text, or row mappings.

add_csv ¶

add_csv(data: Any, x: str = 'longitude', y: str = 'latitude', name: str = 'CSV', **style: Any) -> str

Add a CSV containing longitude and latitude columns.

add_choropleth ¶

add_choropleth(data: Any, column: str, name: str = 'Choropleth', *, class_count: int = 5, colormap: str = 'viridis', scheme: str = 'equal-interval', **style: Any) -> str

Add a GeoJSON layer with data-driven (graduated) symbology.

Classifies column into class_count numeric ranges and colors each range from colormap, building the same graduated symbology the Style panel produces from the UI. The stops are computed kernel-side from the data, so no precomputed styling is required.

Parameters:

Name	Type	Description	Default
`data`	`Any`	Any source accepted by `add_geojson` (a GeoJSON dict, file path, URL, JSON string, or GeoDataFrame).	required
`column`	`str`	The feature property to classify (must be numeric).	required
`name`	`str`	Layer display name.	`'Choropleth'`
`class_count`	`int`	Number of classes (clamped to at least 2).	`5`
`colormap`	`str`	A color ramp name (e.g. `"viridis"`, `"blues"`, `"rdylgn"`).	`'viridis'`
`scheme`	`str`	Classification scheme, `"equal-interval"` or `"quantile"`.	`'equal-interval'`
`**style`	`Any`	Additional style overrides.	`{}`

Returns:

Type	Description
`str`	The id of the added layer.

Raises:

Type	Description
`ValueError`	If the column is missing from every feature, or `scheme` is not supported.

add_data ¶

add_data(data: Any, column: str | None = None, name: str = 'Data', **kwargs: Any) -> str

Add data, optionally styled as a choropleth by column.

With column set this is add_choropleth; without it, a plain GeoJSON layer (add_geojson). Provided for leafmap parity.

Parameters:

Name	Type	Description	Default
`data`	`Any`	Any source accepted by `add_geojson`.	required
`column`	`str \| None`	Optional numeric property to drive graduated symbology.	`None`
`name`	`str`	Layer display name.	`'Data'`
`**kwargs`	`Any`	Forwarded to `add_choropleth` (when `column` is given) or `add_geojson`.	`{}`

Returns:

Type	Description
`str`	The id of the added layer.

add_tile_layer ¶

add_tile_layer(url: str, name: str = 'Tile Layer', *, tile_size: int = 256, attribution: str | None = None, bounds: list[float] | None = None, **style: Any) -> str

Add a raster XYZ tile layer.

Parameters:

Name	Type	Description	Default
`url`	`str`	An XYZ tile URL template (`{z}/{x}/{y}`).	required
`name`	`str`	Layer display name.	`'Tile Layer'`
`tile_size`	`int`	Tile size in pixels.	`256`
`attribution`	`str \| None`	Optional attribution string.	`None`
`bounds`	`list[float] \| None`	Optional `[west, south, east, north]` request bounds.	`None`
`**style`	`Any`	Style overrides.	`{}`

Returns:

Type	Description
`str`	The id of the added layer.

add_ee_layer ¶

add_ee_layer(ee_object: Any, vis_params: dict[str, Any] | None = None, name: str = 'Earth Engine', shown: bool = True, opacity: float = 1.0) -> str

Add a Google Earth Engine object as a raster tile layer.

This follows the geemap/leafmap convention: Earth Engine is evaluated in the Python kernel to obtain a map tile URL, while the GeoLibre app renders that URL as a normal raster layer. Earth Engine must already be authenticated and initialized (usually with ee.Authenticate() and ee.Initialize(project=...)).

Parameters:

Name	Type	Description	Default
`ee_object`	`Any`	An `ee.Image`, `ee.ImageCollection`, `ee.FeatureCollection`, `ee.Feature`, or `ee.Geometry`. A compatible object exposing `getMapId` is also accepted.	required
`vis_params`	`dict[str, Any] \| None`	Earth Engine visualization parameters, such as `bands`, `min`, `max`, and `palette`. For vector objects these are `ee.FeatureCollection.style()` keys instead (`color`, `fillColor`, `width`, `pointSize`, `pointShape`, `lineType`, `styleProperty`, `neighborhood`).	`None`
`name`	`str`	Layer display name.	`'Earth Engine'`
`shown`	`bool`	Whether the layer is initially visible.	`True`
`opacity`	`float`	Initial opacity between 0 and 1.	`1.0`

Returns:

Type	Description
`str`	The id of the added layer.

Raises:

Type	Description
`ImportError`	If conversion requires the optional Earth Engine Python package and it is not installed.
`TypeError`	If `ee_object` is not a supported Earth Engine object, or `vis_params` is not a mapping.
`ValueError`	If Earth Engine returns no usable tile URL, opacity is outside the range 0--1, or `vis_params` carries a key `ee.FeatureCollection.style()` does not accept.
`RuntimeError`	If Earth Engine fails to prepare the object or to create map tiles (for example when it is not initialized, or the request is rejected).

Note

The generated tile URL is tied to the Earth Engine map ID. A saved project may need the layer to be regenerated after that map ID expires.

The layer is a plain raster tile layer, not one of the live layers the app's own Earth Engine panel manages, so it is listed and styled like any other tile layer rather than appearing in that panel.

add_cog ¶

add_cog(url: str | PathLike[str], name: str = 'COG', *, bands: list[int] | None = None, colormap: str | None = None, rescale: list[list[float]] | None = None, **style: Any) -> str

Add a Cloud Optimized GeoTIFF (COG) layer.

Parameters:

Name	Type	Description	Default
`url`	`str \| PathLike[str]`	URL of the COG / GeoTIFF, or a path to a local GeoTIFF on the kernel host. A local file is served by the bundled static server so the app can read it; that URL lives only for this kernel session, so a project saved with a local raster will not restore the raster when reopened later. It is read directly in local Jupyter and VS Code. Colab renders it as PNG XYZ tiles in the kernel instead, and JupyterHub can route it through the kernel port when `jupyter-server-proxy` is available; a deployment that can only serve the app extension cannot expose kernel files, so pass a hosted URL there.	required
`name`	`str`	Layer display name.	`'COG'`
`bands`	`list[int] \| None`	Optional 1-based band indices to render.	`None`
`colormap`	`str \| None`	Optional colormap name (single-band rendering).	`None`
`rescale`	`list[list[float]] \| None`	Optional `[[min, max], ...]` ranges per band.	`None`
`**style`	`Any`	Style overrides.	`{}`

Returns:

Type	Description
`str`	The id of the added layer.

add_raster ¶

add_raster(source: Any = None, name: str = 'Raster', *, url: str | PathLike[str] | None = None, bands: list[int] | None = None, colormap: str | None = None, rescale: list[list[float]] | None = None, array_args: dict[str, Any] | None = None, **style: Any) -> str

Add a raster from a COG, GeoTIFF, or xarray object.

URLs and paths are passed to add_cog. An xarray.DataArray or xarray.Dataset is first materialized as a temporary GeoTIFF using rioxarray. Longitude/latitude dimensions imply EPSG:4326; other dimension names require georeferencing through the object's .rio accessor or array_args.

The temporary GeoTIFF is removed by close, and, if that is never called, when the Map is garbage collected or the interpreter exits normally. A killed kernel leaves the file in the system temp directory.

Parameters:

Name	Type	Description	Default
`source`	`Any`	URL or path of a COG / GeoTIFF, or an `xarray.DataArray` / `xarray.Dataset`.	`None`
`name`	`str`	Layer display name.	`'Raster'`
`url`	`str \| PathLike[str] \| None`	Deprecated alias of `source`, kept because this method used to name its first parameter `url` (as `add_cog` still does). Passing it emits a `DeprecationWarning`.	`None`
`bands`	`list[int] \| None`	Optional 1-based band indices to render.	`None`
`colormap`	`str \| None`	Optional colormap name (single-band rendering).	`None`
`rescale`	`list[list[float]] \| None`	Optional `[[min, max], ...]` ranges per band.	`None`
`array_args`	`dict[str, Any] \| None`	Options used only for xarray inputs. `variable` selects one Dataset variable, `isel` slices extra dimensions, and `x_dim`, `y_dim`, `crs`, and `nodata` override the corresponding spatial metadata. Remaining options are passed to `rio.to_raster`.	`None`
`**style`	`Any`	Style overrides.	`{}`

Returns:

Type	Description
`str`	The id of the added layer.

add_wms ¶

add_wms(endpoint: str, layers: str, name: str = 'WMS Layer', *, styles: str = '', image_format: str = 'image/png', transparent: bool = True, tile_size: int = 256, version: str | None = '1.1.1', crs: str | None = None, bounds: list[float] | None = None, **style: Any) -> str

Add a WMS layer rendered as tiled raster (a WMS GetMap request).

Parameters:

Name	Type	Description	Default
`endpoint`	`str`	WMS service endpoint (the GetMap base URL).	required
`layers`	`str`	Comma-separated WMS layer name(s).	required
`name`	`str`	Layer display name.	`'WMS Layer'`
`styles`	`str`	Comma-separated WMS style name(s) (empty for the default).	`''`
`image_format`	`str`	WMS image format (e.g. `"image/png"`).	`'image/png'`
`transparent`	`bool`	Whether to request transparent tiles.	`True`
`tile_size`	`int`	Tile size in pixels.	`256`
`version`	`str \| None`	WMS protocol version, `"1.1.1"` (default) or `"1.3.0"`. Version 1.3.0 sends `CRS` instead of `SRS`; some servers accept only one version.	`'1.1.1'`
`crs`	`str \| None`	The CRS tiles are requested in, `"EPSG:3857"` when None. For a server without Web Mercator, a CRS it lists: a geographic one (`"EPSG:4326"`, `"EPSG:4258"`, `"EPSG:6706"`, `"CRS:84"`) or a projected `"EPSG:<code>"` such as `"EPSG:25832"`. The desktop app redraws those tiles into Web Mercator.	`None`
`bounds`	`list[float] \| None`	Optional `[west, south, east, north]` request bounds, in WGS84. A WMS layer has no geometry to derive an extent from, so without these "zoom to layer" cannot reach it.	`None`
`**style`	`Any`	Style overrides.	`{}`

Returns:

Type	Description
`str`	The id of the added layer.

Raises:

Type	Description
`ValueError`	If `bounds` is not four finite numbers with valid latitudes, or `crs` is not a supported CRS.

add_wmts ¶

add_wmts(url: str, name: str = 'WMTS Layer', *, tile_size: int = 256, bounds: list[float] | None = None, **style: Any) -> str

Add a WMTS layer from a tile URL template.

Parameters:

Name	Type	Description	Default
`url`	`str`	A WMTS tile URL template (`{z}/{y}/{x}`).	required
`name`	`str`	Layer display name.	`'WMTS Layer'`
`tile_size`	`int`	Tile size in pixels.	`256`
`bounds`	`list[float] \| None`	Optional `[west, south, east, north]` request bounds, in WGS84.	`None`
`**style`	`Any`	Style overrides.	`{}`

Returns:

Type	Description
`str`	The id of the added layer.

Raises:

Type	Description
`ValueError`	If `bounds` is not four finite numbers with valid latitudes.

add_wfs ¶

add_wfs(endpoint: str, type_name: str, name: str = 'WFS Layer', *, version: str = '2.0.0', output_format: str = 'application/json', srs_name: str = 'EPSG:4326', max_features: int | None = 1000, **style: Any) -> str

Add a WFS layer.

The WFS GetFeature response (GeoJSON) is fetched and inlined into the project, so the endpoint must support a GeoJSON output_format.

Parameters:

Name	Type	Description	Default
`endpoint`	`str`	WFS service endpoint.	required
`type_name`	`str`	WFS feature type name (e.g. `"topp:states"`).	required
`name`	`str`	Layer display name.	`'WFS Layer'`
`version`	`str`	WFS protocol version (e.g. `"2.0.0"` or `"1.1.0"`).	`'2.0.0'`
`output_format`	`str`	Requested output format (must yield GeoJSON).	`'application/json'`
`srs_name`	`str`	Spatial reference of the response.	`'EPSG:4326'`
`max_features`	`int \| None`	Cap on the number of returned features (defaults to 1000, matching the UI, since the response is inlined). Pass `None` to request every feature.	`1000`
`**style`	`Any`	Style overrides.	`{}`

Returns:

Type	Description
`str`	The id of the added layer.

add_vector ¶

add_vector(data: Any, name: str = 'Vector', *, render_mode: str = 'geojson', data_format: str | None = None, source_layer: str | None = None, **style: Any) -> str

Add a vector layer from a URL, a local file, or a geo object.

A remote URL is handed to the in-browser vector control (so any GDAL-readable format streams without being inlined). A local file path is read with GeoPandas and inlined as GeoJSON, since the browser cannot read a kernel-side file. An object exposing __geo_interface__ (e.g. a GeoDataFrame) is inlined directly.

Parameters:

Name	Type	Description	Default
`data`	`Any`	A dataset URL, a local file path, or a `__geo_interface__` object.	required
`name`	`str`	Layer display name.	`'Vector'`
`render_mode`	`str`	`"geojson"` or `"tiles"` (remote URLs only).	`'geojson'`
`data_format`	`str \| None`	Optional GDAL format hint for remote URLs (e.g. `"parquet"`, `"flatgeobuf"`).	`None`
`source_layer`	`str \| None`	Optional source/container layer for multi-layer files.	`None`
`**style`	`Any`	Style overrides.	`{}`

Returns:

Type	Description
`str`	The id of the added layer.

Raises:

Type	Description
`ImportError`	If a local file is given but GeoPandas is not installed.
`ValueError`	If a local file path does not exist.

add_geoparquet ¶

add_geoparquet(data: Any, name: str = 'GeoParquet', **style: Any) -> str

Add a GeoParquet layer from a URL or local file.

Parameters:

Name	Type	Description	Default
`data`	`Any`	A GeoParquet URL or local file path.	required
`name`	`str`	Layer display name.	`'GeoParquet'`
`**style`	`Any`	Style overrides.	`{}`

Returns:

Type	Description
`str`	The id of the added layer.

add_flatgeobuf ¶

add_flatgeobuf(data: Any, name: str = 'FlatGeobuf', **style: Any) -> str

Add a FlatGeobuf layer from a URL or local file.

Parameters:

Name	Type	Description	Default
`data`	`Any`	A FlatGeobuf URL or local file path.	required
`name`	`str`	Layer display name.	`'FlatGeobuf'`
`**style`	`Any`	Style overrides.	`{}`

Returns:

Type	Description
`str`	The id of the added layer.

add_shp ¶

add_shp(data: Any, name: str = 'Shapefile', **style: Any) -> str

Add a Shapefile layer from a URL (zipped) or local file.

Parameters:

Name	Type	Description	Default
`data`	`Any`	A zipped Shapefile URL or a local `.shp` path.	required
`name`	`str`	Layer display name.	`'Shapefile'`
`**style`	`Any`	Style overrides.	`{}`

Returns:

Type	Description
`str`	The id of the added layer.

add_vector_tiles ¶

add_vector_tiles(url: str, name: str = 'Vector Tiles', *, source_layers: list[str] | None = None, source_layer: str | None = None, **style: Any) -> str

Add a vector tile layer from a TileJSON endpoint.

Parameters:

Name	Type	Description	Default
`url`	`str`	TileJSON endpoint for the vector tileset.	required
`name`	`str`	Layer display name.	`'Vector Tiles'`
`source_layers`	`list[str] \| None`	Source-layer names to render (multi-layer tilesets).	`None`
`source_layer`	`str \| None`	A single source-layer name (single-layer convenience).	`None`
`**style`	`Any`	Style overrides.	`{}`

Returns:

Type	Description
`str`	The id of the added layer.

add_pmtiles ¶

add_pmtiles(url: str, name: str = 'PMTiles', *, tile_type: str = 'vector', source_layers: list[str] | None = None, **style: Any) -> str

Add a PMTiles layer from a .pmtiles URL.

Parameters:

Name	Type	Description	Default
`url`	`str`	URL of the `.pmtiles` archive.	required
`name`	`str`	Layer display name.	`'PMTiles'`
`tile_type`	`str`	`"vector"` or `"raster"`.	`'vector'`
`source_layers`	`list[str] \| None`	Vector source-layer names to render (vector only).	`None`
`**style`	`Any`	Style overrides.	`{}`

Returns:

Type	Description
`str`	The id of the added layer.

add_3d_tiles ¶

add_3d_tiles(url: str | None = None, name: str = '3D Tiles', *, ion_asset_id: int | None = None, altitude_offset: float = 0, request_headers: dict[str, str] | None = None, **style: Any) -> str

Add a 3D Tiles layer from a tileset.json URL or a Cesium Ion asset.

Parameters:

Name	Type	Description	Default
`url`	`str \| None`	URL of the 3D Tiles `tileset.json`. Omit for an Ion asset.	`None`
`name`	`str`	Layer display name.	`'3D Tiles'`
`ion_asset_id`	`int \| None`	A Cesium Ion asset id (for example 96188, Cesium OSM Buildings). Renders on the 3D globe only, with the app's Ion token.	`None`
`altitude_offset`	`float`	Vertical offset applied to the tileset, in meters.	`0`
`request_headers`	`dict[str, str] \| None`	Optional request headers (persisted in the project).	`None`
`**style`	`Any`	Style overrides.	`{}`

Returns:

Type	Description
`str`	The id of the added layer.

add_lidar ¶

add_lidar(url: str, name: str | None = None, **style: Any) -> str

Add a LiDAR point cloud from a LAS, LAZ, COPC or EPT URL.

COPC and EPT stream by level of detail; LAS/LAZ download whole. Open the app's Plugins → Point Cloud Annotation to label its points.

Parameters:

Name	Type	Description	Default
`url`	`str`	HTTP(S) URL of a `.las`, `.laz`, `.copc.laz` file or an EPT `ept.json`.	required
`name`	`str \| None`	Layer display name (defaults to the file name).	`None`
`**style`	`Any`	Style overrides.	`{}`

Returns:

Type	Description
`str`	The id of the added layer.

add_icesat2 ¶

add_icesat2(source: str | PathLike[str], name: str | None = None, *, beams: Sequence[str] | None = None, fields: Sequence[Any] | None = None, quality_filter: bool = True, bbox: Sequence[float] | None = None, max_points: int | None = 100000, color_by: str | None = None, colormap: str = 'viridis', **style: Any) -> str

Add ICESat-2 ATL06 or ATL08 footprints from an HDF5 granule.

Reads the granule locally (with h5py) the way the app's Add Data → ICESat-2 / GEDI does: one point per along-track segment in each ground track, the product's quality filter applied, and beam, beam_type (strong/weak), time and distance_km on every point, colored by the main field (h_li for ATL06, h_te_best_fit for ATL08). Download granules with earthaccess (earthaccess.download(...)) or from NASA Earthdata Search.

Parameters:

Name	Type	Description	Default
`source`	`str \| PathLike[str]`	Path to an ATL06 or ATL08 `.h5` granule.	required
`name`	`str \| None`	Layer name; `"<product> <file name>"` by default.	`None`
`beams`	`Sequence[str] \| None`	Ground tracks to read, e.g. `["gt1l", "gt2l"]` (all by default).	`None`
`fields`	`Sequence[Any] \| None`	Fields to attach: default names (`"h_canopy"`) or dataset paths relative to the ground track (the product defaults when omitted).	`None`
`quality_filter`	`bool`	Drop segments the product's quality flag rejects.	`True`
`bbox`	`Sequence[float] \| None`	`[west, south, east, north]` to keep only segments inside.	`None`
`max_points`	`int \| None`	Cap on points; every beam is thinned evenly to stay under it. `None` keeps every segment.	`100000`
`color_by`	`str \| None`	Field to color by; `""` for a single color.	`None`
`colormap`	`str`	Color ramp for the graduated colors.	`'viridis'`
`**style`	`Any`	Style overrides (e.g. `circleRadius=4`).	`{}`

Returns:

Type	Description
`str`	The id of the added layer.

Raises:

Type	Description
`ImportError`	Without h5py (`pip install "geolibre[spaceborne]"`).
`ValueError`	For a GEDI or unsupported granule, or no footprints kept.

add_gedi ¶

add_gedi(source: str | PathLike[str], name: str | None = None, *, beams: Sequence[str] | None = None, fields: Sequence[Any] | None = None, quality_filter: bool = True, bbox: Sequence[float] | None = None, max_points: int | None = 100000, color_by: str | None = None, colormap: str = 'viridis', **style: Any) -> str

Add GEDI L2A, L2B or L4A shots from an HDF5 granule.

Reads the granule locally (with h5py) the way the app's Add Data → ICESat-2 / GEDI does: one point per shot in each beam, the product's quality flag applied, and beam, beam_type (power/coverage), time and distance_km on every point, colored by the main field (rh98 for L2A, cover for L2B, agbd for L4A). A full orbit holds millions of shots, so pass bbox for a regional subset.

Parameters:

Name	Type	Description	Default
`source`	`str \| PathLike[str]`	Path to a GEDI L2A, L2B or L4A `.h5` granule.	required
`name`	`str \| None`	Layer name; `"<product> <file name>"` by default.	`None`
`beams`	`Sequence[str] \| None`	Beams to read, e.g. `["BEAM0101"]` (all by default).	`None`
`fields`	`Sequence[Any] \| None`	Fields to attach: default names (`"rh50"`) or dataset paths relative to the beam (the product defaults when omitted).	`None`
`quality_filter`	`bool`	Drop shots the product's quality flag rejects.	`True`
`bbox`	`Sequence[float] \| None`	`[west, south, east, north]` to keep only shots inside.	`None`
`max_points`	`int \| None`	Cap on points; every beam is thinned evenly to stay under it. `None` keeps every shot.	`100000`
`color_by`	`str \| None`	Field to color by; `""` for a single color.	`None`
`colormap`	`str`	Color ramp for the graduated colors.	`'viridis'`
`**style`	`Any`	Style overrides (e.g. `circleRadius=4`).	`{}`

Returns:

Type	Description
`str`	The id of the added layer.

Raises:

Type	Description
`ImportError`	Without h5py (`pip install "geolibre[spaceborne]"`).
`ValueError`	For an ICESat-2 or unsupported granule, or no shots kept.

point_cloud_annotations ¶

point_cloud_annotations() -> dict[str, Any]

The point labels and 3D boxes saved by the app's point cloud annotator.

Returns:

Type	Description
`dict[str, Any]`	`{"labels", "instances", "boxes", "classes"}`; see
`dict[str, Any]`	`geolibre.project.point_cloud_annotations`. Apply the
`dict[str, Any]`	labels of a whole-file LAS/LAZ source to `laspy` data with
`dict[str, Any]`	`geolibre.project.apply_point_labels`.

prelabel_point_cloud ¶

prelabel_point_cloud(url: str, input_file: str, tool: str = 'ground', *, only_unclassified: bool = True) -> dict[str, int]

Pre-label a LiDAR layer with a Whitebox classifier, without the app.

Runs the app's Pre-label classifiers on a local copy of the layer's file and saves the changed classes as annotator labels for the layer, so they show when the project opens. Needs geolibre[pointcloud].

Parameters:

Name	Type	Description	Default
`url`	`str`	The LiDAR layer's source URL (as passed to `add_lidar`).	required
`input_file`	`str`	A local copy of that point cloud (LAS/LAZ/COPC).	required
`tool`	`str`	`"ground"` or `"ground-vegetation"`.	`'ground'`
`only_unclassified`	`bool`	Only relabel points still 0 or 1.	`True`

Returns:

Type	Description
`dict[str, int]`	Class code -> number of points relabelled into it.

Raises:

Type	Description
`ValueError`	When no LiDAR layer uses `url`, or for an unknown tool.

write_labeled_point_cloud ¶

write_labeled_point_cloud(url: str, input_file: str, output_file: str) -> dict[str, int]

Write a LiDAR layer's file with this map's point labels applied.

Streams input_file (a local copy of the layer's LAS/LAZ/COPC file) and writes every point with the annotator's saved classes and instance ids applied. Needs geolibre[pointcloud].

Parameters:

Name	Type	Description	Default
`url`	`str`	The LiDAR layer's source URL whose labels to apply.	required
`input_file`	`str`	A local copy of that point cloud.	required
`output_file`	`str`	The `.las` or `.laz` file to write.	required

Returns:

Type	Description
`dict[str, int]`	`{"points", "relabelled", "instanced"}` counts.

set_point_cloud_classes ¶

set_point_cloud_classes(classes: list[dict[str, Any]]) -> list[dict[str, Any]]

Define custom point cloud classes for the app's annotator.

Custom classes (codes 19-255) extend the ASPRS standard classes: the annotator can assign them, and the LiDAR layer draws them in their colour and names them in its legend.

Parameters:

Name	Type	Description	Default
`classes`	`list[dict[str, Any]]`	`{"code", "name", "color"}` dicts, e.g. `[{"code": 64, "name": "Car", "color": "#e11d48"}]`; `color` may also be an `(r, g, b)` triple. An empty list clears them.	required

Returns:

Type	Description
`list[dict[str, Any]]`	The validated classes as saved.

Raises:

Type	Description
`ValueError`	For an invalid class.

add_cesium_ion ¶

add_cesium_ion(asset_id: int, name: str = 'Cesium Ion asset', *, kind: str = '3d-tiles', altitude_offset: float = 0, **style: Any) -> str

Add a Cesium Ion asset (a 3D Tiles tileset or imagery) by asset id.

The layer renders on the 3D globe only, which loads it with the app's Cesium Ion token; the token is never written to the project.

Parameters:

Name	Type	Description	Default
`asset_id`	`int`	The Cesium Ion asset id (a positive integer).	required
`name`	`str`	Layer display name.	`'Cesium Ion asset'`
`kind`	`str`	`"3d-tiles"` for a tileset or `"imagery"` for an imagery asset.	`'3d-tiles'`
`altitude_offset`	`float`	Vertical offset applied to a tileset, in meters.	`0`
`**style`	`Any`	Style overrides.	`{}`

Returns:

Type	Description
`str`	The id of the added layer.

add_czml ¶

add_czml(url: str | None = None, name: str = 'CZML scene', *, data: list[dict[str, Any]] | dict[str, Any] | None = None, source_path: str | None = None, **style: Any) -> str

Add a CZML (Cesium Language) dynamic 3D scene.

CZML describes time-varying scenes (satellite orbits, vehicle tracks, moving models with paths). The 3D globe loads it natively and follows the document's clock; the 2D map badges the layer "3D only".

Parameters:

Name	Type	Description	Default
`url`	`str \| None`	URL of a `.czml` document.	`None`
`name`	`str`	Layer display name.	`'CZML scene'`
`data`	`list[dict[str, Any]] \| dict[str, Any] \| None`	Inline CZML packets (a list, or one packet dict) instead of a URL.	`None`
`source_path`	`str \| None`	Local path the document was loaded from, if any.	`None`
`**style`	`Any`	Style overrides.	`{}`

Returns:

Type	Description
`str`	The id of the added layer.

Raises:

Type	Description
`ValueError`	If neither `url` nor `data` is given.

add_cesium_kml ¶

add_cesium_kml(url: str | None = None, name: str = 'KML / KMZ', *, data: str | None = None, source_path: str | None = None, **style: Any) -> str

Add native KML/KMZ on the globe, preserving document styling.

Supply a URL, inline XML, or a KMZ data URL. Use add_kml for the vector conversion that works on both rendering engines.

add_video ¶

add_video(urls: str | list[str], coordinates: list[list[float]], name: str = 'Video', **style: Any) -> str

Add a georeferenced video layer.

Parameters:

Name	Type	Description	Default
`urls`	`str \| list[str]`	One video URL or a list of format fallbacks (e.g. MP4, WebM).	required
`coordinates`	`list[list[float]]`	Four `[lng, lat]` corners in top-left, top-right, bottom-right, bottom-left order.	required
`name`	`str`	Layer display name.	`'Video'`
`**style`	`Any`	Style overrides.	`{}`

Returns:

Type	Description
`str`	The id of the added layer.

remove_layer ¶

remove_layer(layer_id: str | Layer) -> None

Remove a layer by id, display name, or handle.

Parameters:

Name	Type	Description	Default
`layer_id`	`str \| Layer`	A layer id, display name, or `Layer` handle.	required

Raises:

Type	Description
`ValueError`	If the reference matches no layer, or matches a display name several layers share. Removing an unknown layer used to be a silent no-op; it now reports the miss.

clear_layers ¶

clear_layers() -> None

Remove all layers from the map.

add_basemap ¶

add_basemap(basemap: str) -> None

Set the background basemap style.

Parameters:

Name	Type	Description	Default
`basemap`	`str`	A basemap name or MapLibre style URL.	required

set_basemap ¶

set_basemap(basemap: str) -> None

Set the background basemap style (alias of add_basemap).

Parameters:

Name	Type	Description	Default
`basemap`	`str`	A basemap name or MapLibre style URL.	required

set_center ¶

set_center(lng: float, lat: float, zoom: float | None = None) -> None

Center the map, optionally setting the zoom.

Parameters:

Name	Type	Description	Default
`lng`	`float`	Longitude of the new center.	required
`lat`	`float`	Latitude of the new center.	required
`zoom`	`float \| None`	Optional zoom level.	`None`

set_renderer ¶

set_renderer(renderer: str, *, pane_id: str | None = None) -> None

Select maplibre, cesium, mapbox or arcgis for the primary map or a named pane.

get_renderer ¶

get_renderer(*, pane_id: str | None = None) -> str

Read the primary renderer or a secondary pane's viewKind.

set_map_layout ¶

set_map_layout(rows: int, cols: int, *, view_kinds: list[str] | None = None, sync_view: bool = True) -> None

Configure a grid; view_kinds lists all pane renderers, primary first.

set_zoom ¶

set_zoom(zoom: float) -> None

Set the map zoom while preserving the other camera fields.

set_bearing ¶

set_bearing(bearing: float) -> None

Set clockwise camera bearing in degrees.

set_pitch ¶

set_pitch(pitch: float) -> None

Set camera pitch in degrees (clamped to the supported range).

fit_project_bounds ¶

fit_project_bounds(bounds: list[float] | tuple[float, float, float, float]) -> None

Persist a fitted camera for [west, south, east, north] bounds.

Unlike fit_bounds, this is a pure project mutation and does not require a live browser connection.

set_identify ¶

set_identify(layer: str | Layer | Sequence[str | Layer] | None = 'all') -> None

Arm the Identify tool so clicking a feature opens its popup.

Popups (including those configured with set_popup or the popup= argument of add_markers) open only while Identify is armed. This does from Python what the Identify button on a layer, or the "Identify visible layers" button in the Layers panel header, does in the app. The choice is applied when the map loads, so it can be made before the map is displayed.

Identify is armed on one layer, on a list of layers, or on every visible layer, and hover tooltips pause while it is armed, as they do in the app. The choice is saved by save_project, to_project and to_html, so a shared map opens with Identify armed the same way.

Parameters:

Name	Type	Description	Default
`layer`	`str \| Layer \| Sequence[str \| Layer] \| None`	A layer id, display name, or `Layer` handle to identify on that layer; a list of them to identify only those layers (clicking opens popups for them and not for the rest); `"all"` (the default) to identify every visible queryable layer; or `None` to turn Identify off. `"all"` is matched before the lookup, so a layer whose id or display name is literally `"all"` cannot be targeted on its own.	`'all'`

Raises:

Type	Description
`ValueError`	If `layer` (or any entry of a list) matches no layer, or a list is empty.

show_control ¶

show_control(name: str, visible: bool = True, *, collapsed: bool | None = None, distance_unit: str | None = None, area_unit: str | None = None) -> None

Show (or hide) a map control or toolbar panel.

Covers the panels in the app's Controls menu ("bookmark", "search", "measure", "minimap", "print") and the built-in map controls ("navigation", "fullscreen", "compass", "geolocate", "globe", "scale", "attribution", "logo"). The choice is applied when the map loads, so it can be made before the map is displayed. It is saved by save_project, to_project and to_html, so a shared map opens with the same controls.

Hiding "globe" removes the globe/flat toggle button only; use set_projection to change how the map is drawn.

The Measure panel opens expanded with the tool active, so a viewer's first clicks on the map place measurement points. For a shared map, m.show_control("measure", collapsed=True) shows only its ruler button until the viewer clicks it, and distance_unit / area_unit pick the units it starts in.

Parameters:

Name	Type	Description	Default
`name`	`str`	The control or panel name.	required
`visible`	`bool`	`True` to show it, `False` to hide it.	`True`
`collapsed`	`bool \| None`	For `"measure"` and `"minimap"`, `True` shows only the control's on-map button, `False` opens it expanded. `None` (the default) keeps the app's default, expanded.	`None`
`distance_unit`	`str \| None`	For `"measure"`, the distance unit: one of `"meters"`, `"kilometers"` (the app's default), `"miles"`, `"feet"`, `"yards"` or `"nautical-miles"`.	`None`
`area_unit`	`str \| None`	For `"measure"`, the area unit: one of `"square-meters"`, `"square-kilometers"` (the app's default), `"square-miles"`, `"hectares"`, `"acres"` or `"square-feet"`.	`None`

Raises:

Type	Description
`ValueError`	If `name` is not a known control or panel, or an option does not apply to it or has an unknown value.

hide_control ¶

hide_control(name: str) -> None

Hide a map control or toolbar panel (see show_control).

Parameters:

Name	Type	Description	Default
`name`	`str`	The control or panel name.	required

set_projection ¶

set_projection(projection: str) -> None

Draw the map as a 3D globe or as a flat Web Mercator map.

New maps use "globe", which shows the Earth as a sphere at low zooms. The projection is saved in the project.

Parameters:

Name	Type	Description	Default
`projection`	`str`	`"globe"` or `"mercator"`.	required

Raises:

Type	Description
`ValueError`	If `projection` is not one of the two.

split_map ¶

split_map(left_layers: Any = None, right_layers: Any = None, *, orientation: str = 'vertical', position: float = 50, control_position: str = 'top-left') -> None

Add a swipe (split-map) comparison slider between two layer sets.

Enables the Layer Swipe control, which clips the left/top layers to one side of a draggable slider and the right/bottom layers to the other, for before/after comparisons. Drives the app's built-in swipe plugin through the project, so it appears with no reload.

Parameters:

Name	Type	Description	Default
`left_layers`	`Any`	Layer(s) shown on the left/top of the slider, as a layer id, a `Layer`, or a list of those. The string `"__basemap__"` selects the basemap.	`None`
`right_layers`	`Any`	Layer(s) shown on the right/bottom of the slider, in the same forms as `left_layers`.	`None`
`orientation`	`str`	`"vertical"` (slider moves left/right) or `"horizontal"` (slider moves up/down).	`'vertical'`
`position`	`float`	Initial slider position as a percentage in `[0, 100]`.	`50`
`control_position`	`str`	Corner for the swipe panel; one of `"top-left"`, `"top-right"`, `"bottom-left"`, `"bottom-right"`.	`'top-left'`

Raises:

Type	Description
`ValueError`	If `orientation`, `control_position`, or a layer reference is invalid.

add_legend ¶

add_legend(title: str | None = None, *, legend_dict: dict[str, str] | None = None, labels: list[str] | None = None, colors: list[str] | None = None, builtin: str | None = None, position: str = 'bottom-left', shape: str = 'square') -> None

Add a legend to the map.

Supply the legend entries one of three ways: a built-in preset (builtin), a {label: color} mapping (legend_dict), or parallel labels and colors lists. Each call adds another legend, so a map can carry several at once.

Parameters:

Name	Type	Description	Default
`title`	`str \| None`	Legend title. Defaults to `"Legend"`, or the preset's title when `builtin` is given and no title is passed.	`None`
`legend_dict`	`dict[str, str] \| None`	A mapping of label to CSS color (preserves order).	`None`
`labels`	`list[str] \| None`	Item labels, paired position-wise with `colors`.	`None`
`colors`	`list[str] \| None`	Item CSS colors, paired position-wise with `labels`.	`None`
`builtin`	`str \| None`	A built-in preset name (e.g. `"nlcd"`, `"esa_worldcover"`). See `geolibre.legends.builtin_legend_names`.	`None`
`position`	`str`	Corner for the legend; one of `"top-left"`, `"top-right"`, `"bottom-left"`, `"bottom-right"`.	`'bottom-left'`
`shape`	`str`	Swatch shape for every item; `"square"`, `"circle"`, or `"line"`.	`'square'`

Raises:

Type	Description
`ValueError`	If no entries are supplied, `labels`/`colors` lengths differ, or `position`/`shape`/`builtin` is invalid.

set_map_legend ¶

set_map_legend(title: str | None = None, *, position: str | None = None, group_by_layer: bool | None = None, visible: bool | None = None, collapsed: bool | None = None) -> None

Show the map legend, the panel behind the app's Controls -> Legend.

Its rows come from each visible layer's symbology, so a classified or categorized layer gets a matching legend without restating its colors (use add_legend for hand-written entries). A map has one; calling this again updates it.

Parameters:

Name	Type	Description	Default
`title`	`str \| None`	Heading drawn above the entries; keeps the current one when omitted.	`None`
`position`	`str \| None`	`"top-left"`, `"top-right"`, `"bottom-left"`, or `"bottom-right"`; keeps the current corner when omitted.	`None`
`group_by_layer`	`bool \| None`	Group each layer's classes under a layer heading; keeps the current setting when omitted.	`None`
`visible`	`bool \| None`	Whether the on-map panel is open; keeps the current state when omitted, and opens it when the map has no legend yet.	`None`
`collapsed`	`bool \| None`	Whether the open panel is collapsed to its header bar; keeps the current state when omitted.	`None`

Raises:

Type	Description
`ValueError`	If `position` is not a map corner.

add_colorbar ¶

add_colorbar(*, colormap: str = 'viridis', vmin: float = 0.0, vmax: float = 1.0, label: str = '', units: str = '', colors: list[str] | None = None, orientation: str = 'vertical', position: str = 'bottom-right') -> None

Add a colorbar for a continuous (single-band) raster.

Renders a gradient with min/max ticks, from either a named colormap or an explicit list of CSS colors. Each call adds another colorbar.

Parameters:

Name	Type	Description	Default
`colormap`	`str`	A named colormap (e.g. `"viridis"`, `"plasma"`, `"inferno"`, `"magma"`, `"cividis"`, `"turbo"`, `"terrain"`). Ignored when `colors` is given.	`'viridis'`
`vmin`	`float`	Value at the low end of the colorbar.	`0.0`
`vmax`	`float`	Value at the high end of the colorbar.	`1.0`
`label`	`str`	Title shown alongside the colorbar.	`''`
`units`	`str`	Units suffix shown with the values.	`''`
`colors`	`list[str] \| None`	Optional list of CSS colors defining a custom gradient; when given, the colorbar uses these instead of `colormap`.	`None`
`orientation`	`str`	`"vertical"` or `"horizontal"`.	`'vertical'`
`position`	`str`	Corner for the colorbar; one of `"top-left"`, `"top-right"`, `"bottom-left"`, `"bottom-right"`.	`'bottom-right'`

Raises:

Type	Description
`ValueError`	If `orientation` or `position` is invalid, `vmin` is not less than `vmax`, or `colors` is given but empty.

add_colormap ¶

add_colormap(colormap: str = 'viridis', *, vmin: float = 0.0, vmax: float = 1.0, label: str = '', **kwargs: Any) -> None

Add a colorbar from a named colormap (alias of add_colorbar).

Provided for leafmap parity; colormap is positional here.

Parameters:

Name	Type	Description	Default
`colormap`	`str`	A named colormap (see `add_colorbar`).	`'viridis'`
`vmin`	`float`	Value at the low end of the colorbar.	`0.0`
`vmax`	`float`	Value at the high end of the colorbar.	`1.0`
`label`	`str`	Title shown alongside the colorbar.	`''`
`**kwargs`	`Any`	Forwarded to `add_colorbar` (e.g. `units`, `orientation`, `position`).	`{}`

to_project ¶

to_project(*, keep_credentials: bool = False) -> dict[str, Any]

Return a detached project dict.

Credentials are removed by default so a returned project is safe to serialize or commit. Pass keep_credentials=True only for a trusted local workflow that must preserve authenticated layer configuration.

The Identify target and control visibility set with set_identify and show_control are included as the project's interaction block.

load_project ¶

load_project(source: Any) -> None

Replace the current project.

Parameters:

Name	Type	Description	Default
`source`	`Any`	A project dict, a JSON string, or a path to a `.geolibre.json` file.	required

Raises:

Type	Description
`ValueError`	If the source is not valid JSON or an existing file, or if the project is not a dict or is missing required top-level keys (`version`, `name`, `mapView`).

save_project ¶

save_project(path: str, *, keep_credentials: bool = False) -> None

Write the current project to a .geolibre.json file.

Like to_project, the file carries the Identify target and control visibility as its interaction block.

Parameters:

Name	Type	Description	Default
`path`	`str`	Destination file path. Parent directories are created if they do not already exist.	required
`keep_credentials`	`bool`	Preserve credentials for a trusted local file. Defaults to `False` so saved projects are safe to share.	`False`

Feature ¶

Bases: dict

A GeoJSON feature with convenience accessors.

A Feature is a plain dict, so it serializes to JSON and feeds straight into tools that consume GeoJSON (e.g. geopandas.GeoDataFrame.from_features), while also offering attribute-style access to the common members.

geometry `property` ¶

geometry: Any

The feature's GeoJSON geometry, or None.

properties `property` ¶

properties: dict[str, Any]

The feature's properties mapping (empty dict if absent).

id `property` ¶

id: Any

The feature's id, or None.

Layer ¶

Layer(m: Map, layer_id: str)

A handle to one layer on a Map.

Reads reflect the live project; property setters and remove mutate the project through the same synced trait the rest of the API uses, so edits propagate to the running app. Query helpers (get_features, zoom_to) round-trip to the app.

Bind a layer handle.

Parameters:

Name	Type	Description	Default
`m`	`Map`	The owning map.	required
`layer_id`	`str`	The layer's id.	required

id `property` ¶

id: str

The layer id.

type `property` ¶

type: Any

The layer type (e.g. "geojson", "raster").

name `property` `writable` ¶

name: Any

The layer's display name.

visible `property` `writable` ¶

visible: bool

Whether the layer is visible.

opacity `property` `writable` ¶

opacity: float

The layer's opacity in [0, 1].

style `property` ¶

style: dict[str, Any]

A copy of the layer's style object.

source `property` ¶

source: Any

A detached copy of the layer source configuration.

Credentials are swept the way Map.to_project sweeps them: a notebook auto-displays whatever a cell returns, and a source built with request_headers or a signed URL would otherwise print its secrets into an output that often gets committed or shared. Read Map.project for the record exactly as stored.

data `property` ¶

data: dict[str, Any]

A detached copy of the complete layer record.

Credentials are swept, as in source. "Complete" is literal: an inlined geojson blob is copied whole, which for a large layer is tens of megabytes to copy and to display. Use properties or Map.describe when a summary will do.

index `property` ¶

index: int

The layer's current index in draw order.

Raises:

Type	Description
`ValueError`	If the layer has been removed, matching the other accessors rather than raising `StopIteration`.

popup `property` ¶

popup: dict[str, Any]

This layer's popup/tooltip config, or {} when it has none.

descriptive_metadata `property` ¶

descriptive_metadata: dict[str, Any]

This layer's descriptive (catalog) metadata, or {} when it has none.

set_style ¶

set_style(**style: Any) -> None

Merge style overrides into the layer (e.g. fillColor="#ff0000").

set_metadata ¶

set_metadata(*, merge: bool = False, **fields: Any) -> dict[str, Any] | None

Set this layer's descriptive metadata (see Map.set_layer_metadata).

set_popup ¶

set_popup(fields: Any = None, **kwargs: Any) -> dict[str, Any]

Configure this layer's popup (see Map.set_popup).

set_tooltip ¶

set_tooltip(fields: Any = True) -> dict[str, Any]

Show a hover tooltip on this layer (see Map.set_tooltip).

clear_popup ¶

clear_popup() -> None

Drop this layer's popup config, restoring the default popup.

get_features ¶

get_features(*, timeout: float = 10.0) -> list[Feature]

Return this layer's features (see Map.get_features).

properties ¶

properties() -> dict[str, list[Any]]

Return sampled property values for inlined GeoJSON.

column ¶

column(name: str) -> list[Any]

Return a property column from inlined GeoJSON.

move ¶

move(index: int) -> None

Move this layer to an index in draw order.

duplicate ¶

duplicate(*, name: str | None = None) -> Layer

Duplicate this layer and return its new handle.

zoom_to ¶

zoom_to(*, timeout: float = 10.0) -> None

Fit the map camera to this layer's extent.

remove ¶

remove() -> None

Remove this layer from the map.

render_project_html ¶

render_project_html(project: dict[str, Any], *, title: str = 'GeoLibre Map', width: str = '100%', height: str = '800px', app_url: str | None = None, layout: str | None = None, theme: str | None = None) -> str

Render a project dict as a standalone HTML page.

The page embeds the GeoLibre app in an <iframe> and injects the project into it over the same postMessage bridge the widget uses, so it renders the map as configured. Credentials are stripped from the inlined project on the way out, exactly as Map.to_html does.

This is the widget-free half of Map.to_html; the MCP server calls it to export a project that was never attached to a live map.

Parameters:

Name	Type	Description	Default
`project`	`dict[str, Any]`	The project dict to embed.	required
`title`	`str`	The exported page's `<title>`.	`'GeoLibre Map'`
`width`	`str`	CSS width of the embedded map (e.g. `"100%"` or `"800px"`).	`'100%'`
`height`	`str`	CSS height of the embedded map.	`'800px'`
`app_url`	`str \| None`	Base URL of the GeoLibre app to embed. Defaults to `DEFAULT_HTML_APP_URL`.	`None`
`layout`	`str \| None`	The app chrome to embed with: `"embed"`, `"full"`, or `"maponly"`, as for `Map`. `None` leaves the app's default chrome.	`None`
`theme`	`str \| None`	`"light"` or `"dark"`; `None` follows the viewer's OS.	`None`

Returns:

Type	Description
`str`	The HTML document as a string.

Raises:

Type	Description
`ValueError`	If `width` or `height` is not a plain CSS dimension, `app_url` is not an `http`/`https` URL, or `layout` or `theme` is not a recognized value.

Map, Layer and Feature¶

Map ¶

user_rois property ¶

layers property ¶

layer_names property ¶

center property ¶

zoom property ¶

bearing property ¶

pitch property ¶

basemap property ¶

name property writable ¶

projection property ¶

close ¶

request ¶

request_async async ¶

on ¶

on_click ¶

on_selection_change ¶

on_layer_change ¶

get_view ¶

get_view_async async ¶

get_center ¶

get_center_async async ¶

get_bounds ¶

get_bounds_async async ¶

fly_to ¶

fly_to_async async ¶

fit_bounds ¶

fit_bounds_async async ¶

zoom_to_bounds ¶

zoom_to_bounds_async async ¶

zoom_to_layer ¶

zoom_to_layer_async async ¶

identify ¶

identify_async async ¶

get_features ¶

get_features_async async ¶

get_selected_features ¶

get_selected_features_async async ¶

get_drawn_features ¶

get_drawn_features_async async ¶

list_algorithms ¶

list_algorithms_async async ¶

run_algorithm ¶

run_algorithm_async async ¶

run_model_builder ¶

run_model_builder_async async ¶

list_whitebox_tools ¶

list_whitebox_tools_async async ¶

run_whitebox_tool ¶

run_whitebox_tool_async async ¶

to_image ¶

to_image_async async ¶

to_html ¶

get_layer ¶

find_layer ¶

find_layer_index ¶

set_layer_visibility ¶

set_layer_opacity ¶

set_popup ¶

set_tooltip ¶

clear_popup ¶

set_layer_metadata ¶

clear_layer_metadata ¶

set_layer_filter ¶

set_floor_picker ¶

set_labels ¶

set_plugin_state ¶

set_story_map ¶

add_story_chapter ¶

remove_story_chapter ¶

move_story_chapter ¶

add_bookmark ¶

remove_bookmark ¶

rename_layer ¶

move_layer ¶

duplicate_layer ¶

show_layer ¶

hide_layer ¶

layer_properties ¶

user_rois `property` ¶

layers `property` ¶

layer_names `property` ¶

center `property` ¶

zoom `property` ¶

bearing `property` ¶

pitch `property` ¶

basemap `property` ¶

name `property` `writable` ¶

projection `property` ¶

request_async `async` ¶

get_view_async `async` ¶

get_center_async `async` ¶

get_bounds_async `async` ¶

fly_to_async `async` ¶

fit_bounds_async `async` ¶

zoom_to_bounds_async `async` ¶

zoom_to_layer_async `async` ¶

identify_async `async` ¶

get_features_async `async` ¶

get_selected_features_async `async` ¶

get_drawn_features_async `async` ¶

list_algorithms_async `async` ¶

run_algorithm_async `async` ¶

run_model_builder_async `async` ¶

list_whitebox_tools_async `async` ¶

run_whitebox_tool_async `async` ¶

to_image_async `async` ¶

geometry `property` ¶

properties `property` ¶

id `property` ¶