kepler.gl

Kepler.gl | Situs web | Aplikasi Demo | Dokumen

Kepler.gl adalah aplikasi berbasis web berbasis web-agnostik-tinggi untuk eksplorasi visual dari set data geolokasi skala besar. Dibangun di atas Maplibre GL dan Deck.gl, Kepler.gl dapat membuat jutaan poin mewakili ribuan perjalanan dan melakukan agregasi spasial dengan cepat.

Kepler.gl juga merupakan komponen bereaksi yang menggunakan Redux untuk mengelola keadaan dan aliran data. Ini dapat tertanam ke dalam aplikasi react-redux lainnya dan sangat dapat disesuaikan. Untuk informasi tentang cara menyematkan kepler.gl di aplikasi Anda, lihat tutorial langkah demi langkah ini di vis.academy.

Tautan

• Situs web
• Demo
• Contoh
• Mulai
• Panduan Pengguna Aplikasi
• Panduan Pengguna Widget Jupyter
• Tutorial
• Stack overflow
• Pedoman Kontribusi
• Referensi API
• Peta jalan

Env

Gunakan simpul 18.18.2 atau lebih, versi node yang lebih tua belum didukung/ diuji. Untuk hasil terbaik, gunakan nvm install NVM.

Instal kepler.gl

Instal Node ( > 18.18.2 ), benang, dan dependensi proyek

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

Kepler.gl dibangun di atas mapbox. Anda akan memerlukan token akses Mapbox untuk menggunakannya.

Jika Anda tidak menggunakan bundler modul, itu juga baik -baik saja. Paket NPM Kepler.gl mencakup produksi pra -kompilasi UMD build di folder UMD. Anda dapat menambahkan tag skrip ke file html Anda karena berikut:

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

atau jika Anda mau, Anda dapat memuat versi tertentu

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

Kembangkan Kepler.gl

Lihatlah panduan pengembangan untuk mengembangkan Kepler.gl secara lokal.

Penggunaan dasar

Berikut adalah langkah -langkah dasar untuk mengimpor Kepler.gl ke aplikasi Anda. Anda juga melihat folder Contoh. Setiap contoh di folder dapat diinstal dan dijalankan secara lokal.

1. Mount Reducer

Kepler.gl menggunakan Redux untuk mengelola keadaan internalnya, bersama dengan middleware React-Palm untuk menangani efek samping.

Anda perlu menambahkan taskMiddleware dari react-palm ke toko Anda juga. Kami secara aktif bekerja pada solusi di mana react-palm tidak akan diperlukan, namun masih merupakan alat manajemen efek samping yang sangat ringan yang lebih mudah diuji daripada bereaksi-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 */
    ] )
  )
) ;

Atau jika menggunakan penambah:

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

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

Jika Anda memasang pereducer kepler.gl di alamat lain alih -alih keplerGl , atau pereducer Kepler.gl tidak dipasang pada akar keadaan Anda, Anda perlu menentukan jalur ke sana ketika Anda memasang komponen dengan prop getState .

Baca lebih lanjut tentang peredam.

2. Komponen pemasangan

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

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

Alat peraga

id (string, wajib)

• Default: map

ID dari instance Keplergl ini. id diperlukan jika Anda memiliki beberapa instance Keplergl di aplikasi Anda. Ini mendefinisikan nama prop dari keadaan Keplergl yang disimpan di Keplergl Reducer. Misalnya, keadaan komponen Keplergl dengan ID foo disimpan di state.keplerGl.foo .

Jika Anda membuat beberapa instance Kepler.gl menggunakan ID yang sama, keadaan Kepler.gl yang ditentukan oleh entri akan ditimpa oleh instance terbaru dan mengatur ulang ke keadaan kosong.

mapboxApiAccessToken (string, wajib*)

• Default: undefined

Secara default, Kepler.gl menggunakan mapbox-gl.js untuk membuat peta dasarnya. Anda dapat membuat akun gratis di MapBox dan membuat token di www.mapbox.com/account/access-tokens.

Jika Anda mengganti gaya peta default kepler.gl dengan gaya Anda sendiri, dan itu bukan gaya mapbox. mapboxApiAccessToken tidak akan diperlukan.

Baca lebih lanjut tentang gaya peta khusus.

getState (fungsi, opsional)

• Default: state => state.keplerGl

Jalur ke status keplergl root di peredam Anda.

width (angka, opsional)

• Default: 800

Lebar Keplergl UI.

height (angka, opsional)

• Default: 800

appName (String, Opsional)

• Default: Kepler.Gl

Nama aplikasi ditampilkan di header panel samping

version (String, Opsional)

• Default: v1.0

Versi ditampilkan di header panel samping

onSaveMap (fungsi, opsional)

• Default: undefined

Tindakan Dipanggil Saat Klik Simpan URL Peta di Header Panel Side.

onViewStateChange (fungsi, opsional)

• Default: undefined
• Parameter: viewState - Objek tampilan yang diperbarui yang berisi parameter seperti bujur, lintang, zoom dll

Tindakan dipicu saat peta viewport diperbarui.

getMapboxRef(mapbox, index) (Fungsi, Opsional)

• Default: undefined

Fungsi Dipanggil Saat KeplerGL Menambahkan atau Menghapus Komponen MapContainer yang memiliki peta MapBox dalam.

Argumen mapbox adalah MapRef saat ditambahkan atau null saat dihapus.

Argumen index adalah 0 untuk satu peta atau 1 untuk peta tambahan (karena KeplerGL mendukung tampilan peta split opsional).

actions (objek, opsional)

• Bawaan: {}

Tindakan Pencipta untuk menggantikan pencler default.gl Action Creator. Hanya gunakan tindakan khusus saat Anda ingin memodifikasi muatan tindakan.

mint (boolean, opsional)

• Default: true

Apakah akan memuat keadaan kosong segar saat komponen dipasang. Ketika Parse mint: true akan selalu memuat keadaan segar saat memasang kembali komponen yang sama, nyatakan di dalam komponen ini akan dihancurkan begitu tidak dipasang. Dengan parsing mint: false kepler.gl akan menjaga keadaan komponen di toko bahkan ketika tidak dipasang, dan menggunakannya sebagai keadaan awal saat dipasang kembali lagi. Ini berguna saat memasang kepler.gl dalam modal, dan simpan peta yang sama saat dibuka kembali.

Baca lebih lanjut tentang komponen.

theme (Objek | String, Opsional)

• Default: null

Salah satu dari "dark" , "light" atau "base" Anda dapat melewati nama tema atau objek yang digunakan untuk menyesuaikan gaya Kepler.gl. Kepler.gl memberikan tema 'light' selain tema 'gelap' default. Saat melewati objek tema Kepler.gl akan menggunakan nilai yang dilewati sebagai input untuk mengganti nilai dari tema.

Baca lebih lanjut tentang tema khusus

mapboxApiUrl (String, Opsional)

• Default: https://api.mapbox.com

Jika Anda menggunakan server ubin Mapbox Anda sendiri, Anda dapat melewati URL API Server Ubin Anda sendiri.

mapStylesReplaceDefault (boolean, opsional)

• Default: false

Kepler.gl menyediakan 4 gaya peta untuk dipilih. Lulus true jika Anda ingin menyediakan mapStyles Anda sendiri. Lihat di bawah.

mapStyles (array, opsional)

• Bawaan: []

Anda dapat menyediakan gaya peta tambahan yang akan ditampilkan di panel pemilihan gaya peta. Secara default, gaya peta tambahan akan ditambahkan ke gaya peta default. Jika pass mapStylesReplaceDefault: true , mereka akan menggantikan yang default. Kepler.gl akan mencoba mengelompokkan lapisan gaya Anda berdasarkan konvensi penamaan id dan menggunakannya untuk memungkinkan visibilitas sakelar lapisan peta dasar. Suplai layerGroups Anda sendiri untuk mengganti default untuk pengelompokan layer yang lebih akurat.

Setiap mapStyles harus memiliki properti berikut:

• id (string, wajib) String unik yang tidak boleh menjadi salah satu dari light dark yang dipesan muted . muted_night
• label (string, wajib) Nama yang akan ditampilkan di panel pemilihan gaya peta
• url (String, Diperlukan) URL Gaya Mapbox atau URL yang menunjuk ke objek gaya peta JSON yang ditulis dalam spesifikasi gaya Mapbox GL.
• icon Ikon (String, Opsional) Ikon gaya, itu bisa berupa URL, atau URL data gambar
• layerGroups (array, opsional)

 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
      }
    ]
  }
] ;

Baca lebih lanjut tentang gaya peta khusus.

initialUiState (objek, opsional)

• Default: undefined

Status UI Intial diterapkan pada peredam uistate, nilai akan digabungkan dengan INITIAL_UI_STATE default

localeMessages (objek, opsional)

• Default: Modifikasi Terjemahan Default undefined atau Tambahkan Terjemahan Baru

Baca lebih lanjut tentang lokalisasi.

3. Pengiriman Tindakan Kustom ke keplerGl Reducer.

Salah satu keuntungan menggunakan reduser atas keadaan komponen reaksi untuk menangani keadaan Keplergl adalah fleksibilitas untuk menyesuaikan perilakunya. Jika Anda hanya memiliki satu instance KeplerGl di aplikasi Anda atau tidak pernah bermaksud untuk mengirim tindakan ke Keplergl dari luar komponen itu sendiri, Anda tidak perlu khawatir tentang penerusan pengiriman dan dapat pindah ke bagian berikutnya. Tetapi hidup ini penuh dengan penyesuaian, dan kami ingin menjadikan Anda secukupnya mungkin.

Ada banyak cara untuk mengirim tindakan ke instance KeplerGl tertentu.

• Di root reducer, dengan pembaruan peredam.

Setiap tindakan dipetakan ke pembaruan peredam di Kepler.gl. Anda dapat mengimpor pembaruan peredam yang sesuai dengan tindakan tertentu, dan memanggilnya dengan status sebelumnya dan muatan tindakan untuk mendapatkan status yang diperbarui. EG updateVisDataUpdater adalah pembaruan untuk ActionTypes.UPDATE_VIS_DATA (lihat setiap reducers/vis-state.js untuk tindakan pemetaan pembaruan). Berikut adalah contoh bagaimana Anda dapat mendengarkan APP Action QUERY_SUCCESS dan menghubungi updateVisDataUpdater untuk memuat data ke 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 ;

Baca lebih lanjut tentang menggunakan pembaruan untuk memodifikasi status Kepler.gl

• Menggunakan Redux connect

Anda dapat menambahkan fungsi pengiriman ke komponen Anda yang mengirim tindakan ke komponen keplerGl tertentu, menggunakan 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 ) ;

• Bungkus muatan tindakan

Anda juga dapat dengan mudah membungkus tindakan ke dalam aksi maju dengan pembantu 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 >
) ;

Baca lebih lanjut tentang tindakan pengiriman ke depan

4. Kustomisasi Gaya.

Kepler.gl mengimplementasikan gaya CSS menggunakan komponen gaya. Dengan menggunakan kerangka kerja kepler.gl menawarkan kemampuan untuk menyesuaikan gaya/temanya menggunakan pendekatan berikut:

• Melewati Prop Tema
• Komponen gaya yang ditata

Properti yang tersedia untuk disesuaikan tercantum di sini.

Contoh Tema Kustom.

Melewati prop tema.

Anda dapat menyesuaikan tema Kepler.gl dengan menyerahkan alat peraga tema ke komponen reaksi Kepler.gl karena berikut:

 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 }
  / >
) ;

Seperti yang Anda dapat melihat objek CustomTheme mendefinisikan properti tertentu yang akan mengganti aturan gaya default Kepler.gl.

Penyedia tema komponen gaya.

Untuk menyesuaikan tema Kepler.gl menggunakan ThemeProvider, Anda cukup membungkus Kepler.gl menggunakan ThemeProvider karena berikut:

 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. Render komponen UI khusus.

Semua orang menginginkan fleksibilitas untuk membuat komponen kepler.gl khusus. Kepler.gl memiliki sistem injeksi ketergantungan yang memungkinkan Anda untuk menyuntikkan komponen ke Keplergl menggantikan yang sudah ada. Yang perlu Anda lakukan adalah membuat pabrik komponen untuk yang ingin Anda ganti, impor pabrik komponen asli dan hubungi injectComponents di komponen root aplikasi Anda di mana KeplerGl dipasang. Lihatlah examples/demo-app/src/app.js dan lihat bagaimana ia membuat header panel samping khusus di 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 >
) ;

Menggunakan helper withState untuk menambahkan status peredam dan tindakan ke komponen yang disesuaikan sebagai alat peraga tambahan.

 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 ) ;

Baca lebih lanjut tentang mengganti komponen UI

6. Cara Menambahkan Data ke Peta

Untuk berinteraksi dengan instance Kepler.gl dan menambahkan data baru ke dalamnya, Anda dapat mengirimkan tindakan addDataToMap dari mana saja di dalam aplikasi Anda. Ini menambahkan dataset atau beberapa dataset ke instance Kepler.gl dan memperbarui konfigurasi lengkap (MapState, MapStyle, Visstate).

Parameter

• Objek data *Diperlukan

  • datasets (Array <Pres Object> | Object) *Dataset yang diperlukan dapat berupa dataset atau array set data, setiap objek dataset perlu memiliki info dan properti data .

    • datasets.info objek -info dari dataset
      • datasets.info.id ID string dari dataset ini. Jika konfigurasi didefinisikan, id harus mencocokkan dataId dalam konfigurasi.
      • datasets.info.label string nama tampilan dari dataset ini
    • datasets.data Object *Membutuhkan Objek Data, dalam format tabel dengan 2 fields dan rows properti
      • datasets.data.fields Array <Papen> *array bidang yang diperlukan ,
        • datasets.data.fields.name String *nama yang diperlukan dari bidang ini,
      • datasets.data.rows array <Rr array> *array baris yang diperlukan , dalam format tabular dengan fields dan rows

  • options Objek

    • options.centerMap BOOLEAN default: true jika centerMap diatur ke true kepler.gl akan menempatkan tampilan peta dalam batas titik data
    • options.readOnly Boolean default: false Jika readOnly diatur ke true Panel pengaturan kiri akan disembunyikan
    • options.keepExistingConfig BOOLEAN default: false Apakah akan terus keluar dari konfigurasi peta, termasuk lapisan, filter, dan splitmaps.

• Objek config Objek ini akan berisi konfigurasi instance kepler.gl lengkap {MapState, MapStyle, Visstate}

Kepler.gl menyediakan API yang mudah KeplerGlSchema.getConfigToSave untuk menghasilkan gumpalan JSON dari konfigurasi instance Kepler saat ini.

Contoh

 // 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
  } )
) ;

Baca lebih lanjut tentang addDataTomap dan menyimpan dan memuat peta dengan manajer skema.