179 lines
8.5 KiB
Markdown
179 lines
8.5 KiB
Markdown
# 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.
|