Структура Feature и FeatureCollection

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

Структура Feature

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

Общая структура

{
  "type": "Feature",
  "geometry": {
    "type": "Point",
    "coordinates": [102.0, 0.5]
  },
  "properties": {
    "name": "Example Point",
    "category": "marker"
  }
}

Основные компоненты

type

Поле type всегда имеет значение:

  • "Feature" — фиксирует объект как GeoJSON Feature

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

geometry

Поле geometry описывает пространственную сущность объекта.

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

  • Point
  • LineString
  • Polygon
  • MultiPoint
  • MultiLineString
  • MultiPolygon
  • GeometryCollection

Пример Point:

{
  "type": "Point",
  "coordinates": [30.5, 50.5]
}

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

  • координаты всегда в порядке [долгота, широта]
  • используется система WGS84 (EPSG:4326)
  • допускаются вложенные массивы для сложных геометрий

properties

properties — контейнер для метаданных.

Это произвольный объект, который может содержать:

  • строки
  • числа
  • булевы значения
  • вложенные структуры (объекты и массивы)

Пример:

{
  "properties": {
    "id": 1,
    "name": "Park",
    "area": 1200.5,
    "active": true,
    "tags": ["green", "recreation"]
  }
}

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

  • не влияет на геометрические вычисления Turf.js
  • используется для фильтрации, группировки и визуализации
  • может быть пустым объектом {}

Геометрия внутри Feature

Feature всегда содержит ровно одну геометрию:

  • либо конкретный объект (Point, Polygon)
  • либо null

Пример пустого объекта:

{
  "type": "Feature",
  "geometry": null,
  "properties": {}
}

Использование null означает отсутствие пространственной информации при сохранении атрибутов.

Структура FeatureCollection

FeatureCollection — контейнер для набора Feature объектов. Это основной формат для массовой обработки данных в Turf.js.

Общая структура

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [102.0, 0.5]
      },
      "properties": {
        "name": "A"
      }
    },
    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [103.0, 1.0]
      },
      "properties": {
        "name": "B"
      }
    }
  ]
}

Основные компоненты

type

Фиксированное значение:

  • "FeatureCollection"

features

Массив объектов Feature.

Свойства массива:

  • содержит 0 или более элементов
  • порядок элементов сохраняется
  • допускается смешение разных типов геометрии

Пустая коллекция

{
  "type": "FeatureCollection",
  "features": []
}

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

Взаимосвязь Feature и FeatureCollection

FeatureCollection является верхнеуровневой структурой, а Feature — атомарной единицей данных.

Иерархия:

  • FeatureCollection

    • Feature

      • Geometry
      • Properties

Turf.js почти все операции принимает в виде:

  • одиночного Feature
  • FeatureCollection
  • массива координат (внутренне преобразуемого в Feature)

Требования к координатам

Порядок координат

Во всех структурах GeoJSON:

[longitude, latitude]

Пример:

[37.6173, 55.7558]

Ошибочный порядок:

[55.7558, 37.6173]

Система координат

GeoJSON предполагает:

  • WGS84 (EPSG:4326)
  • градусы, а не метры

Любые расчёты расстояний в Turf.js учитывают сферическую модель Земли.

Особенности использования properties в Turf.js

properties активно используются для:

Фильтрации

features.filter(f => f.properties.type === "park")

Группировки

  • по категориям
  • по регионам
  • по числовым диапазонам

Сохранения результатов анализа

Turf.js часто добавляет вычисленные поля:

{
  "properties": {
    "length": 1250.7,
    "buffer_radius": 100
  }
}

Вложенные и сложные структуры

GeometryCollection внутри Feature

{
  "type": "Feature",
  "geometry": {
    "type": "GeometryCollection",
    "geometries": [
      {
        "type": "Point",
        "coordinates": [10, 10]
      },
      {
        "type": "LineString",
        "coordinates": [[10, 10], [20, 20]]
      }
    ]
  },
  "properties": {}
}

Используется реже, но поддерживается Turf.js для комплексных операций.

Типичные ошибки при работе с Feature и FeatureCollection

1. Отсутствие поля type

{
  "geometry": {...},
  "properties": {}
}

Недопустимо — структура не распознаётся как GeoJSON.

2. Перепутанный порядок координат

Критическая ошибка при расчётах расстояний и буферов.

3. Использование невалидных типов геометрии

Например:

"PointLine"

Такой тип не существует в стандарте.

4. Null geometry без обработки

{
  "type": "Feature",
  "geometry": null,
  "properties": {}
}

Turf.js операции часто требуют проверки geometry !== null.

Роль Feature и FeatureCollection в Turf.js

Внутри Turf.js эти структуры используются как универсальный вход и выход:

  • расчёт расстояний между Feature
  • построение буферов вокруг Feature
  • пересечения FeatureCollection
  • кластеризация точек
  • анализ полигонов

Любая функция библиотеки опирается на единый контракт данных: GeoJSON Feature или FeatureCollection.

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

Feature → FeatureCollection

const collection = {
  type: "FeatureCollection",
  features: [feature]
};

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

Внутреннее представление:

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

const feature = point([30, 50]);

FeatureCollection → массив Feature

const features = collection.features;

Семантика неизменяемости данных

GeoJSON в контексте Turf.js рассматривается как:

  • неизменяемая структура
  • результат операций создаёт новый объект
  • исходные Feature не модифицируются

Это важно для предсказуемости геоалгоритмов.

Совместимость Feature и FeatureCollection с другими системами

GeoJSON структуры широко поддерживаются:

  • картографическими библиотеками (Mapbox GL, Leaflet)
  • GIS-системами
  • API геокодирования
  • пространственными базами данных

Turf.js выступает как слой вычислений поверх стандартного формата.

Композиция данных в FeatureCollection

FeatureCollection может включать:

  • точки наблюдений
  • линии маршрутов
  • полигоны зон
  • смешанные типы объектов

Пример смешанной коллекции:

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": { "type": "Point", "coordinates": [0, 0] },
      "properties": { "type": "station" }
    },
    {
      "type": "Feature",
      "geometry": {
        "type": "LineString",
        "coordinates": [[0, 0], [10, 10]]
      },
      "properties": { "type": "route" }
    }
  ]
}

Значение структуры для пространственных алгоритмов

Чёткое разделение:

  • геометрии (geometry)
  • атрибутов (properties)
  • контейнера (FeatureCollection)

обеспечивает:

  • унификацию входных данных
  • совместимость алгоритмов
  • масштабируемость обработки
  • предсказуемость результатов Turf.js
Оглавление