Skip to content

Kepler.gl is a powerful open source geospatial analysis tool for large-scale data sets.

5.4 KB
Raw Blame
# SPDX-License-Identifier: MIT
# Copyright contributors to the kepler.gl project

"""Kepler.gl Jupyter Widget using anywidget."""

import pathlib
import copy
import anywidget
import traitlets

from .serializers import data_to_json, data_from_json
from ._html_export import export_map_html, DEFAULT_KEPLER_GL_CDN_VERSION

_STATIC_DIR = pathlib.Path(__file__).parent / "static"

class KeplerGl(anywidget.AnyWidget):
    """Kepler.gl Jupyter Widget using anywidget."""

    _esm = _STATIC_DIR / "widget.js"
    _css = _STATIC_DIR / "widget.css"

    data = traitlets.Dict({}).tag(sync=True, to_json=data_to_json, from_json=data_from_json)
    config = traitlets.Dict({}).tag(sync=True)
    height = traitlets.Int(400).tag(sync=True)
    mapbox_token = traitlets.Unicode("").tag(sync=True)
    theme = traitlets.Unicode("").tag(sync=True)
    app_name = traitlets.Unicode("kepler.gl").tag(sync=True)

    def __init__(self, data=None, config=None, height=400, mapbox_token="", use_arrow=False, show_docs=False, theme="", app_name="kepler.gl", **kwargs):
        """
        Initialize KeplerGl widget.

        Args:
            data: Dict of dataset name to data (DataFrame, GeoDataFrame, CSV, GeoJSON)
            config: Kepler.gl config dict
            height: Widget height in pixels
            mapbox_token: Mapbox API access token for Mapbox basemap styles
            use_arrow: If True, serialize DataFrames as Arrow IPC (more compact, preserves types)
            show_docs: Deprecated, kept for compatibility
            theme: UI theme for exported maps. Accepted values are
                "light", "dark", "base", or "" (default dark theme).
            app_name: Application name shown in the side panel header
                and used as HTML ``<title>`` when exporting. Defaults to
                ``"kepler.gl"``.
        """
        super().__init__(**kwargs)
        self._use_arrow = use_arrow
        self.theme = theme
        self.app_name = app_name
        self.height = height
        self.mapbox_token = mapbox_token

        if config:
            self.config = config

        if data:
            self._add_data_dict(data)

    def add_data(self, data, name="data", use_arrow=None):
        """Add data to the map.

        Args:
            data: DataFrame, GeoDataFrame, CSV string, or GeoJSON dict/string
            name: Dataset name/identifier
            use_arrow: If True, serialize DataFrame as Arrow IPC. If None (default),
                falls back to the widget-level use_arrow setting.
        """
        updated = copy.deepcopy(self.data)
        updated[name] = data
        if use_arrow is not None:
            self._use_arrow = use_arrow
        self.data = updated

    def _add_data_dict(self, data_dict):
        """Add multiple datasets from a dict."""
        updated = copy.deepcopy(self.data)
        for name, data in data_dict.items():
            updated[name] = data
        self.data = updated

    def save_to_html(
        self,
        file_name="keplergl_map.html",
        data=None,
        config=None,
        read_only=False,
        center_map=True,
        mapbox_token="",
        json_encoder=str,
        app_name=None,
        theme=None,
    ):
        """Export the map to a standalone HTML file.

        The exported HTML loads kepler.gl from the unpkg CDN (no local build needed)
        and embeds the current data and configuration.

        Args:
            file_name: Output HTML file path (default: 'keplergl_map.html')
            data: Dict of dataset name to data. If None, uses current widget data.
            config: Map config dict. If None, uses current widget config.
            read_only: If True, hide side panel to disable map customization.
            center_map: If True, fit map bounds to the data (default: True).
            mapbox_token: Mapbox access token. Required for Mapbox basemap styles
                (e.g. "Dark", "Muted Light"). Leave empty for free MapLibre styles.
            json_encoder: Fallback function passed as ``default`` when
                JSON-serializing GeoDataFrame data.  Defaults to ``str`` so
                that ``datetime`` and similar types are converted automatically.
                Pass ``None`` to disable (will raise on non-serializable types).
            app_name: Application name shown in the side panel header and used
                as HTML ``<title>``.  If None, uses the value set at widget
                creation (default ``"kepler.gl"``).
            theme: UI theme for the kepler.gl component (``"light"``,
                ``"dark"``, ``"base"``, or ``""``).  If None, uses the value
                set at widget creation.
        """
        data_to_save = data if data is not None else self.data
        config_to_save = config if config is not None else self.config
        token = mapbox_token if mapbox_token else self.mapbox_token
        resolved_theme = theme if theme is not None else self.theme
        resolved_app_name = app_name if app_name is not None else self.app_name

        html = export_map_html(
            data=data_to_save,
            config=config_to_save,
            read_only=read_only,
            center_map=center_map,
            mapbox_token=token,
            kepler_gl_version=DEFAULT_KEPLER_GL_CDN_VERSION,
            json_encoder=json_encoder,
            app_name=resolved_app_name,
            theme=resolved_theme,
        )

        with open(file_name, "w", encoding="utf-8") as f:
            f.write(html)

        print(f"Map saved to {file_name}!")