fixes

dissertation/chapter_3/3.10_cli_and_cache/3.10_cli_and_cache.md

@@ -0,0 +1,71 @@
+# 3.10 Параметры запуска и кэширование маршрутов
+
+Основной сценарий работы с программой задаётся через аргументы командной строки в файле `main.py`. Это позволяет запускать систему в разных режимах, выбирать источник карт, задавать координаты эксперимента и переиспользовать ранее построенные маршруты.
+
+\section{Режимы работы}
+
+Ключевым параметром является `--mode`. Он определяет, какую часть эксперимента необходимо выполнить:
+
+\begin{itemize}
+    \item `build` -- построение маршрута, сбор эталонных кадров и сохранение данных;
+    \item `run` -- запуск симуляции по ранее сохранённому маршруту;
+    \item `standalone` -- последовательное выполнение построения и запуска в одном процессе.
+\end{itemize}
+
+Разделение на режимы `build` и `run` позволяет сначала подготовить набор данных, а затем многократно запускать навигационный алгоритм на одинаковом маршруте.
+
+\section{Поддерживаемые аргументы}
+
+Программа поддерживает следующие параметры:
+
+\begin{itemize}
+    \item `--mode` -- режим работы программы: `standalone`, `build` или `run`;
+    \item `--name` -- имя маршрута, под которым сохраняются или загружаются данные;
+    \item `--lat` -- широта начальной области карты;
+    \item `--lon` -- долгота начальной области карты;
+    \item `--reference` -- источник эталонных изображений: `google` или `yandex`;
+    \item `--simulation` -- картографический источник, в котором выполняется симуляция: `google` или `yandex`;
+    \item `--ref-min-distance` -- минимальное расстояние между эталонными кадрами;
+    \item `--debug-fps` -- включение отладочного вывода, связанного со скоростью обработки кадров;
+    \item `--debug-landmark` -- включение отладочного вывода, связанного с поиском ориентиров.
+\end{itemize}
+
+Параметры `--reference` и `--simulation` могут отличаться. Это позволяет проводить эксперименты, в которых эталонные изображения получены из одного картографического сервиса, а движение моделируется в другом. Такой сценарий используется для проверки устойчивости алгоритма к различиям в цветовой палитре, детализации и способе отрисовки спутниковых снимков.
+
+\section{Кэширование маршрутов}
+
+При запуске в режиме `build` программа создаёт каталог `trajectories/<name>/`. В него сохраняются:
+
+\begin{itemize}
+    \item каталог `chunks/` с эталонными изображениями маршрута;
+    \item файл `positions.pkl` с координатами контрольных точек, позициями кадров и начальной геолокацией;
+    \item данные, необходимые для повторного запуска без повторного ручного построения маршрута.
+\end{itemize}
+
+Файл `positions.pkl` содержит словарь с полями `points`, `chunk_positions` и `initial_geolocation`. Поле `points` хранит маршрут в координатах карты, `chunk_positions` связывает сохранённые кадры с положением БПЛА, а `initial_geolocation` используется для открытия карты в той же области при повторном запуске.
+
+\section{Повторные запуски и сравнение}
+
+В режиме `run` программа загружает данные из `trajectories/<name>/`, восстанавливает список эталонных кадров и запускает симуляцию без повторного этапа разметки. Параметр `--ref-min-distance` позволяет управлять плотностью используемых ориентиров: чем больше значение, тем меньше эталонных кадров участвует в коррекции позиции.
+
+За счёт кэширования один и тот же маршрут можно использовать для серии сравнительных экспериментов. Например, можно запускать симуляцию с разными картографическими источниками, разной плотностью ориентиров или различными отладочными режимами, сохраняя неизменной геометрию маршрута и набор исходных данных.
+
+\section{Примеры запуска}
+
+Построение нового маршрута:
+
+```bash
+python main.py --mode build --name route_01 --reference google --lat 49.103814 --lon 55.794258
+```
+
+Повторный запуск по сохранённому маршруту:
+
+```bash
+python main.py --mode run --name route_01 --simulation yandex --ref-min-distance 100
+```
+
+Полный запуск без разделения на этапы:
+
+```bash
+python main.py --mode standalone --name route_02 --reference google --simulation yandex
+```

dissertation/chapter_3/3.10_cli_and_cache/readme.md

@@ -0,0 +1,3 @@
+# 3.10 Параметры запуска и кэширование маршрутов
+
+Описание параметров запуска и кэширования маршрутов находится в файле 3.10_cli_and_cache.md

dissertation/chapter_3/3.8_experiment_visualizer/3.8_experiment_visualizer.md

@@ -0,0 +1,46 @@
+# 3.8 Визуализатор эксперимента
+
+Визуализатор эксперимента используется для наблюдения за ходом симуляции и анализа качества работы алгоритма навигации. Он реализован в модуле `visualization.py` классом `VisualizationManager` и запускается в режиме выполнения маршрута.
+
+<image description="Скриншот окна визуализатора эксперимента с графиком ошибки, глобальной картой, сопоставлением признаков и областью поиска ориентиров">
+
+\section{Назначение визуализатора}
+
+Визуализатор объединяет в одном окне несколько источников диагностической информации. Это позволяет одновременно контролировать реальное положение БПЛА в симуляторе, положение, вычисленное алгоритмом визуальной одометрии, качество сопоставления кадров и динамику ошибки.
+
+В процессе эксперимента отображаются:
+
+\begin{itemize}
+    \item график погрешности позиционирования по кадрам;
+    \item глобальная карта с фактической траекторией и траекторией, восстановленной автопилотом;
+    \item текущий целевой ориентир и уже пройденные контрольные точки;
+    \item результат сопоставления признаков между последовательными кадрами;
+    \item результат сопоставления текущего кадра с ближайшим эталонным ориентиром;
+    \item визуализация движения ключевых точек и сетки гомографии.
+\end{itemize}
+
+\section{Структура окна}
+
+Окно визуализации построено как сетка из нескольких областей. Левая часть отвечает за численную и траекторную оценку: сверху расположен график ошибки, снизу -- карта перемещения. Правая и центральная части отведены под изображения, получаемые в ходе обработки кадров: сопоставление признаков, поиск ориентиров и отображение преобразования изображения.
+
+Такое размещение выбрано для того, чтобы во время запуска видеть не только итоговую метрику, но и причину изменения ошибки. Например, резкий рост погрешности можно сопоставить с отсутствием устойчивых ключевых точек или с ошибочным сопоставлением текущего кадра с эталонным.
+
+\section{Обновление данных}
+
+В режиме `run` объект `VisualizationManager` передаётся в автопилот и дополнительно обновляется из основного цикла симуляции. После обработки очередного кадра вызываются методы обновления целевого ориентира, траектории БПЛА, фактического положения и графика ошибки. Затем окно перерисовывается методом `update_display`.
+
+График ошибки строится как евклидово расстояние между координатами, рассчитанными автопилотом, и координатами симулятора. Для более удобного анализа поверх исходных значений может отображаться сглаженный тренд.
+
+\section{Использование при отладке}
+
+Визуализатор выполняет роль инструмента отладки. Он позволяет проверять:
+
+\begin{itemize}
+    \item устойчивость визуальной одометрии на соседних кадрах;
+    \item корректность выбора ближайшего ориентира;
+    \item влияние крена, тангажа и изменения масштаба на ошибку;
+    \item моменты, в которые автопилот переходит к следующей целевой точке;
+    \item расхождение между фактической траекторией и траекторией, восстановленной по изображениям.
+\end{itemize}
+
+Таким образом, визуализатор связывает численные результаты эксперимента с визуальными признаками, по которым алгоритм принимает решение.

dissertation/chapter_3/3.8_experiment_visualizer/readme.md

@@ -0,0 +1,3 @@
+# 3.8 Визуализатор эксперимента
+
+Описание визуализатора эксперимента находится в файле 3.8_experiment_visualizer.md

dissertation/chapter_3/3.9_route_editor/3.9_route_editor.md

@@ -0,0 +1,35 @@
+# 3.9 Редактор маршрута
+
+Редактор маршрута предназначен для интерактивного задания траектории полёта на спутниковом снимке. Он реализован в модуле `trajectory_drawer.py` классом `TrajectoryDrawer` и используется на этапе построения маршрута.
+
+<image description="Скриншот редактора маршрута со спутниковой картой и отмеченными контрольными точками траектории">
+
+\section{Назначение редактора}
+
+Перед запуском симуляции необходимо задать последовательность контрольных точек, по которым должен пройти БПЛА. Для этого программа сначала получает обзорный снимок местности, а затем открывает его в интерактивном окне. Пользователь кликами мыши выбирает точки маршрута, после чего редактор соединяет их линией.
+
+Такой подход удобен для экспериментов, поскольку маршрут задаётся непосредственно на изображении той области, где будет выполняться симуляция. Пользователь может быстро создавать траектории разной формы: прямолинейные, замкнутые, с поворотами или с возвращением к исходной точке.
+
+\section{Процесс построения маршрута}
+
+Построение маршрута выполняется в режиме `build`. Основные этапы:
+
+\begin{enumerate}
+    \item программа сохраняет обзорный снимок карты в файл `map.jpg`;
+    \item редактор открывает изображение и ожидает ввод точек;
+    \item каждый клик мыши добавляет новую точку маршрута;
+    \item после завершения ввода точки переводятся из координат изображения в относительные координаты;
+    \item относительные координаты преобразуются в пиксельные смещения с учётом масштаба карты.
+\end{enumerate}
+
+Завершение ввода выполняется клавишей Enter. Клавиша Escape очищает текущую траекторию, а клавиша `e` добавляет в конец маршрута первую точку, что позволяет быстро построить замкнутый контур.
+
+\section{Формат данных}
+
+Внутри редактора точки хранятся в координатах изображения: `x` соответствует горизонтальной координате пикселя, `y` -- вертикальной. После закрытия редактора функция `get_trajectory_points` нормирует координаты на ширину и высоту изображения. Это делает маршрут независимым от конкретного размера окна и позволяет затем пересчитать его в координаты выбранного картографического источника.
+
+Полученный набор точек используется автопилотом как список целевых ориентиров. На этапе построения маршрута программа также сохраняет кадры, полученные вдоль траектории, чтобы при последующих запусках использовать их как эталонные изображения.
+
+\section{Роль в эксперименте}
+
+Редактор маршрута отделяет подготовку эксперимента от его выполнения. Один раз заданная траектория может быть сохранена и затем многократно использоваться при разных параметрах симуляции. Это важно для сравнительных запусков, так как алгоритмы проверяются на одном и том же маршруте и наборе эталонных кадров.

dissertation/chapter_3/3.9_route_editor/readme.md

@@ -0,0 +1,3 @@
+# 3.9 Редактор маршрута
+
+Описание редактора маршрута находится в файле 3.9_route_editor.md

dissertation/chapter_3/_plan.md

@@ -25,6 +25,9 @@
 | 3.5 | `3.5_visualization/` | Визуализация — траектории, кадры, ошибки |
 | 3.6 | `3.6_map_providers/` | Поставщики карт — Google Maps, Яндекс.Карты |
 | 3.7 | `3.7_simulation_results/` | Результаты симуляции — метрики, выводы |
+| 3.8 | `3.8_experiment_visualizer/` | Визуализатор эксперимента — окно диагностики, графики, сопоставления |
+| 3.9 | `3.9_route_editor/` | Редактор маршрута — интерактивное задание контрольных точек |
+| 3.10 | `3.10_cli_and_cache/` | Параметры запуска и кэширование маршрутов |
 
 ## Следующие шаги
 

dissertation/chapter_3/readme.md

@@ -11,6 +11,9 @@
 | 3.5 | Визуализация | 3.5_visualization/ |
 | 3.6 | Поставщики карт | 3.6_map_providers/ |
 | 3.7 | Результаты симуляции | 3.7_simulation_results/ |
+| 3.8 | Визуализатор эксперимента | 3.8_experiment_visualizer/ |
+| 3.9 | Редактор маршрута | 3.9_route_editor/ |
+| 3.10 | Параметры запуска и кэширование маршрутов | 3.10_cli_and_cache/ |
 
 ## Описание
 
@@ -20,5 +23,7 @@
 
 - **Симулятор полёта** — моделирование движения БПЛА по заданной траектории
 - **Модуль визуализации** — отображение траекторий, кадров и результатов
+- **Редактор маршрута** — интерактивное задание контрольных точек на карте
 - **Система захвата кадров** — формирование видеопоследовательности
 - **Обработка данных ИНС** — моделирование инерциальных измерений
+- **Кэш маршрутов** — сохранение эталонных кадров и координат для повторных запусков