API reference#

class jupytergis.GISDocument(path=None, latitude=None, longitude=None, zoom=None, extent=None, bearing=None, pitch=None, projection=None)#

Create a new GISDocument object.

Parameters:

path (str | Path | None) – the path to the file that you would like to open. If not provided, a new ephemeral widget will be created.

Collaborative client state from the front end is mirrored into ypywidgets Awareness on the kernel. Subscribe with on_awareness_change(callback) (returns a subscription id; use unobserve_awareness(id) to remove). The current snapshot is available as awareness.states on the underlying pycrdt.Awareness via the inherited awareness property.

async add_data_array_layer(data_array, *, name='Data Array layer', colormap_name='viridis', colormap_range=None, opacity=1, tile_dim_scale=1, algorithm=None, **params)#

Add an Xarray DataArray as a layer on the map.

Parameters:

  • data_array (DataArray) – An Xarray DataArray to display on the map

  • name (str) – The layer’s name

  • colormap_name (str) – A rio-tiler-supported colormap name. See the rio-tiler docs for details.

  • colormap_range (tuple[float, float] | None) – The range of data values (min, max) to be colormapped

  • opacity (float) – The opacity, between 0 and 1

  • tile_dim_scale (int) – Tile dimension scale. Default 1 corresponds to 256*256px tiles

  • algorithm (BaseAlgorithm | None) – A TiTiler algorithm class. See the TiTiler algorithm docs for details.

add_geojson_layer(path=None, data=None, name=None, opacity=1, symbology=None)#

Add a GeoJSON Layer to the document.

Parameters:
add_geopackage_raster_layer(path, table_names=None, name=None, attribution='', opacity=1)#

Add a GeoPackage Raster Layer to the document.

Parameters:

  • path (str) – The tiles path.

  • table_names (list[str] | str | None) – A list of table names to create layers for.

  • name (str | None) – The name that will be used for the object in the document.

  • attribution (str) – The attribution.

  • opacity (float) – The opacity, between 0 and 1.

add_geopackage_vector_layer(path, table_names=None, name=None, type='line', opacity=1, symbology=None)#

Add a GeoPackage Vector Layer to the document.

Parameters:
add_geoparquet_layer(path, name=None, opacity=1, symbology=None)#

Add a GeoParquet Layer to the document.

Parameters:
add_geotiff_layer(url, min=None, max=None, name=None, normalize=True, wrapX=False, attribution='', opacity=1.0, symbology=None)#

Add a GeoTIFF layer.

Parameters:

  • url (str) – URL of the GeoTIFF

  • min (int) – Minimum pixel value to be displayed, defaults to letting the map display set the value

  • max (int) – Maximum pixel value to be displayed, defaults to letting the map display set the value

  • name (str | None) – The name that will be used for the object in the document, defaults to “GeoTIFF Layer”

  • normalize (bool) – Select whether to normalize values between 0..1, if false than min/max have no effect, defaults to True

  • wrapX (bool) – Render tiles beyond the tile grid extent, defaults to False

  • opacity (float) – The opacity, between 0 and 1, defaults to 1.0

  • symbology (GrammarSymbology | Layer | list[Mapping] | list[GrammarSymbology | Layer | list[Mapping] | tuple[Mapping, ...]] | BaseModel | dict[str, Any] | None) – The symbology configuration to persist with the layer.

add_hillshade_layer(url, name=None, urlParameters=None, attribution='')#

Add a hillshade layer

Parameters:

  • url (str) – URL of the hillshade layer

  • name (str | None) – The name that will be used for the object in the document, defaults to “Hillshade Layer”

  • attribution (str) – The attribution.

add_image_layer(url, coordinates, name=None, opacity=1)#

Add a Image Layer to the document.

Parameters:

  • name (str | None) – The name that will be used for the object in the document.

  • url (str) – The image url.

  • coordinates ([]) – Corners of image specified in longitude, latitude pairs.

  • opacity (float) – The opacity, between 0 and 1.

add_raster_layer(url, name=None, attribution='', opacity=1, url_parameters=None)#

Add a Raster Layer to the document.

Parameters:

  • name (str | None) – The name that will be used for the object in the document.

  • url (str) – The tiles url.

  • attribution (str) – The attribution.

  • opacity (float) – The opacity, between 0 and 1.

  • url_parameters (dict[str, Any] | None) – Extra URL parameters for tile requests.

add_vectortile_layer(url, name=None, attribution='', min_zoom=0, max_zoom=24, opacity=1, symbology=None)#

Add a Vector Tile Layer to the document.

Parameters:
add_video_layer(urls, name=None, coordinates=None, opacity=1)#

Add a Video Layer to the document.

Parameters:

  • name (str | None) – The name that will be used for the object in the document.

  • urls (list) – URLs to video content in order of preferred format.

  • coordinates (list | None) – Corners of video specified in longitude, latitude pairs.

  • opacity (float) – The opacity, between 0 and 1.

add_wms_tile_layer(url, layer_name, name=None, attribution='', opacity=1, interpolate=False)#

Add a WMS tile layer to the document.

Return type:

str

url:

Base WMS service URL (without SERVICE/REQUEST parameters), e.g. ‘https://ows.terrestris.de/osm/service’

layer_name:

WMS layer name to request (from GetCapabilities Name).

name:

Display name for the layer.

attribution:

Optional attribution text.

opacity:

Layer opacity in [0, 1].

interpolate:

Whether to interpolate between grid cells when overzooming.

get_wms_available_layers(wms_url, version='1.3.0', timeout=30.0)#

Fetch a WMS GetCapabilities document and parse available top-level layers.

Matches the behavior in the frontend WmsTileSourceUrlInput: - Calls: ?SERVICE=WMS&VERSION=…&REQUEST=GetCapabilities - Parses Capability > Layer (root Layer) - Returns direct child Layer elements with Name and Title.

Returns a list of objects shaped like: { ‘name’: <layer name>, ‘title’: <layer title> }.

Return type:

list[dict[str, str]]

property layer_tree: list[str | dict]#

Get the layer tree

property layers: dict#

Get the layer list

remove_layer(layer_id)#

Remove a layer from the GIS document.

Parameters:

layer_id (str) – The ID of the layer to remove.

Raises:

KeyError – If the layer does not exist.

sidecar(*, title='JupyterGIS sidecar', anchor='split-right')#

Open the document in a new sidecar panel.

Parameters:

anchor (Literal['split-right', 'split-left', 'split-top', 'split-bottom', 'tab-before', 'tab-after', 'right']) – Where to position the new sidecar panel.

to_py()#

Get the document structure as a Python dictionary.

Return type:

dict

jupytergis.field(name)#

Create a field reference used by predicates and mapping chains.

Examples:

field("temperature").colormap("viridis").encoding("fill")
when(field("magnitude") > 3).constant("red").encoding("fill")
Return type:

FieldPredicate

jupytergis.constant(value)#

Create a constant mapping source for chain-style symbology.

Finalize with encoding(...) to create a mapping.

Return type:

MappingChain

jupytergis.when(*when)#

Create a when-first builder for readable guarded mapping chains.

Examples:

when(field("mag") >= 5).constant("red").encoding("fill")
when(field("mag") > 3, field("mag") < 8).when_op("all").field("mag").identity().encoding("radius")
Return type:

WhenBuilder

jupytergis.heatmap(*, radius=2.0, blur=5.0, weight_field=None, weight=None, mappings=None)#

Create a heatmap layer with KDE (kernel density estimation) transform.

Parameters:

  • radius (float) – The radius of the KDE transform in pixels.

  • blur (float) – The blur of the KDE transform.

  • weight_field (str | None) – Optional field to use for weighting the KDE.

  • weight (str | None) – Alias for weight_field.

  • mappings (Sequence[Mapping] | None) – Optional mapping chains for this layer.

Return type:

Layer

jupytergis.cluster(*, radius, mappings=None)#

Create a symbology that aggregates nearby points into clusters.

Parameters:

  • radius (float) – Clustering radius in pixels.

  • mappings (Sequence[Mapping] | None) – Optional mapping chains for this layer.

Return type:

Layer

Returns:

A Layer with a cluster preprocessing transform.

jupytergis.geometry_type(value)#

Create a predicate that matches features by their geometry type.

Parameters:

value (Literal['Point', 'LineString', 'Polygon']) – The geometry type to match: "Point", "LineString", or "Polygon".

Return type:

Predicate

Returns:

A predicate that can be passed to encoding_rule or grammar_layer.

jupytergis.between(field, minimum, maximum)#

Create a predicate that matches features where a field value falls in a range.

The range is inclusive: minimum <= field_value <= maximum.

Parameters:

  • field (str) – Name of the numeric feature field to test.

  • minimum (float) – Lower bound of the range (inclusive).

  • maximum (float) – Upper bound of the range (inclusive).

Return type:

Predicate

Returns:

A predicate that evaluates to True when the field is in range.

jupytergis.has_field(field)#

Create a predicate that matches features which have a given field.

Parameters:

field (str) – Name of the feature field to test for existence.

Return type:

Predicate

Returns:

A predicate that evaluates to True when the field is present.

class jupytergis.GrammarSymbology(**data)#

Container for the normalized grammar symbology state.

Prefer constructing symbology via mapping chains and layer lists, then serializing with to_symbology_state(...).

with_layer(item)#

Return a copy with one additional layer appended.

Return type:

Self

class jupytergis.VisualEncoding(allowed values: 'fill', 'stroke', 'radius', 'circle-fill', 'circle-stroke', 'pixel-rgba', 'circle-fill-color', 'circle-radius', 'circle-stroke-color', 'circle-stroke-width', 'fill-alpha', 'fill-blue', 'fill-color', 'fill-green', 'fill-red', 'pixel-alpha', 'pixel-blue', 'pixel-color', 'pixel-green', 'pixel-red', 'pixel-rgb', 'stroke-color', 'stroke-width')#

Allowed values: - fill - stroke - radius - circle-fill - circle-stroke - pixel-rgba - circle-fill-color - circle-radius - circle-stroke-color - circle-stroke-width - fill-alpha - fill-blue - fill-color - fill-green - fill-red - pixel-alpha - pixel-blue - pixel-color - pixel-green - pixel-red - pixel-rgb - stroke-color - stroke-width

jupytergis.VisualEncodings#

alias of VisualEncoding | str | Sequence[VisualEncoding | str]

class jupytergis.WhenBuilder(*, when, when_op=None)#

Start a mapping chain by declaring guard predicates first.

Use when() to create instances, then choose a source with constant() or field().

constant(value)#

Start a constant mapping chain with the builder predicates attached.

Return type:

MappingChain

field(name)#

Start a field mapping chain with the builder predicates attached.

Return type:

MappingChain

when_op(when_op)#

Set the logical combinator for this builder’s predicates.

Return type:

WhenBuilder

class jupytergis.FieldPredicate(name)#

Fluent predicate builder for when= guards.

Use field to construct instances. Rich comparisons return schema predicate objects, for example field("magnitude") > 3.

between(minimum, maximum)#

Build an inclusive numeric range predicate.

Parameters:

  • minimum (float) – Lower inclusive bound.

  • maximum (float) – Upper inclusive bound.

Return type:

Predicate

Returns:

A between predicate.

categorical(colormap='viridis', *, n_shades=None, reverse=None, fallback=(0.0, 0.0, 0.0, 1.0))#

Apply a categorical scale to this field before encoding(...).

Return type:

MappingChain

colormap(colormap='viridis', *, domain=None, n_shades=9, mode=ClassificationMode.EQUAL_INTERVAL, reverse=False, fallback=(0.0, 0.0, 0.0, 1.0))#

Apply a color-ramp scale to this field before encoding(...).

Return type:

MappingChain

encoding(*targets)#

Map this symbolizer to visual encoding.

Return type:

Mapping

exists()#

Build a predicate that checks field existence.

Return type:

Predicate

Returns:

A hasField predicate.

identity()#

Apply an identity scale to this field before encoding(...).

Return type:

MappingChain

scalar(*, domain, output_range, fallback=None, scalar_stops=None)#

Apply a scalar interpolation scale to this field before encoding(...).

Return type:

MappingChain

class jupytergis.Predicate#

User-facing predicate value for when= guards.

Build these via helpers such as field(...) comparisons, geometry_type(...), has_field(...), and between(...), then pass them to the when= argument of symbology functions.

class jupytergis.ScalarStop(stop, output)#

User-facing scalar interpolation stop.

Use this with scalar(..., scalar_stops=[...]) to define explicit stop-to-output mappings.

class jupytergis.ClassificationMode(allowed values: 'equal interval', 'quantile', 'jenks', 'pretty', 'logarithmic')#

Allowed values: - equal interval - quantile - jenks - pretty - logarithmic

class jupytergis.Layer(mappings=None, *, preprocess=None)#

A single symbology layer made of mapping chains.

when(*when)#

Attach layer-level predicates.

Parameters:

when (Predicate | Sequence[Predicate] | None) – Predicate or predicates created with helpers such as field(), has_field(), or between().

Return type:

Layer

Returns:

A new Layer with the predicates applied.

when_op(when_op)#

Set the logical combinator for layer-level predicates.

Parameters:

when_op (Optional[Literal['all', 'any']]) – "all" or "any".

Return type:

Layer

Returns:

A new Layer with the combinator applied.

class jupytergis.Mapping(rule)#

Final mapping produced by ...encoding(...) chains.

class jupytergis.MappingChain(*, kind, value, scale=None, scale_kind=None, when=None, when_op=None)#

Fluent chain for building a single mapping.

A mapping chain starts from field(...) or constant(...), optionally applies a scale (identity, colormap, categorical, scalar), and is finalized with encoding(...).

categorical(colormap='viridis', *, n_shades=None, reverse=None, fallback=(0.0, 0.0, 0.0, 1.0))#

Apply a categorical scale to a field(...) source.

Parameters:

colormap (str) – Name of the categorical color ramp.

Return type:

MappingChain

Returns:

The updated MappingChain.

Raises:

TypeError – If the source was created with constant().

colormap(colormap='viridis', *, domain=None, n_shades=9, mode=ClassificationMode.EQUAL_INTERVAL, reverse=False, fallback=(0.0, 0.0, 0.0, 1.0))#

Apply a color-ramp scale to a field(...) source.

Parameters:
Return type:

MappingChain

Returns:

The updated MappingChain.

Raises:

TypeError – If the source was created with constant().

encoding(*targets)#

Finalize the chain and encode to output channel(s).

Return type:

Mapping

identity()#

Apply an identity scale to a field(...) source.

Return type:

MappingChain

Returns:

The updated MappingChain.

Raises:

TypeError – If the source was created with constant().

scalar(*, domain, output_range, fallback=None, scalar_stops=None)#

Apply a scalar interpolation scale to a field(...) source.

Return type:

MappingChain

Returns:

The updated MappingChain.

Raises:

TypeError – If the source was created with constant().

when(*when)#

Attach guard predicate(s) to this mapping chain.

Return type:

MappingChain

when_op(when_op)#

Set the logical combinator used for mapping when predicates.

Return type:

MappingChain