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.

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

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.

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

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

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

python -m venv .venv

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

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

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

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

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

..\.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, но исходные точки могут оставаться в служебных метаданных.

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

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

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

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

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

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

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

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

.\.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:

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

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

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

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

dist/LEDMapper.exe

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

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

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