isard-map 0.1.0__py3-none-any.whl

isard_map/__init__.py

@@ -0,0 +1,8 @@
+"""isard maps in Jupyter: the IGN's WebGL2 map engine as a notebook widget (anywidget)."""
+
+from ._data import prop, to_geojson
+from ._geoplateforme import geoplateforme_wfs
+from ._map import Map
+
+__version__ = "0.1.0"
+__all__ = ["Map", "geoplateforme_wfs", "prop", "to_geojson", "__version__"]

isard_map/_data.py

@@ -0,0 +1,48 @@
+"""The layers' data and options as the map takes them: GeoJSON in longitudes and latitudes, options in camelCase."""
+
+from __future__ import annotations
+
+import json
+import math
+import re
+from typing import Any
+
+
+def to_geojson(data: Any) -> dict[str, Any]:
+    """A layer's data as GeoJSON: a dict as it is, a JSON string read, anything with `__geo_interface__` (a
+    GeoDataFrame, a GeoSeries, a shapely geometry) taken through it, a frame with a CRS first brought to WGS 84."""
+    if isinstance(data, dict):
+        return data
+    if isinstance(data, str):
+        return json.loads(data)
+    if getattr(data, "crs", None) is not None and hasattr(data, "to_crs"):
+        data = data.to_crs(4326)
+    interface = getattr(data, "__geo_interface__", None)
+    if interface is None:
+        raise TypeError(f"isard: no GeoJSON in a {type(data).__name__} (a dict, a JSON string or __geo_interface__)")
+    # Through JSON: plain values only (numpy numbers, timestamps written as the frame's to_json writes them)
+    return json.loads(json.dumps(interface, default=str))
+
+
+def prop(name: str, default: Any = None) -> dict[str, Any]:
+    """An option read from each feature's properties: `height=prop("hauteur", 6)`, `default` where a feature has none"""
+    return {"property": name} if default is None else {"property": name, "default": default}
+
+
+def camel(name: str) -> str:
+    """`stroke_color` as the map names it: `strokeColor`"""
+    return re.sub(r"_([a-z0-9])", lambda m: m.group(1).upper(), name)
+
+
+def plain(value: Any) -> Any:
+    """A value as JSON takes it: a column or an array a list (`tolist`), a missing number (NaN) None"""
+    if hasattr(value, "tolist"):
+        value = value.tolist()
+    if isinstance(value, list):
+        return [None if isinstance(v, float) and math.isnan(v) else v for v in value]
+    return value
+
+
+def options(values: dict[str, Any]) -> dict[str, Any]:
+    """A layer's or the map's options in camelCase, those left as None out, columns and arrays as lists"""
+    return {camel(k): plain(v) for k, v in values.items() if v is not None}

isard_map/_geoplateforme.py

@@ -0,0 +1,30 @@
+"""The IGN's Géoplateforme from Python: its WFS layers as GeoDataFrames (geopandas)."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Any
+from urllib.parse import urlencode
+
+WFS = "https://data.geopf.fr/wfs/ows"
+
+
+def geoplateforme_wfs(type_name: str, bbox: Sequence[float], count: int = 5000) -> Any:
+    """The features of a Géoplateforme WFS layer within `bbox` (west, south, east, north, degrees), as a GeoDataFrame in
+    longitudes and latitudes: `geoplateforme_wfs("BDTOPO_V3:batiment", (2.41, 48.84, 2.43, 48.85))`. At most `count`
+    features. The type names are those of its capabilities (BD TOPO, ADMIN EXPRESS…). Needs geopandas."""
+    import geopandas as gpd
+
+    west, south, east, north = bbox
+    query = {
+        "SERVICE": "WFS",
+        "VERSION": "2.0.0",
+        "REQUEST": "GetFeature",
+        "TYPENAMES": type_name,
+        "OUTPUTFORMAT": "application/json",
+        "SRSNAME": "EPSG:4326",
+        # WFS 2.0 in EPSG:4326: latitude first
+        "BBOX": f"{south},{west},{north},{east},urn:ogc:def:crs:EPSG::4326",
+        "COUNT": str(count),
+    }
+    return gpd.read_file(f"{WFS}?{urlencode(query)}")

isard_map/_map.py

@@ -0,0 +1,145 @@
+"""The map widget: an isard map in a notebook, its layers set from Python."""
+
+from __future__ import annotations
+
+import pathlib
+from collections.abc import Callable, Sequence
+from typing import Any
+
+import anywidget
+import traitlets
+
+from ._data import camel, options, to_geojson
+
+Camera = dict[str, Any]
+"""Where the map looks: `center` ([longitude, latitude]), `zoom`, `pitch` and `bearing` (degrees)"""
+
+
+class Map(anywidget.AnyWidget):
+    """An isard map: the IGN's WebGL2 engine in the notebook, the globe or a flat map, the relief, vector tiles, 3D
+    Tiles, point clouds, glTF models and the data of your frames.
+
+    >>> m = Map(center=(2.35, 48.85), zoom=15, pitch=60, basemap="ign-plan")
+    >>> m.add_circles(gdf, color="#e8590c", radius=6)
+    >>> m
+    """
+
+    _esm = pathlib.Path(__file__).parent / "static" / "widget.js"
+
+    #: The map's options at its creation (`GeoMapOptions` of isard, in camelCase): set by the constructor
+    options = traitlets.Dict().tag(sync=True)
+    #: The map's layers, the last on top: `map.add`'s options with an `id` (set them with `add_…`, `remove`)
+    layers = traitlets.List().tag(sync=True)
+    #: Where the map stopped last (read only): `center`, `zoom`, `pitch`, `bearing`
+    camera = traitlets.Dict().tag(sync=True)
+    #: The height of the map in the notebook (CSS)
+    height = traitlets.Unicode("500px").tag(sync=True)
+
+    def __init__(
+        self,
+        center: Sequence[float] = (2.35, 46.6),
+        zoom: float = 5,
+        pitch: float = 0,
+        bearing: float = 0,
+        basemap: str | None = None,
+        height: str = "500px",
+        **more: Any,
+    ) -> None:
+        """`basemap`: a name of isard's (`'ign-plan'`, `'ign-ortho'`, `'osm-liberty'`…); `more`: other options of
+        `GeoMap.create` (`terrain`, `projection`, `sun`, `quality`…), in snake_case or camelCase"""
+        settings = {"center": list(center), "zoom": zoom, "pitch": pitch, "bearing": bearing, "basemap": basemap}
+        super().__init__(options=options({**settings, **more}), height=height)
+        self._clicks: list[Callable[[dict[str, Any]], None]] = []
+        self._ids = 0
+        # The calls made before the map is shown, sent once it is there
+        self._ready = False
+        self._pending: list[dict[str, Any]] = []
+        self.on_msg(self._message)
+
+    # Layers
+
+    def add(self, type: str, data: Any = None, id: str | None = None, **settings: Any) -> str:
+        """Adds a layer of a kind of `map.add` (`'circles'`, `'lines'`, `'fills'`, `'extrusions'`, `'tiles3d'`,
+        `'models'`…) with its options; its id, given or made, is returned. A layer of the same id is replaced."""
+        self._ids += 1
+        key = id or f"{type}-{self._ids}"
+        spec = {"id": key, "type": type, **options(settings)}
+        if data is not None:
+            spec["data"] = to_geojson(data)
+        self.layers = [*(layer for layer in self.layers if layer["id"] != key), spec]
+        return key
+
+    def add_circles(self, data: Any, **style: Any) -> str:
+        """Points as circles: `color`, `radius`, `stroke_color`, `stroke_width`, `opacity`"""
+        return self.add("circles", data, **style)
+
+    def add_lines(self, data: Any, **style: Any) -> str:
+        """Lines (and the rings of polygons): `color`, `width`, `opacity`"""
+        return self.add("lines", data, **style)
+
+    def add_fills(self, data: Any, **style: Any) -> str:
+        """Polygons filled: `color`, `opacity`"""
+        return self.add("fills", data, **style)
+
+    def add_extrusions(self, data: Any, **style: Any) -> str:
+        """Polygons raised: `height` (metres, or a property's name), `base`, `color`"""
+        return self.add("extrusions", data, **style)
+
+    def add_tiles3d(self, url: str, **style: Any) -> str:
+        """A 3D Tiles tileset (`tileset.json`): `max_screen_space_error`, `opacity`"""
+        return self.add("tiles3d", url=url, **style)
+
+    def set_data(self, id: str, data: Any) -> None:
+        """A layer's data, given anew (the layer kept, its data set in place)"""
+        self.layers = [{**layer, "data": to_geojson(data)} if layer["id"] == id else layer for layer in self.layers]
+
+    def remove(self, id: str) -> None:
+        """Takes a layer away"""
+        self.layers = [layer for layer in self.layers if layer["id"] != id]
+
+    # Camera
+
+    def fly_to(self, center: Sequence[float] | None = None, duration: float | None = None, **camera: Any) -> None:
+        """A flight to a camera (`center`, `zoom`, `pitch`, `bearing`), zooming out on its way"""
+        self._call("flyTo", self._camera(center, camera), duration)
+
+    def ease_to(self, center: Sequence[float] | None = None, duration: float | None = None, **camera: Any) -> None:
+        """An animated move to a camera, in `duration` milliseconds"""
+        self._call("easeTo", self._camera(center, camera), duration)
+
+    def set_camera(self, center: Sequence[float] | None = None, **camera: Any) -> None:
+        """Moves the camera at once"""
+        self._call("setCamera", self._camera(center, camera))
+
+    # Events
+
+    def on_click(self, callback: Callable[[dict[str, Any]], None]) -> None:
+        """Calls `callback` with each click: `point` (pixels), `lon_lat`, and `feature` (its layer's `layer` id and
+        `properties`) when one of the layers is under it"""
+        self._clicks.append(callback)
+
+    # The widget's messages
+
+    @staticmethod
+    def _camera(center: Sequence[float] | None, camera: dict[str, Any]) -> Camera:
+        return {camel(k): v for k, v in {**camera, "center": list(center) if center else None}.items() if v is not None}
+
+    def _call(self, method: str, *args: Any) -> None:
+        self._ids += 1
+        message = {"kind": "call", "id": self._ids, "method": method, "args": [a for a in args if a is not None]}
+        if self._ready:
+            self.send(message)
+        else:
+            self._pending.append(message)
+
+    def _message(self, _widget: Any, content: dict[str, Any], _buffers: Any) -> None:
+        if content.get("kind") == "ready":
+            self._ready = True
+            for message in self._pending:
+                self.send(message)
+            self._pending.clear()
+        if content.get("kind") == "click":
+            click = content["click"]
+            event = {"point": click.get("point"), "lon_lat": click.get("lonLat"), "feature": click.get("feature")}
+            for callback in self._clicks:
+                callback(event)

isard_map/static/widget.js

@@ -0,0 +1,17 @@
+// Made by `bun scripts/build-widget.ts` from js/widget.ts: not to edit (isard 1.12.1)
+var k="1.12.1";var z=`https://cdn.jsdelivr.net/npm/isard@${k}/dist/index.js`,v=`(() => {
+  const Native = window.Worker;
+  window.Worker = class extends Native {
+    constructor(url, options) {
+      const href = new URL(String(url), document.baseURI);
+      if (href.origin === location.origin || href.protocol === 'blob:' || href.protocol === 'data:') {
+        super(url, options);
+        return;
+      }
+      const source = options && options.type === 'module'
+        ? 'import ' + JSON.stringify(href.href) + ';'
+        : 'importScripts(' + JSON.stringify(href.href) + ');';
+      super(URL.createObjectURL(new Blob([source], { type: 'text/javascript' })), options);
+    }
+  };
+})();`;import{GeoMap as j}from"https://cdn.jsdelivr.net/npm/isard@1.12.1/dist/index.js";var y=(e)=>typeof e==="object"&&e!==null&&!Array.isArray(e),N=["setCamera","easeTo","flyTo","getCamera","pickSurface"],A=(e)=>y(e)&&typeof e.id==="string"&&typeof e.type==="string",w=(e)=>Array.isArray(e)&&e.every(A),O=(e)=>typeof e==="string"&&N.includes(e);var x=(e)=>{if(!y(e))return!1;switch(e.kind){case"init":return y(e.options)&&w(e.layers);case"layers":return w(e.layers);case"call":return typeof e.id==="number"&&O(e.method)&&Array.isArray(e.args);default:return!1}};var f=(e)=>{let r=b(e);return x(r)?r:void 0},b=(e)=>{if(typeof e!=="string")return e;try{return JSON.parse(e)}catch{return}},c=({id:e,...r})=>r,P=(e)=>y(e)&&typeof e.property==="string"&&Object.keys(e).every((r)=>r==="property"||r==="default"),M=(e)=>({...Object.fromEntries(Object.entries(e).map(([r,t])=>{if(r==="data"||r==="values"||!P(t))return[r,t];let{property:n,default:a}=t;return[r,(o)=>o?.[n]??a]})),type:e.type}),L=(e,r)=>{let t=new Map(r.map((a)=>[a.id,a])),n={add:[],data:[],rebuild:[],remove:[]};return t.forEach((a,o)=>{let s=e.get(o);if(s===void 0){n.add.push(a);return}if(s===JSON.stringify(c(a)))return;let d=b(s),{data:p,values:i,...l}=y(d)?d:{},{data:g,values:m,...u}=c(a);(JSON.stringify(l)===JSON.stringify(u)?n.data:n.rebuild).push(a)}),e.forEach((a,o)=>{if(!t.has(o))n.remove.push(o)}),n};var J=()=>{let e=Reflect.get(window,"ReactNativeWebView"),r=typeof e==="object"&&e!==null?Reflect.get(e,"postMessage"):void 0;return typeof r==="function"?{postMessage:(t)=>Reflect.apply(r,e,[t])}:void 0},_=()=>{let e=J();return{send:(t)=>{let n=JSON.stringify(t);if(e)e.postMessage(n);else window.parent.postMessage(n,"*")},listen:(t)=>{let n=(a)=>{let o=a instanceof MessageEvent?f(a.data):void 0;if(o)t(o)};window.addEventListener("message",n),document.addEventListener("message",n)}}},D=(e)=>{let r=Reflect.get(e,"setData");return typeof r==="function"?(t)=>Reflect.apply(r,e,[t]):void 0},R=(e,r)=>{let t=Reflect.get(e,"setValues");if(typeof t!=="function"||!Array.isArray(r))return;Reflect.apply(t,e,[Float32Array.from(r,(n)=>typeof n==="number"?n:Number.NaN)])};class S{map;held=new Map;constructor(e){this.map=e}set(e){let r=L(new Map([...this.held].map(([n,{json:a}])=>[n,a])),e);r.remove.forEach((n)=>{this.held.get(n)?.layer.remove(),this.held.delete(n)}),r.data.forEach((n)=>{let a=this.held.get(n.id),o=a&&D(a.layer);if(a&&o&&F(n.data))o(n.data),R(a.layer,n.values),a.json=JSON.stringify(c(n));else r.rebuild.push(n)}),r.rebuild.forEach((n)=>{this.held.get(n.id)?.layer.remove(),this.held.delete(n.id)}),[...r.add,...r.rebuild].forEach((n)=>{let{values:a,...o}=c(n),s=this.map.add(M({...o,type:n.type}));R(s,a),this.held.set(n.id,{layer:s,json:JSON.stringify(c(n))})});let t=e.flatMap(({id:n})=>this.held.get(n)?.layer??[]);t.slice(0,-1).forEach((n,a)=>{n.moveBefore(t[a+1])})}idOf(e){return[...this.held].find(([,r])=>r.layer===e)?.[0]}get all(){return[...this.held.values()].map(({layer:e})=>e)}}var F=(e)=>typeof e==="object"&&e!==null&&("type"in e),T=(e)=>{let{center:r,zoom:t,pitch:n,bearing:a}=e.getCamera();return{center:r,zoom:t,pitch:n,bearing:a}},I=(e)=>({setCamera:(r)=>e.setCamera(r),easeTo:(r,t)=>e.easeTo(r,t),flyTo:(r,t)=>e.flyTo(r,t===void 0?{}:{duration:t}),getCamera:()=>T(e),pickSurface:(r)=>e.pickSurface(r)}),V=(e,r,t)=>Reflect.apply(e[r],void 0,t),C=(e=_(),r)=>{let t={waiting:[]},n=(s)=>e.send({kind:"error",message:String(s)}),a=(s)=>{let{map:d,layers:p}=t;if(s.kind==="init"){if(t.map)return;o(s.options,s.layers).catch(n);return}if(!d||!p){t.waiting.push(s);return}if(s.kind==="layers"){try{p.set(s.layers)}catch(i){n(i)}return}try{e.send({kind:"result",id:s.id,value:V(I(d),s.method,s.args)??null})}catch(i){e.send({kind:"failed",id:s.id,message:String(i)})}},o=async(s,d)=>{let p=r??document.getElementById("map");if(!p)throw Error("the page has no #map");let i=await j.create(p,s);if(t.gone){i.destroy();return}let l=new S(i);t.map=i,t.layers=l,l.set(d),i.on("click",({point:g,lonLat:m})=>{let u=i.pickFeature(g,{layers:l.all}),h=u&&l.idOf(u.layer),E={point:g,lonLat:m,feature:h?{layer:h,properties:u.feature?.properties??{}}:void 0};e.send({kind:"click",click:E})}),i.on("moveend",()=>e.send({kind:"moveend",camera:T(i)})),e.send({kind:"ready"}),t.waiting.splice(0).forEach(a)};return e.listen(a),e.send({kind:"loaded"}),()=>{t.gone=!0,t.map?.destroy()}};var B=()=>{if(document.querySelector("script[data-isard-workers]"))return;let e=document.createElement("script");e.dataset.isardWorkers="",e.textContent=v,document.head.append(e)},G=(e,r)=>({send:(t)=>{if(t.kind==="moveend"){e.set("camera",t.camera),e.save_changes();return}if(t.kind==="error")console.error(`isard: ${t.message}`);e.send(t)},listen:(t)=>{let n=()=>t({kind:"layers",layers:e.get("layers")}),a=(o)=>{let s=f(typeof o==="string"?o:JSON.stringify(o));if(s?.kind==="call")t(s)};e.on("change:layers",n),e.on("msg:custom",a),r.push(()=>e.off("change:layers",n),()=>e.off("msg:custom",a)),t({kind:"init",options:e.get("options"),layers:e.get("layers")})}}),re={render({model:e,el:r}){B();let t=document.createElement("div");t.style.position="relative",t.style.width="100%",t.style.height=e.get("height"),r.append(t);let n=[],a=C(G(e,n),t);return()=>{n.forEach((o)=>{o()}),a()}}};export{re as default};

isard_map-0.1.0.dist-info/METADATA

@@ -0,0 +1,78 @@
+Metadata-Version: 2.5
+Name: isard-map
+Version: 0.1.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
+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.

isard_map-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+isard_map/__init__.py,sha256=dGL_-6OgFdtC4oNwKrZ-JHcXbGOw4kVj65LQzx-uXlE,295
+isard_map/_data.py,sha256=6TeSPGcF3YzhPWD5N8jfjrLskRMuQfOL1iDQZpaF3mU,2083
+isard_map/_geoplateforme.py,sha256=yi0VZ4UwLtDYYZ2OO_ql4n7Hk2iQGgq85Ul4O7y1YS0,1184
+isard_map/_map.py,sha256=NXimk2i99ej4L-BGh7MOmTTSJrMDhABUDtFE7NBaNoU,6464
+isard_map/static/widget.js,sha256=CwON3CeK8Jp1KriK3J6qTMAIcaZtWSS83eeP-LEHoQA,6059
+isard_map-0.1.0.dist-info/METADATA,sha256=bjBD_rlEDy1QFxZveYGz-DqjoPBRyMD1YHZ04lNXE_E,3280
+isard_map-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+isard_map-0.1.0.dist-info/RECORD,,

isard_map-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any