sequenceDiagram
actor user as User
participant widget as Map<br/>widget
box jupyter-tiler
participant API@{"type": "boundary"}
participant proxy as jupyter-server-proxy
participant tileserver as TiTiler
end
user->>widget: Show my data<br/>on the map
widget->>API: add_data_array(...)
API->>tileserver: Add DataArray to tileserver
tileserver->>API: tiles URL
API->>widget: proxy-friendly<br/>tiles URL
widget->>proxy: Request map tiles with tiles URL
tileserver<<->>proxy: proxy
proxy->>widget: Here's your map tiles!
widget->>user: Here's your map!
accDescr {
A diagram shows a data flow: A third-party interactive map widget leverages jupyter-tiler to display data on the map.
First, the user requests to visualize data on the map with the widget.
The widget tells the jupyter-tiler API to add a `DataArray` layer.
jupyter-tiler then tells TiTiler to add a `DataArray` route to its HTTP API.
This triggers jupyter-server-proxy to serve that route through Jupyter Server.
The map widget receives a proxy-friendly URL it can use to request tiles.
The map widget uses that URL to request and receive tiles from TiTiler via jupyter-server-proxy.
Finally, the user receives the requested interactive map displaying their data.
}
Announcing jupyter-tiler!
Announcements
jupyter-tiler enables users of Jupyter interactive map widgets (like JupyterGIS) to visualize large raster datasets without switching tools or worrying about file formats by leveraging dynamic tile servers under the hood (currently supporting TiTiler or Xpublish).
Matt Fisher 
When users of geospatial data compute with raster data, they often face challenges with visualizing their results. A typical workflow involves first reading data into an analysis tool like xarray, then performing computations on the data, then visualizing their results. This analysis ↔︎ visualization cycle is usually repeated many times.
While users can easily produce static plots of their raster dataset, they usually need interactive maps to effectively explore their results. Interactive visualization often requires writing data to disk, decisions about visualization-friendly file formats, and/or context-switching to another tool (like QGIS).
jupyter-tiler helps those users create interactive maps of their computation results without leaving the Notebook environment or writing files, eliminating costly decision-making and context switches.
jupyter-tiler in JupyterGIS
jupyter-tiler has been integrated with JupyterGIS, streamlining interactive visualization of xarray DataArrays to a single function call:
data_min = int(xarray_dataarray_flow_acc.min().compute())
data_max = int(xarray_dataarray_flow_acc.max().compute())
await jgis_document.add_data_array_layer(
name="Flow accumulation", # The layer name for display in JupyterGIS
data_array=xarray_dataarray_flow_acc, # Our computation results!
colormap_name="terrain",
colormap_range=(data_min, data_max), # The range of data values our colormap will span
)DataArrays da_dem (a Digital Elevation Model) and da_acc (a flow accumulation model) to the map, each in one step. The tile server handles displaying the data at the optimal resolution depending on the user’s zoom level.Try it!
You can try jupyter-tiler with JupyterGIS today! The command below will install JupyterGIS plus its “tiler” extra, which adds the functionality you saw in the code example and video above.
This is only available as a pre-release right now, so you’ll need to explicitly set the version (pip won’t install pre-releases unless asked explicitly)! When JupyterGIS 0.16.0 is fully released, you won’t need this anymore.
pip install jupytergis[tiler]==0.16.0a2
Note
At time of writing, JupyterGIS’ latest prerelease is 0.16.0a2, and jupyter-tiler’s latest release is 0.8.0.
How jupyter-tiler works
jupyter-tiler provides an engine for generating map tiles dynamically from xarray Datasets for real-time display on interactive maps. But end-users don’t install jupyter-tiler themselves – we built this to make it easier for authors of Jupyter interactive map widgets, like ipyleaflet, ipyopenlayers, and JupyterGIS, to offer their users a lower-friction path to visualizing their data.
jupyter-tiler provides a Python API for interacting with a dynamic tile server (currently supporting both TiTiler and Xpublish). You hand off an xarray DataArray and some options, jupyter-tiler sets up the tile server for you, and returns a URL template that you can directly display with a Javascript interactive map (Leaflet, OpenLayers, MapLibre, etc.).
jupyter-tiler also provides a proxy (jupyter-server-proxy) to enable usage of jupyter-tiler in cloud environments (like JupyterHub) without extra deployment complexity. As a user, you don’t need to think about ports; just use the URL that jupyter-tiler returns to you.
How jupyter-tiler was made
jupyter-tiler started life as jupytergis-tiler, a similar library by David Brochart at QuantStack that is specific to JupyterGIS. You can read more about jupytergis-tiler in its own announcement blog post!
We built jupyter-tiler to supersede jupytergis-tiler.
It’s different in the following ways:
- Now supports any Jupyter interactive map widget, not only JupyterGIS – the purpose of the GeoJupyter community is to benefit the whole geospatial-in-Jupyter ecosystem!
- Simplified interface
- Supports multiple dynamic tiling backends (currently, TiTiler and Xpublish)
- Supports usage on JupyterHub
- Has a full documentation website!
- Has a full suite of unit tests
- Provides a
py.typedmarker and is typechecked in strict mode
❤️ Thanks for reading!
We appreciate your interest!
If you would like to connect with the GeoJupyter community to learn more, please join us on the Project Jupyter Zulip chat space. We’d love to hear about your use cases and challenges working with geospatial data in Jupyter.