Map
Parameters
Optional[list[LayerInput]]
default:"None"
Layers to render. Each entry is either a bare source URL string
(the layer
type is inferred from the URL’s extension) or a
config dict. A dict needs only source; an explicit type
(zarr / pmtiles / cog / geoparquet) wins over
inference, and any other layer option, such as opacity, is passed
to the map unchanged. Examples:Optional[dict[str, float]]
default:"None"
Map viewport
{"zoom", "lat", "lng", "bearing", "pitch"} — the last
two in degrees (rotation clockwise from north, and tilt from straight
down), written back with the rest so a tilted 3D-terrain camera
round-trips. Both may be omitted when constructing; they default to 0.
Updated in place when the
user pans/zooms. Empty ({}) on a from_url map built
without a view kwarg: the URL’s z/lat/lng (or the
map’s default view) apply until the first pan writes it back.str
default:"'light'"
Basemap style. One of
BASEMAP_STYLES. Set from Python only —
the widget shows no basemap switcher; assigning m.basemap re-styles
the map. Empty ("") on a from_url map built without a
basemap kwarg: the URL’s basemap= (or the map’s default)
applies until one is assigned.Union[str, float]
default:"DEFAULT_HEIGHT"
Map height as a CSS length string (e.g.
"600px", "80vh") or a
number of pixels. Defaults to DEFAULT_HEIGHT.Optional[dict[str, str]]
default:"None"
Optional static, global
{"accessKeyId", "secretAccessKey", "sessionToken"?} for private S3 sources. Held in kernel memory and
never stored in the widget state, so it is never embedded in a saved
.ipynb. Takes precedence over credentials_provider and applies to
every source. Leave None for public URLs or to use per-source minting.
Reassign m.aws_credentials = {...} to update a live map.Optional[CredentialsProvider]
default:"None"
Optional callable
(source_url, region) -> creds_dict | None invoked
once per private source to mint path-scoped credentials on demand.
When neither this nor aws_credentials is given, credentials are
minted through Wherobots storage credentials, so a private-S3 map works
out of the box in a Wherobots kernel and no credentials are used when no
Wherobots authentication is available.str
default:"'mercator'"
Map projection — one of
MAP_PROJECTIONS. "globe" renders the
same basemap and layers on a 3D sphere; "mercator" (the default) is
the flat map. Set from Python only — the widget shows no globe toggle;
assigning m.projection reprojects the map in place (layers are not
reloaded). Empty ("") on a from_url map built without a
projection kwarg: the URL’s projection= (or the map’s
default) applies until one is assigned.bool
default:"False"
Whether to render 3D terrain (a shipped elevation source; exaggeration is
fixed at 1). Orthogonal to
basemap — relief sits under any style. Set
from Python only; the widget shows no toggle. Zarr, COG and GeoParquet
layers are hidden by terrain, because they render without elevation
and would end up behind the ground, and a WARNING is logged when
both are present; PMTiles is unaffected.Any
aws_credentials
.ipynb. Assigning new credentials updates
a map that is already displayed.
viewport_bbox
(west, south, east, north) in EPSG:4326, or
None if the map hasn’t reported its bounds yet (it reports once the
map first renders).
Order matches the common (minx, miny, maxx, maxy) bbox convention, so
e.g. shapely.geometry.box(*m.viewport_bbox) works directly. Also
None if the map reports bounds that are not numbers.
viewport_bbox_wkt
POLYGON (EPSG:4326), or None if the
map hasn’t reported bounds yet. Feed it to Spatial SQL via
ST_GeomFromText.
add_layer()
Parameters
LayerInput
required
A source URL string or a layer config dict, as in
layers.close()
from_url()
Map from a wherobots-gl share URL (or query string).
The map reads the URL the same way the Wherobots web app does, so a
shared map opens with the same layers, view and settings. The reverse,
turning a map built in Python into a share URL, is not supported (see
to_url).
Parameters
str
required
A full
https://…?… share URL, a "?z=…&l0.src=…" string, or
a bare "z=…&l0.src=…" query. Extra kwargs (basemap,
projection, terrain, height, aws_credentials) are
passed to __init__.Any
to_sql_filter()
geometry to the current viewport:
ST_Intersects(<geometry>, ST_GeomFromText('POLYGON(...)', 4326)).
Returns None if the map hasn’t reported bounds yet.
The bounds are EPSG:4326 (lng/lat); the predicate assumes geometry is
also 4326 — wrap it in ST_Transform yourself if your column’s CRS
differs. Example:
Parameters
str
default:"'geometry'"
Name of the geometry column to filter, or any SQL expression that
returns a geometry.
to_url()
from_url.
Changes made afterwards, such as layers added in Python or the current
viewport, are not encoded, and a map not built from a URL returns an
empty string.