pyglobegl 0.2.0

AnyWidget wrapper for globe.gl

pyglobegl

AnyWidget wrapper for globe.gl with integrations with popular Python spatial packages.

Goals

• Provide a modern AnyWidget-based globe.gl wrapper for Jupyter, JupyterLab, Colab, VS Code, and marimo.
• Ship a prebuilt JupyterLab extension via pip install (no separate lab build/extension install).
• Keep the Python API friendly for spatial data workflows.

Roadmap

• Near term

  • Expose globe.gl APIs in order (by section):
    • Initialisation
    • Container layout
    • Globe layer
    • Points layer
    • Arcs layer
    • Polygons layer
    • Paths layer
    • Heatmaps layer
    • Hex bin layer
    • Hexed polygons layer
    • Tiles layer
    • Particles layer
    • Rings layer
    • Labels layer
    • HTML elements layer
    • 3D objects layer
    • Custom layer
    • Render control
    • Utility options
  • Prioritize strongly typed, overload-heavy Python APIs with flexible input unions (e.g., accept Pillow images, NumPy arrays, or remote URLs anywhere globe.gl accepts textures/images).
  • Solidify a CRS-first API: detect CRS on inputs and auto-reproject to EPSG:4326 before emitting lat/lng data for globe.gl layers.

• Mid term

  • GeoPandas adapter: map geometry types to globe.gl layers with sensible defaults and schema validation.
  • MovingPandas trajectories (static): accept trajectory/segment outputs and render via paths/arcs without time animation in v1.
  • Geometry-only inputs: accept bare geometry collections (Shapely or GeoJSON-like) as a convenience layer when CRS metadata is explicit.

• Long term / research

  • GeoPolars exploration: track maturity and define an adapter plan once CRS metadata and extension types are stable upstream.
  • Raster feasibility: investigate mapping rasters to globe.gl via tiles, heatmaps, or sampled grids; document constraints and recommended workflows.

WSL2 Test Notes

• WSL2 UI tests require WSLg with a working display socket (Wayland or X11) and WebGL available in the Playwright Chromium build.
• If the UI tests are meant to enforce hardware acceleration, set PYGLOBEGL_REQUIRE_HW_ACCEL=1 before running pytest so software renderers skip early.
• Canvas reference comparisons allow a small pixel-diff tolerance. Override with PYGLOBEGL_MAX_DIFF_RATIO (e.g. 0.02 for a 2% threshold) to tighten or loosen comparisons across platforms.
• On WSL2, the UI test harness retries the browser launch with the D3D12-backed Mesa driver if the initial WebGL probe reports a software renderer. You can still set GALLIUM_DRIVER=d3d12 and MESA_LOADER_DRIVER_OVERRIDE=d3d12 manually, and optionally set PYGLOBEGL_WSL_GPU_ADAPTER=<GPU name> to map to MESA_D3D12_DEFAULT_ADAPTER_NAME when multiple adapters are present.

Build Assets (Release Checklist)

1. cd frontend && pnpm run build
2. uv build

Quickstart

from pyglobegl import GlobeWidget, image_to_data_url
from PIL import Image

GlobeWidget()

Image Inputs

Globe image fields expect URLs, but you can pass a PIL image by converting it to a PNG data URL:

from pyglobegl import GlobeLayerConfig, image_to_data_url
from PIL import Image

image = Image.open("earth.png")
config = GlobeLayerConfig(globe_image_url=image_to_data_url(image))