Skip to content

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

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

"""Generate standalone HTML export using the kepler.gl UMD bundle from CDN."""

from __future__ import annotations

import json
import html
from typing import Optional

import pandas as pd
import geopandas as gpd

DEFAULT_KEPLER_GL_CDN_VERSION = "3.3.0-alpha.18"

REACT_VERSION = "19.1.0"
REACT_DOM_VERSION = "19.1.0"
REDUX_VERSION = "5.0.1"
REACT_REDUX_VERSION = "9.3.0"
STYLED_COMPONENTS_VERSION = "6.1.19"
ES_MODULE_SHIMS_VERSION = "2.8.1"


def _dataset_to_csv(data) -> Optional[str]:
    """Convert a dataset value to CSV string for kepler.gl processCsvData."""
    if isinstance(data, gpd.GeoDataFrame):
        import shapely.wkt

        if data.crs and data.crs.to_epsg() != 4326:
            data = data.to_crs(4326)
        df = pd.DataFrame(data)
        geom_col = data.geometry.name
        df[geom_col] = data.geometry.apply(shapely.wkt.dumps)
        return df.to_csv(index=False)
    elif isinstance(data, pd.DataFrame):
        return data.to_csv(index=False)
    elif isinstance(data, str):
        return data
    else:
        return None


def _dataset_to_geojson(data, json_encoder=str) -> Optional[dict]:
    """Try to convert dataset to GeoJSON dict.

    Args:
        data: Dataset value (GeoDataFrame, dict, or string).
        json_encoder: Fallback function passed as ``default`` to
            ``GeoDataFrame.to_json()`` so that non-serializable types
            (e.g. ``datetime``) are converted instead of raising.
            Defaults to ``str``.  Pass ``None`` to disable (will raise
            on non-serializable types).
    """
    if isinstance(data, gpd.GeoDataFrame):
        if data.crs and data.crs.to_epsg() != 4326:
            data = data.to_crs(4326)
        return json.loads(data.to_json(default=json_encoder))
    elif isinstance(data, dict):
        geojson_types = {
            "FeatureCollection", "Feature", "Point", "MultiPoint",
            "LineString", "MultiLineString", "Polygon", "MultiPolygon",
            "GeometryCollection",
        }
        if data.get("type") in geojson_types:
            return data
    elif isinstance(data, str):
        try:
            parsed = json.loads(data)
            if isinstance(parsed, dict) and parsed.get("type") in {
                "FeatureCollection", "Feature",
            }:
                return parsed
        except (json.JSONDecodeError, TypeError):
            pass
    return None


def _geojson_dataset_names(data: dict, json_encoder=str) -> set:
    """Return the set of dataset names that will be serialized as GeoJSON."""
    names: set = set()
    for name, dataset in data.items():
        if _dataset_to_geojson(dataset, json_encoder=json_encoder) is not None:
            names.add(name)
    return names


def _fixup_geojson_columns(config: Optional[dict], geojson_names: set) -> Optional[dict]:
    """Rewrite layer column references for GeoJSON datasets.

    ``processGeojson`` stores the geometry as ``_geojson`` regardless of the
    original column name.  Configs produced by the Jupyter widget use the
    source GeoDataFrame column name (commonly ``geometry``), so the layer
    merger cannot match them.  This helper patches those references so the
    exported HTML applies the full config.
    """
    if not config or not geojson_names:
        return config

    import copy
    config = copy.deepcopy(config)
    layers = (config
              .get("config", {})
              .get("visState", {})
              .get("layers", []))
    for layer in layers:
        layer_cfg = layer.get("config", {})
        data_id = layer_cfg.get("dataId")
        if data_id not in geojson_names:
            continue
        columns = layer_cfg.get("columns", {})
        if "geojson" in columns and columns["geojson"] != "_geojson":
            columns["geojson"] = "_geojson"
    return config


def _serialize_datasets_for_html(data: dict, json_encoder=str) -> str:
    """Serialize datasets dict into JS code that calls addDataToMap.

    Generates a JS snippet that processes each dataset using kepler.gl's
    processCsvData or processGeojson, then dispatches addDataToMap.

    Args:
        data: Dict mapping dataset names to data objects.
        json_encoder: Fallback encoder passed to ``_dataset_to_geojson``.
    """
    snippets = []
    for name, dataset in data.items():
        geojson = _dataset_to_geojson(dataset, json_encoder=json_encoder)
        if geojson is not None:
            snippets.append(
                f"  datasets.push({{info: {{id: {json.dumps(name, ensure_ascii=False)}, label: {json.dumps(name, ensure_ascii=False)}}}, "
                f"data: keplerGl.processGeojson({json.dumps(geojson, ensure_ascii=False)})}});"
            )
        else:
            csv_str = _dataset_to_csv(dataset)
            if csv_str is not None:
                snippets.append(
                    f"  datasets.push({{info: {{id: {json.dumps(name, ensure_ascii=False)}, label: {json.dumps(name, ensure_ascii=False)}}}, "
                    f"data: keplerGl.processCsvData({json.dumps(csv_str, ensure_ascii=False)})}});"
                )
    return "\n".join(snippets)


def export_map_html(
    data: dict,
    config: Optional[dict],
    read_only: bool = False,
    center_map: bool = False,
    mapbox_token: str = "",
    kepler_gl_version: str = DEFAULT_KEPLER_GL_CDN_VERSION,
    json_encoder=str,
    app_name: str = "kepler.gl",
    theme: str = "",
) -> str:
    """Generate a standalone HTML string that renders a kepler.gl map.

    Loads all dependencies from CDN (unpkg). No local JS build required.

    Args:
        data: Dict of dataset name to data.
        config: Map config dict.
        read_only: If True, hide side panel to disable map customization.
        center_map: If True, fit map bounds to the data.
        mapbox_token: Mapbox API access token.
        kepler_gl_version: kepler.gl UMD bundle version tag for unpkg.
        json_encoder: Fallback function passed as ``default`` when
            JSON-serializing GeoDataFrame data.  Defaults to ``str`` so
            that ``datetime`` and other non-native JSON types are
            converted automatically.  Pass ``None`` to disable.
        app_name: Application name displayed in the side panel header
            and used as the HTML ``<title>``.  Defaults to ``"kepler.gl"``.
        theme: UI theme for the kepler.gl component.  Accepted values
            are ``"light"``, ``"dark"``, ``"base"``, or an empty string
            (default) which uses the built-in dark theme.
    """
    dataset_js = _serialize_datasets_for_html(data, json_encoder=json_encoder)
    geojson_names = _geojson_dataset_names(data, json_encoder=json_encoder)
    fixed_config = _fixup_geojson_columns(config, geojson_names)
    config_json = json.dumps(fixed_config, ensure_ascii=False) if fixed_config else "{}"
    mapbox_token_json = json.dumps(mapbox_token)
    read_only_js = "true" if read_only else "false"
    center_map_js = "true" if center_map else "false"
    app_name_json = json.dumps(app_name)
    theme_js = json.dumps(theme) if theme else "undefined"
    title_html = html.escape(app_name) if app_name else "kepler.gl"

    return f"""\
<!DOCTYPE html>
<html>
  <head>
    <meta charset="UTF-8"/>
    <title>{title_html} embedded map</title>

    <!--Uber Font-->
    <link rel="stylesheet" href="https://d1a3f4spazzrp4.cloudfront.net/kepler.gl/uber-fonts/4.0.0/superfine.css">

    <!--Kepler css-->
    <link href="https://unpkg.com/kepler.gl@{kepler_gl_version}/umd/keplergl.min.css" rel="stylesheet">

    <!--MapLibre css-->
    <link href="https://unpkg.com/maplibre-gl@^4/dist/maplibre-gl.css" rel="stylesheet">

    <!--
      React >= 19 no longer ships UMD builds, so we load React and the other
      peer dependencies as ES modules from esm.sh via an import map, then
      expose them as window globals that the kepler.gl UMD bundle expects.

      es-module-shims runs in "shim mode" so the page also works when opened
      as a local file:// (native import maps are blocked under file://).
    -->
    <script>
      window.esmsInitOptions = {{shimMode: true, version: '{ES_MODULE_SHIMS_VERSION}'}};
    </script>
    <script async src="https://ga.jspm.io/npm:es-module-shims@{ES_MODULE_SHIMS_VERSION}/dist/es-module-shims.js" crossorigin="anonymous"></script>

    <script type="importmap-shim">
      {{
        "imports": {{
          "react":              "https://esm.sh/react@{REACT_VERSION}",
          "react/jsx-runtime":  "https://esm.sh/react@{REACT_VERSION}/jsx-runtime",
          "react-dom":          "https://esm.sh/react-dom@{REACT_DOM_VERSION}?external=react",
          "react-dom/client":   "https://esm.sh/react-dom@{REACT_DOM_VERSION}/client?external=react",
          "redux":              "https://esm.sh/redux@{REDUX_VERSION}",
          "react-redux":        "https://esm.sh/react-redux@{REACT_REDUX_VERSION}?external=react,react-dom,redux",
          "styled-components":  "https://esm.sh/styled-components@{STYLED_COMPONENTS_VERSION}?external=react,react-dom"
        }}
      }}
    </script>

    <!--
      Expose the ES modules as globals for the kepler.gl UMD bundle, then
      dynamically load that bundle and run the bootstrap scripts once ready.
    -->
    <script type="module-shim">
      import * as React            from 'react';
      import * as ReactDOM         from 'react-dom';
      import * as ReactDOMClient   from 'react-dom/client';
      import * as Redux            from 'redux';
      import * as ReactRedux       from 'react-redux';
      import * as StyledComponents from 'styled-components';

      window.React       = React.default || React;
      window.ReactDOM    = Object.assign({{}}, ReactDOM.default || ReactDOM, ReactDOMClient);
      window.Redux       = Redux.default || Redux;
      window.ReactRedux  = ReactRedux.default || ReactRedux;
      window.styled      = Object.assign(StyledComponents.default, StyledComponents);

      function loadScript(src) {{
        return new Promise(function(resolve, reject) {{
          var s = document.createElement('script');
          s.src = src; s.crossOrigin = 'anonymous';
          s.onload = resolve; s.onerror = reject;
          document.head.appendChild(s);
        }});
      }}

      loadScript('https://unpkg.com/kepler.gl@{kepler_gl_version}/umd/keplergl.min.js')
        .then(function() {{
          document.querySelectorAll('script[type="text/kepler-bootstrap"]').forEach(function(node) {{
            var s = document.createElement('script');
            s.text = node.textContent;
            document.body.appendChild(s);
          }});
        }})
        .catch(function(err) {{ console.error('kepler.gl: failed to load UMD bundle', err); }});
    </script>

    <style type="text/css">
      body {{margin: 0; padding: 0; overflow: hidden;}}
    </style>

    <script>
      const MAPBOX_TOKEN = {mapbox_token_json};
    </script>
  </head>
  <body>
    <div id="app"></div>

    <script type="text/kepler-bootstrap">
      /** STORE **/
      const reducers = (function createReducers(redux, keplerGl) {{
        return redux.combineReducers({{
          keplerGl: keplerGl.keplerGlReducer.initialState({{
            uiState: {{
              readOnly: {read_only_js},
              currentModal: null
            }}
          }})
        }});
      }}(Redux, KeplerGl));

      const middleWares = (function createMiddlewares(keplerGl) {{
        return keplerGl.enhanceReduxMiddleware([]);
      }}(KeplerGl));

      const enhancers = (function createEnhancers(redux, middles) {{
        return redux.applyMiddleware(...middles);
      }}(Redux, middleWares));

      const store = (function createStore(redux, enhancers) {{
        return redux.legacy_createStore(reducers, {{}}, redux.compose(enhancers));
      }}(Redux, enhancers));
      /** END STORE **/

      /** COMPONENTS **/
      var KeplerElement = (function makeKeplerElement(react, keplerGl, mapboxToken) {{
        return function App() {{
          var _useState = react.useState({{
            width: window.innerWidth,
            height: window.innerHeight
          }});
          var windowDimension = _useState[0];
          var setDimension = _useState[1];
          react.useEffect(function sideEffect() {{
            function handleResize() {{
              setDimension({{width: window.innerWidth, height: window.innerHeight}});
            }}
            window.addEventListener('resize', handleResize);
            return function() {{ window.removeEventListener('resize', handleResize); }};
          }}, []);
          return react.createElement(
            'div',
            {{style: {{position: 'absolute', left: 0, width: '100vw', height: '100vh'}}}},
            react.createElement(keplerGl.KeplerGl, Object.assign({{
              mapboxApiAccessToken: mapboxToken,
              id: "map",
              width: windowDimension.width,
              height: windowDimension.height,
              appName: {app_name_json}
            }}, {theme_js} !== undefined ? {{theme: {theme_js}}} : {{}}))
          );
        }};
      }}(React, KeplerGl, MAPBOX_TOKEN));

      const app = (function createReactReduxProvider(react, reactRedux, KeplerElement) {{
        return react.createElement(
          reactRedux.Provider,
          {{store}},
          react.createElement(KeplerElement, null)
        );
      }}(React, ReactRedux, KeplerElement));
      /** END COMPONENTS **/

      /** Render **/
      (function render(reactDOM, app) {{
        const root = reactDOM.createRoot(document.getElementById('app'));
        root.render(app);
      }}(ReactDOM, app));
    </script>

    <script type="text/kepler-bootstrap">
      (function customize(keplerGl, store) {{
        var datasets = [];
{dataset_js}

        var config = {config_json};

        window.setTimeout(function() {{
          store.dispatch(keplerGl.addDataToMap({{
            datasets: datasets,
            config: config,
            options: {{
              centerMap: {center_map_js}
            }}
          }}));
        }}, 500);
      }}(KeplerGl, store));
    </script>
  </body>
</html>
"""