# LED Mapper

LED Mapper — настольное приложение на Python и PySide6 для разметки LED-точек на схеме, распределения их по физическим линиям светодиодных лент и генерации `vm_map.h` для прошивки.

Приложение помогает вручную или полуавтоматически собрать адресацию светодиодов: выбрать точки на схеме, создать линии, разбить их на блоки, проверить индексацию и сгенерировать готовые файлы маппинга.

## Возможности

- Загрузка карты LED-точек из JSON.
- Отображение схемы в реальных координатах.
- Выделение точек мышью и работа через таблицу выбранных LED.
- До 4 физических линий светодиодных лент.
- Блоки внутри линий, включая пустые блоки.
- Индексация LED отдельно для каждой линии, начиная с `0`.
- Индексация внутри каждого блока.
- Добавление блоков вручную, из выделения, автоблоками и кистью.
- Продолжение существующего блока кистью от последней точки блока.
- Предпросмотр зоны действия кисти и точек, которые будут добавлены.
- Сетка 34 мм.
- Undo/redo для операций разметки.
- Удаление назначений через `Del` и контекстные меню.
- Сворачивание боковой панели.
- Сортировка таблицы выбранных точек по столбцам.
- Генерация `vm_map.h`, `virtual_matrix_legacy.ino.txt`, `ordered_circles.json`, `validation_report.txt` и README для результата.
- Сборка самостоятельного Windows EXE через PyInstaller.

## Структура приложения

```text
main.py                    Точка входа GUI-приложения
main_window.py             Главное окно, меню, действия, таблица и дерево линий
canvas.py                  Холст схемы, выделение, кисть, сетка и связи
models.py                  Модель карты, линий, блоков и алгоритмы маршрутов
panel_mapping_generator.py Генерация файлов маппинга
icons.py                   Встроенные lucide-иконки
unfolding.py               Описание развертки линий и блоков
qa_smoke.py                Smoke-тесты приложения
requirements.txt           Runtime-зависимости
LEDMapper.spec             PyInstaller-конфигурация для сборки EXE
```

## Требования

- Windows.
- Python 3.10 или новее.
- PySide6.

Для разработки и запуска используется локальное виртуальное окружение проекта.

## Быстрый старт

Из корневой папки проекта создайте окружение:

```powershell
python -m venv .venv
```

Установите зависимости:

```powershell
.\.venv\Scripts\python.exe -m pip install -r app\requirements.txt
```

Запустите приложение:

```powershell
.\.venv\Scripts\python.exe app\main.py
```

Если вы находитесь внутри папки `app`, запуск выглядит так:

```powershell
..\.venv\Scripts\python.exe main.py
```

## Основной сценарий работы

1. Откройте JSON-карту точек через `Файл -> Открыть`.
2. Создайте линию кнопкой `Линия` или через меню `Инструменты -> Новая линия`.
3. Выберите точки на схеме или в таблице.
4. Создайте блок из выбранных точек, автоблоки или включите инструмент `Кисть`.
5. Повторите разметку для остальных линий и блоков.
6. Проверьте счетчики в верхней части боковой панели: количество линий, блоков и назначенных LED.
7. Сгенерируйте скрипт через `Файл -> Сгенерировать скрипт`.

Если не назначен ни один светодиод, генерация не запускается. Если назначены не все светодиоды, приложение показывает предупреждение и предлагает либо сгенерировать неполный маппинг, либо продолжить редактирование.

## Горячие клавиши

| Действие | Клавиши |
| --- | --- |
| Открыть | `Ctrl+O` |
| Сохранить | `Ctrl+S` |
| Сохранить как | `Ctrl+Shift+S` |
| Сгенерировать скрипт | `Ctrl+G` |
| Отменить | `Ctrl+Z` |
| Повторить | `Ctrl+Y` |
| Удалить фиксацию | `Del` |
| Удалить все | `Ctrl+Shift+Del` |
| Очистить выбор | `Esc` |
| Показать всю схему | `Ctrl+0` |
| Сетка 34 мм | `G` |
| Стрелки направления | `Ctrl+Shift+A` |
| Скрыть/показать боковую панель | `F9` |
| Новая линия | `Ctrl+L` |
| Автоблоки | `Ctrl+Shift+B` |
| Кисть | `B` |

## Генерация файлов маппинга

Генератор создает:

- `vm_map.h` — основной header для прошивки.
- `virtual_matrix_legacy.ino.txt` — читаемая legacy-версия с `setLEDs(...)`.
- `ordered_circles.json` — нормализованные точки и координаты виртуальной матрицы.
- `validation_report.txt` — отчет о проверках маршрутов и ячеек.
- `README.md` — краткое описание результата генерации.

В `vm_map.h` используются физические адреса из GUI:

- `strip = line_id - 1`
- `led_id = line_index`

Неназначенные точки не попадают в рабочий `VM_MAPPINGS`, но исходные точки могут оставаться в служебных метаданных.

## Ориентация виртуальной матрицы

Текущий формат явно описывает преобразование координат:

```cpp
#define VM_ROW_FROM_GRID_COL(col) (GRID_COL_MAX - (col))
#define VM_COL_FROM_GRID_ROW(row) ((row) - GRID_ROW_MIN)
```

То есть строка виртуальной матрицы получается из исходной колонки с отражением, а колонка виртуальной матрицы получается из исходного ряда.

## Проверка качества

Из корня проекта:

```powershell
.\.venv\Scripts\python.exe app\qa_smoke.py
```

Проверка компиляции основных модулей:

```powershell
.\.venv\Scripts\python.exe -m py_compile app\main.py app\main_window.py app\canvas.py app\models.py app\panel_mapping_generator.py app\qa_smoke.py
```

## Сборка EXE

Установите PyInstaller в `.venv`:

```powershell
.\.venv\Scripts\python.exe -m pip install pyinstaller
```

Сборка из корня проекта:

```powershell
.\.venv\Scripts\python.exe -m PyInstaller --noconfirm --clean app\LEDMapper.spec
```

Готовый файл появится здесь:

```text
dist/LEDMapper.exe
```

`build/` и `dist/` не коммитятся, потому что это воспроизводимые артефакты сборки.

## Примечания для разработки

- Для работы с приложением использовать только Python из `.venv`.
- Не коммитить `.venv`, `build`, `dist`, `output` и `__pycache__`.
- Перед коммитом желательно запускать `app\qa_smoke.py`.
- Максимальное количество линий светодиодных лент: 4.