ipyd3geo 0.1.0__tar.gz

ipyd3geo-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+docs/superpowers/
+docs/_build/
+__pycache__/
+*.pyc
+node_modules/
+.venv/
+dist/

ipyd3geo-0.1.0/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, ipyd3geo contributors
+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.

ipyd3geo-0.1.0/PKG-INFO

@@ -0,0 +1,61 @@
+Metadata-Version: 2.5
+Name: ipyd3geo
+Version: 0.1.0
+Summary: An interactive map widget for Jupyter that uses D3 Geo as its renderer.
+Project-URL: Repository, https://github.com/geojupyter/prototype-ipyd3geo
+Project-URL: Issues, https://github.com/geojupyter/prototype-ipyd3geo/issues
+Author-email: Benjamin Szeghy <benjamin.szeghy@berkeley.edu>
+License-Expression: BSD-3-Clause
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Jupyter
+Classifier: Framework :: Jupyter :: JupyterLab
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: GIS
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Python: >=3.10
+Requires-Dist: anywidget>=0.11.0
+Description-Content-Type: text/markdown
+
+# ipyd3geo
+
+A Jupyter widget for D3-based geospatial visualization.
+
+It is designed to work similarly to other map renderer widgets, but uses D3-Geo as its renderer.
+
+Using D3-Geo over other map renderers has a number of key benefits:
+- Renders directly to an SVG. This package acts as a bridge between Jupyter-based geospatial tools, and cartography in design software.
+- Maps can be arbitrarily styled with CSS or D3
+- Native vector output means no pixelation, so rendered maps are infinitely scalable.
+- Native best in class projection support. There are few if any conventionally defined projections that D3-Geo does not support (including certain very obscure ones)
+
+However, there are a few tradeoffs:
+- Due to its lack of virtualization, it is far less performant with large datasets than alternatives.
+- It is intentionally client-side only, so it does not have any tiling server functionality
+
+
+</br></br>
+> [!WARNING]
+> For now this project is experimental. We cannot guarantee further development or ongoing maintenance.
+>
+> If you or your organization are interested in supporting this project's development, either financially or in kind, please email Benny@BennySzeghy.com
+
+## Installation
+
+```sh
+pip install ipyd3geo
+```
+or 
+```sh
+uv add ipyd3geo
+```
+
+## Development
+
+```sh
+uv sync
+pnpm install ## No build step is actually needed yet. This will be added in the future
+```
+
+See [examples/example.ipynb](examples/example.ipynb) for usage.

ipyd3geo-0.1.0/README.md

@@ -0,0 +1,41 @@
+# ipyd3geo
+
+A Jupyter widget for D3-based geospatial visualization.
+
+It is designed to work similarly to other map renderer widgets, but uses D3-Geo as its renderer.
+
+Using D3-Geo over other map renderers has a number of key benefits:
+- Renders directly to an SVG. This package acts as a bridge between Jupyter-based geospatial tools, and cartography in design software.
+- Maps can be arbitrarily styled with CSS or D3
+- Native vector output means no pixelation, so rendered maps are infinitely scalable.
+- Native best in class projection support. There are few if any conventionally defined projections that D3-Geo does not support (including certain very obscure ones)
+
+However, there are a few tradeoffs:
+- Due to its lack of virtualization, it is far less performant with large datasets than alternatives.
+- It is intentionally client-side only, so it does not have any tiling server functionality
+
+
+</br></br>
+> [!WARNING]
+> For now this project is experimental. We cannot guarantee further development or ongoing maintenance.
+>
+> If you or your organization are interested in supporting this project's development, either financially or in kind, please email Benny@BennySzeghy.com
+
+## Installation
+
+```sh
+pip install ipyd3geo
+```
+or 
+```sh
+uv add ipyd3geo
+```
+
+## Development
+
+```sh
+uv sync
+pnpm install ## No build step is actually needed yet. This will be added in the future
+```
+
+See [examples/example.ipynb](examples/example.ipynb) for usage.

ipyd3geo-0.1.0/pyproject.toml

@@ -0,0 +1,54 @@
+[project]
+name = "ipyd3geo"
+version = "0.1.0"
+description = "An interactive map widget for Jupyter that uses D3 Geo as its renderer."
+readme = "README.md"
+license = "BSD-3-Clause"
+authors = [
+    { name = "Benjamin Szeghy", email = "benjamin.szeghy@berkeley.edu" }
+]
+requires-python = ">=3.10"
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Framework :: Jupyter",
+    "Framework :: Jupyter :: JupyterLab",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3",
+    "Topic :: Scientific/Engineering :: GIS",
+    "Topic :: Scientific/Engineering :: Visualization",
+]
+dependencies = [
+    "anywidget>=0.11.0",
+]
+
+[project.urls]
+Repository = "https://github.com/geojupyter/prototype-ipyd3geo"
+Issues = "https://github.com/geojupyter/prototype-ipyd3geo/issues"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "src/ipyd3geo",
+    "LICENSE",
+    "README.md",
+    "pyproject.toml",
+]
+
+[dependency-groups]
+dev = [
+    "ipykernel>=7.3.0",
+    "jupyterlab>=4.6.4",
+    "pytest>=9.1.1",
+]
+docs = [
+    "myst-parser>=5.1.0",
+    "pydata-sphinx-theme>=0.21.0",
+    "sphinx>=9.1.0",
+    "sphinx-autodoc-typehints>=3.13.7",
+]
+
+[tool.uv.dependency-groups]
+docs = { requires-python = ">=3.12" }

ipyd3geo-0.1.0/src/ipyd3geo/__init__.py

@@ -0,0 +1,4 @@
+from .widget import Map, Projection, GeoJSON, VectorStyle
+
+__all__ = ["Map", "Projection", "GeoJSON", "VectorStyle"]
+

ipyd3geo-0.1.0/src/ipyd3geo/static/widget.js

@@ -0,0 +1,156 @@
+import * as d3 from "https://esm.sh/d3-geo@3.1.1";
+import { zoom } from "https://esm.sh/d3-zoom@3.0.0";
+import { select } from "https://esm.sh/d3-selection@3.0.0";
+
+async function render({ model, el }) {
+
+  if (model.get("hamburger")) {
+    const menuButton = document.createElement("button");
+    menuButton.textContent = "☰";
+    menuButton.style.display = "block";
+    el.appendChild(menuButton);
+    const menuContent = document.createElement("div");
+    menuContent.style.display = "none";
+    menuContent.style.position = "absolute";
+    menuContent.style.color = "black";
+    menuContent.style.cursor = "pointer";
+    menuContent.style.backgroundColor = "lightgray";
+    menuContent.style.padding = "5px";
+    menuContent.style.border = "1px solid black";
+
+    const exportSvgButton = document.createElement("div");
+    exportSvgButton.textContent = "Export SVG";
+    exportSvgButton.addEventListener('click', () => {
+      const svgString = new XMLSerializer().serializeToString(svg);
+      const blob = new Blob([svgString], { type: "image/svg+xml" });
+      const url = URL.createObjectURL(blob);
+      const a = document.createElement("a");
+      a.href = url;
+      a.download = "map.svg";
+      a.click();
+      URL.revokeObjectURL(url);
+    });
+    menuContent.appendChild(exportSvgButton);
+
+//TODO this is the wrong approach to toggling graticule visibility, bc it doesn't toggle on if it didn't start visible.
+    const graticuleButton = document.createElement("div");
+    graticuleButton.textContent = `Toggle Graticule${model.get("graticule") ? " ✓" : ""}`;
+    graticuleButton.addEventListener('click', () => {
+      if (graticule) {
+        const isShown = graticule.style.display === 'none';
+        graticule.style.display = isShown ? 'block' : 'none';
+        model.set("graticule", isShown);
+        model.save_changes();
+        graticuleButton.textContent = `Toggle Graticule${isShown ? ' ✓' : ''}`;
+      }
+    });
+    menuContent.appendChild(graticuleButton);
+
+    el.appendChild(menuContent);
+
+    menuButton.addEventListener('click', () => {
+      menuContent.style.display = menuContent.style.display === 'none' ? 'block' : 'none';
+    });
+  }
+
+  const countries = await fetch(
+    "https://cdn.jsdelivr.net/gh/nvkelso/natural-earth-vector/geojson/ne_110m_admin_0_countries.geojson"
+  ).then((res) => res.json());
+
+  const projection = d3[model.get("projection")]();
+  projection.rotate(model.get("projection_rotate"));
+  const center = model.get("projection_center");
+  if (center) projection.center(center);
+  const precision = model.get("projection_precision");
+  if (precision != null) projection.precision(precision);
+  const parallels = model.get("projection_parallels");
+  if (parallels) projection.parallels(parallels);
+  const path = d3.geoPath(projection);
+  const baseScale = projection.scale();
+  const baseTranslate = projection.translate();
+  const basemap = model.get("basemap");
+
+  const svg = document.createElementNS("http://www.w3.org/2000/svg", "svg");
+  svg.setAttribute("viewBox", "0 0 960 500");
+  svg.setAttribute("width", "960");
+  svg.setAttribute("height", "500");
+  const sphere = document.createElementNS("http://www.w3.org/2000/svg", "path");
+  sphere.setAttribute("fill", "none");
+  sphere.setAttribute("stroke", model.get("border") ? "black" : "none");
+  svg.appendChild(sphere);
+
+  let naturalEarth = null;
+  if (basemap === "naturalearth") {
+    naturalEarth = document.createElementNS("http://www.w3.org/2000/svg", "path");
+    naturalEarth.setAttribute("fill", "none");
+    naturalEarth.setAttribute("stroke", "black");
+    svg.appendChild(naturalEarth);
+  }
+
+  const layerGroup = document.createElementNS("http://www.w3.org/2000/svg", "g");
+  svg.appendChild(layerGroup);
+  function drawLayers() {
+    layerGroup.replaceChildren();
+    for (const layerData of model.get("layers")) {
+      for (const feature of layerData.features) {
+        const style = feature.properties.__ipyd3geo_style__ || {};
+        const layer = document.createElementNS("http://www.w3.org/2000/svg", "path");
+        layer.setAttribute("d", path(feature));
+        layer.setAttribute("fill", style.fill_color || "none");
+        layer.setAttribute("stroke", style.stroke_color || "#000000");
+        layer.setAttribute("stroke-width", style.weight || 3);
+        layer.setAttribute("stroke-opacity", style.stroke_opacity || 1.0);
+        layer.setAttribute("fill-opacity", style.fill_opacity || 0.2);
+        layerGroup.appendChild(layer);
+      }
+    }
+  }
+  model.on("change:layers", drawLayers);
+
+  let graticule = null;
+  if (model.get("graticule")) {
+    graticule = document.createElementNS("http://www.w3.org/2000/svg", "path");
+    graticule.setAttribute("fill", "none");
+    graticule.setAttribute("stroke", "lightgray");
+    graticule.setAttribute("opacity", "0.5");
+    svg.appendChild(graticule);
+  }
+
+  function redraw() {
+    sphere.setAttribute("d", path({ type: "Sphere" }));
+    if (naturalEarth) naturalEarth.setAttribute("d", path(countries));
+    if (graticule) graticule.setAttribute("d", path(d3.geoGraticule()()));
+    drawLayers();
+  }
+  redraw();
+
+  const dynamic = model.get("dynamic");
+  if (dynamic !== "none") {
+    let prev = { x: 0, y: 0 };
+    const zoomBehavior = zoom().on("zoom", (event) => {
+      const t = event.transform;
+      projection.scale(baseScale * t.k);
+      const isDrag = /^(mouse|touch)move$/.test(event.sourceEvent?.type);
+      if (dynamic === "rotate") {
+        if (isDrag) {
+          const [lambda, phi, gamma] = projection.rotate();
+          const degPerPixel = 180 / (Math.PI * projection.scale());
+          projection.rotate([
+            lambda + (t.x - prev.x) * degPerPixel,
+            phi - (t.y - prev.y) * degPerPixel,
+            gamma,
+          ]);
+        }
+      } else {
+        projection.translate([t.x + baseTranslate[0] * t.k, t.y + baseTranslate[1] * t.k]);
+      }
+      prev = { x: t.x, y: t.y };
+      redraw();
+    });
+    select(svg).call(zoomBehavior);
+  }
+
+  el.appendChild(svg);
+}
+
+export default { render };

ipyd3geo-0.1.0/src/ipyd3geo/widget.py

@@ -0,0 +1,192 @@
+import inspect
+import pathlib
+
+import anywidget
+import traitlets
+
+import json
+
+class Map(anywidget.AnyWidget):
+    """Defines a D3-Geo backed map widget for Jupyter notebooks.
+
+    Args:
+        center (tuple): center of the map (longitude, latitude). **Not implemented yet.**
+        zoom (float): The zoom level of the map. **Not implemented yet.**
+        projection (Projection or str): The projection to use for the map. If a string is provided, it will be used to create a Projection object. Defaults to "geoEqualEarth".
+        graticule (bool): Whether to show the graticule.
+        border (bool): Whether to draw a border frame around the map.
+        basemap (str): The basemap to use. **Not implemented yet. Currently defaults to Natural Earth small scale borders.**
+        hamburger (bool): Whether to show the hamburger menu. **Not implemented yet.**
+        dynamic (str or bool): Whether the map is dynamically draggable. Value can be True, False, "pan", or "rotate". If True, the map will be draggable, and choose a default mode. If False, the map will not be draggable. If "pan", the map will pan post-projection. If "rotate", the map will be rotatable pre-projection.
+    """
+
+    _esm = pathlib.Path(__file__).parent / "static" / "widget.js"
+
+    projection = traitlets.Unicode("geoEqualEarth").tag(sync=True)
+    border = traitlets.Bool(True).tag(sync=True)
+    graticule = traitlets.Bool(False).tag(sync=True)
+    projection_rotate = traitlets.Tuple(traitlets.Float(), traitlets.Float(), traitlets.Float(), default_value=(0, 0, 0)).tag(sync=True)
+    projection_center = traitlets.Tuple(traitlets.Float(), traitlets.Float(), allow_none=True, default_value=None).tag(sync=True)
+    projection_precision = traitlets.Float(allow_none=True, default_value=None).tag(sync=True)
+    projection_parallels = traitlets.Tuple(traitlets.Float(), traitlets.Float(), allow_none=True, default_value=None).tag(sync=True)
+    layers = traitlets.List().tag(sync=True)
+    dynamic = traitlets.Unicode("pan").tag(sync=True)
+    basemap = traitlets.Unicode("").tag(sync=True)
+    hamburger = traitlets.Bool(True).tag(sync=True)
+
+    class Export:
+        def __init__(self, map):
+            self._map = map
+
+        def svg(self, path):
+            raise NotImplementedError
+
+    def __init__(self, center=(0.0, 0.0), zoom=1.0, projection=None, graticule=False, border=True, basemap=False, hamburger=True, dynamic=True):
+        if center != (0.0, 0.0):
+            raise NotImplementedError
+        if zoom != 1.0:
+            raise NotImplementedError
+        if projection is None:
+            projection = Projection()
+        elif isinstance(projection, str):
+            projection = Projection(projection)
+        super().__init__()
+        self.projection = projection.name
+        self.projection_rotate = projection.rotate
+        self.projection_center = projection.center
+        self.projection_precision = projection.precision
+        self.projection_parallels = projection.parallels
+        self.border = border
+        self.graticule = graticule
+        if basemap == "naturalearth" or basemap == True:
+            self.basemap = "naturalearth"
+        elif basemap == False:
+            self.basemap = ""
+        else:
+            raise ValueError(f"basemap must be 'naturalearth', True, or False")
+        self.hamburger = hamburger
+        if dynamic is True or dynamic is False:
+            self.dynamic = "pan" if dynamic else "none" #TODO: figure out how to make it decide mode based on whether or not the projection is globe-like
+        elif dynamic == "pan":
+            self.dynamic = "pan"
+        elif dynamic == "rotate":
+            self.dynamic = "rotate"
+        else:
+            raise ValueError(f"dynamic must be True, False, 'pan', or 'rotate'")
+        self.export = Map.Export(self)
+
+    def add(self, layer):
+        """Add a layer to the map. Only GeoJSON layers are supported so far."""
+        self.layers = [*self.layers, layer.data]
+
+    def remove(self, layer):
+        """Remove a layer from the map. **Not implemented yet.**"""
+        raise NotImplementedError
+
+Map.__signature__ = inspect.Signature(list(inspect.signature(Map.__init__).parameters.values())[1:])
+
+class Projection:
+    """Defines a D3-Geo projection for the map widget.
+
+    Args:
+        name (str): The name of the projection. Defaults to "geoEqualEarth". See `d3-geo geoProjection docs <https://d3js.org/d3-geo/projection#geoProjection>`_ for options.
+        rotate (tuple): The rotation of the projection.
+        center (tuple): The center of the projection.
+        precision (float): The precision of the projection.
+        parallels (tuple): The parallels of the projection. Only applicable for conic projections.
+    """
+    def __init__(self, name="geoEqualEarth", rotate=(0, 0, 0), center=None, precision=None, parallels=None):
+        self.name = name
+        self.rotate = tuple(rotate)
+        self.center = center
+        self.precision = precision
+        self.parallels = parallels
+
+class VectorStyle:
+
+    def __init__(self, stroke_color="#000000", fill_color="#ffffff", weight=3, stroke_opacity=1.0, fill_opacity=1.0):
+        self.stroke_color = stroke_color
+        self.fill_color = fill_color
+        self.weight = weight
+        self.stroke_opacity = stroke_opacity
+        self.fill_opacity = fill_opacity
+
+    def resolve(self, properties):
+        """Return the concrete style for one feature. Callables receive the feature's properties."""
+        return {
+            attribute: value(properties) if callable(value) else value
+            for attribute, value in vars(self).items()
+        }
+
+class Layer:
+    """Base class for all layers in the map widget.
+
+    Args:
+        name (str): The name of the layer.
+    """
+    def __init__(self, name=""):
+        self.name = name
+
+class Point(Layer):
+    """A point layer on the map. **Not implemented yet.**"""
+    def __init__(self, location, color="#3388ff", name=""):
+        raise NotImplementedError
+
+class Polygon(Layer):
+    """A polygon layer on the map. **Not implemented yet.**"""
+    def __init__(self, locations, color="#3388ff", fill_color="#3388ff", name=""):
+        raise NotImplementedError
+
+class Line(Layer):
+    """A line layer on the map. **Not implemented yet.**"""
+    def __init__(self, locations, color="#3388ff", name=""):
+        raise NotImplementedError
+
+class GeoJSON(Layer):
+    """A GeoJSON layer on the map.
+
+    Args:
+        data (dict, str, or pathlib.Path): GeoJSON as a dict, a JSON string, or a path to a GeoJSON file.
+        name (str): The name of the layer.
+        style (VectorStyle): The style of the layer.
+    """
+    def __init__(self, data, name="",style=None):
+        super().__init__(name)
+        if isinstance(data, pathlib.Path):
+            with open(data, "r") as f:
+                data = json.load(f)
+        elif type(data) is str:
+            if not data.strip().startswith("{"):
+                if pathlib.Path(data).exists():
+                    with open(data, "r") as f:
+                        data = json.load(f)
+                else:
+                    raise ValueError(f"data string is not a valid JSON or file path: {data}")
+            else:
+                data = json.loads(data)
+        elif not isinstance(data, dict):
+            raise TypeError("data must be a dict, str, or pathlib.Path")
+        style = style or VectorStyle()
+        features = []
+        for f in data.get("features", []):
+            props = f.get("properties") or {}
+            features.append({**f, "properties": {**props, "__ipyd3geo_style__": style.resolve(props)}})
+        self.data = {**data, "features": features}
+
+class GeoData(Layer):
+    """A GeoDataFrame (such as from geopandas) layer on the map. **Not implemented yet.**"""
+    def __init__(self, data, name=""):
+        raise NotImplementedError
+
+class Raster(Layer):
+    """A local raster layer on the map. **Not implemented yet.**"""
+    def __init__(self, data, name=""):
+        raise NotImplementedError
+
+class TileService(Layer):
+    """Raster tiles from a service. **Not implemented yet.**"""
+    def __init__(self, url, name=""):
+        raise NotImplementedError
+
+if __name__ == "__main__":
+    pass