Преобразование между форматами

В экосистеме GeoJSON данные могут существовать в нескольких уровнях абстракции: Geometry, Feature и FeatureCollection. Turf.js оперирует всеми тремя, но большинство функций требуют строго определённого формата входных данных, что делает преобразование между форматами ключевым этапом обработки геоданных.

Geometry представляет чистую геометрию без дополнительных свойств. Feature добавляет к геометрии свойства properties и служит основным рабочим объектом. FeatureCollection объединяет множество объектов Feature в одну структуру.

Преобразование между Geometry и Feature

Оборачивание геометрии в Feature

Базовая операция — преобразование «голой» геометрии в полноценный GeoJSON Feature.

import { feature } from "@turf/helpers";

const geometry = {
  type: "Point",
  coordinates: [30, 50]
};

const ft = feature(geometry, { name: "A" });

Особенности:

  • геометрия не изменяется;
  • добавляется обёртка Feature;
  • второй аргумент формирует properties.

Извлечение геометрии из Feature

Во многих функциях Turf требуется именно geometry-часть:

const geometry = ft.geometry;

Использование geometry напрямую уменьшает накладные расходы при массовых операциях.

Работа с FeatureCollection

Создание коллекции

import { featureCollection, point } from "@turf/helpers";

const fc = featureCollection([
  point([30, 10]),
  point([40, 20])
]);

Особенности:

  • все элементы обязаны быть Feature;
  • коллекция используется в batch-операциях.

Преобразование FeatureCollection в массив координат

Для низкоуровневых операций часто требуется извлечь координаты:

import { coordEach } from "@turf/meta";

const coords = [];

coordEach(fc, (coord) => {
  coords.push(coord);
});

Поведение:

  • проходит по всем геометриям;
  • игнорирует структуру Feature;
  • возвращает только координаты.

Конвертация между типами геометрий

Point ↔︎ LineString

Создание LineString из точек

import { lineString } from "@turf/helpers";

const line = lineString([
  [0, 0],
  [10, 10],
  [20, 25]
]);

Разложение линии на точки

import { explode } from "@turf/explode";

const points = explode(line);

Результат:

  • каждый узел линии становится отдельным Feature;
  • сохраняются свойства исходного объекта.

Polygon ↔︎ набор линий и точек

Преобразование полигона в точки

import { explode } from "@turf/explode";

const points = explode(polygon);

Получение контуров полигона

const rings = polygon.geometry.coordinates;

Структура:

  • первый массив — внешний контур;
  • последующие — внутренние отверстия.

Преобразование Multi-геометрий

MultiPoint / MultiLineString / MultiPolygon

Multi-структуры часто требуют нормализации.

const multiPoint = {
  type: "MultiPoint",
  coordinates: [
    [10, 10],
    [20, 20]
  ]
};

Разворачивание MultiPoint в набор Point

import { featureCollection, point } from "@turf/helpers";

const points = featureCollection(
  multiPoint.coordinates.map(c => point(c))
);

Унификация MultiLineString

Для обработки каждой линии отдельно:

const lines = multiLine.coordinates.map(coords =>
  lineString(coords)
);

Результат — массив отдельных LineString.

Преобразование FeatureCollection ↔︎ массив объектов

FeatureCollection → массив Feature

const features = fc.features;

Используется при:

  • фильтрации;
  • сортировке;
  • трансформациях.

Массив Feature → FeatureCollection

const fc2 = featureCollection(features);

Важно:

  • все элементы должны быть валидными Feature;
  • геометрии не проверяются автоматически.

Работа с координатными массивами

GeoJSON → массив координат

import { coordAll } from "@turf/meta";

const allCoords = coordAll(fc);

Особенности:

  • возвращает плоский список координат;
  • сохраняет порядок обхода;
  • включает все уровни вложенности.

Координаты → Feature

import { point } from "@turf/helpers";

const features = coords.map(c => point(c));

Типовой сценарий:

  • данные из API;
  • GPS-треки;
  • сенсорные потоки.

Преобразование систем координат

WGS84 ↔︎ Web Mercator

Turf поддерживает преобразования через @turf/projection.

WGS84 → Web Mercator

import { toMercator } from "@turf/projection";

const merc = toMercator(geojson);

Web Mercator → WGS84

import { toWgs84 } from "@turf/projection";

const wgs = toWgs84(geojson);

Особенности:

  • преобразуются все вложенные координаты;
  • структура GeoJSON сохраняется;
  • работает с Feature и FeatureCollection.

Нормализация геометрий

Приведение к единому формату Feature

import { feature } from "@turf/helpers";

function normalize(input) {
  if (input.type === "Feature") return input;
  return feature(input);
}

Сценарии применения:

  • унификация входных данных;
  • подготовка к batch-обработке.

Очистка и упрощение структуры

import { cleanCoords } from "@turf/clean-coords";

const cleaned = cleanCoords(geojson);

Удаляет:

  • дублирующиеся точки;
  • некорректные координаты;
  • лишние узлы.

Обрезка и контроль точности координат

Ограничение количества знаков

import { truncate } from "@turf/truncate";

const short = truncate(geojson, {
  precision: 4
});

Назначение:

  • уменьшение размера данных;
  • подготовка к визуализации;
  • устранение «шума» GPS.

Преобразование геометрий в наборы точек

Универсальная декомпозиция

import { explode } from "@turf/explode";

Поддерживаемые типы:

  • LineString
  • Polygon
  • MultiLineString
  • MultiPolygon

Результат:

  • FeatureCollection;
  • сохраняется принадлежность к исходной геометрии.

Геометрическая агрегация и обратные преобразования

Сбор точек в линии

import { lineString } from "@turf/helpers";

const line = lineString(points.map(p => p.geometry.coordinates));

Используется при:

  • реконструкции маршрутов;
  • объединении GPS-треков.

Построение полигонов из линий

const polygon = {
  type: "Polygon",
  coordinates: [lineCoordinates]
};

Требования:

  • замкнутый контур;
  • минимум 4 точки;
  • первая и последняя координаты совпадают.

Итерации по структурам без изменения формата

featureEach

import { featureEach } from "@turf/meta";

featureEach(fc, (feature) => {
  console.log(feature);
});

geomEach

import { geomEach } from "@turf/meta";

geomEach(fc, (geom) => {
  console.log(geom.type);
});

Назначение:

  • обход без преобразования структуры;
  • подготовка к конвертации.

Преобразование сложных коллекций

Flatten Multi-геометрий

import { flatten } from "@turf/flatten";

const flat = flatten(multiGeojson);

Результат:

  • MultiPolygon → набор Polygon;
  • MultiLineString → LineString;
  • MultiPoint → Point.

Практическая схема преобразований данных

Типовой поток обработки геоданных в Turf.js выглядит как последовательность трансформаций:

  • входные данные (API / GPS / GeoJSON)
  • нормализация → Feature
  • декомпозиция → explode / flatten
  • преобразование → coordEach / coordAll
  • агрегирование → lineString / polygon
  • финальная упаковка → featureCollection

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

Оглавление