Статичные слои (PMTiles)

Запечённый слой карта берёт из готового файла, а не строит каждый тайл запросом к базе: здания города показываются быстрее, а база меньше нагружена.

Возможности

• Видно, какие слои базы города можно запечь, какие уже запечены и с какими зумами, сколько в архиве тайлов, какой он по размеру и когда собран.
• «Запечь» и «Пересобрать» ставят сборку в очередь; ход виден в карточке слоя, окно можно не держать открытым.
• «До зума» — верхний уровень архива (от нижнего уровня слоя до 18, по умолчанию 16).
• «Удалить» убирает архив: слой снова строится из базы.

Как это работает

Какие слои можно запечь. Только слои без параметров — здания и другие слои, тайл которых одинаков для всех. Слои сети (участки, узлы) зависят от выбранных фрагментов и подписей, их запечь нельзя. Список строит сервер по функциям тайлов martin в базе города (tgid_mvt_<слой>), нижний зум берётся из описания функции («виден с зума N»).

Как идёт сборка. Воркер обходит тайлы от нижнего уровня слоя вниз — только там, где есть объекты слоя или узлы сети города (клетки зума 12 вокруг них); у пустого тайла дочерние не строятся. Тайлы строятся в четыре потока той же функцией, что отдаёт martin, сжимаются gzip, одинаковые хранятся один раз. Предел — 200 000 тайлов: больше — сборка останавливается с ошибкой «Больше 200000 тайлов — уменьшите верхний зум». Новый архив пишется во временный файл и заменяет старый целиком, поэтому карта никогда не читает полусобранный.

Как карта его использует. При загрузке слоёв карта спрашивает список архивов и у слоя с тем же именем в рабочей области базы города подменяет адрес тайлов на API. Ниже нижнего зума архива слой не показывается, крупнее верхнего — растягиваются тайлы последнего уровня. В адресе тайла есть версия архива: после пересборки браузер берёт новые тайлы, а не старые из кеша (тайлы кешируются на 7 дней). Уже открытые вкладки увидят новый архив после обновления страницы.

Устаревание. Архив не следит за базой. После правки зданий — в вебе, десктопе или загрузкой — нажмите «Пересобрать», иначе карта покажет прежние контуры.

Что нужно для работы

• Права: роль «Администратор» — запечь, пересобрать, удалить. Сами тайлы архива берёт с сервера любая вошедшая вкладка.
• База: функции тайлов martin в базе города. Их создаёт API при подготовке базы города; без них — «В базе города нет слоёв, которые можно запечь».
• Сервер: работающий воркер Celery — сборка идёт задачей в очереди. API и воркер должны видеть один каталог архивов.

Шаги

1. Откройте «Инструменты» и наберите в поиске «Статичные слои (PMTiles)» — пункт выделен рамкой.

   

2. Нажмите пункт — откроется окно.

   

Примеры

Здания Алматы. На копии Алматы (almatygid_copy) запечены два слоя зданий, оба — зумы 14–16:

Слой	Тайлов	Архив
zdaniya_2	3 120	21 МБ
zdaniya_tu	1 360	1,1 МБ

По замерам разработчиков на той же копии zdaniya_2 (187 тыс. контуров) запекается около 48 секунд, тайл из архива отдаётся за 7–10 мс, а тот же тайл из базы — от 50 мс до 0,4 с.

Нужно видеть отдельные дома на крупном масштабе. Поднимите «До зума» до 17 и нажмите «Пересобрать». Каждый лишний уровень даёт примерно вчетверо больше тайлов — следите за размером архива.

Если не получается

• «В базе города нет слоёв, которые можно запечь» — нет функций тайлов martin для слоёв без параметров (зданий); их создаёт API при подготовке базы города.
• «Больше 200000 тайлов — уменьшите верхний зум» — сборка остановлена: уровней слишком много для охвата слоя.
• Карта показывает старые здания — архив собран до правки; нажмите «Пересобрать» и обновите страницу.
• Сборка висит в очереди — не запущен воркер Celery или он слушает другую очередь (STATIC_TILES_QUEUE).
• «Архив слоя повреждён — пересоберите его» — сервер не смог прочитать файл архива.

Для администратора

• Архивы лежат в STATIC_TILES_DIR (по умолчанию files/static_tiles в каталоге API), внутри — каталог города: almaty/zdaniya_2.pmtiles. Удаление файла вручную равносильно «Удалить».
• STATIC_TILES_QUEUE — очередь задачи сборки (по умолчанию основная; в API на несколько городов — очередь города).
• Архив целиком можно скачать (/api/v1/static-tiles/<слой>.pmtiles, с поддержкой Range) — например, для работы без связи.

Для разработчика

• API: GET /api/v1/static-tiles (архивы и слои для сборки, can_build), POST /api/v1/static-tiles/{слой}/build {maxzoom, minzoom?} (ход — GET /api/v1/task/{id}), DELETE /api/v1/static-tiles/{слой}, GET /api/v1/static-tiles/{слой}/{z}/{x}/{y}.mvt?v=<версия> (нет тайла — 204), GET …/{слой}.pmtiles — routers/static_tiles.py, database/static_tiles.py, формат — database/pmtiles.py. Описание — docs/static-tiles.md в репозитории API.
• Веб: components/StaticTilesDialog.vue, подмена адресов слоёв — utils/staticTiles.ts (applyStaticTiles).
• Тесты: e2e — e2e/functions/admin.spec.ts.