kepler.gl

kepler.gl | Site Web | Application de démonstration | Docs

Kepler.gl est une application Web à haute performance aux données et à haute performance pour l'exploration visuelle des ensembles de données de géolocalisation à grande échelle. Construit au-dessus de Maplibre GL et Deck.gl, Kepler.gl peut rendre des millions de points représentant des milliers de voyages et effectuer des agrégations spatiales à la volée.

Kepler.gl est également un composant React qui utilise Redux pour gérer son état et son flux de données. Il peut être intégré à d'autres applications React-Redux et est hautement personnalisable. Pour plus d'informations sur la façon d'intégrer Kepler.gl dans votre application, consultez ce tutoriel étape par étape sur vis.academy.

Links

• Site web
• Démo
• Exemples
• Commencer
• Guide de l'utilisateur de l'application
• Guide de l'utilisateur du widget Jupyter
• Tutoriel
• Débordement de pile
• Lignes directrices de contribution
• Référence de l'API
• Feuille de route

Env

Utilisez le nœud 18.18.2 ou plus, les versions de nœuds plus anciennes n'ont pas été pris en charge / testées. Pour les meilleurs résultats, utilisez nvm install NVM.

Installer kepler.gl

Installez le nœud ( > 18.18.2 ), le fil et les dépendances du projet

npm install --save kepler.gl
// or
yarn add kepler.gl

Kepler.gl est construit sur Mapbox. Vous aurez besoin d'un jeton d'accès Mapbox pour l'utiliser.

Si vous n'utilisez pas de bundler de module, c'est aussi bien. Le package KEPLER.GL NPM comprend des constructions UMD de production précompilée dans le dossier UMD. Vous pouvez ajouter la balise de script à votre fichier html comme il suit:

 < script src =" https://unpkg.com/kepler.gl/umd/keplergl.min.js " />

ou si vous le souhaitez, vous pouvez charger une version spécifique

 < script src =" https://unpkg.com/[email protected]/umd/keplergl.min.js " />

Développer kepler.gl

Jetez un œil au guide de développement pour développer Kepler.gl localement.

Utilisation de base

Voici les étapes de base pour importer Kepler.gl dans votre application. Vous jetez également un œil au dossier Exemples. Chaque exemple du dossier peut être installé et exécuté localement.

1. Réducteur de montage

Kepler.gl utilise Redux pour gérer son état interne, ainsi que le middleware React-Palm pour gérer les effets secondaires.

Vous devez également ajouter taskMiddleware de react-palm à votre magasin. Nous travaillons activement sur une solution où react-palm ne sera pas nécessaire, mais il s'agit toujours d'un outil de gestion des effets secondaires très légers qui est plus facile à tester que React-Thunk.

 import { createStore , combineReducers , applyMiddleware , compose } from 'redux' ;
import keplerGlReducer from '@kepler.gl/reducers' ;
import { enhanceReduxMiddleware } from '@kepler.gl/middleware' ;

const initialState = { } ;
const reducers = combineReducers ( {
  // <-- mount kepler.gl reducer in your app
  keplerGl : keplerGlReducer ,

  // Your other reducers here
  app : appReducer
} ) ;

// using createStore
export default createStore (
  reducer ,
  initialState ,
  applyMiddleware (
    enhanceReduxMiddleware ( [
      /* Add other middlewares here */
    ] )
  )
) ;

Ou si vous utilisez un amplificateur:

 // using enhancers
const initialState = { } ;
const middlewares = enhanceReduxMiddleware ( [
  // Add other middlewares here
] ) ;
const enhancers = [ applyMiddleware ( ... middlewares ) ] ;

export default createStore ( reducer , initialState , compose ( ... enhancers ) ) ;

Si vous montez le réducteur Kepler.gl dans une autre adresse au lieu de keplerGl , ou que le réducteur Kepler.gl n'est pas monté à la racine de votre état, vous devrez spécifier le chemin vers celui-ci lorsque vous montez le composant avec l'hélice getState .

En savoir plus sur les réducteurs.

2. Composant de montage

 import KeplerGl from '@kepler.gl/components' ;

const Map = props => (
  < KeplerGl id = "foo" width = { width } mapboxApiAccessToken = { token } height = { height } / >
) ; 

Accessoires

id (chaîne, requis)

• Par défaut: map

L'ID de cette instance Keplegl. id est requis si vous avez plusieurs instances Keplgl dans votre application. Il définit le nom d'accessoire de l'état de Keplegl qui est stocké dans le réducteur de Keplegl. Par exemple, l'état de la composante KePlgl avec ID foo est stocké dans state.keplerGl.foo .

Dans le cas où vous créez plusieurs instances Kepler.gl utilisant le même ID, l'état Kepler.gl défini par l'entrée sera remplacé par la dernière instance et réinitialise à un état vierge.

mapboxApiAccessToken (chaîne, requise *)

• Par défaut: undefined

Par défaut, Kepler.gl utilise Mapbox-Gl.js pour rendre ses cartes de base. Vous pouvez créer un compte gratuit sur Mapbox et créer un jeton sur www.mapbox.com/account/access-tokens.

Si vous avez remplacé les styles de carte par défaut de Kepler.gl par les vôtres, et ce ne sont pas des styles de mapbox. mapboxApiAccessToken ne sera pas nécessaire.

En savoir plus sur les styles de carte personnalisés.

getState (fonction, facultatif)

• Par défaut: state => state.keplerGl

Le chemin vers l'état de Keplegl racine dans votre réducteur.

width (numéro, facultatif)

• Par défaut: 800

Largeur du Keplegl UI.

height (numéro, facultatif)

• Par défaut: 800

appName (String, Facultatif)

• Par défaut: Kepler.Gl

Nom de l'application affichée dans l'en-tête du panneau latéral

version (chaîne, facultatif)

• Par défaut: v1.0

Version affichée dans l'en-tête du panneau latéral

onSaveMap (fonction, facultatif)

• Par défaut: undefined

Action appelée lorsque cliquez sur Url de carte dans l'en-tête du panneau latéral.

onViewStateChange (fonction, facultatif)

• Par défaut: undefined
• Paramètre: viewState - Un objet d'état de vue mis à jour contenant des paramètres tels que la longitude, la latitude, le zoom, etc.

Action déclenchée lorsque la fenêtre de carte est mise à jour.

getMapboxRef(mapbox, index) (fonction, facultatif)

• Par défaut: undefined

Fonction appelée lorsque KeplerGL ajoute ou supprime un composant MapContainer ayant une carte de mapbox intérieure.

L'argument mapbox est un MapRef lorsqu'il est ajouté ou null lorsqu'il est supprimé.

L'argument index est 0 pour une seule carte ou 1 pour une carte supplémentaire (car KeplerGL prend en charge une vue de carte divisée en option).

actions (objet, facultatif)

• Défaut: {}

Créateurs d'actions pour remplacer le créateur d'action Kepler.gl par défaut. Utilisez une action personnalisée lorsque vous souhaitez modifier la charge utile de l'action.

mint (booléen, facultatif)

• Par défaut: true

S'il faut charger un état vide frais lorsque le composant est monté. Lorsque Parse mint: true Kepler.GL Le composant chargera toujours un état frais lors de la réapprovisionnement du même composant, l'état à l'intérieur de ce composant sera détruit une fois non monté. En analysant mint: false kepler.gl gardera l'état du composant dans le magasin même lorsqu'il n'est pas monté, et l'utilisera comme état initial lorsque vous montez à nouveau. Ceci est utile lors du montage kepler.gl dans un modal et gardez la même carte lors de la réouverture.

En savoir plus sur les composants.

theme (objet | chaîne, facultatif)

• par défaut: null

L'un des "dark" , "light" ou "base" vous pouvez passer le nom du thème ou l'objet utilisé pour personnaliser le style Kepler.gl. Kepler.gl fournit un thème 'light' en plus du thème «sombre» par défaut. Lorsque vous passez dans un objet de thème, Kepler.gl utilisera la valeur passée comme entrée pour remplacer les valeurs du thème.

En savoir plus sur le thème personnalisé

mapboxApiUrl (chaîne, facultatif)

• Par défaut: https://api.mapbox.com

Si vous utilisez votre propre serveur de carreaux Mapbox, vous pouvez transmettre votre propre URL de l'API de serveur de carreaux.

mapStylesReplaceDefault (booléen, facultatif)

• Par défaut: false

kepler.gl fournit 4 styles de carte au choix. Passez true si vous souhaitez fournir vos propres mapStyles . Voir ci-dessous.

mapStyles (tableau, facultatif)

• Défaut: []

Vous pouvez fournir des styles de carte supplémentaires à afficher dans le panneau de sélection du style de carte. Par défaut, des styles de carte supplémentaires seront ajoutés aux styles de carte par défaut. Si passer mapStylesReplaceDefault: true , ils remplaceront ceux par défaut. Kepler.gl tentera de regrouper les couches de votre style en fonction de sa convention de dénomination id et l'utilisera pour permettre la visibilité bascule des couches de carte de base. Fournissez vos propres layerGroups pour remplacer la valeur par défaut pour un regroupement de couche plus précis.

Chaque mapStyles doit avoir les propriétés suivantes:

• id (chaîne, requise) chaîne unique qui ne devrait pas être l'une de ces muted light dark réservés. muted_night
• label (chaîne, requise) Nom à afficher dans le panneau de sélection du style de carte
• url (chaîne, requise) URL de style mapbox ou URL pointant vers l'objet JSON Style de carte écrit dans Mapbox GL Style Spec.
• icon (chaîne, facultatif) Icône d'image du style, il peut s'agir d'une URL ou d'une URL de données d'image
• layerGroups (tableau, facultatif)

 const mapStyles = [
  {
    id : 'my_dark_map' ,
    label : 'Dark Streets 9' ,
    url : 'mapbox://styles/mapbox/dark-v9' ,
    icon : ` ${ apiHost } /styles/v1/mapbox/dark-v9/static/-122.3391,37.7922,9.19,0,0/400x300?access_token= ${ accessToken } &logo=false&attribution=false` ,
    layerGroups : [
      {
        slug : 'label' ,
        filter : ( { id } ) => id . match ( / (?=(label|place-|poi-)) / ) ,
        defaultVisibility : true
      } ,
      {
        // adding this will keep the 3d building option
        slug : '3d building' ,
        filter : ( ) => false ,
        defaultVisibility : false
      }
    ]
  }
] ;

En savoir plus sur les styles de carte personnalisés.

initialUiState (objet, facultatif)

• Par défaut: undefined

État d'interface utilisateur intial appliqué au réducteur Uistate, la valeur sera fusionnée avec une initiale par INITIAL_UI_STATE

localeMessages (objet, facultatif)

• Par défaut: undefined Modifier la traduction par défaut ou ajouter une nouvelle traduction

En savoir plus sur la localisation.

3. Dépasser les actions personnalisées à keplerGl Reducer.

Un avantage de l'utilisation du réducteur sur l'état du composant React pour gérer l'état de Keplegl est la flexibilité pour personnaliser son comportement. Si vous n'avez qu'une seule instance KeplerGl dans votre application ou que vous n'avez jamais l'intention d'envoyer des actions à Keplegl de l'extérieur du composant lui-même, vous n'avez pas à vous soucier de transmettre l'expédition et de passer à la section suivante. Mais la vie est pleine de personnalisations, et nous voulons rendre le vôtre aussi agréable que possible.

Il existe plusieurs façons d'envoyer des actions à une instance KeplerGl spécifique.

• Dans le réducteur de racine, avec des mises à jour du réducteur.

Chaque action est cartographiée à un réducteur de mise à jour dans kepler.gl. Vous pouvez importer la mise à jour du réducteur correspondant à une action spécifique et l'appeler avec l'état précédent et la charge utile d'action pour obtenir l'état mis à jour. Par exemple, updateVisDataUpdater est le Updater de ActionTypes.UPDATE_VIS_DATA (jetez un œil à chaque reducers/vis-state.js pour l'action à la cartographie de mise à jour). Voici un exemple comment vous pouvez écouter une action d'application QUERY_SUCCESS et appeler updateVisDataUpdater pour charger des données dans kepler.gl.

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

// Root Reducer
const reducers = combineReducers ( {
  keplerGl : keplerGlReducer ,

  app : appReducer
} ) ;

const composedReducer = ( state , action ) => {
  switch ( action . type ) {
    case 'QUERY_SUCCESS' :
      return {
        ... state ,
        keplerGl : {
          ... state . keplerGl ,

          // 'map' is the id of the keplerGl instance
          map : {
            ... state . keplerGl . map ,
            visState : visStateUpdaters . updateVisDataUpdater ( state . keplerGl . map . visState , {
              datasets : action . payload
            } )
          }
        }
      } ;
  }
  return reducers ( state , action ) ;
} ;

export default composedReducer ;

En savoir plus sur l'utilisation des mises à jour pour modifier l'état de kepler.gl

• Utilisation de Redux connect

Vous pouvez ajouter une fonction de répartition à votre composant qui répartit les actions à un composant keplerGl spécifique, à l'aide de Connect.

 // component
import KeplerGl from '@kepler.gl/components' ;

// action and forward dispatcher
import { toggleFullScreen , forwardTo } from '@kepler.gl/actions' ;
import { connect } from 'react-redux' ;

const MapContainer = props => (
  < div >
    < button onClick = { ( ) => props . keplerGlDispatch ( toggleFullScreen ( ) ) } / >
    < KeplerGl
      id = "foo"
    / >
  < / div >
)

const mapStateToProps = state => state
const mapDispatchToProps = ( dispatch , props ) => ( {
 dispatch ,
 keplerGlDispatch : forwardTo ( ‘foo’ , dispatch )
} ) ;

export default connect (
 mapStateToProps ,
 mapDispatchToProps
) ( MapContainer ) ;

• Charge utile d'action enveloppe

Vous pouvez également simplement envelopper une action dans une action vers l'avant avec l'assistant wrapTo

 // component
import KeplerGl from '@kepler.gl/components' ;

// action and forward dispatcher
import { toggleFullScreen , wrapTo } from '@kepler.gl/actions' ;

// create a function to wrapper action payload to 'foo'
const wrapToMap = wrapTo ( 'foo' ) ;
const MapContainer = ( { dispatch } ) => (
  < div >
    < button onClick = { ( ) => dispatch ( wrapToMap ( toggleFullScreen ( ) ) } / >
    < KeplerGl
      id = "foo"
    / >
  < / div >
) ;

En savoir plus sur les actions de répartition avant

4. Personnaliser le style.

Kepler.gl implémente le style CSS à l'aide de composants stylisés. En utilisant ledit framework, Kepler.gl offre la possibilité de personnaliser son style / thème en utilisant les approches suivantes:

• Passer un accessoire de thème
• Composants stylisés Themeprovider

Les propriétés disponibles à personnaliser sont répertoriées ici.

Exemple de thème personnalisé.

Passer un thème prop.

Vous pouvez personnaliser le thème Kepler.gl en passant un thème d'accessoires au composant Kepler.gl React comme il suit:

 const white = '#ffffff' ;
const customTheme = {
  sidePanelBg : white ,
  titleTextColor : '#000000' ,
  sidePanelHeaderBg : '#f7f7F7' ,
  subtextColorActive : '#2473bd'
} ;

return (
  < KeplerGl
    mapboxApiAccessToken = { MAPBOX_TOKEN }
    id = "map"
    width = { 800 }
    height = { 800 }
    theme = { customTheme }
  / >
) ;

Comme vous pouvez le voir, l'objet CustomTheme définit certaines propriétés qui remplaceront les règles de style par défaut KEPLER.GL.

Proviseur de thème des composants stylisés.

Afin de personnaliser le thème Kepler.gl à l'aide de themeprovider, vous pouvez simplement envelopper kepler.gl en utilisant le themeprovider comme il suit:

 import { ThemeProvider } from 'styled-components' ;

const white = '#ffffff' ;
const customTheme = {
  sidePanelBg : white ,
  titleTextColor : '#000000' ,
  sidePanelHeaderBg : '#f7f7F7' ,
  subtextColorActive : '#2473bd'
} ;

return (
  < ThemeProvider theme = { customTheme } >
    < KeplerGl mapboxApiAccessToken = { MAPBOX_TOKEN } id = "map" width = { 800 } height = { 800 } / >
  < / ThemeProvider >
) ;

5. Rendre les composants de l'interface utilisateur personnalisés.

Tout le monde veut la flexibilité de rendre les composants Kepler.gl personnalisés. Kepler.gl possède un système d'injection de dépendance qui vous permet d'injecter des composants à Keplegl en remplacement de ceux existants. Tout ce que vous avez à faire est de créer une usine de composants pour celle que vous souhaitez remplacer, d'importer l'usine de composants d'origine et d'appeler injectComponents dans le composant racine de votre application où KeplerGl est monté. Jetez un œil aux examples/demo-app/src/app.js et voyez comment il rend un en-tête de panneau latéral personnalisé dans kepler.gl

 import { injectComponents , PanelHeaderFactory } from '@kepler.gl/components' ;

// define custom header
const CustomHeader = ( ) => < div > My kepler.gl app < / div > ;
const myCustomHeaderFactory = ( ) => CustomHeader ;

// Inject custom header into Kepler.gl, replacing default
const KeplerGl = injectComponents ( [ [ PanelHeaderFactory , myCustomHeaderFactory ] ] ) ;

// render KeplerGl, it will render your custom header instead of the default
const MapContainer = ( ) => (
  < div >
    < KeplerGl id = "foo" / >
  < / div >
) ;

Utilisation withState un état de réducteur et des actions à des composants personnalisés comme accessoires supplémentaires.

 import { withState , injectComponents , PanelHeaderFactory } from '@kepler.gl/components' ;
import { visStateLens } from '@kepler.gl/reducers' ;

// custom action wrap to mounted instance
const addTodo = text =>
  wrapTo ( 'map' , {
    type : 'ADD_TODO' ,
    text
  } ) ;

// define custom header
const CustomHeader = ( { visState , addTodo } ) => (
  < div onClick = { ( ) => addTodo ( 'hello' ) } > { ` ${
    Object . keys ( visState . datasets ) . length
  } dataset loaded` } < / div >
) ;

// now CustomHeader will receive `visState` and `addTodo` as additional props.
const myCustomHeaderFactory = ( ) =>
  withState (
    // keplerGl state lenses
    [ visStateLens ] ,
    // customMapStateToProps
    headerStateToProps ,
    // actions
    { addTodo }
  ) ( CustomHeader ) ;

En savoir plus sur le remplacement du composant d'interface utilisateur

6. Comment ajouter des données à la carte

Pour interagir avec une instance Kepler.gl et y ajouter de nouvelles données, vous pouvez envoyer l'action addDataToMap de n'importe où à l'intérieur de votre application. Il ajoute un ensemble de données ou plusieurs ensembles de données à une instance Kepler.gl et met à jour la configuration complète (MapState, MapStyle, Visstate).

Paramètres

• objet data * requis

  • datasets (array <objet> | objet) * Les ensembles de données requis peuvent être un ensemble de données ou un tableau d'ensembles de données chaque objet de jeu de données doit avoir info et une propriété data .

    • datasets.info Object -info d'un ensemble de données
      • datasets.info.id ID de chaîne de cet ensemble de données. Si la configuration est définie, id doit correspondre au dataId dans config.
      • datasets.info.label String Un nom d'affichage de cet ensemble de données
    • datasets.data Objet * Obligation de l'objet de données, dans un format tabulaire avec 2 fields et rows de propriétés
      • datasets.data.fields Array <Bject> * Tableau de champs requis ,
        • datasets.data.fields.name String * Nom requis du champ,
      • datasets.data.rows Array <Berray> * Tableau de lignes requise , dans un format tabulaire avec fields et rows

  • options Object

    • options.centerMap booléen default: true si centerMap est défini sur true kepler.gl placera la vue de la carte dans les limites des points de données
    • options.readOnly booléen default: false si readOnly est défini sur true le panneau de réglage de gauche sera masqué
    • options.keepExistingConfig booléen default: false SI pour continuer à sortir de la configuration de la carte, y compris les couches, les filtres et les SplitMaps.

• config Object Cet objet contiendra la configuration d'instance Kepler.gl complète {MapState, MapStyle, Visstate}

Kepler.gl fournit une API facile KeplerGlSchema.getConfigToSave pour générer un blob JSON de la configuration d'instance Kepler actuelle.

Exemples

 // app.js
import { addDataToMap } from '@kepler.gl/actions' ;

const sampleTripData = {
  fields : [
    { name : 'tpep_pickup_datetime' , format : 'YYYY-M-D H:m:s' , type : 'timestamp' } ,
    { name : 'pickup_longitude' , format : '' , type : 'real' } ,
    { name : 'pickup_latitude' , format : '' , type : 'real' }
  ] ,
  rows : [
    [ '2015-01-15 19:05:39 +00:00' , - 73.99389648 , 40.75011063 ] ,
    [ '2015-01-15 19:05:39 +00:00' , - 73.97642517 , 40.73981094 ] ,
    [ '2015-01-15 19:05:40 +00:00' , - 73.96870422 , 40.75424576 ]
  ]
} ;

const sampleConfig = {
  visState : {
    filters : [
      {
        id : 'me' ,
        dataId : 'test_trip_data' ,
        name : 'tpep_pickup_datetime' ,
        type : 'timeRange' ,
        view : 'enlarged'
      }
    ]
  }
} ;

this . props . dispatch (
  addDataToMap ( {
    datasets : {
      info : {
        label : 'Sample Taxi Trips in New York City' ,
        id : 'test_trip_data'
      } ,
      data : sampleTripData
    } ,
    option : {
      centerMap : true ,
      readOnly : false
    } ,
    config : sampleConfig
  } )
) ;

En savoir plus sur AddDatatoMap et enregistrer et charger des cartes avec Schema Manager.