ipyeoxelements 1.0.0rc1

Jupyter notebook wrapper for EOxElements web components

EOxElements Jupyter

A Python wrapper for using EOxElements web components inside Jupyter Notebooks.

Built on top of anywidget, this package provides a Pythonic API to visualize Earth Observation data using modern web standards (Custom Elements) directly in your notebook.

Useful Links:

• Demos & Docs: EOxElements Documentation
• Source: GitHub Repository

Features

• Simple Python API: CamelCase Python classes (e.g., EOxMap) map automatically to kebab-case HTML tags (<eox-map>).
• Auto-generated: Wrappers are generated from the official custom-elements.json manifest, ensuring API parity.
• Version Pinning: Manage specific versions of the underlying JavaScript libraries via a simple configuration file.
• Jupyter Integration: Works in JupyterLab, Jupyter Notebook, and VS Code.

Installation

pip install ipyeoxelements

Note: After installing, you may need to restart your Jupyter kernel/server for the widget extensions to load correctly.

Usage

For a comprehensive walkthrough, check out examples.ipynb included in this repository.

1. Chart (EOxChart)

Pass a Vega-Lite specification dictionary directly to the widget.

from ipyeoxelements import EOxChart

spec_data = {
    "$schema": "[https://vega.github.io/schema/vega-lite/v5.json](https://vega.github.io/schema/vega-lite/v5.json)",
    "description": "A simple bar chart with embedded data.",
    "data": {
        "values": [
            {"a": "A", "b": 28}, {"a": "B", "b": 55}, {"a": "C", "b": 43},
            {"a": "D", "b": 91}, {"a": "E", "b": 81}, {"a": "F", "b": 53},
            {"a": "G", "b": 19}, {"a": "H", "b": 87}, {"a": "I", "b": 52},
        ],
    },
    "mark": {"type": "bar", "tooltip": True, "fill": "#004170"},
    "encoding": {
        "x": {"field": "a", "type": "ordinal"},
        "y": {"field": "b", "type": "quantitative"},
    },
}

# Layout can be passed as a simple dictionary
my_chart = EOxChart(spec=spec_data, layout={"height": "400px"})
display(my_chart)

2. Map (EOxMap)

Define layers using Python lists and dictionaries.

from ipyeoxelements import EOxMap

map_layers = [
    {
        "type": "STAC",
        "properties": {
          "id": "stacLayer",
        },
        "url": "[https://s3.us-west-2.amazonaws.com/sentinel-cogs/sentinel-s2-l2a-cogs/10/T/ES/2022/7/S2A_10TES_20220726_0_L2A/S2A_10TES_20220726_0_L2A.json](https://s3.us-west-2.amazonaws.com/sentinel-cogs/sentinel-s2-l2a-cogs/10/T/ES/2022/7/S2A_10TES_20220726_0_L2A/S2A_10TES_20220726_0_L2A.json)",
    },
    {
        "type": "Tile",
        "properties": {"id": "osm", "title": "OSM"},
        "source": {"type": "OSM"},
    }
]

map = EOxMap(
    layers=map_layers, 
    zoom=7, 
    center=[-122, 46.5], 
    layout={"height": "400px"}
)
display(map)

3. Advanced Layout (EOxMap + EOxLayercontrol)

To combine widgets, use standard ipywidgets layout containers like HBox or VBox.

Important: You must link the Layer Control to the Map using the map's id and the controller's for_ argument.

from ipywidgets import HBox, Layout
from ipyeoxelements import EOxMap, EOxLayercontrol

MAP_ID = "my-unique-map-id"

# 1. Create Map
my_map = EOxMap(
    id=MAP_ID,
    layers=[{"type": "Tile", "source": {"type": "OSM"}}],
    center=[16, 48],
    zoom=5,
    layout=Layout(flex="2", height="400px") # Take up 2/3 width
)

# 2. Create Control linked to Map
control = EOxLayercontrol(
    for_=f"#{MAP_ID}", # Must match the Map ID selector
    tools=["config"],
    layout=Layout(flex="1", height="400px", overflow="auto") # Take up 1/3 width
)

# 3. Display side-by-side
display(HBox([my_map, control]))

Local Development

This package uses a Code Generator (generate.py) to create the Python wrappers based on a configuration file (elements_config.json).

1. Configuration

To add new elements, update versions, or add dependencies, edit elements_config.json:

{
  "eox-map": {
    "version": "latest",
    "dependencies": [],
    "extra_imports": ["dist/eox-map-advanced-layers-and-sources.js"]
  }
}

Then run the generator to update ipyeoxelements/generated.py:

python generate.py

2. Development Environment

Option A: Jupyter inside Docker (Recommended)

This ensures a clean environment isolated from your system Python.

1. Run Jupyter mounting your current directory to /home/jovyan/work:

   docker run -p 8888:8888 -v "$(pwd):/home/jovyan/work" jupyter/base-notebook
   

2. Open the link printed in the terminal to access JupyterLab.
3. Open a Terminal inside JupyterLab.
4. Install the package in Editable Mode:

   cd work
   pip install -e . --break-system-packages
   

   (Note: --break-system-packages is safe here as it is a disposable container).
5. Open examples.ipynb and run the cells. If you make changes to generate.py, run it, then Restart the Kernel to see changes.

Option B: VS Code

You can develop locally using VS Code's native Jupyter support.

1. Create a virtual environment:

   python -m venv .venv
   source .venv/bin/activate
   

2. Install dependencies and the package in editable mode:

   pip install -e .
   pip install ipykernel
   

3. Open examples.ipynb in VS Code.
4. Click Select Kernel (top right) -> Python Environments -> Select your .venv.
5. Run the cells.

License

MIT