Python API#

Basic Usage#

JupyterGIS provides a Python API that can be used for opening QGIS projects, add raster or vector layers and apply filtering.

You can open an existing QGIS project and display it in your Jupyter Notebook:

from jupytergis import GISDocument

doc = GISDocument('file.qgz')

doc

Opening an existing file connects you to the file’s collaborative session, meaning that anyone working on the same QGIS project file, whether through the JupyterLab extension or the Python API, will see the edits you make.

Creating a GISDocument object without providing a path to an existing file creates a new empty document:

from jupytergis import GISDocument

doc = GISDocument()

doc

Once the document is opened/created, you can start creating GIS layers.

explore#

jupytergis_lab.explore(data, *, layer_name='Exploration layer', basemap='topo')#

Run a JupyterGIS data interaction interface alongside a Notebook.

Parameters:

data (str | Path | Any) – A GeoDataFrame or path to a GeoJSON file.

Raises:
Return type:

GISDocument

GISDocument#

class jupytergis_lab.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.

add_filter(layer_id, logical_op, feature, operator, value)#

Add a filter to a layer

Parameters:

  • layer_id (str) – The ID of the layer to filter

  • logical_op (str) – The logical combination to apply to filters. Must be “any” or “all”

  • feature (str) – The feature to be filtered on

  • operator (str) – The operator used to compare the feature and value

  • value (str | float) – The value to be filtered on

add_geojson_layer(path=None, data=None, name='GeoJSON Layer', opacity=1, logical_op=None, feature=None, operator=None, value=None, color_expr=None)#

Add a GeoJSON Layer to the document.

Parameters:

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

  • path (str | Path | None) – The path to the JSON file or URL to embed into the jGIS file.

  • data (dict | None) – The raw GeoJSON data to embed into the jGIS file.

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

  • color_expr – The style expression used to style the layer, defaults to None

add_geopackage_raster_layer(path, table_names=None, name='GeoPackage Layer', 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) – 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='GeoPackage Layer', type='line', opacity=1, logical_op=None, feature=None, operator=None, value=None, color_expr=None)#

Add a GeoPackage Vector Layer to the document

Parameters:

  • path (str) – The path to the GeoPackage file to embed into the jGIS file.

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

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

  • type (Literal['circle', 'fill', 'line']) – The type of the vector layer to create.

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

  • logical_op (str | None) – The logical combination to apply to filters. Must be “any” or “all”

  • feature (str | None) – The feature to be filtered on

  • operator (str | None) – The operator used to compare the feature and value

  • value (str | float | None) – The value to be filtered on

  • color_expr – The style expression used to style the layer

add_geoparquet_layer(path, name='GeoParquetLayer', opacity=1, logical_op=None, feature=None, operator=None, value=None, color_expr=None)#

Add a GeoParquet Layer to the document

Parameters:

  • path (str) – The path to the GeoParquet file to embed into the jGIS file.

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

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

  • logical_op (str | None) – The logical combination to apply to filters. Must be “any” or “all”

  • feature (str | None) – The feature to be filtered on

  • operator (str | None) – The operator used to compare the feature and value

  • value (str | float | None) – The value to be filtered on

  • color_expr – The style expression used to style the layer

add_heatmap_layer(feature, path=None, data=None, name='Heatmap Layer', opacity=1, blur=15, radius=8, gradient=None)#

Add a Heatmap Layer to the document.

Parameters:

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

  • path (str | Path | None) – The path to the JSON file to embed into the jGIS file.

  • data (dict | None) – The raw GeoJSON data to embed into the jGIS file.

  • gradient (list[str] | None) – The color gradient to apply.

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

  • blur (int) – The blur size in pixels

  • radius (int) – The radius size in pixels

  • feature (str) – The feature to use to heatmap weights

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

Add a hillshade layer

Parameters:

  • url (str) – URL of the hillshade layer

  • name (str) – 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='Image Layer', opacity=1)#

Add a Image Layer to the document.

Parameters:

  • name (str) – 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='Raster Layer', attribution='', opacity=1, url_parameters=None)#

Add a Raster Layer to the document.

Parameters:

  • name (str) – 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_tiff_layer(url, min=None, max=None, name='Tiff Layer', normalize=True, wrapX=False, attribution='', opacity=1.0, color_expr=None)#

Add a tiff layer

Parameters:

  • url (str) – URL of the tif

  • 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) – The name that will be used for the object in the document, defaults to “Tiff 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

  • color_expr – The style expression used to style the layer, defaults to None

add_vectortile_layer(url, name='Vector Tile Layer', attribution='', min_zoom=0, max_zoom=24, color_expr=None, opacity=1, logical_op=None, feature=None, operator=None, value=None)#

Add a Vector Tile Layer to the document.

Parameters:

  • name (str) – 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.

add_video_layer(urls, name='Image Layer', coordinates=None, opacity=1)#

Add a Video Layer to the document.

Parameters:

  • name (str) – 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='WMS Layer', 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.

clear_filters(layer_id)#

Clear filters on a layer

Parameters:

layer_id (str) – The ID of the layer to clear filters from

create_color_expr(color_stops, band=1.0, interpolation_type='linear')#

Create a color expression used to style the layer

Parameters:

  • color_stops (dict) – Dictionary of stop values to [r, g, b, a] colors

  • band (float) – The band to be colored, defaults to 1.0

  • interpolation_type (str) – The interpolation function. Can be linear, discrete, or exact, defaults to ‘linear’

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

update_filter(layer_id, logical_op, feature, operator, value)#

Update a filter applied to a layer

Parameters:

  • layer_id (str) – The ID of the layer to filter

  • logical_op (str) – The logical combination to apply to filters. Must be “any” or “all”

  • feature (str) – The feature to update the value for

  • operator (str) – The operator used to compare the feature and value

  • value (str | float) – The new value to be filtered on

Symbology#

class jupytergis_lab.notebook.symbology.GraduatedSymbology(**data)#

Graduated symbology config for a vector layer.

Mirrors the frontend symbologyState (renderType: Graduated). Stops and color expressions are computed at runtime from this state, so only the minimal config is persisted.

Only value is required; every other field falls back to the same defaults the frontend applies when the field is absent.

value#

Name of the numeric attribute to classify on.

data#

Optional sample of attribute values, used solely to derive vmin/vmax when the caller does not supply them. The frontend recomputes the range from the live source data; passing data is just a kernel-side convenience.

method#

"color" drives fill/stroke colors; "radius" drives circle size for point layers.

color_ramp#

Name of the color ramp (e.g. "viridis", "plasma", "magma").

n_classes#

Number of classification bins. Must be >= 1.

mode#

Classification method. One of "equal interval", "quantile", "jenks", "pretty", "logarithmic".

reverse#

Reverse the color ramp.

vmin#

Lower bound of the classification range. If omitted, derived from data when given, otherwise computed by the frontend from the source.

vmax#

Upper bound of the classification range.

fallback_color#

RGBA color for features outside [vmin, vmax] or with null/missing attribute values.

stroke_color#

RGBA stroke color.

stroke_width#

Stroke width in pixels.

stroke_follows_fill#

When True, the stroke is drawn in the same color as the fill instead of stroke_color.

radius#

Circle radius (pixels) for point layers.

stops_override#

Manual per-stop overrides. When set, the frontend uses these stops instead of computing from (mode, n_classes, color_ramp).

class jupytergis_lab.notebook.symbology.GraduatedStopOverride(**data)#

A single manual stop in a Graduated symbology.

value#

The numeric break point. Features whose attribute value is <= value are colored with color (with the previous stop acting as the lower bound).

color#

RGBA tuple. r, g, b in 0-255; a in 0-1.