Преобразование форматов данных

Работа с геоданными в JavaScript-API требует строгого понимания того, как представляются координаты, геометрии и пространственные объекты в различных форматах. В экосистеме HERE используются как внутренние структуры SDK, так и внешние стандарты обмена данными, включая GeoJSON, WKT, KML и собственные модели платформы.

Внутренние структуры данных HERE Maps API

В JavaScript SDK геометрия обычно представляется через объекты пространства H.geo и классы H.map.

Основные типы геометрии

  • точка (H.geo.Point)
  • линия (H.geo.LineString)
  • многоугольник (H.geo.Polygon)

Пример создания точки:

const point = new H.geo.Point(52.5200, 13.4050);

Линия:

const lineString = new H.geo.LineString();
lineString.pushPoint({ lat: 52.5200, lng: 13.4050 });
lineString.pushPoint({ lat: 52.5206, lng: 13.4090 });

Многоугольник:

const polygon = new H.geo.Polygon(
  new H.geo.LineString([
    { lat: 52.52, lng: 13.40 },
    { lat: 52.52, lng: 13.41 },
    { lat: 52.51, lng: 13.41 },
    { lat: 52.51, lng: 13.40 }
  ])
);

GeoJSON как основной формат обмена

GeoJSON является стандартом де-факто для интеграции геоданных в веб-приложениях. HERE Maps API поддерживает преобразование GeoJSON в свои внутренние объекты.

Пример GeoJSON точки

{
  "type": "Point",
  "coordinates": [13.4050, 52.5200]
}

Важно: порядок координат в GeoJSON — [longitude, latitude], что часто вызывает ошибки при миграции данных.

Пример конвертации GeoJSON → HERE Geometry

const geojsonPoint = {
  type: "Point",
  coordinates: [13.4050, 52.5200]
};

const herePoint = H.geo.Point.fromGeoPoint(geojsonPoint);

Пример Feature Collection

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "LineString",
        "coordinates": [
          [13.4, 52.52],
          [13.41, 52.53]
        ]
      },
      "properties": {
        "name": "Route A"
      }
    }
  ]
}

Конвертация HERE → GeoJSON

В SDK доступны методы преобразования внутренних структур в GeoJSON:

const line = new H.geo.LineString([
  { lat: 52.52, lng: 13.4 },
  { lat: 52.53, lng: 13.41 }
]);

const geojson = H.geo.LineString.prototype.toGeoJSON.call(line);

Для полигонов:

const geojsonPolygon = polygon.toGeoJSON();

WKT (Well-Known Text)

WKT используется в GIS-системах и базах данных (PostGIS, Oracle Spatial). В экосистеме HERE Technologies он применяется при интеграции с внешними пространственными хранилищами.

Примеры WKT

Точка:

POINT (13.4050 52.5200)

Линия:

LINESTRING (13.4 52.52, 13.41 52.53)

Полигон:

POLYGON ((13.4 52.52, 13.41 52.52, 13.41 52.51, 13.4 52.51, 13.4 52.52))

Преобразование WKT → HERE Geometry

const wkt = "POINT (13.4050 52.5200)";

const geometry = H.util.wkt.parse(wkt);

Обратное преобразование

const wktString = H.util.wkt.stringify(geometry);

KML (Keyhole Markup Language)

KML используется в Google Earth и GIS-инструментах. В HERE Maps API его поддержка реализуется через парсеры данных или промежуточное преобразование.

Пример KML

<Placemark>
  <Point>
    <coordinates>13.4050,52.5200,0</coordinates>
  </Point>
</Placemark>

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

Типичный рабочий процесс:

  1. Парсинг XML
  2. Извлечение координат
  3. Формирование GeoJSON
  4. Конвертация в HERE Geometry
function kmlPointToGeoJSON(kmlCoords) {
  const [lng, lat] = kmlCoords.split(',').map(Number);

  return {
    type: "Point",
    coordinates: [lng, lat]
  };
}

Форматирование координат

WGS84 как основа

Все данные в HERE Maps API используют систему координат WGS84:

  • широта (latitude): -90 до 90
  • долгота (longitude): -180 до 180

Ошибки порядка координат

Наиболее частая проблема — путаница форматов:

Формат Порядок
HERE API lat, lng
GeoJSON lng, lat
WKT lng lat

Конвертация между форматами в прикладных сценариях

GeoJSON → LineString → маршрут

const routeGeoJSON = {
  type: "LineString",
  coordinates: [
    [13.4, 52.52],
    [13.41, 52.53],
    [13.42, 52.54]
  ]
};

const line = new H.geo.LineString();

routeGeoJSON.coordinates.forEach(([lng, lat]) => {
  line.pushPoint({ lat, lng });
});

Массив координат → Polygon

const coords = [
  [13.4, 52.52],
  [13.41, 52.52],
  [13.41, 52.51],
  [13.4, 52.51]
];

const polygon = new H.geo.Polygon(
  new H.geo.LineString(coords.map(([lng, lat]) => ({ lat, lng })))
);

Сериализация и десериализация объектов карты

В рамках HERE Maps API часто требуется сохранять геометрии для последующего восстановления.

Сериализация

const serialized = JSON.stringify(polygon.toGeoJSON());
localStorage.setItem("polygon", serialized);

Десериализация

const restored = JSON.parse(localStorage.getItem("polygon"));

const polygon = H.geo.Polygon.fromGeoJson(restored);

Конвертация данных из внешних GIS-систем

При интеграции с корпоративными GIS системами часто встречаются:

  • ESRI JSON
  • Shapefile (через промежуточное преобразование)
  • PostGIS геометрии
  • WFS (Web Feature Service)

Типовой пайплайн:

Shapefile → GeoJSON → HERE Geometry → Map Object

Нормализация и очистка данных

Перед конвертацией выполняются операции:

  • удаление некорректных координат
  • проверка замыкания полигонов
  • устранение дубликатов точек
  • нормализация порядка координат
  • приведение типов (string → number)

Пример фильтрации:

function normalizeCoords(coords) {
  return coords
    .filter(c => Array.isArray(c) && c.length === 2)
    .map(([lng, lat]) => ({
      lng: Number(lng),
      lat: Number(lat)
    }))
    .filter(p => isFinite(p.lat) && isFinite(p.lng));
}

Использование адаптеров данных в архитектуре приложения

В сложных системах вводится слой адаптации:

  • Input Adapter (GeoJSON / WKT / API)
  • Internal Model (HERE Geometry)
  • Output Adapter (Map Layers / Tiles / Rendering)

Такой подход снижает связанность кода и упрощает поддержку различных форматов.

Особенности преобразования в маршрутизации

При работе с routing API используется специализированная структура:

  • waypoint формат
  • polyline encoding
  • maneuver representation

Пример waypoint:

const waypoints = [
  { lat: 52.52, lng: 13.4 },
  { lat: 52.53, lng: 13.41 }
];

Далее они преобразуются в маршрутный запрос без промежуточных GeoJSON-структур.

Кодирование полилиний

В некоторых API используется компактное представление маршрутов:

  • encoded polyline
  • delta encoding координат

Это уменьшает размер передаваемых данных при больших маршрутах и потоковой визуализации.

Оглавление