# Руководство пользователя Garmin Export Plugin

## 📖 Содержание

1. [Обзор интерфейса](#обзор-интерфейса)
2. [Выбор слоёв](#выбор-слоёв)
3. [Настройки экспорта](#настройки-экспорта)
4. [Сопоставление стилей](#сопоставление-стилей)
5. [Уровни карты](#уровни-карты)
6. [Процесс компиляции](#процесс-компиляции)
7. [Примеры использования](#примеры-использования)
8. [Советы и рекомендации](#советы-и-рекомендации)

## 🖥️ Обзор интерфейса

Плагин имеет современный табличный интерфейс, разделённый на несколько секций:

### Заголовок
- **Выбор языка**: переключение между русским и английским
- **Кнопка поддержки**: ссылки на пожертвования
- **Об авторе**: информация о разработчике

### Основные табы
1. **📁 Выбор слоёв** - выбор данных для экспорта
2. **⚙️ Настройки экспорта** - параметры карты и mkgmap
3. **🎨 Сопоставление стилей** - JSON-настройки типов объектов
4. **📊 Уровни карты** - настройка детализации

### Панель управления
- **🚀 Скомпилировать карту** - запуск экспорта
- **❌ Отмена** - остановка процесса
- **🧹 Очистить логи** - очистка сообщений

### Результаты
- **📋 Логи** - подробные сообщения процесса
- **📈 Результаты** - таблица обработанных слоёв

## 📁 Выбор слоёв

### Автоматическая загрузка
При запуске плагин автоматически сканирует проект и отображает все векторные слои:
- 📍 Точечные слои (Point)
- 〰️ Линейные слои (LineString) 
- ⬜ Полигональные слои (Polygon)

### Управление выбором
- **✅ Выбрать все слои** - отметить все слои для экспорта
- **❌ Снять выделение** - убрать отметки со всех слоёв
- **Ручной выбор** - отметить только нужные слои

### Информация о слоях
Для каждого слоя отображается:
- Название слоя
- Тип геометрии
- Количество объектов (если доступно)

## ⚙️ Настройки экспорта

### Выходные файлы
- **Выходная папка** - где сохранить готовую карту
- **Имя файла карты** - название без расширения (по умолчанию "map")

### Настройки карты
- **Family ID** - уникальный идентификатор семейства карт (1-65535)
- **Map ID** - идентификатор карты (должен быть уникальным)
- **Название карты** - отображается в навигаторе Garmin
- **Описание карты** - дополнительная информация
- **Прозрачная карта** - накладывается поверх базовой карты
- **Поддержка маршрутизации** - включает возможности навигации

### Настройки mkgmap
- **Путь к mkgmap.jar** - расположение компилятора mkgmap

### Рекомендуемые значения
- **Family ID**: используйте уникальные значения (например, год + номер проекта)
- **Map ID**: Family ID * 10000 + 1 (например, 12340001)
- **Название**: краткое и понятное описание карты

## 🎨 Сопоставление стилей

### Основная концепция
JSON-сопоставление определяет, как слои QGIS преобразуются в объекты Garmin:
- Какой тип Garmin присваивается слою
- Какое поле используется для подписей
- На каком уровне отображается объект

### Структура JSON
```json
{
  "layers": {
    "название_слоя": {
      "geometry": "тип_геометрии",
      "type": "код_garmin",
      "label_field": "поле_подписи",
      "level": уровень_отображения
    }
  }
}
```

### Управление сопоставлением
- **📂 Загрузить** - импорт JSON из файла
- **💾 Сохранить** - экспорт текущих настроек
- **✏️ Редактировать** - встроенный редактор с подсветкой
- **🔄 По умолчанию** - восстановить базовые настройки

### Автоматическое сопоставление
Если слой не найден в JSON, плагин:
1. Ищет похожие названия слоёв
2. Использует сопоставление по типу геометрии
3. Применяет настройки по умолчанию

### Типы объектов Garmin
#### Дороги (LineString)
- `0x01` - Автомагистраль (красная, толстая)
- `0x06` - Основная дорога (жёлтая, средняя)
- `0x07` - Второстепенная дорога (белая, тонкая)

#### Водные объекты
- `0x1F` - Река/ручей (синяя линия)
- `0x3C` - Озеро/пруд (синий полигон)

#### Точки интереса (Point)
- `0x0100` - Крупный город
- `0x2A00` - Больница (красный крест)
- `0x2B00` - Заправка (символ топлива)

#### Области (Polygon)
- `0x13` - Здание (серый)
- `0x16` - Лес (зелёный)
- `0x1A` - Парк (светло-зелёный)

## 📊 Уровни карты

### Концепция уровней
Garmin использует 4 уровня детализации для оптимизации отображения:

- **Уровень 0 (детальный)** - максимальное приближение
- **Уровень 1 (основной)** - стандартный масштаб
- **Уровень 2 (средний)** - средний масштаб
- **Уровень 3 (обзорный)** - мелкий масштаб

### Выбор уровней
- Отметьте нужные уровни галочками
- Рекомендуется включать все уровни для универсальности
- Для простых карт достаточно уровней 1-2

### Распределение объектов по уровням
- **Уровень 0**: автомагистрали, крупные города, важные POI
- **Уровень 1**: основные дороги, здания, большинство POI
- **Уровень 2**: второстепенные дороги, реки, парки
- **Уровень 3**: лесные массивы, водоёмы, административные границы

## 🚀 Процесс компиляции

### Этапы экспорта
1. **Подготовка** - проверка настроек и инициализация
2. **Обработка слоёв** - преобразование геометрии и атрибутов
3. **Генерация MP** - создание файла Polish format
4. **Компиляция mkgmap** - преобразование в IMG
5. **Завершение** - очистка временных файлов

### Мониторинг процесса
- **Прогресс-бар** показывает общий прогресс
- **Логи** содержат подробную информацию
- **Таблица результатов** показывает статус каждого слоя

### Возможные статусы
- ✅ **Успешно** - слой обработан корректно
- ❌ **Ошибка** - проблемы с геометрией или данными
- ⚠️ **Предупреждение** - слой обработан с замечаниями
- ⏳ **Обработка** - процесс в процессе выполнения

## 📚 Примеры использования

### Пример 1: Простая туристическая карта
**Цель**: создать карту для пешего туризма

**Данные**:
- Тропы (линии)
- Достопримечательности (точки)
- Леса (полигоны)
- Водоёмы (полигоны)

**Настройки**:
```json
{
  "layers": {
    "trails": {
      "geometry": "LineString",
      "type": "0x16",
      "label_field": "name",
      "level": 1
    },
    "poi": {
      "geometry": "Point", 
      "type": "0x2F00",
      "label_field": "name",
      "level": 1
    }
  }
}
```

### Пример 2: Автомобильная навигация
**Цель**: карта для GPS-навигации

**Данные**:
- Автомагистрали (линии)
- Дороги разных категорий (линии)
- Заправки (точки)
- Города (точки)

**Настройки**:
- Включить поддержку маршрутизации
- Использовать все уровни детализации
- Настроить правильную иерархию дорог

### Пример 3: Специализированная карта
**Цель**: карта для геодезических работ

**Данные**:
- Границы участков (полигоны)
- Точки съёмки (точки)
- Коммуникации (линии)

**Особенности**:
- Детальное сопоставление типов
- Максимальная точность координат
- Подробные подписи объектов

## 💡 Советы и рекомендации

### Подготовка данных
1. **Проверьте геометрию** - используйте инструменты QGIS для исправления ошибок
2. **Упростите атрибуты** - оставьте только нужные поля
3. **Стандартизируйте названия** - используйте поле "name" для подписей
4. **Проверьте CRS** - убедитесь в корректности системы координат

### Оптимизация производительности
1. **Ограничьте область** - экспортируйте только нужный регион
2. **Упростите геометрию** - используйте генерализацию для мелких масштабов
3. **Разделите большие слои** - создавайте отдельные слои по типам объектов
4. **Используйте фильтры** - экспортируйте только значимые объекты

### Настройка качества
1. **Правильные типы Garmin** - изучите документацию типов объектов
2. **Логичная иерархия уровней** - важные объекты на младших уровнях
3. **Осмысленные подписи** - проверьте поля с названиями
4. **Тестирование** - проверяйте результат на реальном устройстве

### Работа с большими проектами
1. **Поэтапный экспорт** - разделите проект на регионы
2. **Мониторинг ресурсов** - следите за использованием памяти
3. **Резервное копирование** - сохраняйте промежуточные результаты
4. **Документирование** - ведите описание настроек проекта

### Устранение ошибок
1. **Изучайте логи** - большинство проблем описано в сообщениях
2. **Тестируйте по частям** - экспортируйте слои по отдельности
3. **Проверяйте JSON** - используйте валидацию синтаксиса
4. **Обновляйте mkgmap** - используйте последние версии компилятора

---

🎯 **Удачного создания карт!**

При возникновении вопросов обращайтесь к автору: kobyakov@lesburo.ru
