====== Формат zmp и создание карт ======

Каждый картографический сервис в SASPlanet описывается в "zmp". Это папка или zip-архив с расширением ''.zmp'', в котором хранится текстовое описание сервиса в особом формате. Один "zmp" соответствует одной карте и независим от других. Сама аббревиатура является производным от слов: **z**ip **m**a**p**.

Коллекция zmp расположена в подпапках ''Maps'' в виде дерева каталогов и распространяется через [[основной_репозиторий|git-репозитарий]] отдельно от SAS.Planet. В прошлом в программе использовались только zip-архивы с расширением ''.zmp''. Сразу после установки программы обновите набор zmp.

===== Общий принцип =====
SAS.Planet скачивает [[тайл|тайлы]] с сервера и сохраняет их в тайловый кеш. В zmp описывается, как формируется ссылка на конкретный тайл и особенности HTTP-запроса на скачивание с конкретного сервера. При создании zmp чаще всего копируют поведение браузера при просмотре online-карт. Удобно пользоваться встроенными в браузер инструментами веб-разработчика, так, для Firefox нажмите //F12//, после чего откройте веб-страницу с картой.

Обучающие примеры:

  * [[Простой пример]]
  * [[Простой пример с плейсхолдерами]]
  * [[Пример порезки на тайлы]]
  * [[Описание Паскаль скриптов]] (GetUrlScript.txt)
  * [[Как скачивать нужные масштабы и не скачивать ненужные]]
  * Сложный пример (подключение dll)


===== Структура ZMP =====

Каждый zmp может содержать следующие файлы и папки:

  * **params.txt** — описывает основные параметры карты или слоя, единственный файл, который **является обязательным**;
  * **[[описание_паскаль_скриптов|GetUrlScript.txt]]** — скрипт, отвечающий за формирование ссылки на тайл карты и пользовательских заголовков; не нужен если используется [[простой_пример_с_плейсхолдерами|упрощенное добавление карт]]). Скрипты пишутся на обычном Pascal. Основными параметрами [[тайл|тайла]] являются масштаб и координаты по осям ''x'' и ''y''. Масштаб обозначается переменной ''GetZ'' (начинается с единицы), координаты по осям ''x'' и ''y'' - соответственно переменными ''GetX'' и ''GetY''. Эти переменные привязаны к [[Тайл|тайловой сетке]], принятой для [[maps:Google Maps|Google Maps]];
  * **24.bmp** — файл иконки, отображаемой на панели инструментов. Содержимое этого файла — изображение произвольного размера в формате BMP, PNG, ICO и других, но имя должно быть ''24.bmp''. В ранних версиях программы требовались иконки ''18.bmp'' (BMP, 18×18 pix, цвет фона RGB(255,0,255)) и ''24.bmp'' 24×24 pix, цвет фона RGB(255,0,255)).
  * **info.txt** — словесное описание карты в подмножестве HTML (в частности, абзацы надо разделять тегом <BR>). Возможен вывод графических файлов (например, легенды карты), через тег ''<img src=”path\to\image.bmp”/>''. Ссылаться можно в т.ч. на изображения в папке zmp.
  * графические файлы, ссылка на которые размещена в ''info.txt'' (например, легенда карты);
  * **EmptyTiles** — директория, содержащая образцы файлов, которые отдаёт сервер вместо пустых (полностью прозрачных) или отсутствующих тайлов, а также в случае бана. Такие тайлы не будут сохраняться в SAS.Planet. В некоторых случаях сервер отдаёт нормальные тайлы в одном формате (например //image/jpeg//), а «пустышки» в другом (например полностью прозрачный //image/png//). Поскольку SAS.Planet конвертирует все принятые тайлы в формат, указанный в параметре ''Ext'' (см. ниже), то в качестве образцов необходимо использовать исходные файлы, отправленные сервером, а не брать их из кэша программы.


===== params.txt =====

> Некоторые из параметров карты могут быть изменены внутри программы без редактирования файла ''params.txt''. Для этого нужно зайти в //Параметры->Параметры карты// или нажать //Ctrl+Alt+P//. Пользовательские изменения настроек карт сохраняются в файле ''Maps/maps.ini''.

Раздел **[PARAMS]**

  *  **asLayer** — если равно 1, карта используется как слой, накладываемый поверх основной карты.
  *  **pnum** — порядковый номер карты в меню. Не обязателен.
  *  **[[GUID]]** — случайный номер, можно [[http://www.guidgen.com/|сгенерировать онлайн]]
  *  **ParentSubMenu** — название пункта родительского меню для данной карты на русском языке.
  *  **ParentSubMenu_en** — название пункта родительского меню для данной карты на английском языке.
  *  **ParentSubMenu_uk** — название пункта родительского меню для данной карты на украинском языке.
     * существует возможность указать иерархическое меню разделив пункты символом "\" (например ''ParentSubMenu=Google\Планеты'')
  *  **name** — имя карты на русском языке.
  *  **name_en** — имя карты на английском языке.
  *  **name_uk** — имя карты на украинском языке.
  *  **CacheType** — можно переопределить тип кэша [[https://github.com/sasgis/sas.planet.src/blob/master/Src/TileStorage/c_CacheTypeCodes.pas|из списка в исходном коде]], в который будут записываться тайлы данной карты. NB! Некоторые форматы кеша подходят только для [[Функции программы#Экспорт карт и спутниковых снимков|экспорта тайлов]].

^ CacheType ^ Название ^ Путь ^ Комментарий ^
| 0  | По умолчанию                  |                                 | Ранее использовался 2, теперь 71 |
| 1  | GoogleMV                      | ''cache_old/ /{z+1}/{q}.{ext}'' | [[https://learn.microsoft.com/en-us/bingmaps/articles/bing-maps-tile-system|Quadkey]] |
| 2  | SAS.Planet                    | ''cache/'' |
| 3  | EarthSlicer 1.95              | ''cache_es/'' |
| 4  | GlobalMapper Tiles (GMT)      | ''cache_gmt/ /z{z}/{x}/{y}.{ext}'' |
| 41 | GlobalMapper Aux              | ''cache_gmt/'' | Не используется? |
| 42 | GlobalMapper Bing             | ''cache_gmt/ /{z}/{y}/{x}.{ext}'' | [[http://www.sasgis.org/mantis/view.php?id=780|Тикет 780]] |
| 43 | **[[https://mobac.sourceforge.io/|Mobile Atlas Creator]] (MOBAC)** | ''cache_ma/ /{z}/{x}/{y}.{ext}'' | [[http://www.sasgis.org/mantis/view.php?id=1936|Тикет 1936]]. Тип кеша известен как [[https://wiki.openstreetmap.org/wiki/Slippy_map_tilenames|Slippy map]]. Нумерация тайлов используется в [[OpenStreetMap]] и Google. Кеш подключается к QGIS, [[https://mapproxy.org/docs/nightly/caches.html#cache-file|MapProxy]]. Для использования с [[https://josm.openstreetmap.de/|JOSM]] достаточно:
  tms:file:///home/user/SAS.Planet/cache_ma/vesat/{z}/{x}/{y}.jpg  # Linux
  tms[18]:file:///c:/SAS.Planet/cache_ma/vesat/{z}/{x}/{y}.jpg  # Windows
|
| 44 | OsmAnd+ Tiles                 | Экспорт ''{z}/{x}/{y}.{ext}.tile'' | [[http://www.sasgis.org/mantis/view.php?id=884|Тикет 884]]. Не то же самое что "OsmAnd (SQLite3)" ''*.sqlitedb'' ([[http://www.sasgis.org/mantis/view.php?id=3577|тикет 3577]]) |
| 45 | [[https://wiki.openstreetmap.org/wiki/TMS|Tile Map Service]] (TMS) | ''cache_tms/ /{z}/{x}/{-y}.{ext}'' | [[http://www.sasgis.org/mantis/view.php?id=2848|Тикет 2848]]. ([[https://wiki.osgeo.org/wiki/Tile_Map_Service_Specification|спецификация osgeo.org)]]. |
| 5  | Google Earth                  | ''cache_ge/'' |
| 51 | GoogleEarth Terrain           |
| 6  | [[https://ru.wikipedia.org/wiki/Berkeley_DB|BerkeleyDB]] | ''cache_db/'' | |
| 61 | BerkeleyDB (Versioned)        |
| 7  | DBMS (СУБД)                   |
| 71 | SQLite3                       | ''cache_sqlite/ /z{z+1}/0/0/0.0.sqlitedb'' | [[http://www.sasgis.org/mantis/view.php?id=1376#c10961|Тикет 1376]]. Создаётся несколько баз SQLite. |
| 72 | [[https://wiki.openstreetmap.org/wiki/MBTiles|MBTiles]] | Экспорт ''*.mbtiles'' | [[http://www.sasgis.org/mantis/view.php?id=1376|Тикет 1376]], ([[https://github.com/mapbox/mbtiles-spec|спецификация MapBox]]). Используется одна база SQLite, но формат так ограничен, что пригоден только для экспорта. |
| 8  | GeoCacher                     |
| 9  | RAM (на диск не записываются) | | [[http://www.sasgis.org/mantis/view.php?id=1755|Тикет 1755]] |


  * **DefURLBase** — неизменная часть адреса ссылки на тайлы карты. Или шаблон URL адреса в случае [[простой_пример_с_плейсхолдерами|упрощенного добавления карт]].
  * **[[epsg_код_проекции|projection]]** — проекция карты. 1 — меркатор на сфероид, 2 — меркатор на эллипсоид, 3 — широта/долгота.
  * **[[epsg_код_проекции|sradiusa]]** — радиус большой полуоси эллипсоида.
  * **[[epsg_код_проекции|sradiusb]]** — радиус меньшей полуоси эллипсоида.
  * **[[epsg_код_проекции|EPSG]]** — код проекции карты.
  * **NameInCache** — имя папки в кэше, в которую будут записываться тайлы карты.
  * **separator** — разделитель в виде горизонтальной черты, отображаемый в меню после данной карты (1 — отображать, 0 — не отображать).
  * **Ext** — расширение тайла (.jpg, .png, .bmp, .gif). Задаёт формат, в котором принудительно будут сохраняться карты, если ContentType другой.
  *  **UseDwn** — если равно 1, то скачивать тайлы карты разрешено.
  *  **Sleep** — величина паузы между загрузками отдельных тайлов в миллисекундах.
  *  **DefHotKey** — сочетание горячих клавиш для данной карты.
  *  **ContentType** — список форматов изображений (например, ''ContentType=image/jpeg,image/png''), которые SAS.Planet ожидает получить от сервера. При несовпадении формата (например сервер вернул текст, а не картинку) отображается ошибка.
  *  **DefaultContentType** — тип, который будет использоваться, если сервер не вернул никакого типа или если стоит игнорирование типа, возвращаемого сервером.
  *  **IgnoreContentType** — игнорирование типа, возвращаемого сервером.
  *  **DetectContentType** - если равно 1, то после загрузки тайла будет выполнятся анализ его содержимого и коррекция поля //Content-Type// в заголовках ответа сервера
  *  **MimeTypeSubst** — подстановка типа загружаемых данных (например, «image/png8bit=image/png»).
  *  **TILERLEFT, TILERRIGHT, TILERTOP, TILERBOTTOM** — параметры для обрезки скачиваемых тайлов соответственно слева, справа, сверху и снизу. Если получившийся прямоугольник не совпадает с квадратом 256×256, он ещё и растягивается или сжимается до этого размера.
  *  **UsePreloadPage** — если равно 1, использовать предварительно загружаемую страницу (обязательно следует указать её адрес).
  *  **PreloadPage** — адрес предварительно загружаемой страницы.
  *  **RequestHead** — пользовательские HTTP-заголовки (headers), передаваемые на сервер. Поля должны отделяться символами ''\r\n'' (пример: ''RequestHead=Referer: maps.kosmosnimki.ru\r\nConnection: Keep-Alive'').
  *  **Version** — версия тайлов, соответствует переменной Version в ''GetUrlScript.txt''.
  *  **MaxConnectToServerCount** — максимальное число потоков. Значение по умолчанию устанавливается в секции **[ZmpDefaultParams]** файла ''SASPlanet.ini''
  *  **IsUseDownloaderInScript=1** - использование скачивания внутри скрипта [[http://sasgis.org/mantis/view.php?id=596|добавить отсюда]]
  *  **UseMemCache** - использовать кэш в памяти (при CacheType=9 (RAM-кэш) отключение данной опции приведёт к ошибке), включено по-умолчанию
  *  **MemCacheCapacity** - количество тайлов кэшируемых в память. По-умолчанию = 100
  *  **MemCacheTTL** - время жизни тайлов (в миллисекундах), кэшируемых в память. По-умолчанию = 60000 мс. (1 мин)
  *  **MemCacheClearStrategy** - стратегия очистки (по TTL) кэшируемых в память тайлов. Принимает значения: 
     * 0 - удалять ВСЕ тайлы из RAM-кэша, если истёк TTL у самого СТАРОГО тайла; 
     * 1 - удалять ВСЕ тайлы из RAM-кэша, если истёк TTL у самого МОЛОДОГО тайла (включён по-умолчанию); 
     * 2 - удалять только те тайлы, у которых истёк TTL;
     * 3 - НЕ удалять тайлы по TTL.
  *  **RestartDownloadOnMemCacheTTL** - автоматически перезакачивать тайлы в пределах видимой области экрана при очистке RAM-кэша (работает только если UseMemCache=1). По-умолчанию отключено.
  * **License=©** - текст лицензии, который будет выводиться в левом верхнем углу карты. Требуется для соблюдения условий распространения некоторых карт. 
  * **LayerZOrder** -  порядок отображения слоёв, по умолчанию 0. Слои с большим значением будут отображаться поверх слоев с меньшим значением
  * **IsReadOnly=1** - использовать кэш в режиме "Только чтение"
  * **IteratorSubRectSize** -  размеры по вертикали и горизонтали, измеряемые в стандартных тайлах (256х256 пикселей) при скачивании так называемых "мегатайлов", то есть тайлов с размерами более чем 256х256 пикселей. (Только в SACS)
  * **IteratorSubRectAlign** - если 0 - всё по умолчанию, если не 0 (1 или 2), то осуществляется точная привязка к размеру мегатайла. Если же не 1, а 2 - то будет дополнительно увеличен размер просматриваемой области, чтобы возможно было скачать даже, например, один левый верхний тайл в режиме кэш+интернет при сдвиге окна влево и вверх. Толкование малопонятное, интересующимся смотреть [[http://www.sasgis.org/mantis/view.php?id=1659|здесь]]. Только в SACS.


Раздел **[ViewInfo]**

  * **[[epsg_код_проекции|EPSG]]** — код проекции карты при выводе на экран.

В ночных версиях появилась возможность использовать более продвинутый хоть и медленный парсер kml, c поддержкой чтения оформления меток, линий и полигонов или принудительно задать свои настройки для конкретного zmp. Для того чтобы включить и настроить эти функции используются следующие разделы:

Раздел **[PARAMS_Vector]**
  *  **UseAppearance** — если равно 1, то включается использование оформления из zmp и загруженных векторных тайлов

Раздел **[PARAMS_Vector_Point]**
Настройки оформления точек.
  *  **IconName** —  имя иконки по-умолчанию
  *  **IsForceIconName**  — если равно 1 (это значение по-умолчанию), то будет принудительно использовать заданную в параметре **IconName**, даже если парсер смог считать имя иконки из праметров точки
  *  **IconSize** — размер иконки по-умолчанию
  *  **IsForceIconSize** — если равно 1 (это значение по-умолчанию), то будет принудительно использовать размер иконки заданный в **IconSize**, даже если парсер смог считать размер из праметров точки


Раздел **[PARAMS_Vector_Line]**
Настройки оформления линий
  *  **LineColor** —  цвет линии по-умолчанию
  *  **IsForceLineColor**  — если равно 1 (это значение по-умолчанию), то будет принудительно использовать цвет из **LineColor**, даже если парсер смог считать настройки из параметров линии
  *  **LineWidth** — толщина линии по-умолчанию
  *  **IsForceLineWidth** — если равно 1 (это значение по-умолчанию), то будет принудительно использовать толщину линии заданную в **LineWidth**, даже если парсер смог считать настройки из параметров линии

Раздел **[PARAMS_Vector_Poly]**
Настройки оформления полигонов
  *  **LineColor** —  цвет границы полигона по-умолчанию
  *  **IsForceLineColor**  — если равно 1 (это значение по-умолчанию), то будет принудительно использовать цвет из **LineColor**, даже если парсер смог считать настройки из параметров полигона
  *  **LineWidth** — толщина границы полигона по-умолчанию
  *  **IsForceLineWidth** — если равно 1 (это значение по-умолчанию), то будет принудительно использовать толщину линии заданную в **LineWidth**, даже если парсер смог считать настройки из параметров полигона
  *  **FillColor** —  цвет заливки полигона по-умолчанию
  *  **IsForceFillColor**  — если равно 1 (это значение по-умолчанию), то будет принудительно использовать цвет из **FillColor**, даже если парсер смог считать настройки из параметров полигона