Трансформация graticule

Трансформация graticule в Vega и Vega-Lite предназначена для генерации координатной сетки географических линий: меридианов и параллелей. Такие линии часто используются при визуализации карт, особенно в сочетании с географическими проекциями (projection) и геометрическими объектами (geoshape).

graticule создаёт GeoJSON-объекты автоматически, без необходимости загружать внешние данные. Это особенно удобно при построении:

карт мира;
тематических географических визуализаций;
астрономических схем;
глобусов;
проекционных сеток;
обучающих географических диаграмм.

Трансформация генерирует объект типа MultiLineString, содержащий набор координатных линий.

Базовая структура `graticule`

Минимальная конфигурация выглядит следующим образом:

{
  "data": {
    "graticule": true
  },
  "mark": "geoshape"
}

В Vega-Lite трансформация обычно располагается внутри блока data.

Пример:

{
  "$schema": "https://vega.github.io/schema/vega-lite/v5.json",

  "width": 600,
  "height": 300,

  "projection": {
    "type": "equalEarth"
  },

  "data": {
    "graticule": true
  },

  "mark": {
    "type": "geoshape",
    "stroke": "#888",
    "strokeWidth": 1,
    "fill": null
  }
}

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

Взаимодействие с `projection`

Трансформация graticule почти всегда используется совместно с географическими проекциями.

Пример:

"projection": {
  "type": "mercator"
}

Или:

"projection": {
  "type": "orthographic"
}

Без проекции координаты долготы и широты не смогут корректно отображаться на плоскости.

Наиболее популярные типы проекций:

Проекция	Особенности
`mercator`	Классическая цилиндрическая проекция
`equalEarth`	Равновеликая карта мира
`orthographic`	Эффект глобуса
`naturalEarth1`	Сглаженная мировая карта
`albers`	Часто используется для США
`azimuthalEqualArea`	Азимутальная проекция

Отрисовка глобуса с координатной сеткой

Один из самых распространённых сценариев — создание глобуса.

{
  "$schema": "https://vega.github.io/schema/vega-lite/v5.json",

  "width": 500,
  "height": 500,

  "projection": {
    "type": "orthographic"
  },

  "layer": [
    {
      "data": {
        "sphere": true
      },

      "mark": {
        "type": "geoshape",
        "fill": "#dbefff",
        "stroke": "#000"
      }
    },

    {
      "data": {
        "graticule": true
      },

      "mark": {
        "type": "geoshape",
        "stroke": "#999",
        "strokeWidth": 0.5
      }
    }
  ]
}

Здесь используются два слоя:

sphere — геометрия земного шара.
graticule — координатная сетка.

Настройка шага линий

По умолчанию Vega использует стандартный шаг между меридианами и параллелями. Однако сетку можно настраивать более точно.

Свойство `step`

Определяет расстояние между линиями.

{
  "data": {
    "graticule": {
      "step": [10, 10]
    }
  }
}

Первое значение:

шаг по долготе.

Второе:

шаг по широте.

В данном случае линии будут проводиться через каждые 10 градусов.

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

graticule поддерживает два уровня детализации:

основные линии;
второстепенные линии.

`stepMajor`

Шаг главных линий.

{
  "graticule": {
    "stepMajor": [90, 45]
  }
}

`stepMinor`

Шаг второстепенных линий.

{
  "graticule": {
    "stepMinor": [10, 10]
  }
}

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

Управление диапазоном координат

Свойство `extent`

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

{
  "graticule": {
    "extent": [
      [-180, -80],
      [180, 80]
    ]
  }
}

Формат:

[
  [minLongitude, minLatitude],
  [maxLongitude, maxLatitude]
]

Раздельное управление долготой и широтой

`extentMajor`

Определяет диапазон для основных линий.

{
  "graticule": {
    "extentMajor": [
      [-180, -90],
      [180, 90]
    ]
  }
}

`extentMinor`

Определяет диапазон второстепенной сетки.

{
  "graticule": {
    "extentMinor": [
      [-180, -80],
      [180, 80]
    ]
  }
}

Стилизация сетки

Поскольку graticule обычно визуализируется через geoshape, доступны все стандартные параметры оформления.

Цвет линий

"mark": {
  "type": "geoshape",
  "stroke": "#666"
}

Толщина линий

"mark": {
  "strokeWidth": 0.8
}

Пунктирные линии

"mark": {
  "strokeDash": [4, 2]
}

Прозрачность

"mark": {
  "opacity": 0.4
}

Создание тонкой координатной сетки

{
  "$schema": "https://vega.github.io/schema/vega-lite/v5.json",

  "width": 700,
  "height": 350,

  "projection": {
    "type": "naturalEarth1"
  },

  "data": {
    "graticule": {
      "step": [5, 5]
    }
  },

  "mark": {
    "type": "geoshape",
    "stroke": "#d0d0d0",
    "strokeWidth": 0.5
  }
}

Шаг 5 градусов создаёт детализированную географическую сетку.

Совмещение `graticule` и GeoJSON-карт

На практике graticule почти всегда комбинируется с географическими данными.

Пример с картой мира:

{
  "layer": [
    {
      "data": {
        "graticule": true
      },

      "mark": {
        "type": "geoshape",
        "stroke": "#ccc"
      }
    },

    {
      "data": {
        "url": "world-110m.json",
        "format": {
          "type": "topojson",
          "feature": "countries"
        }
      },

      "mark": {
        "type": "geoshape",
        "fill": "#4c78a8",
        "stroke": "#fff"
      }
    }
  ]
}

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

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

Использование `graticule` в Vega

В чистом Vega синтаксис более гибкий.

Пример:

{
  "$schema": "https://vega.github.io/schema/vega/v5.json",

  "width": 600,
  "height": 300,

  "projections": [
    {
      "name": "projection",
      "type": "mercator"
    }
  ],

  "data": [
    {
      "name": "grid",
      "transform": [
        {
          "type": "graticule",
          "step": [15, 15]
        }
      ]
    }
  ],

  "marks": [
    {
      "type": "shape",

      "from": {
        "data": "grid"
      },

      "transform": [
        {
          "type": "geoshape",
          "projection": "projection"
        }
      ],

      "encode": {
        "update": {
          "stroke": {
            "value": "#999"
          },

          "strokeWidth": {
            "value": 1
          },

          "fill": {
            "value": null
          }
        }
      }
    }
  ]
}

Отличие Vega от Vega-Lite

Vega-Lite

более декларативный подход;
меньше кода;
упрощённая настройка;
автоматическая генерация геометрии.

Vega

полный контроль над трансформациями;
сложные композиции;
кастомные пайплайны обработки;
более тонкая работа с проекциями.

Использование `graticule` как источника данных

graticule создаёт полноценный географический объект, который можно использовать далее в трансформациях.

Например:

{
  "data": [
    {
      "name": "grid",

      "transform": [
        {
          "type": "graticule"
        }
      ]
    }
  ]
}

Полученные данные затем могут:

фильтроваться;
модифицироваться;
объединяться с другими источниками;
использоваться в слоях;
участвовать в анимациях.

Производительность

graticule генерируется динамически, поэтому при слишком маленьком шаге возможно увеличение нагрузки на рендеринг.

Потенциально проблемные значения:

"step": [1, 1]

или:

"stepMinor": [0.5, 0.5]

Такие параметры создают огромное количество сегментов линий.

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

Тип карты	Рекомендуемый шаг
Общая карта мира	10–20
Детализированная карта	5
Глобус	15
Анимации	20–30

Комбинация с интерактивностью

graticule можно использовать совместно с:

масштабированием;
вращением глобуса;
drag/pan;
анимацией проекции;
параметрами signal в Vega.

Пример вращающегося глобуса в Vega:

{
  "signals": [
    {
      "name": "rotate",
      "value": 0,

      "on": [
        {
          "events": {
            "type": "timer",
            "throttle": 50
          },

          "update": "rotate + 1"
        }
      ]
    }
  ]
}

Далее значение rotate связывается с параметром проекции.

Практический пример: атмосферная карта

{
  "$schema": "https://vega.github.io/schema/vega-lite/v5.json",

  "width": 800,
  "height": 450,

  "projection": {
    "type": "equalEarth"
  },

  "layer": [
    {
      "data": {
        "sphere": true
      },

      "mark": {
        "type": "geoshape",
        "fill": "#071b2d"
      }
    },

    {
      "data": {
        "graticule": {
          "step": [10, 10]
        }
      },

      "mark": {
        "type": "geoshape",
        "stroke": "#1d4e89",
        "strokeWidth": 0.7,
        "opacity": 0.7
      }
    }
  ]
}

Такой стиль часто используется в:

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

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

Отсутствие `projection`

Ошибка:

"data": {
  "graticule": true
}

без:

"projection"

Результат:

линии не отображаются;
геометрия строится некорректно.

Использование обычного `mark`

Неверно:

"mark": "line"

Правильно:

"mark": "geoshape"

graticule генерирует географическую геометрию, а не обычные Cartesian-координаты.

Слишком маленький шаг

"step": [1, 1]

Может привести к:

падению FPS;
долгому рендерингу;
высокой нагрузке на браузер.

Полезные комбинации

`graticule` + `sphere`

Создание глобуса.

`graticule` + `topojson`

Отрисовка карт государств.

`graticule` + `lookup`

Связывание геометрии с табличными данными.

`graticule` + `signal`

Интерактивные географические интерфейсы.

Архитектурная роль `graticule`

Трансформация занимает особое место в географическом стеке Vega:

graticule
    ↓
projection
    ↓
geoshape
    ↓
rendering

Этапы обработки:

Генерация географической сетки.
Преобразование координат проекцией.
Конвертация геометрии в экранные пути.
Рендеринг SVG или Canvas.

Когда использовать `graticule`

Трансформация особенно полезна в следующих случаях:

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

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

Параметр	Назначение
`step`	Общий шаг линий
`stepMajor`	Шаг основных линий
`stepMinor`	Шаг вспомогательных линий
`extent`	Общая область
`extentMajor`	Область основных линий
`extentMinor`	Область второстепенных линий
`precision`	Точность генерации сегментов

Параметр `precision`

Определяет детализацию кривых.

Пример:

{
  "graticule": {
    "precision": 2.5
  }
}

Меньшие значения:

увеличивают точность;
создают больше сегментов.

Большие значения:

уменьшают детализацию;
повышают производительность.

Внутренний формат данных

graticule генерирует GeoJSON-подобную структуру:

{
  "type": "MultiLineString",
  "coordinates": [...]
}

Это делает трансформацию совместимой со всей географической экосистемой Vega и D3 Geo.

Связь с D3 Geo

Внутренне Vega использует механизмы D3 Geo, поэтому поведение graticule близко к:

d3.geoGraticule()

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

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

Типичные сценарии использования

Научные визуализации

климат;
океанография;
метеорология;
геофизика.

Образовательные карты

география;
астрономия;
навигация.

Аналитические панели

международная статистика;
транспорт;
авиация;
спутниковые системы.

Дизайнерские интерфейсы

фоновые карты;
декоративные глобусы;
футуристические панели управления.

Трансформация graticule

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

Взаимодействие с projection

Отрисовка глобуса с координатной сеткой

Настройка шага линий

Свойство step

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

stepMajor

stepMinor

Управление диапазоном координат

Свойство extent

Раздельное управление долготой и широтой

extentMajor

extentMinor

Стилизация сетки

Цвет линий

Толщина линий

Пунктирные линии

Прозрачность

Создание тонкой координатной сетки

Совмещение graticule и GeoJSON-карт

Использование graticule в Vega

Отличие Vega от Vega-Lite

Vega-Lite

Vega

Использование graticule как источника данных

Производительность

Комбинация с интерактивностью

Практический пример: атмосферная карта

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

Отсутствие projection

Использование обычного mark

Слишком маленький шаг

Полезные комбинации

graticule + sphere

graticule + topojson

graticule + lookup

graticule + signal

Архитектурная роль graticule

Когда использовать graticule

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

Параметр precision

Внутренний формат данных

Связь с D3 Geo

Типичные сценарии использования

Научные визуализации

Образовательные карты

Аналитические панели

Дизайнерские интерфейсы

Базовая структура `graticule`

Взаимодействие с `projection`

Свойство `step`

`stepMajor`

`stepMinor`

Свойство `extent`

`extentMajor`

`extentMinor`

Совмещение `graticule` и GeoJSON-карт

Использование `graticule` в Vega

Использование `graticule` как источника данных

Отсутствие `projection`

Использование обычного `mark`

`graticule` + `sphere`

`graticule` + `topojson`

`graticule` + `lookup`

`graticule` + `signal`

Архитектурная роль `graticule`

Когда использовать `graticule`

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

Параметр `precision`