KML

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

Структура KML включает:

  • Placemark — геообъект (точка, линия, полигон)
  • Point / LineString / Polygon — геометрия
  • Style — описание визуального оформления
  • Folder — группировка объектов
  • NetworkLink — удалённая загрузка данных

Особенность формата заключается в том, что он изначально рассчитан на визуализацию, а не на аналитическую обработку, поэтому часто содержит встроенные стили и описания объектов.

Поддержка KML в OpenLayers

OpenLayers предоставляет встроенный парсер KML через модуль ol/format/KML. Он позволяет:

  • читать KML-файлы (локальные и удалённые)
  • преобразовывать их в объекты OpenLayers
  • сохранять геометрию и свойства
  • извлекать стили из KML
  • работать с NetworkLink

Основной класс для работы:

import KML from 'ol/format/KML';

Загрузка KML через VectorSource

Чаще всего KML подключается как источник векторного слоя.

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

const kmlSource = new VectorSource({
  url: 'data/routes.kml',
  format: new KML()
});

const kmlLayer = new VectorLayer({
  source: kmlSource
});

Особенности загрузки

  • url может указывать на локальный файл или удалённый ресурс
  • загрузка происходит асинхронно
  • данные автоматически парсятся в объекты Feature
  • геометрии преобразуются в проекцию карты (обычно EPSG:3857)

Параметры KML-формата в OpenLayers

Конструктор KML поддерживает ряд настроек, влияющих на поведение парсинга.

extractStyles

Определяет, будут ли использоваться стили из KML.

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

Если включено:

  • применяются иконки Placemark
  • учитываются цвета линий и полигонов
  • используются масштабируемые символы

Если выключено:

  • применяется стиль слоя OpenLayers
  • KML становится только источником геометрии

showPointNames

Управляет отображением названий точек.

new KML({
  showPointNames: true
});

При включении:

  • подписи берутся из <name>
  • отображаются как текстовые метки

defaultStyle

Позволяет задать fallback-стиль для объектов без встроенного оформления.

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

const format = new KML({
  defaultStyle: new Style({
    fill: new Fill({
      color: 'rgba(0, 150, 255, 0.3)'
    }),
    stroke: new Stroke({
      color: '#0096ff',
      width: 2
    })
  })
});

Работа с геометрией KML

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

  • Point
  • LineString
  • Polygon
  • MultiGeometry

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

kmlSource.on('addfeature', (event) => {
  const feature = event.feature;
  const geometry = feature.getGeometry();
  const properties = feature.getProperties();
});

Типовые свойства KML-объектов

  • name — название объекта
  • description — HTML-описание
  • styleUrl — ссылка на стиль
  • пользовательские атрибуты

Стилизация KML-объектов

Даже при использовании встроенных стилей часто требуется переопределение отображения через styleFunction.

import Style from 'ol/style/Style';
import CircleStyle from 'ol/style/Circle';
import Fill from 'ol/style/Fill';

const layer = new VectorLayer({
  source: kmlSource,
  style: (feature) => {
    const type = feature.getGeometry().getType();

    if (type === 'Point') {
      return new Style({
        image: new CircleStyle({
          radius: 6,
          fill: new Fill({ color: 'red' })
        })
      });
    }
  }
});

При этом стили KML могут быть полностью игнорированы, если extractStyles отключён.

KML может содержать ссылки на внешние данные, обновляемые динамически.

OpenLayers поддерживает их загрузку, но с ограничениями:

  • обновление происходит при загрузке источника
  • автоматический polling не реализован нативно
  • возможна необходимость ручного обновления source.refresh()
kmlSource.refresh();

Координатные системы и преобразования

KML использует WGS84 (EPSG:4326), где координаты представлены как:

longitude, latitude, altitude

OpenLayers автоматически преобразует данные в проекцию карты.

При необходимости ручного контроля используется:

import { transform } from 'ol/proj';

const coord = transform([lon, lat], 'EPSG:4326', 'EPSG:3857');

Чтение KML из строки

Помимо загрузки по URL, KML можно парсить из строки:

const kmlText = `
<kml xmlns="http://www.opengis.net/kml/2.2">
  <Placemark>
    <name>Example</name>
    <Point>
      <coordinates>70.0,50.0</coordinates>
    </Point>
  </Placemark>
</kml>
`;

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

Экспорт данных в KML

OpenLayers поддерживает обратное преобразование через writeFeatures.

const kmlFormat = new KML();

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

Результат — строка XML, готовая для сохранения или передачи.

Особенности обработки сложных KML-структур

Мультигеометрии

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

  • MultiGeometry объединяется в единый Feature
  • каждая часть сохраняется внутри GeometryCollection

Вложенные Folder

Иерархия Folder преобразуется в плоский набор Feature, при этом:

  • сохраняется информация о группировке
  • может использоваться атрибут folderName

Производительность при работе с KML

При больших файлах KML возникают типовые ограничения:

  • высокая нагрузка на парсинг XML
  • большое количество Feature снижает FPS
  • стили KML увеличивают время отрисовки

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

  • отключение extractStyles
  • использование кластеризации точек
  • упрощение геометрии до загрузки
  • разбиение KML на несколько слоёв

Типовые ошибки при загрузке KML

  • неверная кодировка XML (должна быть UTF-8)
  • отсутствие namespace http://www.opengis.net/kml/2.2
  • CORS-блокировка при загрузке с внешнего сервера
  • некорректные координаты (перепутаны latitude/longitude)

Интеграция KML-слоя в композицию карты

KML-слой может комбинироваться с другими слоями:

  • тайловыми слоями (OSM, XYZ)
  • WMS/WMTS слоями
  • другими векторными источниками

При наложении важно учитывать порядок:

map.addLayer(rasterLayer);
map.addLayer(kmlLayer);

Векторный слой KML обычно размещается поверх растровых данных для корректной визуализации объектов.

Оглавление