Любая визуализация в Kepler.gl начинается с импорта данных. Библиотека предоставляет несколько механизмов загрузки наборов данных, поддерживает различные форматы файлов и автоматически выполняет анализ структуры таблиц для дальнейшего отображения на карте.
В основе работы Kepler.gl лежит табличная модель данных. Независимо от источника, информация преобразуется в набор строк и столбцов, после чего становится доступной для визуализации в слоях, фильтрах, временных шкалах и аналитических инструментах.
Основные поддерживаемые форматы:
После импорта файла Kepler.gl выполняет несколько этапов обработки:
Упрощённая схема выглядит следующим образом:
Файл
↓
Parser
↓
Dataset
↓
Kepler.gl Store
↓
Map LayersПосле завершения загрузки данные становятся частью состояния Redux и могут использоваться всеми компонентами карты.
Для работы с загрузкой данных необходимо установить Kepler.gl и его зависимости.
npm install kepler.glДля React-проекта обычно дополнительно используются:
npm install react react-dom redux react-reduxПример базового подключения:
import KeplerGl from 'kepler.gl';
function App() {
return (
<KeplerGl
id="map"
width={1200}
height={800}
/>
);
}Основной способ программной загрузки данных — действие
addDataToMap.
Импорт:
import { addDataToMap } from 'kepler.gl/actions';Это действие принимает объект с описанием набора данных и параметрами отображения.
Общая структура:
dispatch(
addDataToMap({
datasets: dataset
})
);После вызова Kepler.gl автоматически создаёт набор данных и отображает его на карте.
Минимальная структура набора данных выглядит следующим образом:
const dataset = {
info: {
label: 'Cities'
},
data: {
fields: [],
rows: []
}
};Содержит служебную информацию.
info: {
label: 'Cities',
id: 'cities_dataset'
}Параметры:
| Поле | Назначение |
|---|---|
| label | Отображаемое имя |
| id | Уникальный идентификатор |
Описывает структуру столбцов.
fields: [
{
name: 'city',
type: 'string'
},
{
name: 'latitude',
type: 'real'
},
{
name: 'longitude',
type: 'real'
}
]Наиболее распространённые типы:
| Тип | Описание |
|---|---|
| string | Строка |
| integer | Целое число |
| real | Число с плавающей точкой |
| boolean | Логическое значение |
| timestamp | Время |
| date | Дата |
| geojson | Геометрия |
Содержит сами данные.
rows: [
['Almaty', 43.2389, 76.8897],
['Astana', 51.1694, 71.4491]
]Порядок значений должен соответствовать порядку полей в массиве
fields.
CSV является наиболее распространённым форматом данных для Kepler.gl.
Пример файла:
city,latitude,longitude,population
Almaty,43.2389,76.8897,2000000
Astana,51.1694,71.4491,1300000Загрузка через выбор файла пользователем:
<input
type="file"
onCha nge={handleFile}
/>Обработчик:
function handleFile(event) {
const file = event.target.files[0];
const reader = new FileReader();
reader.onl oad = function(e) {
const csvText = e.target.result;
dispatch(
addDataToMap({
datasets: csvText
})
);
};
reader.readAsText(file);
}Kepler.gl самостоятельно определит формат CSV и создаст набор данных.
Во встроенном интерфейсе Kepler.gl присутствует поддержка перетаскивания файлов.
Пользователь может:
После попадания файла в область карты автоматически запускается механизм импорта.
GeoJSON является стандартом представления геопространственных объектов.
Пример:
{
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"properties": {
"name": "Almaty"
},
"geometry": {
"type": "Point",
"coordinates": [
76.8897,
43.2389
]
}
}
]
}Загрузка:
fetch('/data/cities.geojson')
.then(response => response.json())
.then(data => {
dispatch(
addDataToMap({
datasets: data
})
);
});После обработки Kepler.gl автоматически создаст слой на основе геометрии объектов.
Если данные представлены обычным JSON-массивом:
[
{
"city": "Almaty",
"lat": 43.2389,
"lng": 76.8897
},
{
"city": "Astana",
"lat": 51.1694,
"lng": 71.4491
}
]Можно загрузить их следующим образом:
fetch('/cities.json')
.then(response => response.json())
.then(data => {
dispatch(
addDataToMap({
datasets: data
})
);
});На практике данные часто поступают от серверного API.
Пример:
async function loadCities() {
const response = await fetch(
'https://api.example.com/cities'
);
const data = await response.json();
dispatch(
addDataToMap({
datasets: data
})
);
}После получения ответа данные сразу становятся доступными в карте.
Kepler.gl способен одновременно работать с несколькими Dataset.
Пример:
dispatch(
addDataToMap({
datasets: [
datasetCities,
datasetRoads,
datasetStations
]
})
);В результате каждый набор данных отображается независимо и может использовать собственные слои.
Для удобства анализа рекомендуется задавать понятные названия.
const dataset = {
info: {
label: 'Weather Stations'
},
data: {
fields,
rows
}
};Название отображается:
Во время загрузки Kepler.gl анализирует названия столбцов.
Типичные имена координат:
lat
latitude
lng
lon
longitudeПри обнаружении подобных полей система предлагает создать слой точек автоматически.
Например:
id,latitude,longitude
1,43.2389,76.8897
2,51.1694,71.4491После импорта карта сразу получает Point Layer.
Если столбцы имеют нестандартные названия:
id,x_coord,y_coord
1,76.8897,43.2389Координаты можно указать вручную в настройках слоя.
Программный вариант:
layerConfig: {
columns: {
lat: 'y_coord',
lng: 'x_coord'
}
}При работе с крупными наборами данных необходимо учитывать объём памяти браузера.
Проблемы:
Рекомендуемые подходы:
Kepler.gl тесно интегрирован с экосистемой loaders.gl.
Установка:
npm install @loaders.gl/coreПример:
import { load } from '@loaders.gl/core';Загрузка файла:
const data = await load(
'/data/file.geojson'
);После получения результата данные передаются в Kepler.gl.
Kepler.gl поддерживает архивированные пространственные данные.
Часто используются:
Пользователь может просто выбрать архив через интерфейс загрузки.
Внутренние загрузчики автоматически распакуют содержимое и преобразуют его в Dataset.
При работе с внешними файлами необходимо контролировать возможные ошибки.
Пример:
try {
const response = await fetch('/data.csv');
if (!response.ok) {
throw new Error('Loading error');
}
const data = await response.text();
dispatch(
addDataToMap({
datasets: data
})
);
}
catch(error) {
console.error(error);
}Основные причины ошибок:
Практически все операции импорта являются асинхронными.
Использование async/await делает код более удобным:
async function loadDataset() {
const response = await fetch(
'/dataset.geojson'
);
const dataset = await response.json();
dispatch(
addDataToMap({
datasets: dataset
})
);
}Подобный подход хорошо масштабируется при работе с несколькими источниками.
Нередко данные требуют очистки ещё до передачи в Kepler.gl.
Пример фильтрации:
const filtered = rows.filter(
row => row.population > 100000
);Преобразование значений:
const normalized = rows.map(row => ({
...row,
population: Number(row.population)
}));Удаление пустых координат:
const cleanRows = rows.filter(
row =>
row.latitude !== null &&
row.longitude !== null
);Подготовленные данные работают быстрее и обеспечивают более корректную визуализацию.
Часто карта должна отображать данные сразу после открытия страницы.
Пример для React:
useEffect(() => {
loadDataset();
}, []);Функция загрузки:
async function loadDataset() {
const response = await fetch(
'/cities.geojson'
);
const data = await response.json();
dispatch(
addDataToMap({
datasets: data
})
);
}В результате карта будет заполнена данными сразу после монтирования компонента.
Во время загрузки можно одновременно передавать настройки визуализации.
Пример:
dispatch(
addDataToMap({
datasets: dataset,
options: {
centerMap: true,
readOnly: false
}
})
);Параметр centerMap автоматически перемещает карту к
загруженным объектам.
Параметр readOnly определяет возможность изменения
настроек пользователем.
Для CSV-файлов
Для GeoJSON
Для API
Для крупных проектов