Простое Windows-приложение для подготовки растровых офлайн-карт для Android-приложения THS2. Помощник принимает кэш SAS.Planet, MBTiles, геопривязанные GeoTIFF/KMZ, папки тайлов XYZ и ZIP-экспорты Global Mapper, приводит источник к единому MBTiles, преобразует его в PMTiles v3 и проверяет готовый архив официальным PMTiles CLI.
Приложение работает рядом с обычной SAS.Planet. Это не форк и не плагин: оно не заменяет SAS.Planet, не вмешивается в скачивание и не изменяет её кэш.
- современная тёмная тема и отдельные вкладки для каждого типа источника;
- русский и английский интерфейс с автовыбором по языку Windows и ручным выбором в настройках;
- автоматическое восстановление выбранной вкладки, путей, масштабов и остальных рабочих параметров;
- создание PMTiles напрямую из SQLite-кэша SAS.Planet CacheType=71;
- автоматическое чтение последнего выделения из
LastSelection.hlg; - выбор диапазона масштабов THS2;
- запасной путь через экспортированный SAS.Planet файл
.mbtiles; - конвертация геопривязанных
.tif,.tiffи.kmzчерез GDAL; - сборка папок тайлов со структурой
z/x/y.pngилиz/x/y.jpg; - безопасное распознавание ZIP Global Mapper со структурой
Z<zoom>/<y>/<x>.<ext>; - поддержка растровых PNG, JPEG, WebP и AVIF;
- запись названия карты и обязательной атрибуции источника;
- проверка результата командой
pmtiles verify; - отчёт
.report.jsonрядом с готовой картой; - живой прогресс текущего этапа и прошедшее время;
- диагностический
.diagnostic.logрядом с результатом; - проверка свободного места и выбор временной папки;
- автоматическое индексирование рабочей копии больших MBTiles;
- быстрый режим без дедупликации для тяжёлых растров;
- предупреждение о недостающих тайлах;
- строгое чтение исходного кэша SQLite в режиме
mode=ro.
Открой раздел Releases,
скачай архив THS2-Map-Builder-Windows-x64.zip и распакуй его в отдельную
папку. Запускай THS2 Map Builder.exe.
Не вынимай EXE из распакованной папки: рядом находится каталог _internal с
Python, Tcl/Tk и официальным pmtiles.exe. Установка Python не требуется.
- Запусти SAS.Planet и выбери источник карты.
- Выдели прямоугольник или многоугольник.
- Через операцию скачивания загрузи все нужные масштабы.
- Закрой окно операции скачивания и открой THS2 Map Builder.
- Выбери папку конкретного источника внутри
cache_sqlite. - Укажи
LastSelection.hlgиз корня SAS.Planet. - Задай стандартные масштабы PMTiles, например
13–19. - Укажи название, атрибуцию и выходной файл.
- Нажми Создать карту THS2.
SAS.Planet исторически обозначает масштабы на единицу выше стандартной XYZ
схемы: стандартный zoom 13–19 хранится в каталогах SAS z14–z20.
Помощник учитывает это автоматически.
Для сложного многоугольника MVP использует его прямоугольную оболочку. Это не теряет пограничные тайлы, но может добавить тайлы за пределами контура.
Если используется другая версия или другой тип кэша SAS.Planet:
- Экспортируй выбранную область из SAS.Planet в
.mbtilesсо схемой TMS. - В помощнике выбери режим Экспортированный MBTiles.
- Выбери файл и нажми Создать карту THS2.
Исходный MBTiles не изменяется. Для добавления названия и атрибуции помощник работает с временной копией.
Выбери режим GeoTIFF или KMZ — геопривязанный растр, исходный файл, масштабы и формат тайлов. PNG сохраняет прозрачность и чёткую графику, JPEG обычно лучше подходит спутниковым снимкам и занимает меньше места.
Приложение проверяет систему координат, переводит растр в Web Mercator, нарезает тайлы, создаёт обзорные масштабы и проверяет PMTiles. Обычный JPG/PNG без геопривязки пока преобразовать нельзя.
Для этого режима требуется GDAL. Приложение автоматически ищет его в PATH,
OSGeo4W, QGIS, каталоге из GDAL_HOME и в bin\gdal рядом с приложением.
Остальные режимы работают без GDAL.
Поддерживаются обычная структура z/x/y.ext и вариант с буквенными
префиксами zZ/xX/yY.ext, например:
tiles/13/5424/2568.jpg
tiles/z13/x5424/y2568.jpg
Масштабы и границы вычисляются автоматически. Координата y читается как XYZ
и переводится в TMS для временного MBTiles. Исходные файлы не меняются. Все
тайлы карты должны иметь одинаковый формат: PNG, JPEG, WebP или AVIF.
Перед упаковкой приложение подсчитывает тайлы и их общий размер. Во время
поиска показывается живой счётчик найденных файлов, а во время сборки — точный
процент, обработано / всего, скорость и примерное оставшееся время. После
подсчёта дополнительно проверяется свободное место для временного MBTiles и
готового PMTiles.
Во вкладке XYZ можно выбрать распакованную папку или ZIP напрямую. Для ZIP
предварительная распаковка не требуется. Формат включается только при наличии
безопасно прочитанного
*.gm_source_def.xml, где указаны creator="Global Mapper" и явный шаблон
BaseURL вида Z%z/%y/%x.png (также поддерживаются JPEG, WebP и AVIF).
Поддерживается и официальный вариант creator вида
Global Mapper - http://www.globalmapper.com.
Global Mapper сохраняет такие тайлы как Z/y/x, например:
произвольная папка/036.gm_source_def.xml
произвольная папка/Z10/302/597.png
Папка после масштаба считается координатой Y, имя файла — X. Координата
Y трактуется как XYZ/Web Mercator и переводится в строку TMS для MBTiles.
Границы и центр вычисляются по фактически найденным тайлам. Временный MBTiles
получает метку source_layout=global-mapper-z-y-x, а итоговый PMTiles проходит
обычную обязательную проверку.
Для исходников размером около 1 ГБ и больше открой раздел Большие карты:
- Выбери временную папку на диске с достаточным запасом места. Если поле
пустое, используется системная
%TEMP%, обычно на дискеC:. - Для спутниковых и других растров включи Быстрый режим. Он передаёт
PMTiles CLI параметр
--no-deduplication: обработка обычно быстрее, но итоговый файл может быть немного больше. - Следи за названием текущего этапа, процентом и временем. При создании индекса точный процент недоступен, поэтому индикатор движется без числа.
Перед запуском приложение оценивает свободное место отдельно для временных
файлов и результата. Исходный MBTiles не изменяется: при необходимости индекс
zoom_level, tile_column, tile_row создаётся только в рабочей копии.
Рядом с результатом всегда появляется файл .diagnostic.log. Если операция
завершилась ошибкой или кажется слишком долгой, пришли этот файл разработчику.
Он содержит этапы и сообщения инструментов, но не содержит сами тайлы.
- кэш SAS.Planet открывается только на чтение;
- приложение не скачивает тайлы из интернета;
- приложение не отправляет карты или координаты на сервер;
- перед заменой существующего результата требуется подтверждение;
- временный MBTiles удаляется после завершения;
- ZIP проверяется на абсолютные и выходящие наружу пути, ссылки, специальные и зашифрованные файлы, опасный объём/сжатие и слишком крупные тайлы;
- XML Global Mapper ограничен 256 КиБ; объявления DOCTYPE/ENTITY запрещены, внешние ресурсы не загружаются;
- рядом с результатом сохраняется понятный JSON-отчёт о сборке.
SAS.Planet является инструментом доступа к разным картографическим источникам, но не передаёт права на их данные. Перед созданием и распространением офлайн- карты проверь условия выбранного источника: разрешены ли скачивание, локальное хранение, публикация и коммерческое использование. Укажи требуемую атрибуцию — она будет записана в метаданные PMTiles.
Проверенная схема базы:
CREATE TABLE t (
x INTEGER NOT NULL,
y INTEGER NOT NULL,
v INTEGER DEFAULT 0 NOT NULL,
c TEXT,
s INTEGER DEFAULT 0 NOT NULL,
h INTEGER DEFAULT 0 NOT NULL,
d INTEGER NOT NULL,
b BLOB,
PRIMARY KEY (x, y, v)
);x/y — глобальные XYZ-координаты, v=0 — основная версия тайла, b —
изображение. Каталоги группируют координаты по блокам 1024 и 256 тайлов.
MBTiles хранит строки в TMS, поэтому помощник выполняет преобразование
tms_y = 2^zoom - 1 - xyz_y.
Подробное обоснование решения находится в ADR-0001. Архитектура универсального импорта описана в ADR-0002, обработка больших карт — в ADR-0003.
Требования: Windows 10/11 и Python 3.10 или новее. Для GeoTIFF/KMZ дополнительно нужен GDAL из OSGeo4W или QGIS.
powershell -ExecutionPolicy Bypass -File .\Install-PmTiles.ps1
python .\ths2_map_builder.pywТакже можно дважды щёлкнуть Start-THS2-Map-Builder.cmd.
powershell -ExecutionPolicy Bypass -File .\Install-PmTiles.ps1
powershell -ExecutionPolicy Bypass -File .\Build-Windows-App.ps1Результат появится в dist\THS2 Map Builder. Скрипт использует PyInstaller и
включает официальный PMTiles CLI в автономный пакет.
python -m unittest -v test_map_builder.pyПрототип проверен на SAS.Planet 260404 x64 и реальном наборе из 4383 JPEG-
тайлов zoom 13–19. Прямая сборка из кэша и конвертация исходного MBTiles дали
одинаковое число тайлов; оба результата прошли pmtiles verify.
- прямое чтение реализовано только для CacheType=71;
- выделения через антимеридиан пока не поддерживаются;
- помощник не докачивает отсутствующие тайлы;
- обычные JPG/PNG без геопривязки пока не поддерживаются;
- векторные SHP, GeoJSON и KML пока не отрисовываются в растр;
- компактная Windows-сборка не включает GDAL и использует установленный OSGeo4W/QGIS;
- загрузка в аккаунт THS2.ru потребует отдельного серверного API загрузки;
- автоматическое наблюдение за каталогом экспорта MBTiles пока не включено.
Исходный код распространяется по лицензии MIT. Компоненты готовой Windows-сборки перечислены в THIRD_PARTY_NOTICES.md.
THS2 Map Builder is a Windows desktop application for creating verified raster PMTiles v3 offline maps for the THS2 Android app. It converts SAS.Planet cache data, MBTiles archives, XYZ tile directories, Global Mapper ZIP exports, and georeferenced GeoTIFF/KMZ rasters into a format that THS2 can open directly.
The application runs next to an unmodified SAS.Planet installation. It is not a SAS.Planet fork or plugin, does not interfere with tile downloads, and never modifies the original SAS.Planet cache or XYZ source directory.
- modern dark Windows interface;
- separate tabs for SAS.Planet, MBTiles, XYZ, and GeoTIFF/KMZ workflows;
- Russian and English UI with automatic Windows-language detection;
- language override under Settings without restarting the application;
- automatic restoration of the last tab, paths, zoom levels, and conversion options;
- direct read-only access to SAS.Planet SQLite CacheType=71;
- raster PNG, JPEG, WebP, and AVIF tile support;
- safe Global Mapper ZIP detection for
Z<zoom>/<y>/<x>.<ext>exports; - live conversion progress, elapsed time, XYZ tile count, speed, and ETA;
- free-space preflight checks and a selectable temporary directory;
- fast mode for very large maps using PMTiles
--no-deduplication; - PMTiles v3 verification with the official PMTiles CLI;
.report.jsonand.diagnostic.logfiles next to the output map.
- Open the latest release.
- Download
THS2-Map-Builder-Windows-x64-vX.Y.Z.zip. - Extract the complete archive to a folder.
- Run
THS2 Map Builder.exe.
Do not move only the EXE out of the extracted folder. The adjacent _internal
directory contains Python, Tcl/Tk, and the official pmtiles.exe. Python does
not need to be installed for the packaged application.
- Select a map source in SAS.Planet.
- Select a rectangle or polygon.
- Download all required zoom levels.
- Open THS2 Map Builder and select the SAS.Planet tab.
- Choose the source folder inside
cache_sqliteand theLastSelection.hlgfile. - Enter standard XYZ/PMTiles zoom levels. SAS.Planet historically displays these levels one number higher.
- Enter a map name, source attribution, and output file.
- Select a temporary folder with sufficient free space for a large map.
- Click Create THS2 map.
The source .sqlitedb files are opened through SQLite mode=ro. The converter
creates all intermediate databases in a separate temporary directory.
Direct conversion reads the fragmented SQLite cache selected by
LastSelection.hlg. Missing tiles are reported after the map is created.
Existing raster MBTiles files can be converted directly. If a large source
lacks the required zoom_level, tile_column, tile_row index, the application
creates the index only in a temporary working copy and leaves the source file
unchanged.
Both common naming layouts are supported:
tiles/13/5424/2568.jpg
tiles/z13/x5424/y2568.jpg
Zoom levels and bounds are detected automatically. XYZ Y coordinates are converted to TMS row numbers for the temporary MBTiles database. All tiles in one map must use the same image format.
The XYZ tab accepts either an extracted directory or a ZIP file directly;
extracting a ZIP first is not required. This layout is enabled only when a
safely parsed
*.gm_source_def.xml declares creator="Global Mapper" and an explicit
Z%z/%y/%x.<format> BaseURL template. An arbitrary or Cyrillic folder prefix
is supported. The official creator form
Global Mapper - http://www.globalmapper.com is also recognized.
In this export, the directory below Z<zoom> is Y and the file name is
X. Y uses XYZ/Web Mercator orientation and is converted to the MBTiles TMS
row. Actual bounds and center are calculated from the tile coordinates, and
the temporary MBTiles records source_layout=global-mapper-z-y-x.
ZIP paths, links, special/encrypted entries, expansion limits, duplicates,
tile sizes, formats, zooms, and coordinate ranges are validated. Metadata XML
is limited to 256 KiB; DOCTYPE and ENTITY declarations are rejected and no
external resources are fetched. The final PMTiles still runs through
pmtiles verify.
Georeferenced .tif, .tiff, and .kmz rasters can be reprojected to Web
Mercator and tiled as PNG or JPEG. This mode requires GDAL from OSGeo4W or QGIS.
Plain JPG/PNG images without georeferencing are not supported.
For sources around 1 GB or larger:
- choose a temporary directory on a drive with several gigabytes of free space;
- enable Fast mode for satellite imagery when a slightly larger PMTiles file is acceptable;
- follow the displayed stage, percentage, elapsed time, and ETA;
- if conversion fails or appears stalled, share the generated
.diagnostic.logfile. It contains tool output, but not the tile images.
On first launch, Russian Windows installations use Russian; all other system languages use English. Use the Settings button in the upper-right corner to change the language manually.
The application automatically saves the selected converter tab, source paths, output path, map name, attribution, zoom levels, raster settings, temporary directory, fast mode, and language. Preferences are stored in:
%APPDATA%\THS2 Map Builder\settings.json
Requirements: Windows 10/11 and Python 3.10 or newer. GeoTIFF/KMZ conversion also requires GDAL.
powershell -ExecutionPolicy Bypass -File .\Install-PmTiles.ps1
python .\ths2_map_builder.pywpowershell -ExecutionPolicy Bypass -File .\Install-PmTiles.ps1
powershell -ExecutionPolicy Bypass -File .\Build-Windows-App.ps1The standalone package is written to dist\THS2 Map Builder.
python -m unittest -v test_map_builder.py- direct SAS.Planet access currently supports CacheType=71 only;
- selections crossing the antimeridian are not supported;
- the application does not download missing tiles;
- vector SHP, GeoJSON, and KML data is not rendered to raster tiles;
- the compact Windows package does not bundle GDAL;
- automatic monitoring of an MBTiles export folder is not implemented.
Only convert and distribute map data when the source license permits it. Enter the required copyright notice and usage terms in the Attribution field; the text is embedded in PMTiles metadata.
Source code is available under the MIT License. Third-party components included in the Windows package are documented in THIRD_PARTY_NOTICES.md.