FeatureCollection и геометрия

В основе работы с пространственными данными в Mapbox GL JS лежит формат GeoJSON. Он определяет стандартизированную структуру для описания географических объектов и их свойств. Центральным контейнером для большинства наборов данных выступает FeatureCollection.

FeatureCollection — это объект верхнего уровня, объединяющий множество геометрических сущностей (Feature) в единый набор данных, который может быть передан в источник (source) карты.

Базовая структура:

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

Каждый элемент массива features представляет собой объект Feature, включающий геометрию и свойства.

Структура Feature и связь с геометрией

Feature в GeoJSON связывает три ключевых компонента:

  • type: всегда "Feature"
  • geometry: описание геометрии объекта
  • properties: пользовательские данные, связанные с объектом

Пример:

{
  "type": "Feature",
  "geometry": {
    "type": "Point",
    "coordinates": [90.0, 55.0]
  },
  "properties": {
    "name": "Точка интереса",
    "category": "landmark"
  }
}

Связь FeatureCollection и Feature

FeatureCollection агрегирует множество Feature, позволяя Mapbox GL JS работать с ними как с единым источником данных:

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [90.0, 55.0]
      },
      "properties": {
        "id": 1
      }
    },
    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [91.0, 56.0]
      },
      "properties": {
        "id": 2
      }
    }
  ]
}

Геометрические типы GeoJSON

В Mapbox GL JS поддерживаются все стандартные типы геометрий GeoJSON. Каждая геометрия определяет форму объекта на карте.

Point

Одиночная точка на карте.

{
  "type": "Point",
  "coordinates": [longitude, latitude]
}

Используется для маркеров, объектов интереса, событий.

LineString

Ломаная линия, состоящая из последовательности координат.

{
  "type": "LineString",
  "coordinates": [
    [lng1, lat1],
    [lng2, lat2],
    [lng3, lat3]
  ]
}

Применяется для маршрутов, дорог, траекторий движения.

Polygon

Многоугольник, описывающий замкнутую область.

{
  "type": "Polygon",
  "coordinates": [
    [
      [lng1, lat1],
      [lng2, lat2],
      [lng3, lat3],
      [lng1, lat1]
    ]
  ]
}

Первый и последний координатный элемент должны совпадать, формируя замкнутый контур.

MultiPoint

Набор точек как единый объект.

{
  "type": "MultiPoint",
  "coordinates": [
    [lng1, lat1],
    [lng2, lat2]
  ]
}

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

MultiLineString

Набор линий.

{
  "type": "MultiLineString",
  "coordinates": [
    [
      [lng1, lat1],
      [lng2, lat2]
    ],
    [
      [lng3, lat3],
      [lng4, lat4]
    ]
  ]
}

Применяется для разветвлённых маршрутов или сетей.

MultiPolygon

Набор полигонов.

{
  "type": "MultiPolygon",
  "coordinates": [
    [
      [
        [lng1, lat1],
        [lng2, lat2],
        [lng3, lat3],
        [lng1, lat1]
      ]
    ],
    [
      [
        [lng4, lat4],
        [lng5, lat5],
        [lng6, lat6],
        [lng4, lat4]
      ]
    ]
  ]
}

Используется для регионов с несколькими отдельными зонами.

GeometryCollection

Коллекция различных геометрий внутри одного объекта.

{
  "type": "GeometryCollection",
  "geometries": [
    {
      "type": "Point",
      "coordinates": [90.0, 55.0]
    },
    {
      "type": "LineString",
      "coordinates": [
        [90.0, 55.0],
        [91.0, 56.0]
      ]
    }
  ]
}

Использование FeatureCollection в источниках Mapbox GL JS

В Mapbox GL JS GeoJSON передаётся через источник типа geojson.

map.on('load', () => {
  map.addSource('points-source', {
    type: 'geojson',
    data: {
      type: 'FeatureCollection',
      features: [
        {
          type: 'Feature',
          geometry: {
            type: 'Point',
            coordinates: [90.0, 55.0]
          },
          properties: {
            title: 'Объект 1'
          }
        }
      ]
    }
  });

  map.addLayer({
    id: 'points-layer',
    type: 'circle',
    source: 'points-source',
    paint: {
      'circle-radius': 6,
      'circle-color': '#ff0000'
    }
  });
});

Обновление FeatureCollection в реальном времени

GeoJSON-источник можно динамически обновлять через setData. Это ключевой механизм для интерактивных приложений.

const source = map.getSource('points-source');

source.setData({
  type: 'FeatureCollection',
  features: [
    {
      type: 'Feature',
      geometry: {
        type: 'Point',
        coordinates: [92.0, 56.0]
      },
      properties: {
        title: 'Обновлённый объект'
      }
    }
  ]
});

При вызове setData Mapbox пересчитывает отображение слоя без необходимости пересоздания источника.

Свойства properties и их роль в визуализации

properties внутри Feature не влияют на геометрию, но активно используются в стилях слоёв:

{
  "type": "Feature",
  "geometry": {
    "type": "Point",
    "coordinates": [90.0, 55.0]
  },
  "properties": {
    "population": 120000,
    "category": "city"
  }
}

Использование в стиле слоя:

map.addLayer({
  id: 'cities',
  type: 'circle',
  source: 'cities-source',
  paint: {
    'circle-radius': [
      'interpolate',
      ['linear'],
      ['get', 'population'],
      1000, 4,
      1000000, 12
    ],
    'circle-color': [
      'match',
      ['get', 'category'],
      'city', '#1f78b4',
      'town', '#33a02c',
      '#999999'
    ]
  }
});

Вложенные структуры и ограничения FeatureCollection

FeatureCollection должен сохранять строгую структуру:

  • только массив features
  • каждый элемент должен быть валидным Feature
  • геометрия обязана соответствовать стандарту GeoJSON
  • координаты всегда в формате [longitude, latitude]

Частые ошибки:

  • перепутанный порядок координат
  • отсутствие замыкания полигона
  • использование нестандартных типов геометрий
  • вложение FeatureCollection в geometry (недопустимо)

Производительность при больших FeatureCollection

При работе с большими наборами данных в Mapbox GL JS критичны:

  • количество Feature в одном источнике
  • сложность геометрий (особенно Polygon)
  • частота вызова setData

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

  • упрощение геометрии (simplification)
  • кластеризация точек через cluster: true
  • разделение данных на несколько источников
  • использование vector tiles вместо GeoJSON при больших объёмах

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

map.addSource('earthquakes', {
  type: 'geojson',
  data: '/data/earthquakes.geojson',
  cluster: true,
  clusterMaxZoom: 14,
  clusterRadius: 50
});

Геометрия как основа визуальной модели карты

Геометрия в FeatureCollection определяет не только форму объектов, но и способ их рендеринга:

  • Point → символы, круги, иконки
  • LineString → линии, маршруты, дороги
  • Polygon → заливки, границы территорий
  • коллекции → комбинированные слои

Связка геометрии и стиля слоя в Mapbox GL JS является декларативной: геометрия описывает структуру, слой — визуальное поведение.

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

Все координаты GeoJSON используют WGS84:

  • долгота (longitude) — ось X
  • широта (latitude) — ось Y
[longitude, latitude]

Нарушение этого порядка приводит к смещению объектов на тысячи километров или их исчезновению из видимой области карты.

Связь FeatureCollection с интерактивностью

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

map.on('click', 'points-layer', (e) => {
  const feature = e.features[0];

  console.log(feature.properties.title);
});

Каждый Feature становится интерактивным объектом, доступным через события click, mouseenter, mouseleave.

Динамическая генерация FeatureCollection

FeatureCollection часто формируется программно:

const points = [];

for (let i = 0; i < 100; i++) {
  points.push({
    type: 'Feature',
    geometry: {
      type: 'Point',
      coordinates: [
        90 + Math.random(),
        55 + Math.random()
      ]
    },
    properties: {
      id: i
    }
  });
}

const featureCollection = {
  type: 'FeatureCollection',
  features: points
};

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

Оглавление