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 would create a new empty document:

from jupytergis import GISDocument

doc = GISDocument()

doc

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

GISDocument API Reference#

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 (Union[str, Path, None]) – the path to the file that you would like to open. If not provided, a new empty document will be created.

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 (Union[str, int, float]) – The value to be filtered on

add_geojson_layer(path=None, data=None, name='GeoJSON Layer', type='line', 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 to embed into the jGIS file.

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

  • type (circle’ | ‘fill’ | ‘line) – The type of the vector layer to create.

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

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

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 (Optional[Dict]) – The raw GeoJSON data to embed into the jGIS file.

  • gradient (Optional[List[str]]) – 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)#

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.

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, type='line', 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 (Optional[List]) – Corners of video specified in longitude, latitude pairs.

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

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’

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.

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 (Union[str, int, float]) – The new value to be filtered on