Metadata-Version: 2.4
Name: jupyter-xarray-tiler
Version: 0.5.0
Summary: A Jupyter server extension providing a TiTiler server, proxy, and a Python API to add Xarray datasets to the TiTiler server.
Project-URL: Repository, https://github.com/geojupyter/jupyter-xarray-tiler.git
Project-URL: Homepage, https://github.com/geojupyter/jupyter-xarray-tiler
Project-URL: Issues, https://github.com/geojupyter/jupyter-xarray-tiler/issues
Author-email: GeoJupyter community <geojupyter@gmail.com>
License: BSD 3-Clause License
        
        Copyright (c) 2025, GeoJupyter Community
        All rights reserved.
        
        Redistribution and use in source and binary forms, with or without
        modification, are permitted provided that the following conditions are met:
        
        1. Redistributions of source code must retain the above copyright notice, this
           list of conditions and the following disclaimer.
        
        2. Redistributions in binary form must reproduce the above copyright notice,
           this list of conditions and the following disclaimer in the documentation
           and/or other materials provided with the distribution.
        
        3. Neither the name of the copyright holder nor the names of its
           contributors may be used to endorse or promote products derived from
           this software without specific prior written permission.
        
        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
        AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
        IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
        DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
        FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
        DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
        SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
        CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
        OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
        OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
License-File: LICENSE
Keywords: jupyter,jupyterlab,jupyterlab-extension
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: Jupyter
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: BSD License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: GIS
Requires-Python: <3.14,>=3.12
Requires-Dist: anycorn
Requires-Dist: anyio
Requires-Dist: geopandas
Requires-Dist: jupyter-server-proxy
Requires-Dist: jupyter-server<3,>=2.4.0
Requires-Dist: rioxarray
Requires-Dist: titiler-core>=1.1.1
Requires-Dist: titiler-xarray>=1.1.1
Requires-Dist: xpublish-tiles>=0.4.2
Description-Content-Type: text/markdown

# Jupyter Xarray Tiler

[![PyPI - Version](https://img.shields.io/pypi/v/jupyter-xarray-tiler)](https://pypi.org/project/jupyter-xarray-tiler/)
[![PyPI - Downloads](https://img.shields.io/pypi/dm/jupyter-xarray-tiler)](https://pypi.org/project/jupyter-xarray-tiler/)
![License](https://img.shields.io/github/license/geojupyter/jupyter-xarray-tiler)
[![ReadTheDocs Status](https://readthedocs.org/projects/jupyter-xarray-tiler/badge/?version=latest)](https://jupyter-xarray-tiler.readthedocs.io)
[![Github Actions Status - Build](https://github.com/geojupyter/jupyter-xarray-tiler/workflows/Build/badge.svg)](https://github.com/geojupyter/jupyter-xarray-tiler/actions/workflows/build.yml)
[![Github Actions Status - Typecheck](https://github.com/geojupyter/jupyter-xarray-tiler/workflows/Typecheck/badge.svg)](https://github.com/geojupyter/jupyter-xarray-tiler/actions/workflows/typecheck.yml)

> [!IMPORTANT]
> This repository is experimental and in the prototype stage.
> Expect bugs.
> Expect a possible pivot and/or name change in the future :smile:
>
> Your feedback and contributions are welcome!
> Please open an issue, DM Matt Fisher, or post in the `#geojupyter` channel on the [Jupyter Zulip](https://jupyter.zulipchat.com)!

A Jupyter server extension which provides an API to launch a server to dynamically tile
[Xarray DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html)s
for interactive visualization.

## Who is this for?

Intended to be consumed by interactive map libraries for Jupyter, **not end-users**,
e.g.:

* [Leafmap](https://leafmap.org/)
* [ipyleaflet](https://ipyleaflet.readthedocs.io)
* [ipyopenlayers](https://ipyopenlayers.readthedocs.io/)
* More?

## What problem does this solve?

For authors of interactive map libraries for Jupyter, providing a dynamic HTTP tile
server presents a unique problem: **they don't know where Jupyter is running**.
It could be, for example, running on:

* users' local machines
* a shared JupyterLab instance on an intranet
* an authenticated JupyterHub in a public cloud

The first case is the simplest; when the tile server is running on `localhost`, the map
viewer running in JavaScript in the user's browser can connect to it.

In the other cases, the map viewer needs a public URL to connect to.
The URL of the current JupyterHub instance may not be known.
Additionally, a map server running in a Jupyter kernel isn't exposed to the public
internet in many cases (for example, when it's running in a Kubernetes pod as part of a
JupyterHub).
This extension provides [dynamic proxying](https://jupyter-server-proxy.readthedocs.io/)
to map servers running in the kernel.

## Usage

As a Jupyter interactive map library author, you may implement a method like:

```python
from jupyter_xarray_tiler.titiler import add_data_array


class MyMapLibrary:
  # ...

  def add_xarray_layer(self, da: xr.DataArray):
    # Add the layer to the tile server.
    # The server will be started the first time this is called.
    # A URL that passes through the Jupyter server proxy will be returned:
    url = add_data_array(da)

    # Add the layer to your map!
    self._add_tile_layer(url)
```

## Install

Recommended:

```bash
uv add jupyter-xarray-tiler
```

Or:

> [!WARNING]
> Installation with pixi/conda/mamba/micromamba is not yet supported.
> Please use another installation method!

```bash
pixi add jupyter-xarray-tiler
```

For other methods of installation, including pip, conda, mamba, and micromamba, see the
[installation instructions in the documentation](https://jupyter-xarray-tiler.readthedocs.io/en/latest/user-guide/install/).

### From source

```bash
uv add git+https://github.com/geojupyter/jupyter-xarray-tiler.git#egg=jupyter-xarray-tiler
```

For _development_ instructions, please view the
[development install instructions in our documentation's Contributor Guide](https://jupyter-xarray-tiler.readthedocs.io/en/latest/contributor-guide/how-tos/development-install/)!

## Contributing

Please see the
[Contributor Guide in our documentation](https://jupyter-xarray-tiler.readthedocs.io/en/latest/contributor-guide/)!

## :rocket: Powered by...

[TiTiler (Development Seed)](https://developmentseed.org/titiler/)

Other backends (e.g.
[xpublish-tiles (earthmover)](https://github.com/earth-mover/xpublish-tiles)) may be
supported in the future!

## :sparkles: Inspired by...

[jupytergis-tiler](https://github.com/geojupyter/jupytergis-tiler) by
[David Brochart](https://github.com/davidbrochart)
