Skip to content
BranchesTags

Repository files navigation

Garmin Export Plugin для QGIS

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

Версия: 1.1.4
Автор: Кобяков Александр Викторович (Alex Kobyakov)
Email: kobyakov@lesburo.ru
Год: 2025-2026

🌐 Языки интерфейса / 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 (variable link) or from a permanent Yandex.Disk backup 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.

Requirements

  • QGIS 3.22 or newer, Python 3.9+
  • 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 (переменная ссылка) или с Яндекс.Диска (постоянная ссылка) и распаковывают его со всеми зависимыми библиотеками (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 с настраиваемым уровнем детализации
  • 💾 Сохранение настроек между сеансами работы

🔧 Требования

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

  • QGIS версии 3.22 или выше
  • 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 General Public License v3.0

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

👨‍💻 Об авторе

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

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

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

🧪 Тесты

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

python tests/run_tests.py

About

No description, website, or topics provided.

Resources

Readme
License
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages