DOCSEARCHbyAlgolia
Submit Docs

Kepler.gl

repository·master·Indexed 11 days ago

https://github.com/keplergl/kepler.gl

A high-performance, WebGL-based geospatial visualization tool for large-scale location data. Built with MapLibre GL and deck.gl, it is provided as a customizable React-Redux component. It supports various data formats including CSV, GeoJSON, Pandas DataFrames, and GeoPandas GeoDataFrames, with GeoArrow support for faster rendering. Version 3.3.0-alpha.6 includes a Python package for Jupyter environments and supports custom cloud provider integrations for map saving and sharing.

Tokens
131.2K
Snippets
318
Records
560
Agent score
92%

What's inside Kepler.gl

  1. Overview of the Kepler.gl workflow

    master

    The Kepler.gl workflow for building geospatial visualizations follows a structured progression:

    1. Add data to the map: The initial step of ingesting datasets into the Kepler.gl environment.
    2. Manage data layers: Once data is present, you can add layers, create new layer types, and manipulate existing ones.
    3. Layer manipulation: Fine-tune the visualization by hiding, editing, or deleting specific layers.
    4. Visual composition: Use blending modes and rearrange layer order to create complex, multi-layered maps.

  2. Overview of kepler.gl

    master

    Kepler.gl is a data-agnostic, high-performance web-based application for visual exploration of large-scale geolocation data sets.

    Key Characteristics:

    • Performance: Built on top of MapLibre GL and deck.gl, it can render millions of points and perform on-the-fly spatial aggregations.
    • Integration: It is a React component that uses Redux to manage state and data flow. It is designed to be embedded into other React-Redux applications and is highly customizable.

  3. Overview of Kepler.gl capabilities

    master

    Kepler.gl is a geospatial data analysis tool designed for visualizing large amounts of location data directly in the browser. It enables users to:

    • Visualize large datasets: Handle significant amounts of location data efficiently.
    • Temporal Analysis: Playback geo-temporal trends over time to see how data changes.
    • Deep Engagement: Explore, filter, and interact with location data to gain insights.

    For practical examples of these capabilities, refer to the sample maps provided in the demo app.

  4. Overview of the Kepler.gl AI Assistant Module

    master

    The AI Assistant is a module designed to integrate an AI chatbot into the Kepler.gl React-based single-page application. It enables seamless interaction between Kepler.gl and various Large Language Models (LLMs) such as OpenAI GPT, Google Gemini, and Ollama.

    Through this integration, users can perform complex spatial data analysis and visualization tasks using natural language prompts. The module works by allowing the LLM to call specific 'AI Tools' that trigger application actions (like updating a basemap) or perform computational spatial operations (like spatial joins or autocorrelation), which are then rendered within the Kepler.gl interface.

  5. Explore kepler.gl integration patterns

    master

    The repository contains several specialized examples demonstrating different ways to integrate and extend kepler.gl:

    • Minimal Setups: Get Started (esbuild) and Get Started (Vite) provide the baseline for adding Kepler to a modern web app.
    • Data & Performance: DuckDB (Vite) demonstrates using the DuckDB plugin.
    • UI & Lifecycle: Open Modal shows how to embed Kepler inside a react-modal and manage state lifecycles. Replace UI Component demonstrates using injectComponents to swap default UI elements.
    • Customization & Extensibility:
      • Custom Reducer: Extend the reducer's initial state and add actions via the plugin system.
      • Custom Theme: Override default style properties.
      • Custom Layer: Add new deck.gl layers (e.g., ContourLayer) to the layer type selector.
      • Custom Map Style: Use basemaps other than Mapbox (e.g., MapLibre / Carto).
    • Deployment & Environments:
      • Node App: Embed Kepler in a Node.js/Express app using esbuild.
      • UMD Client: Load Kepler via CDN in a single HTML file without npm install or build tools.
      • Demo App: A full single-page application with remote map loading and Dropbox integration.

  6. Supported data formats in keplergl-jupyter

    master

    The keplergl-jupyter integration supports the following data formats for the map.add_data() method:

    • CSV: A raw CSV string.
    • GeoJSON: A single Feature or a FeatureCollection (as a string or dict). Note that GeometryCollection is not supported.
    • Pandas DataFrame: Standard tabular data.
    • GeoPandas GeoDataFrame: Spatially enabled DataFrames. In the live Jupyter widget, these are serialized via GeoArrow to preserve geometry types and Coordinate Reference Systems (CRS). When exporting to HTML via .save_to_html(), GeoDataFrames are automatically reprojected to EPSG:4326 (latitude/longitude) if necessary.

  7. Overview of Kepler.gl Visual Effects

    master

    Kepler.gl provides a collection of visual effects applied as post-processing passes. These effects include lighting simulations, atmospheric effects, artistic color grading, and various blur filters.

    Usage and Stacking

    • Effects can be added via the Effects panel in the sidebar.
    • Multiple effects can be stacked and reordered; they are applied sequentially from top to bottom.

    Limitations and Compatibility

    • Concurrency Limits: You can only have one Light & Shadow effect and one fog effect (Distance Fog or Surface Fog) active at a time.
    • Feature Combinations: While effects work with flat maps, globe view, split/swipe maps, and video export individually, combining several (e.g., effects on a globe during a video export in swipe mode) has limited support and may result in rendering or export issues. If issues occur, try disabling effects first.

  8. Overview of Kepler.gl Architecture

    master

    Kepler.gl is a Redux-connected component designed to be embedded within a React application. It relies on Redux for state management. To successfully integrate and use Kepler.gl, developers should have a working knowledge of:

    • React
    • Redux (state container)
    • React Redux connect

    The core integration pattern involves two primary steps: mounting the Kepler.gl UI component and mounting the Kepler.gl reducer into your application's Redux store. The ecosystem provides additional tools such as actions, schema managers, and utilities for loading and saving map data to provide full functionality.

  9. Docker Build Context and Environment Variable Notes

    master

    When working with the Kepler.gl Docker setup, keep the following technical constraints in mind:

    • Build Context: Always run docker build commands from the repository root. The Dockerfiles reference directories like src/ and scripts/ which are located at the root.
    • Environment Variables: Variables like MapboxAccessToken are read from the .env file during the build process. If you change these values, you must rebuild the image for the changes to take effect.
    • Build Exclusions: The .dockerignore file at the root excludes node_modules/, .git/, website/, bindings/, test/, and docs/ to optimize build speed.
    • Native Packages: During yarn install within the build process, postinstall scripts are disabled to avoid attempting to build the gl native package (which requires GPU headers).

  10. How to use visStateUpdaters to modify Kepler.gl state

    master

    The visStateUpdaters are functions used within your root reducer to directly modify the visState of the keplerGl reducer. This allows you to intercept custom actions in your application and apply specific state changes to the Kepler.gl instance.

    To use them, you typically compose your root reducer by wrapping the keplerGlReducer with a custom reducer function that handles specific action types using the provided updaters.

    import keplerGlReducer, {visStateUpdaters} from '@kepler.gl/reducers';

// Root Reducer
const reducers = combineReducers({
 keplerGl: keplerGlReducer,
 app: appReducer
});

const composedReducer = (state, action) => {
 switch (action.type) {
   case 'CLICK_BUTTON':
     return {
       ...state,
       keplerGl: {
         ...state.keplerGl,
         foo: {
            ...state.keplerGl.foo,
            visState: visStateUpdaters.enlargeFilterUpdater(
              state.keplerGl.foo.visState,
              {idx: 0}
            )
         }
       }
     };
 }
 return reducers(state, action);
};

export default composedReducer;

  12. Manage Kepler.gl instances with rootActions

    master

    The rootActions manage the lifecycle of Kepler.gl instances within the keplerGlReducer. While the KeplerGl component handles registration automatically upon mounting, you may need to call these manually if data is ready before the component is mounted.

    • registerEntry: Add a new instance.
      • Parameters: payload object containing:
        • id (required): The instance ID.
        • mint (boolean): If true, always loads a fresh state on re-mount. If false, reuses existing state for the same ID. Defaults to true.
        • mapboxApiAccessToken: Token for the map-style reducer.
        • mapboxApiUrl: URL for the map-style reducer.
        • mapStylesReplaceDefault: Boolean for map-style reducer.
    • deleteEntry: Remove an instance from the reducer. If mint: true was used during registration, the state is deleted on unmount. If mint: false, the state is preserved for future mounting with the same ID.
    • renameEntry: Rename an existing instance in the root reducer while preserving its entire state.
      • Parameters: oldId (required) and newId (required).