Metadata-Version: 2.5
Name: isard-map
Version: 0.5.0
Summary: isard maps in Jupyter: the IGN's WebGL2 map engine (globe, relief, 3D Tiles, vector tiles) as a notebook widget
Project-URL: Homepage, https://github.com/IGNF/isard
Project-URL: Documentation, https://github.com/IGNF/isard/tree/main/packages/python
Author: IGN
License-Expression: MIT
License-File: LICENSE
Keywords: 3d,gis,ign,jupyter,map,webgl,widget
Classifier: Framework :: Jupyter
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: GIS
Requires-Python: >=3.10
Requires-Dist: anywidget>=0.9
Requires-Dist: traitlets>=5
Provides-Extra: geo
Requires-Dist: geopandas>=0.14; extra == 'geo'
Description-Content-Type: text/markdown

# isard-map

[isard](https://github.com/IGNF/isard), the IGN's WebGL2 map engine, in Jupyter: a notebook widget (JupyterLab,
Notebook, VS Code, Colab) showing the globe or a flat map, the relief, vector tiles, 3D Tiles and the data of your
frames, its layers set from Python.

```sh
pip install isard-map            # geopandas too: pip install "isard-map[geo]"
```

```python
import geopandas as gpd
from isard_map import Map

m = Map(center=(2.35, 48.85), zoom=15, pitch=60, basemap="ign-plan")
m.add_circles(gpd.read_file("places.geojson"), color="#e8590c", radius=6, stroke_color="#fff", stroke_width=2)
m
```

## The map

`Map(center, zoom, pitch, bearing, basemap, height="500px", **options)`: `options` are those of isard's
`GeoMap.create`, in snake_case or camelCase (`terrain={"model": "ign"}`, `projection="globe"`, `quality="medium"`…).
`m.camera` tells where the map stopped last.

## Layers

`m.add(type, data=None, id=None, **options)` adds a layer of isard's `map.add` (`"circles"`, `"lines"`, `"fills"`,
`"extrusions"`, `"tiles3d"`, `"models"`…) and returns its id; the same id replaces it. `data` is GeoJSON: a dict, a
JSON string, or anything with `__geo_interface__` (a GeoDataFrame, a GeoSeries, a shapely geometry), a frame with a
CRS brought to WGS 84 first. Shortcuts: `add_circles`, `add_lines`, `add_fills`, `add_extrusions`, `add_tiles3d`.
`m.set_data(id, data)` sets a layer's data anew (in place on the map), `m.remove(id)` takes it away.

```python
m.add_extrusions(buildings, height=prop("hauteur", 6), color="#d0d0d0")  # from isard_map import prop
m.add_tiles3d("https://webimaging.lillemetropole.fr/externe/maillage/2020_mel_5cm/tileset.json")
```

## Camera and clicks

`m.fly_to(center, zoom=…, pitch=…, bearing=…, duration=…)`, `m.ease_to(…)`, `m.set_camera(…)`.
`m.on_click(callback)`: each click as `{"point", "lon_lat", "feature"}`, `feature` (its layer's id and properties)
when one of the layers is under it.

## How it works

The widget ([anywidget](https://anywidget.dev)) runs the page of `isard-react-native`, the same messages as a React
Native app's: isard itself is loaded from jsDelivr (the version this package was made for), so the notebook needs the
network. The layers are sent as JSON when they change; a change of their data alone is set in place.

## Develop

```sh
uv sync && uv run pytest        # in packages/python
bun scripts/build-widget.ts     # the widget's script (src/isard_map/static/widget.js), from js/widget.ts
```

MIT licence.
