https://github.com/2gis/general
Fast marker generalization algorithm
https://github.com/2gis/general
javascript webmaps
Last synced: 11 months ago
JSON representation
Fast marker generalization algorithm
- Host: GitHub
- URL: https://github.com/2gis/general
- Owner: 2gis
- License: bsd-2-clause
- Created: 2017-03-29T09:42:16.000Z (almost 9 years ago)
- Default Branch: master
- Last Pushed: 2020-02-12T05:44:27.000Z (about 6 years ago)
- Last Synced: 2025-04-13T02:07:50.412Z (11 months ago)
- Topics: javascript, webmaps
- Language: TypeScript
- Homepage: https://2gis.github.io/general/
- Size: 1.38 MB
- Stars: 8
- Watchers: 20
- Forks: 3
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# General [](https://travis-ci.org/2gis/general)
Fast marker generalization algorithm
[Demo](https://2gis.github.io/general/)
## Содержание
- [Общий принцип работы](#Общий-принцип-работы)
- [Установка](#Установка)
- [Использование](#Использование)
- [Релиз](#Релиз)
## Общий принцип работы ##
На вход алгоритму генерализации маркеров передается большой список маркеров. Алгоритм во время работы откидывает какое-то количество маркеров из этого списка так, чтобы оставшиеся отобразились на карте не пересекаясь друг с другом.
\
_Пример отображения маркеров на карте до и после генерализации_
Считается, что список маркеров отсортирован в порядке убывания приоритета. Маркера идущие впереди списка имеет больше шансов отобразиться на карте.
Можно отображать разные группы маркеров на карте одновременно, например:
- С коронкой
- Обычный
- Точка
Каждая группа имеет собственные настройки того, как она будет обрабатываться алгоритмом.
Пример настроек:
```js
{
safeZone: 5,
margin: 10,
degradation: 180
}
```
Изначально каждый из маркеров привязан к какой-то конкретной группе. Группы идут по порядку. Если маркер из первой группы не смог разместиться на карте, он попробует это сделать уже в рамках менее приоритетной _(второй)_ группы. Если и там он не смог появиться на карте, то он перейдет в следующую _(третью)_ группу и т.д.
Каждый маркер для алгоритма генерализации представляется прямоугольной областью размерами равными размерам иконки маркера плюс один из вышеперечисленных параметров.
### safeZone ###
Перед вставкой на карту маркер проверяется на пересечение с другими, уже попавшими маркерами на карту. Для этой проверки берется область вокруг маркера равная его размеру плюс параметру `safeZone`.
Маркер A уже встал на карту и занял область равную своему размеру, но:
- В первом случае маркер B успешно попадает на карту, т.к. параметр safeZone равен 40, и проверяемая область (красный квадрат) не пересекает область маркера A.
- Во втором случае safeZone равен 80, проверяемая область пересекает маркер A, и B вынужден сменить группу на менее приоритетную (точка), в которой safeZone равен 0.
Таким образом можно регулировать плотность одинаковых групп маркеров на карте, так чтобы они не кучковались, а распределялись равномерно.
### margin ###
Когда маркер попадает на карту, он занимает уже другую область не связанную с той, которая использовалась при проверке. Размеры этой области равны размерам иконки маркера плюс параметр `margin`.
Это параметр можно использовать, чтобы освободить зону на карте вокруг одного маркера от любых других:
\
_Слева параметр margin равен 0, справа – 40_
### degradation ###
Маркер, попавший в область заданную параметром `degradation` маркера из более приоритетной группы, автоматически переходят на одну группу ниже, вне зависимости от свободного места. Если группа была последней, то маркер пропадает.
Таким образом можно выделить одни маркера, не уничтожая других полностью:
\
_Слева параметр degradation равен 0, справа - 40_
## Установка ##
С помощью `npm`:
```bash
npm install @2gis/general
```
Можно подключить через `script` использовать через глобальную переменную `General`:
```html
```
Либо подключить как es6 модуль:
```js
import { General } from 'general';
```
## Использование ##
Для работы нужно создать экземпляр класса:
```js
const general = new General();
```
Основной метод для генерализации:
```js
general.generalize(bounds, groups, atlas, markers);
```
где
- `bounds: BBox` – границы, в которых происходит генерализация, маркера не попавшие в эти границы просто откидываются
- `groups: PriorityGroup[]` – массив групп маркеров с настройками для генерализации
- `atlas: Sprite[]` – массив объектов описывающих размеры иконок, которые могут использоваться маркерами
- `markers: Marker[]` – массив маркеров
Метод возвращает `Promise`, который резолвится после выполнения генерализации. Алгоритм выполняется асинхронно в воркере.
Каждая из групп `PriorityGroup` содержит следующие параметры:
- `iconIndex` – индекс иконки в атласе, которая будет установлена маркеру, попавшему в эту группу
- `safeZone`, `margin`, `degradation` – описывались выше
Атлас описывается массивом из `Sprite`, каждый из которых состоит из:
- `size: Vec2` – размер иконки
- `anchor: Vec2` – центр иконки относительно ее размеров, принимает значения от 0 до 1
Каждый `Marker` состоит из:
- `pixelPosition` – позиция маркера в пикселях, должна вычисляться вне алгоритма генерализации и находиться в той же системе координат, что и `bounds` переданные в метод `generalize`
- `groupIndex` – индекс в массиве групп, к которой маркер будет изначально принадлежать
Метод `generalize` **не возвращает** новый массив маркеров, он мутирует старый.
В процессе генерализации, алгоритм выставляет маркерам параметр `iconIndex` соответсвующий какой-то иконке в атласе. Если этот параметр стал равным `-1`, значит, что маркер не должен попасть на карту и его надо скрыть.
## Релиз ##
1. `npm version patch` – обновить версию в `package.json`
2. `git push --follow-tags` – запушить изменения на github
3. `rm -rf dist && npm run build` – собрать проект
4. `npm publish` – отправить в npm