kepler.gl

kepler.gl | الموقع | التطبيق التجريبي | مستندات

kepler.gl هو تطبيق على شبكة الإنترنت عالي الأداء للبيانات للبيانات للاستكشاف المرئي لمجموعات بيانات تحديد الموقع الجغرافي على نطاق واسع. بنيت على قمة Maplibre GL و Deck.GL ، يمكن لـ Kepler.GL تقديم ملايين النقاط التي تمثل آلاف الرحلات وأداء التجمعات المكانية أثناء الطيران.

kepler.gl هو أيضًا مكون React يستخدم Redux لإدارة حالتها وبياناتها. يمكن تضمينها في تطبيقات React-Redux الأخرى ويمكن تخصيصها بشكل كبير. للحصول على معلومات حول كيفية تضمين kepler.gl في تطبيقك ، ألقِ نظرة على هذا البرنامج التعليمي خطوة بخطوة على Vis.Academy.

الروابط

• موقع إلكتروني
• العرض التوضيحي
• أمثلة
• ابدأ
• دليل مستخدم التطبيق
• دليل مستخدم عنصر واجهة المستخدم Jupyter
• درس تعليمي
• مكدس فائض
• إرشادات المساهمة
• مرجع API
• خريطة الطريق

البيئة

استخدم العقدة 18.18.2 أو أعلى ، لم يتم دعم/ اختبار إصدارات العقدة القديمة. للحصول على أفضل النتائج ، استخدم nvm install .

تثبيت kepler.gl

تثبيت العقدة ( > 18.18.2 ) ، والغزل ، وتبعيات المشروع

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

تم بناء kepler.gl على mapbox. ستحتاج إلى رمز الوصول إلى MapBox لاستخدامه.

إذا لم تستخدم مجموعة الوحدة النمطية ، فلا بأس بذلك. تتضمن حزمة Kepler.GL NPM إنشاءات UMD PRODUCTION في مجلد UMD. يمكنك إضافة علامة البرنامج النصي إلى ملف HTML الخاص بك كما يتبع:

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

أو إذا كنت ترغب في ذلك ، يمكنك تحميل إصدار معين

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

تطوير kepler.gl

ألقِ نظرة على دليل التطوير لتطوير kepler.gl محليًا.

الاستخدام الأساسي

فيما يلي الخطوات الأساسية لاستيراد kepler.gl في تطبيقك. يمكنك أيضًا إلقاء نظرة على مجلد الأمثلة. يمكن تثبيت كل مثال في المجلد وتشغيله محليًا.

1. مخفض جبل

يستخدم Kepler.GL Redux لإدارة حالته الداخلية ، إلى جانب برامج الوسيطة React-Palm للتعامل مع الآثار الجانبية.

تحتاج إلى إضافة taskMiddleware من react-palm إلى متجرك أيضًا. نحن نعمل بنشاط على حل لن تكون هناك حاجة إلى react-palm ، ومع ذلك لا يزال أداة إدارة الآثار الجانبية خفيفة الوزن للغاية والتي يسهل اختبارها من 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 */
    ] )
  )
) ;

أو إذا استخدم المحسن:

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

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

إذا قمت بتثبيت kepler.gl المخفض في عنوان آخر بدلاً من keplerGl ، أو لم يتم تركيب مخفض kepler.gl عند جذر ولايتك ، فستحتاج إلى تحديد المسار إليه عند تثبيت المكون باستخدام getState Prop.

اقرأ المزيد عن المخفضات.

2. مكون جبل

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

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

الدعائم

id (سلسلة ، مطلوب)

• الافتراضي: map

معرف هذا مثيل Keplergl. مطلوب id إذا كان لديك العديد من مثيلات Keplergl في تطبيقك. يحدد اسم Prop of keplergl الذي يتم تخزينه في مخفض Keplergl. على سبيل المثال ، يتم تخزين حالة مكون keplergl مع معرف foo في state.keplerGl.foo .

في حالة إنشاء مثيلات kepler.gl متعددة باستخدام نفس المعرف ، سيتم تجاوز حالة kepler.gl المحددة بواسطة الإدخال بواسطة أحدث مثيل وإعادة ضبطه على حالة فارغة.

mapboxApiAccessToken (سلسلة ، مطلوب*)

• الافتراضي: undefined

بشكل افتراضي ، يستخدم kepler.gl mapbox-gl.js لتقديم خرائطه الأساسية. يمكنك إنشاء حساب مجاني في MapBox وإنشاء رمز على www.mapbox.com/account/access-tokens.

إذا قمت باستبدال أنماط خريطة Kepler.GL الخاصة بك ، فهي ليست أنماط MapBox. لن تكون هناك حاجة إلى mapboxApiAccessToken .

اقرأ المزيد عن أنماط الخريطة المخصصة.

getState (وظيفة ، اختيارية)

• الافتراضي: state => state.keplerGl

المسار إلى حالة keplergl الجذر في المخفض الخاص بك.

width (الرقم ، اختياري)

• الافتراضي: 800

عرض Keplergl واجهة المستخدم.

height (رقم ، اختياري)

• الافتراضي: 800

appName (سلسلة ، اختياري)

• الافتراضي: Kepler.Gl

اسم التطبيق المعروض في رأس اللوحة الجانبية

version (سلسلة ، اختياري)

• الافتراضي: v1.0

الإصدار المعروض في رأس اللوحة الجانبية

onSaveMap (وظيفة ، اختيارية)

• الافتراضي: undefined

الإجراء الذي يسمى عند النقر فوق حفظ عنوان URL MAP في رأس اللوحة الجانبية.

onViewStateChange (وظيفة ، اختيارية)

• الافتراضي: undefined
• المعلمة: viewState - كائن حالة عرض محدث يحتوي على معلمات مثل خط الطول ، خط العرض ، التكبير وما إلى ذلك

الإجراء الذي يتم تشغيله عند تحديث منفذ عرض الخريطة.

getMapboxRef(mapbox, index) (وظيفة ، اختياري)

• الافتراضي: undefined

وظيفة تسمى عندما تضيف KeplerGL أو تزيل مكون MapContainer يحتوي على خريطة MapBox الداخلية.

وسيطة mapbox هي MapRef عند إضافتها أو null عند إزالتها.

وسيطة index هي 0 لخريطة واحدة أو 1 لخريطة إضافية (لأن KeplerGL تدعم عرض خريطة تقسيم اختياري).

actions (كائن ، اختياري)

• تقصير: {}

الإجراءات المبدعين لاستبدال kepler.gl action creator. فقط استخدم الإجراء المخصص عندما تريد تعديل حمولة الإجراء.

mint (منطقي ، اختياري)

• الافتراضي: true

ما إذا كنت تريد تحميل حالة فارغة طازجة عند تثبيت المكون. عندما يكون Parse mint: true سوف يقوم دائمًا بتحميل حالة جديدة عند إعادة تشغيل نفس المكون ، سيتم تدمير الحالة داخل هذا المكون بمجرد عدم المثبتة. عن طريق تحليل mint: false بحالة المكون في المتجر حتى عندما يكون غير مثبت ، ويستخدمها كحالة أولية عند إعادة تثبيتها مرة أخرى. يكون هذا مفيدًا عند تثبيت kepler.gl في وسيط ، والحفاظ على نفس الخريطة عند إعادة فتحه.

اقرأ المزيد عن المكونات.

theme (كائن | سلسلة ، اختياري)

• الافتراضي: null

واحدة من "dark" أو "light" أو "base" يمكنك تمرير اسم السمة أو الكائن المستخدم لتخصيص نمط kepler.gl. يوفر Kepler.GL موضوع 'light' إلى جانب موضوع "الظلام الافتراضي". عندما يتم تمرير كائن موضوع kepler.gl سيستخدم القيمة التي تم تمريرها كإدخال لتجاوز القيم من السمة.

اقرأ المزيد عن السمة المخصصة

mapboxApiUrl (سلسلة ، اختيارية)

• الافتراضي: https://api.mapbox.com

إذا كنت تستخدم خادم Tile MapBox الخاص بك ، فيمكنك تمرير عنوان URL الخاص بـ Tile Server الخاص بك.

mapStylesReplaceDefault (منطقية ، اختيارية)

• الافتراضي: false

Kepler.GL توفير 4 أنماط خريطة للاختيار من بينها. مرر true إذا كنت تريد توفير mapStyles الخاص بك. انظر أدناه.

mapStyles (صفيف ، اختياري)

• تقصير: []

يمكنك توفير أنماط خريطة إضافية ليتم عرضها في لوحة اختيار نمط الخريطة. بشكل افتراضي ، ستتم إضافة أنماط خريطة إضافية إلى أنماط الخريطة الافتراضية. إذا تم تمرير mapStylesReplaceDefault: true ، فسوف يحل محلها الافتراضي. ستحاول kepler.gl تجميع طبقات من أسلوبك استنادًا إلى اتفاقية تسمية id واستخدامها للسماح بتبديل رؤية طبقات الخريطة الأساسية. قم بتزويد layerGroups الخاصة بك لتجاوز الافتراضي لتجميع طبقة أكثر دقة.

يجب أن يكون لكل mapStyles الخصائص التالية:

• id (سلسلة ، مطلوب) سلسلة فريدة لا ينبغي أن تكون واحدة من هذه light dark المحجوز muted . muted_night
• label (سلسلة ، مطلوب) اسم ليتم عرضه في لوحة اختيار نمط الخريطة
• url (سلسلة ، مطلوب) عنوان URL MapBox Style أو عنوان URL يشير إلى كائن JSON النمط الخريطة المكتوب في مواصفات نمط Mapbox GL.
• icon (سلسلة ، اختيارية) أيقونة صورة للنمط ، يمكن أن يكون عنوان URL أو عنوان URL لبيانات الصورة
• layerGroups (صفيف ، اختياري)

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

اقرأ المزيد عن أنماط الخريطة المخصصة.

initialUiState (كائن ، اختياري)

• الافتراضي: undefined

حالة واجهة مستخدم INTIAL التي يتم تطبيقها على مخفض Uistate ، سيتم دمج القيمة ضحلة مع الافتراضي INITIAL_UI_STATE

localeMessages (كائن ، اختياري)

• الافتراضي: تعديل الترجمة الافتراضية undefined أو إضافة ترجمة جديدة

اقرأ المزيد عن التوطين.

3. إرسال الإجراءات المخصصة إلى مخفض keplerGl .

تتمثل إحدى ميزة استخدام المخفض فوق حالة مكون React في التعامل مع حالة Keplergl وهي المرونة في تخصيص سلوكها. إذا كان لديك مثيل KeplerGl واحد فقط في تطبيقك أو لا تنوي أبدًا إرسال الإجراءات إلى Keplergl من خارج المكون نفسه ، فلن تحتاج إلى القلق بشأن إعادة إرسال الإرسال ويمكنك الانتقال إلى القسم التالي. لكن الحياة مليئة بالتخصيصات ، ونريد أن نجعلك ممتعًا قدر الإمكان.

هناك طرق متعددة لإرسال الإجراءات إلى مثيل KeplerGl معين.

• في مخفض الجذر ، مع التحديثات المخفضة.

يتم تعيين كل إجراء إلى محدث مخفض في kepler.gl. يمكنك استيراد محدث المخفض الذي يتوافق مع إجراء محدد ، والاتصال به مع حمولة الحالة والحركة السابقة للحصول على الحالة المحدثة. على سبيل المثال ، updateVisDataUpdater هو updater for ActionTypes.UPDATE_VIS_DATA (ألق نظرة على كل reducers/vis-state.js للعمل على رسم الخرائط). فيما يلي مثال على كيفية الاستماع إلى APP Action QUERY_SUCCESS و Call updateVisDataUpdater لتحميل البيانات إلى 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 ;

اقرأ المزيد حول استخدام التحديثات لتعديل حالة kepler.gl

• باستخدام Redux connect

يمكنك إضافة وظيفة إرسال إلى المكون الذي يرسل الإجراءات إلى مكون keplerGl معين ، باستخدام 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 ) ;

• التفاف حمولة الإجراء

يمكنك أيضًا ببساطة لف إجراءً في إجراء إلى الأمام مع wrapTo Helper

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

اقرأ المزيد عن الإجراءات الإرسال إلى الأمام

4. تخصيص النمط.

Kepler.GL ينفذ تصميم CSS باستخدام المكونات المصممة. باستخدام Framework Kepler.GL يوفر القدرة على تخصيص أسلوبه/موضوعه باستخدام النهج التالية:

• تمرير موضوع الدعامة
• مصممة على غرار

يتم سرد الخصائص المتاحة للتخصيص هنا موضوع.

مثال موضوع مخصص.

تمرير موضوع الدعامة.

يمكنك تخصيص موضوع Kepler.gl من خلال تمرير الدعائم السمة إلى مكون React.GL كما يتبع:

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

كما يمكنك أن ترى كائن CustomTheme يحدد خصائص معينة ستتجاوز قواعد النمط الافتراضية kepler.gl.

مزود موضوع التصميم.

من أجل تخصيص سمة kepler.gl باستخدام thereprovider ، يمكنك ببساطة لف kepler.gl باستخدام thereprovider كما يتبع:

 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. عرض مكونات واجهة المستخدم المخصصة.

الجميع يريد المرونة لجعل مكونات kepler.gl مخصصة. لدى kepler.gl نظام حقن التبعية يسمح لك بحقن المكونات لاستبدال Keplergl الاستبدال. كل ما عليك فعله هو إنشاء مصنع مكون للمكونات التي تريد استبدالها ، واستيراد مصنع المكون الأصلي ومكالمات injectComponents في مكون الجذر في تطبيقك حيث يتم تثبيت KeplerGl . ألقِ نظرة على examples/demo-app/src/app.js وشاهد كيف يجعل رأس لوحة جانبية مخصصة في 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 >
) ;

باستخدام withState Helper لإضافة حالة المخفض والإجراءات إلى مكون مخصص كدعائم إضافية.

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

اقرأ المزيد عن استبدال مكون واجهة المستخدم

6. كيفية إضافة البيانات إلى خريطة

للتفاعل مع مثيل kepler.gl وإضافة بيانات جديدة إليه ، يمكنك إرسال إجراء addDataToMap من أي مكان داخل التطبيق الخاص بك. يضيف مجموعة بيانات أو مجموعات بيانات متعددة إلى مثيل kepler.gl ويقوم بتحديث التكوين الكامل (MapState ، MapStyle ، Visstate).

حدود

• كائن data *المطلوب

  • datasets (Array <Object> | Object) *يمكن أن تكون مجموعات البيانات المطلوبة مجموعة بيانات أو مجموعة من مجموعات البيانات التي يحتاج كل كائن مجموعة بيانات إلى info وخاصية data .

    • datasets.info كائن -info من مجموعة البيانات
      • معرف سلسلة datasets.info.id من مجموعة البيانات هذه. إذا تم تعريف التكوين ، يجب أن يطابق id dataId في التكوين.
      • مجموعات datasets.info.label
    • datasets.data كائن data *يتطلب كائن البيانات ، بتنسيق جدولي مع 2 خصائص fields rows
      • مجموعات datasets.data.fields .
        • مجموعات datasets.data.fields.name .
      • مجموعات datasets.data.rows . fields rows

  • كائن options

    • options.centerMap Boolean default: true إذا تم تعيين centerMap على kepler true سيضع عرض الخريطة ضمن حدود نقاط البيانات
    • options.readOnly . default: false readOnly true
    • options.keepExistingConfig الافتراضي default: false ما إذا كان يجب الاستمرار في الخروج من تكوين الخريطة ، بما في ذلك الطبقات والمرشحات والقسمة.

• كائن config سيحتوي هذا الكائن على تكوين مثيل kepler.gl الكامل {mapState ، mapStyle ، Visstate}

يوفر kepler.gl سهلة api KeplerGlSchema.getConfigToSave لإنشاء نقطة JSON من تكوين مثيل kepler الحالي.

أمثلة

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

اقرأ المزيد حول AddDatatomap وحفظ الخرائط وتحميلها مع Schema Manager.