Skip to content
BranchesTags

Repository files navigation

Garmin Export Plugin для QGIS

CI License: AGPLv3 QGIS 3.22+ / 4.x Qt5 + Qt6 Version Tests

🎯 Профессиональный плагин для экспорта векторных данных QGIS в формат Garmin IMG

Версия: 1.3.1 Автор: Кобяков Александр Викторович (Alex Kobyakov)
Email: kobyakov@lesburo.ru
Год: 2025-2026 Совместимость: QGIS 3.44/Qt5 и QGIS 4.2/Qt6

🌐 Языки интерфейса / UI languages: 🇷🇺 Русский · 🇺🇸 English · 🇩🇪 Deutsch · 🇪🇸 Español · 🇫🇷 Français · 🇧🇷 Português · 🇨🇳 中文 · 🇮🇳 हिन्दी · 🇸🇦 العربية · 🇮🇩 Bahasa Indonesia · 🇹🇭 ไทย · 🇻🇳 Tiếng Việt

🇬🇧 English description · 🇷🇺 Русское описание

🇬🇧 English

Garmin Export Plugin is a professional QGIS tool for exporting vector layers to the Garmin IMG map format using the mkgmap compiler. It covers the whole workflow — from selecting layers in QGIS to producing a ready-to-use map for Garmin GPS devices.

Key features

  • 🗺️ Exports every geometry type: points (POI), lines (roads, rivers), polygons (forests, water bodies), including multipart geometries.
  • 📥 Built-in mkgmap/splitter download: the "Download mkgmap" / "Download splitter" buttons fetch the full ZIP distribution from mkgmap.org.uk, GitHub wheels, Dropbox or a permanent Yandex.Disk backup (the Russian UI starts with Yandex.Disk) and unpack it with all dependency libraries (lib/: osmpbf, protobuf, fastutil…) so OSM/PBF reading works. You can also "Add" a local jar. QGIS rules forbid bundling jars, so it is fetched on demand.
  • 🖌️ Automatic TYP styling: the plugin generates a TYP file from the QGIS layer symbology (polygon fills, line width/color, POI icons) so the map on the device looks like it does in QGIS.
  • 🎨 Flexible style mapping: a JSON system for configuring Garmin object types.
  • 📊 Multi-level maps: 4 detail levels (Level0–Level3).
  • 🔧 mkgmap fine-tuning: Java heap (-Xmx), threads (--max-jobs), generalization, draw priority, code page, address index — all following the official mkgmap documentation.
  • ☕ Java auto-detection: the plugin finds Java on the system (PATH, JAVA_HOME, common install directories).
  • 🔄 Batch processing: export all project layers at once.
  • 🌐 Multilingual interface: 12 languages (EN, RU, DE, ES, FR, PT, ZH, HI, AR, ID, TH, VI), including right-to-left layout for Arabic.
  • 🔤 Comprehensive label code pages: 18 options — UTF-8/Unicode (covers every language) plus Windows 1250–1258, Thai 874, CJK 932/936/949/950 and DOS 850/852/866 — so labels in any script export correctly.
  • 📋 mkgmap logging: optional mkgmap.log file with a configurable verbosity.
  • 💾 Persistent settings between sessions.
  • 🧾 Reliable lifecycle: cancellation-safe export runs, stale-worker isolation and an anonymized .garmin_export/run_manifest.json on every completed run.
  • 🧰 Processing Toolbox (G6): validate the environment, build TYP mappings, validate TYP/code pages and mapping JSON, diagnose/download dependencies, generate MP previews and export IMG through Processing with generated, existing or disabled TYP styling, selected levels and advanced mkgmap options. Existing complete mkgmap/splitter installations are auto-detected; network download is explicit via the AUTO_DOWNLOAD parameter and reuses the UI fallback order with feedback cancellation.
  • 🖥️ Qt5/Qt6 dual support: one compatibility boundary for QGIS 3.44/Qt5 and QGIS 4.2/Qt6, with scoped enum fallbacks and no direct PyQt5/PyQt6 imports.
  • 🎛️ Polished UI contract: live/restart-safe language switching, SVG flags, readable combo/check controls, retranslate-safe dialogs, translated tooltips, placeholders and actions.

Processing Toolbox and QGIS Modeler

The provider is available under Processing → Toolbox → Garmin Export and in QGIS Modeler, Batch and the Python Processing API. It provides seven GUI-independent algorithms:

  1. Validate environment — reports Java, mkgmap and splitter separately.
  2. Build TYP mapping — creates TYP from QGIS layer symbology.
  3. Export selected layers to Garmin IMG — selected layers or all valid project vectors, generated/existing/default TYP, levels, code page and typed mkgmap tuning; returns IMG plus a redacted run_manifest.json.
  4. Validate TYP/code page — checks a TYP/TXT path and label encoding.
  5. Generate MP preview — writes Polish MP without Java or mkgmap.
  6. Validate mapping JSON — validates file/inline JSON, geometry, Garmin type and level ranges.
  7. Dependency diagnostics/download — discovers a complete local distribution and downloads only when AUTO_DOWNLOAD is enabled.

Parameter names are stable ASCII identifiers across QGIS 3.44/Qt5 and QGIS 4.2/Qt6. Existing complete distributions are auto-detected; network download is opt-in and reuses the UI fallback order, transactional install and cancellable feedback.

QGIS can run many independent Processing algorithms as tasks, and Modeler can chain validation → MP/TYP generation → export. QGIS controls task parallelism; the provider does not create duplicate GUI workers. For parallel exports use a distinct output directory, map id and temporary directory per task.

Python console example:

processing.run("garmin_export:validate_mapping_json", {
    "MAPPING_FILE": r"C:\maps\mapping.json"
})
processing.run("garmin_export:export_selected_layers", {
    "USE_PROJECT_LAYERS": True,
    "OUTPUT": r"C:\maps\out"
})

In Modeler, connect validation outputs to export inputs and expose OUTPUT, AUTO_DOWNLOAD, code page, TYP mode and tuning as model inputs.

Requirements

  • QGIS 3.22 or newer (Qt5 on QGIS 3.x; Qt6 on QGIS 4.x), Python 3.9+
  • Manually verified in QGIS 3.44/Qt5 and QGIS 4.2/Qt6.
  • Java Runtime Environment (JRE 8+) for mkgmap (the plugin can auto-detect it)

Quick start

  1. Open a QGIS project with vector layers and run the plugin from the Vector menu → "🎯 Garmin IMG Export".
  2. On the Tools tab click Download mkgmap (or Add mkgmap for a local jar); Java is detected automatically.
  3. Select the layers to export, set the output folder and map settings.
  4. Optionally choose a TYP styling mode and tune mkgmap options.
  5. Click Compile Map and get the ready .img file.

Tests

Core logic (MP/TYP generation, mkgmap command building, download link parsing, jar validation, style mapping) is covered by offline tests that run without QGIS:

python tests/run_tests.py

📋 Описание

Garmin Export Plugin - это современный инструмент для экспорта векторных слоёв QGIS в формат карт Garmin IMG через компилятор mkgmap. Плагин обеспечивает полноценный рабочий процесс от выбора слоёв до получения готовой карты для GPS-навигаторов Garmin.

✨ Основные возможности

  • 🗺️ Экспорт всех типов геометрии: точки (POI), линии (дороги, реки), полигоны (леса, водоёмы), включая мультигеометрии
  • 📥 Встроенное скачивание mkgmap/splitter: кнопки «Скачать mkgmap» и «Скачать splitter» получают полный ZIP-дистрибутив с mkgmap.org.uk, GitHub wheels, Dropbox или Яндекс.Диска и распаковывают его со всеми зависимыми библиотеками. Для русского интерфейса первым используется Яндекс.Диск (lib/: osmpbf, protobuf, fastutil…), чтобы работало чтение OSM/PBF. Также можно «Добавить» локальный jar. QGIS запрещает включать jar в состав плагина, поэтому файл загружается по требованию
  • 🖌️ Автоматическая стилизация TYP: плагин генерирует TYP-файл из символики слоёв QGIS (цвета полигонов, толщина и цвет линий, иконки точек) — карта на навигаторе выглядит как в QGIS
  • 🎨 Гибкое сопоставление стилей: JSON-система для настройки типов объектов Garmin
  • 📊 Многоуровневые карты: поддержка 4 уровней детализации (Level0-Level3)
  • 🔧 Тонкая настройка mkgmap: память Java (-Xmx), число потоков (--max-jobs), генерализация, приоритет отрисовки, кодовая страница, адресный индекс — всё по официальной документации mkgmap
  • ☕ Автопоиск Java: плагин сам находит Java в системе (PATH, JAVA_HOME, типовые каталоги)
  • 🔄 Пакетная обработка: экспорт всех слоёв проекта одновременно
  • 🌐 Многоязычный интерфейс: 12 языков (RU, EN, DE, ES, FR, PT, ZH, HI, AR, ID, TH, VI), включая письмо справа налево для арабского
  • 🔤 Полный набор кодовых страниц подписей: 18 вариантов — UTF-8/Unicode (покрывает любой язык), Windows 1250–1258, тайская 874, CJK 932/936/949/950 и DOS 850/852/866 — подписи на любом письме экспортируются корректно
  • 📋 Логирование mkgmap: опциональный файл журнала mkgmap.log с настраиваемым уровнем детализации
  • 💾 Сохранение настроек между сеансами работы
  • 🧾 Надёжный жизненный цикл: безопасная отмена, защита от устаревших worker-сигналов и обезличенный .garmin_export/run_manifest.json для каждого завершённого запуска
  • 🧰 Processing Toolbox (G6): проверка окружения, построение и проверка TYP, проверка кодовой страницы и mapping JSON, диагностика/загрузка зависимостей, MP-preview и экспорт IMG с выбором TYP, уровней карты и расширенных параметров mkgmap. Установленные дистрибутивы mkgmap/splitter с каталогом lib/ определяются автоматически; скачивание выполняется только при включённом параметре AUTO_DOWNLOAD и использует тот же порядок зеркал и отмену через feedback.

Processing Toolbox и QGIS Modeler

Провайдер доступен в Обработка → Панель инструментов → Garmin Export, а также в QGIS Modeler, пакетном запуске и Python API Processing. Семь алгоритмов не зависят от окна плагина: проверка окружения; построение TYP; экспорт IMG с генерацией/существующим/отключённым TYP, уровнями, кодовой страницей и tuning; проверка TYP и кодовой страницы; MP-preview; проверка mapping JSON; диагностика и загрузка зависимостей. Экспорт возвращает обезличенный run_manifest.json.

Имена параметров Processing — стабильные ASCII-идентификаторы для QGIS 3.44/Qt5 и QGIS 4.2/Qt6. Полные дистрибутивы определяются автоматически; сеть включается только через AUTO_DOWNLOAD и использует порядок зеркал и отмену из UI.

QGIS может выполнять много независимых алгоритмов Processing как задачи, а Modeler — связывать проверку -> генерацию MP/TYP -> экспорт. Параллелизм контролирует QGIS. Для параллельных экспортов используйте разные выходные каталоги, map id и временные папки.

Пример в Python-консоли QGIS:

processing.run("garmin_export:validate_mapping_json", {"MAPPING_FILE": r"C:\maps\mapping.json"})
processing.run("garmin_export:export_selected_layers", {"USE_PROJECT_LAYERS": True, "OUTPUT": r"C:\maps\out"})

В Modeler соедините результаты проверок с экспортом и вынесите OUTPUT, AUTO_DOWNLOAD, кодовую страницу, режим TYP и tuning в параметры модели.

🔧 Требования

Обязательные:

  • QGIS версии 3.22 или выше (Qt5 в QGIS 3.x; Qt6 в QGIS 4.x)
  • Python 3.9+
  • Java Runtime Environment (JRE) для работы mkgmap

Рекомендуемые:

  • mkgmap r4900+ (последняя версия)
  • Оперативная память: минимум 4 ГБ для больших проектов

📦 Установка

  1. Скачайте файлы плагина в папку C:\\AlexKo\\garmin_export

  2. Скопируйте папку в директорию плагинов QGIS:

    • Windows: %APPDATA%\\QGIS\\QGIS3\\profiles\\default\\python\\plugins\\
    • Linux: ~/.local/share/QGIS/QGIS3/profiles/default/python/plugins/
    • macOS: ~/Library/Application Support/QGIS/QGIS3/profiles/default/python/plugins/

  3. Активируйте плагин в QGIS:

    • Зайдите в меню "Модули" → "Управление модулями"
    • Найдите "Garmin Export" и поставьте галочку

🚀 Быстрый старт

Шаг 1: Подготовка данных

  1. Откройте проект QGIS с векторными слоями
  2. Убедитесь, что слои имеют корректную геометрию
  3. Проверьте наличие полей с названиями объектов

Шаг 2: Запуск плагина

  1. В меню "Векторы" выберите "🎯 Garmin IMG Export"
  2. Или нажмите кнопку на панели инструментов

Шаг 3: Настройка экспорта

  1. Выбор слоёв: отметьте нужные слои для экспорта
  2. Настройки карты: укажите Family ID, название карты
  3. Путь к mkgmap: выберите файл mkgmap.jar
  4. Выходная папка: укажите, куда сохранить результат

Шаг 4: Сопоставление стилей

  1. Настройте JSON-сопоставление типов объектов
  2. Или используйте настройки по умолчанию
  3. При необходимости отредактируйте через встроенный редактор

Шаг 5: Компиляция

  1. Нажмите "🚀 Скомпилировать карту"
  2. Дождитесь завершения процесса
  3. Получите готовый файл .img

📝 Структура JSON-сопоставления

{
  "layers": {
    "roads": {
      "geometry": "LineString",
      "type": "0x06",
      "label_field": "name",
      "level": 1,
      "style": {
        "color": "#FF0000",
        "width": 2
      }
    }
  }
}

Поля сопоставления:

  • geometry: тип геометрии (Point, LineString, Polygon)
  • type: код типа объекта Garmin (например, 0x06 для дорог)
  • label_field: поле атрибутов для подписей
  • level: уровень отображения (0-3)
  • style: дополнительные параметры стиля

🗺️ Типы объектов Garmin

Дороги (LineString):

  • 0x01 - Автомагистраль
  • 0x06 - Основная дорога
  • 0x07 - Второстепенная дорога
  • 0x14 - Железная дорога

Водные объекты:

  • 0x1F - Река/ручей (LineString)
  • 0x3C - Озеро/пруд (Polygon)

Точки интереса (Point):

  • 0x0100 - Крупный город
  • 0x2A00 - Больница
  • 0x2B00 - Заправка
  • 0x2F00 - Общая POI

Области (Polygon):

  • 0x13 - Здание
  • 0x16 - Лес
  • 0x1A - Парк

📊 Уровни детализации

  • Level 0 - Самый детальный уровень (крупный масштаб)
  • Level 1 - Основной уровень отображения
  • Level 2 - Средний уровень детализации
  • Level 3 - Обзорный уровень (мелкий масштаб)

🔧 Настройка mkgmap

Получение mkgmap (вкладка «Инструменты»):

Правила репозитория плагинов QGIS запрещают включать сторонние jar-библиотеки в состав плагина, поэтому mkgmap загружается по требованию:

  • Скачать mkgmap — плагин определяет последнюю версию на https://www.mkgmap.org.uk/download/mkgmap.html (переменная ссылка вида mkgmap-rXXXX.jar) и скачивает её; при недоступности сайта используется резервная копия на Яндекс.Диске. Файл сохраняется в профиле QGIS и проверяется на корректность.
  • Добавить mkgmap — выбрать уже скачанный mkgmap.jar на диске.
  • Аналогично для splitter (нужен только для нарезки очень больших карт).
  • Java определяется автоматически кнопкой «Найти автоматически» или указывается вручную.

Параметры компиляции:

Команда формируется строго по документации mkgmap (Java-опции до -jar, опции mkgmap до входных файлов). Базовый набор:

  • --gmapsupp — создание gmapsupp.img для загрузки в устройство;
  • --family-id, --product-id, --family-name, --description — идентификация карты;
  • --code-page / --unicode — кодировка подписей;
  • --keep-going — не прерывать сборку из-за ошибки в одном тайле.

Дополнительно на вкладке «Тюнинг» доступны: --index (адресный поиск), --route (маршрутизация), --transparent, --draw-priority, --add-pois-to-areas, --reduce-point-density[-polygon], --min-size-polygon, --order-by-decreasing-area, --max-jobs, -Xmx, а также поле произвольных аргументов и включение журнала mkgmap.log.

🐛 Решение проблем

Ошибка "Java не найдена":

  1. Установите Java Runtime Environment (JRE)
  2. Убедитесь, что Java доступна в PATH
  3. Перезапустите QGIS

Ошибка "mkgmap.jar не найден":

  1. Скачайте mkgmap с официального сайта
  2. Укажите правильный путь к файлу mkgmap.jar
  3. Убедитесь в корректности версии mkgmap

Пустой результат экспорта:

  1. Проверьте корректность геометрии слоёв
  2. Убедитесь в наличии данных в выбранных слоях
  3. Проверьте JSON-сопоставление

Ошибки сопоставления:

  1. Проверьте синтаксис JSON
  2. Убедитесь в корректности типов Garmin
  3. Используйте кнопку "Проверить JSON"

📚 Дополнительные ресурсы

🤝 Поддержка проекта

Плагин разрабатывается бесплатно! Вы можете поддержать разработку:

📄 Лицензия

GNU Affero General Public License v3.0

Плагин распространяется бесплатно под лицензией AGPL v3. Вы можете свободно использовать, модифицировать и распространять код согласно условиям лицензии. Полный текст лицензии находится в файле LICENSE.

👨‍💻 Об авторе

Кобяков Александр Викторович (Alex Kobyakov)

  • Email: kobyakov@lesburo.ru
  • Организация: Lesburo
  • Специализация: ГИС-разработка, Python, QGIS

© 2025 - 2026 Alex Kobyakov. Все права защищены.

🧪 Тесты

Логика ядра (генерация MP/TYP, построение команды mkgmap, разбор ссылок скачивания, валидация jar, сопоставление стилей, отмена и run manifest) покрыта офлайн-тестами, которые запускаются без QGIS:

python tests/run_tests.py

About

No description, website, or topics provided.

Resources

Readme
AGPL-3.0 license
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages