Работа с KML

KML (Keyhole Markup Language) представляет собой XML-формат для описания географических данных: точек, линий, полигонов, а также их стилизации и метаданных. В OpenLayers поддержка KML реализована через модуль ol/format/KML, который позволяет загружать, интерпретировать и отображать такие данные как векторные объекты на карте.

Основная задача при работе с KML в OpenLayers — преобразование XML-документа в набор геометрий и атрибутов, которые могут быть использованы внутри VectorLayer.

Ключевые особенности KML в контексте OpenLayers:

  • поддержка геометрий (Point, LineString, Polygon, MultiGeometry)
  • чтение описаний (description, name, extendedData)
  • поддержка стилей (частично)
  • работа с внешними ссылками и сетевыми ресурсами
  • возможность трансформации координат

Чтение KML через ol/format/KML

Базовый класс для работы с KML — ol/format/KML. Он предоставляет методы для чтения и записи данных.

import KML from 'ol/format/KML.js';
import VectorSource from 'ol/source/Vector.js';
import VectorLayer from 'ol/layer/Vector.js';

const kmlFormat = new KML({
  extractStyles: true,
  showPointNames: true
});

const vectorSource = new VectorSource({
  url: 'data/route.kml',
  format: kmlFormat
});

const vectorLayer = new VectorLayer({
  source: vectorSource
});

Параметр url позволяет автоматически загружать KML-файл по HTTP. OpenLayers выполняет запрос, парсит XML и создаёт набор объектов ol/Feature.

Разбор структуры KML

После парсинга каждый элемент KML преобразуется в объект Feature, содержащий:

  • геометрию (geometry)
  • свойства (properties)
  • идентификатор (id)

Пример структуры KML:

<Placemark>
  <name>Маршрут</name>
  <description>Пример линии</description>
  <LineString>
    <coordinates>
      30.1,50.2,0 30.5,50.6,0
    </coordinates>
  </LineString>
</Placemark>

После обработки OpenLayers создаёт:

  • LineString geometry
  • свойства name = "Маршрут"
  • description = "Пример линии"

Координаты и проекции

KML всегда использует координаты в системе WGS84 (EPSG:4326). OpenLayers по умолчанию работает в проекции карты (часто EPSG:3857), поэтому происходит автоматическое преобразование.

При ручной обработке важно учитывать:

  • входные координаты KML — всегда lon/lat
  • отображение на карте — обычно Web Mercator
  • преобразование выполняется внутри ol/format/KML

При необходимости можно явно задать проекцию:

const kmlFormat = new KML({
  dataProjection: 'EPSG:4326',
  featureProjection: 'EPSG:3857'
});

Загрузка KML вручную

Помимо загрузки через VectorSource, данные можно читать напрямую:

fetch('data/route.kml')
  .then(response => response.text())
  .then(kmlText => {
    const features = new KML().readFeatures(kmlText, {
      dataProjection: 'EPSG:4326',
      featureProjection: 'EPSG:3857'
    });

    vectorSource.addFeatures(features);
  });

Такой подход используется при необходимости предварительной обработки данных или интеграции с другими API.

Стилизация KML

OpenLayers может извлекать стили из KML, если включена опция extractStyles.

const kmlFormat = new KML({
  extractStyles: true
});

В этом случае учитываются:

  • Style
  • IconStyle
  • LineStyle
  • PolyStyle

Если стили отключены, используется стиль слоя VectorLayer.

Пример пользовательского стиля:

import Style from 'ol/style/Style.js';
import Stroke from 'ol/style/Stroke.js';
import Fill from 'ol/style/Fill.js';

const style = new Style({
  stroke: new Stroke({
    color: '#3399CC',
    width: 3
  }),
  fill: new Fill({
    color: 'rgba(255, 255, 255, 0.2)'
  })
});

Работа с описаниями и HTML-содержимым

Поле description в KML часто содержит HTML-разметку. OpenLayers сохраняет её как строку, но не интерпретирует автоматически.

Пример доступа к данным:

vectorSource.on('addfeature', (event) => {
  const feature = event.feature;
  const name = feature.get('name');
  const description = feature.get('description');
});

При отображении в интерфейсе необходимо учитывать возможное наличие HTML-тегов, ссылок и встроенных таблиц.

Обработка сложных геометрий

KML поддерживает составные геометрии:

  • MultiGeometry
  • вложенные Placemark
  • вложенные стили

OpenLayers автоматически разворачивает такие структуры в отдельные Feature, если это возможно. В противном случае создаётся единый объект с комбинированной геометрией.

Особенность работы с MultiGeometry:

  • каждая часть может иметь собственную интерпретацию
  • стили могут наследоваться от родительского элемента
  • порядок координат сохраняется

Работа с удалёнными KML-файлами

При загрузке KML с внешнего источника важно учитывать CORS-ограничения. Сервер должен разрешать кросс-доменные запросы.

const vectorSource = new VectorSource({
  url: 'https://example.com/data.kml',
  format: new KML()
});

При ошибках загрузки данные не будут отображены, а источник останется пустым.

Обновление KML-данных

KML можно обновлять динамически, перезагружая источник:

vectorSource.clear();
vectorSource.refresh();

или задавая новый URL:

vectorSource.setUrl('data/new-route.kml');
vectorSource.refresh();

Этот механизм применяется для отображения изменяющихся маршрутов или потоковых данных.

Преобразование KML в GeoJSON

OpenLayers позволяет преобразовывать KML в другие форматы, например GeoJSON:

import GeoJSON from 'ol/format/GeoJSON.js';

const kmlFormat = new KML();
const geojsonFormat = new GeoJSON();

const features = kmlFormat.readFeatures(kmlText, {
  dataProjection: 'EPSG:4326',
  featureProjection: 'EPSG:3857'
});

const geojson = geojsonFormat.writeFeaturesObject(features);

Такой подход используется при интеграции с REST API и серверными сервисами.

Оптимизация работы с большими KML-файлами

При больших объёмах данных производительность становится критичной.

Основные методы оптимизации:

  • отключение extractStyles
  • использование кластеризации (Cluster source)
  • предварительное упрощение геометрий
  • разбиение KML на части
  • ленивую загрузку по bbox

Пример кластеризации:

import Cluster from 'ol/source/Cluster.js';

const clusterSource = new Cluster({
  distance: 40,
  source: vectorSource
});

Обработка событий загрузки

VectorSource генерирует события, связанные с загрузкой KML:

  • featuresloadstart
  • featuresloadend
  • featuresloaderror
vectorSource.on('featuresloadstart', () => {
  console.log('Загрузка началась');
});

vectorSource.on('featuresloadend', () => {
  console.log('Загрузка завершена');
});

Эти события используются для управления состоянием интерфейса и индикаторами загрузки.

Ограничения формата KML в OpenLayers

Несмотря на поддержку, KML имеет ряд ограничений:

  • ограниченная поддержка расширенных KML-спецификаций
  • слабая работа с динамическими данными
  • зависимость от XML-структуры
  • не всегда корректная интерпретация сложных стилей Google Earth
  • отсутствие нативной поддержки некоторых расширений GX

При сложных сценариях предпочтение часто отдаётся GeoJSON или специализированным протоколам передачи геоданных.

Оглавление