Формат MapData

MapData — внутренний формат карты проекта. В этом формате редактор сохраняет карты, в нём же они передаются вычислительной ноде, и его же вы получаете при скачивании map_data.arp.

Для кого этот раздел

Пользователям сервиса работать с MapData напрямую не нужно — всё происходит через редактор. Этот раздел пригодится интеграторам, разработчикам плагинов и тем, кто хочет программно генерировать или обрабатывать карты.

Верхний уровень

{
  "crs": { ... },
  "params": { ... },
  "geometry": { ... }
}

Поле	Обязательное	Описание
crs	Да	Система координат карты
params	Только для X_Y	Параметры подложки и масштаб
geometry	Да	GeoJSON FeatureCollection со всеми объектами карты

---

crs — система координат

X_Y (прямоугольная)

Используется по умолчанию при создании нового проекта. Координаты — пиксельные, относительно подложки.

{
  "crs": {
    "type": "X_Y",
    "distanceUnit": { "ratio": 1.0 }
  }
}

Координаты объектов находятся в диапазоне [0, 1000] по оси X и [0, projHeight] по оси Y, где:

projHeight = (params.height / params.width) × 1000

Ось Y растёт вверх — как в Leaflet, но противоположно растровому изображению на экране.

LAT_LONG (географическая)

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

{
  "crs": {
    "type": "LAT_LONG"
  }
}

Координаты — стандартные для GeoJSON: [longitude, latitude] в WGS 84.

---

params — параметры подложки (только X_Y)

{
  "params": {
    "background": "data:image/png;base64,...",
    "width": 1920,
    "height": 1080,
    "widthInMeters": 200
  }
}

Поле	Тип	Описание
background	string	Base64-изображение подложки (PNG/JPG) с data-URI-префиксом или без
width	number	Ширина исходного изображения в пикселях
height	number	Высота исходного изображения в пикселях
widthInMeters	number	Реальная ширина участка в метрах (то самое значение из диалога создания проекта)

---

geometry — объекты карты

Стандартный GeoJSON FeatureCollection. Каждый объект определяется типом в properties.type и, опционально, подтипами.

{
  "geometry": {
    "type": "FeatureCollection",
    "features": [
      {
        "type": "Feature",
        "geometry": { "type": "Polygon", "coordinates": [...] },
        "properties": { "type": "border" }
      }
    ]
  }
}

Типы объектов

Основной дискриминатор — поле properties.type.

properties.type	Геометрия	Описание
border	Polygon	Граница участка моделирования
generator	Point / Polygon	Источник, сток или двусторонняя точка притяжения
walkway	Polygon	Существующая дорожка или результирующая сеть
service_road	Polygon	Служебная дорога / площадка (как walkway)
obstacle	Polygon	Непроходимое препятствие
passable_obstacle	Polygon / LineString	Препятствие, проходимое со штрафом
barrier	Polygon / LineString	Непреодолимый барьер (высокий забор)

---

generator — точки притяжения

Для объектов типа generator дополнительно указываются подтипы:

{
  "type": "Feature",
  "geometry": { "type": "Point", "coordinates": [100, 200] },
  "properties": {
    "type": "generator",
    "generator_type": "SOURCE",
    "generator_subtype": "ENTRANCE"
  }
}

generator_type

Значение	Роль
SOURCE	Источник — отсюда выходят пешеходы
SINK	Сток — сюда направляются пешеходы
BOTH	Двусторонний объект (и источник, и сток)

Когда рассчитывается маршрут для пешехода, выбирается случайный генератор, который может служить истоком (SOURCE или BOTH), затем случайный генератор, который может служить стоком (SINK или BOTH), и между ними строится маршрут.

Такое разделение на типы позволяет задавать базовые ограничения на логику движения. Например, генераторы создаваемые кнопкой Подъезд в редакторе являются SOURCE. Это значит, что между двумя подъездами пешеходы ходить не будут. А будут, например, между подъездом (SOURCE) и магазином (BOTH). Или между двумя магазинами (оба имеют тип BOTH)

generator_subtype

Семантический подтип, отвечающий инструментам редактора:

Подтип	Инструмент редактора	Геометрия	generator_type
ENTRANCE	Подъезд	Point	SOURCE
PARKING	Парковка	Polygon	SINK
BUS_STOP	Остановка	Polygon	BOTH
SHOP	Магазин (вход)	Point	BOTH
OFFICE	Офис (вход)	Point	BOTH
PLAYGROUND	Площадка	Polygon	BOTH
EXIT	Выход с терр.	Polygon	BOTH
CUSTOM_AREA	Иной полигон	Polygon	BOTH
CUSTOM_POINT	Иная точка	Point	BOTH

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

spawn_type

Для полигональных генераторов указывается:

"spawn_type": "AREA"

Это значит, что пешеходы появляются/исчезают не в одной точке, а распределённо по всей площади полигона.

Полигональные генераторы — не обычные полигоны

Для некоторых инструментов редактор создаёт сразу два объекта: сам генератор и полигон с твёрдым покрытием той же геометрии — чтобы область была покрыта твёрдым покрытием и одновременно служила целью движения. Для Парковки это полигон service_road, для Площадки — walkway.

---

obstacle и passable_obstacle

Препятствия различаются проходимостью:

• obstacle — полностью непроходимо (пешеходы обходят)
• passable_obstacle — проходимо со штрафом (пересекают, если нет удобного обхода)

obstacle_type

Дополнительное уточнение типа:

Значение	Инструмент	Тип
building	Здание	obstacle
WATER	Вода	obstacle
(без значения)	Препятствие	obstacle
PLANTS	Растительность	passable_obstacle
PASSABLE_FENCE	Пр. забор	passable_obstacle (LineString)
ROAD	Проезжая часть	passable_obstacle

---

walkway, service_road, border, barrier

Эти типы не имеют подтипов:

{ "properties": { "type": "border" } }
{ "properties": { "type": "walkway" } }
{ "properties": { "type": "service_road" } }
{ "properties": { "type": "barrier" } }

• border — полигон-граница участка;
• walkway — существующие дорожки или результат расчёта (в выходных файлах).
• service_road — дворовой проезд или площадка с твёрдым покрытием (проезды, парковочные карманы). Для алгоритма генерации дорог эквивалентна walkway; выделена отдельным типом для удобства разметки и экспорта в CAD.
• barrier — высокий забор или стена; пешеходы его не преодолевают.

Задавать границу участка не обязательно, но в таком случае вся область за пределами нарисованных объектов считается пустой и проходимой. Пешеходы смогут обходить препятствия, выходя на это пустое пространство.

---

Полный пример

Минимальная карта с границей, подъездом и выходом:

{
  "crs": {
    "type": "X_Y",
    "distanceUnit": { "ratio": 1.0 }
  },
  "params": {
    "background": "",
    "width": 1000,
    "height": 600,
    "widthInMeters": 200
  },
  "geometry": {
    "type": "FeatureCollection",
    "features": [
      {
        "type": "Feature",
        "geometry": {
          "type": "Polygon",
          "coordinates": [[[0, 0], [1000, 0], [1000, 600], [0, 600], [0, 0]]]
        },
        "properties": { "type": "border" }
      },
      {
        "type": "Feature",
        "geometry": { "type": "Point", "coordinates": [100, 300] },
        "properties": {
          "type": "generator",
          "generator_type": "SOURCE",
          "generator_subtype": "ENTRANCE"
        }
      },
      {
        "type": "Feature",
        "geometry": {
          "type": "Polygon",
          "coordinates": [[[900, 250], [990, 250], [990, 350], [900, 350], [900, 250]]]
        },
        "properties": {
          "type": "generator",
          "generator_type": "BOTH",
          "generator_subtype": "EXIT",
          "spawn_type": "AREA"
        }
      },
      {
        "type": "Feature",
        "geometry": {
          "type": "Polygon",
          "coordinates": [[[400, 200], [600, 200], [600, 400], [400, 400], [400, 200]]]
        },
        "properties": { "type": "obstacle", "obstacle_type": "building" }
      }
    ]
  }
}

---

Программный доступ через API

Исходные данные проекта доступны как файл через REST API:

GET /api/v1/projects/{projectId}/files
Authorization: Bearer <jwt>

Среди возвращённых файлов тот, у которого fileType=arp, содержит сериализованный MapData. Скачать сам файл:

GET /api/v1/projects/{projectId}/files/{fileId}/download
Authorization: Bearer <jwt>

Полная спецификация API доступна в Swagger UI: https://app.antroadplanner.com/swagger-ui.html.