Report

Report/zivro-open-project-report.md

@@ -0,0 +1,427 @@
+# Лабораторная работа 3  
+## Анализ и описание открытого проекта `Zivro`
+
+## 1. Цель работы
+
+Изучить архитектуру и ключевые алгоритмы открытого графического проекта, реализованного на языке Zig, и подготовить технический отчёт по его устройству, процессу сборки и принципам работы основных подсистем.
+
+## 2. Постановка задачи
+
+В рамках лабораторной работы требуется:
+
+- выбрать открытый проект и изучить его структуру;
+- выделить основные модули и описать их взаимодействие;
+- разобрать математические алгоритмы, используемые в проекте;
+- описать процесс сборки, запуска и тестирования;
+- подготовить отчёт в формате Markdown;
+- сформировать приложение с исходным кодом автоматически, без ручной вставки кода в текст отчёта.
+
+## 3. Краткое описание проекта
+
+В качестве открытого проекта выбран `Zivro` - настольное графическое приложение для работы с векторными объектами (линия, эллипс, ломаная), с собственной моделью документа, иерархией объектов и CPU-рендерингом.
+
+Приложение использует:
+
+- язык `Zig`;
+- UI-библиотеку `dvui` с SDL3-бэкендом;
+- модульную архитектуру (UI, модель данных, рендер, сериализация, инструменты).
+
+Точка входа находится в `src/main.zig`: создаётся окно, инициализируется `WindowContext`, далее выполняется event/render loop.
+
+## 4. Структура проекта
+
+Основные каталоги и файлы:
+
+- `build.zig` - сценарий сборки и шагов `run`/`test`;
+- `src/main.zig` - запуск приложения и главный цикл;
+- `src/WindowContext.zig` - управление открытыми документами и активным документом;
+- `src/Canvas.zig` - логика холста, масштабирование, вычисление видимой области, запуск рендера;
+- `src/models/*` - модель документа, объектов и их свойств;
+- `src/render/*` - CPU-рендер и конвейер отрисовки;
+- `src/persistence/json_io.zig` - сохранение/загрузка документов в JSON;
+- `src/ui/*` - интерфейсные панели и компоновка экрана;
+- `src/tests.zig` - entry-point тестов.
+
+## 5. Архитектура приложения
+
+### 5.1. Высокоуровневая схема
+
+Архитектурно проект разделён на три уровня:
+
+1. **UI-уровень** (`src/ui`, `src/Canvas.zig`)  
+   Обрабатывает пользовательские события, отображает панели и холст, передаёт действия в модель и рендер.
+
+2. **Модель данных** (`src/models`)  
+   Хранит документ, дерево объектов и свойства (позиция, угол, масштаб, цвет, точки, радиусы и др.).
+
+3. **Рендер-уровень** (`src/render`)  
+   Преобразует модель объектов в набор пикселей видимой области и формирует текстуру.
+
+### 5.2. Управление документами
+
+`WindowContext` хранит массив открытых документов (`OpenDocument`) и индекс активного документа.  
+Каждый `OpenDocument` содержит:
+
+- `Document`;
+- экземпляр `CpuRenderEngine`;
+- `Canvas`;
+- идентификатор выбранного объекта.
+
+Это позволяет одновременно работать с несколькими документами во вкладках.
+
+### 5.3. Рендер-конвейер
+
+Ключевой путь рендера:
+
+1. `Canvas.redraw()` вычисляет масштаб качества и видимую часть документа;
+2. вызывается `RenderEngine.render(...)` (в текущей конфигурации CPU-вариант);
+3. `CpuRenderEngine.renderDocument(...)` подготавливает пиксельный буфер;
+4. `cpu/draw.zig` рекурсивно обходит объекты документа;
+5. для каждого объекта применяется `Transform.compose(parent, local)`;
+6. shape-специфичные модули рисуют примитивы в буфер;
+7. буфер превращается в текстуру UI.
+
+## 6. Математические алгоритмы проекта (подробное текстовое описание)
+
+В данном разделе подробно рассмотрены алгоритмы, которые формируют геометрию и цвет в CPU-рендере.  
+Диаграммы PlantUML будут добавлены отдельным шагом, после фиксации текстовой части.
+
+### 6.1. Иерархические трансформации объектов
+
+В основе рендера лежит сцена-дерево: каждый объект может иметь дочерние элементы.  
+Следовательно, координаты дочернего объекта заданы не в мировой системе, а в системе координат родителя.
+
+В `Transform` хранятся:
+
+- `position = (tx, ty)` - перенос;
+- `angle = a` - поворот;
+- `scale = (sx, sy)` - независимый масштаб по осям;
+- `opacity = o` - накопленная непрозрачность.
+
+Для перехода из локальных координат объекта к мировым используется аффинное преобразование:
+
+$$
+\begin{aligned}
+x_w &= t_x + (x_l \cdot s_x)\cos a - (y_l \cdot s_y)\sin a, \\
+y_w &= t_y + (x_l \cdot s_x)\sin a + (y_l \cdot s_y)\cos a.
+\end{aligned}
+$$
+
+При композиции `parent * local` (в `Transform.compose`) выполняются шаги:
+
+1. локальная позиция сначала масштабируется масштабом родителя;
+2. результат поворачивается на угол родителя;
+3. добавляется перенос родителя;
+4. углы складываются: `a_world = a_parent + a_local`;
+5. масштабы перемножаются покомпонентно: `sx_world = sx_parent * sx_local`, `sy_world = sy_parent * sy_local`;
+6. прозрачности перемножаются: `o_world = o_parent * o_local`.
+
+Почему это важно: такой порядок гарантирует, что при повороте/масштабе группы объектов дочерние элементы ведут себя как единая связанная конструкция.
+
+### 6.2. Цепочка преобразований координат в рендере
+
+Рендер использует 4 системы координат:
+
+1. **локальная** (внутри shape);  
+2. **мировая** (внутри документа);  
+3. **координаты канвы** (после масштабирования документа под текущий размер);  
+4. **координаты буфера viewport** (видимая часть, начинающаяся с `(0,0)`).
+
+Основные формулы:
+
+- `canvas_x = world_x * scale_x`, `canvas_y = world_y * scale_y`;
+- `buffer_x = canvas_x - visible_rect.x`, `buffer_y = canvas_y - visible_rect.y`.
+
+Обратное преобразование также используется (например, в эллипсе):
+
+- `canvas_x = buffer_x + visible_rect.x`, `canvas_y = buffer_y + visible_rect.y`;
+- `world_x = canvas_x / scale_x`, `world_y = canvas_y / scale_y`.
+
+Для вычисления локальных координат из мировых применяется обратный поворот и обратный масштаб:
+
+$$
+\begin{aligned}
+dx &= x_w - t_x,\quad dy = y_w - t_y, \\
+x_l &= \frac{dx\cos(-a)-dy\sin(-a)}{s_x}, \\
+y_l &= \frac{dx\sin(-a)+dy\cos(-a)}{s_y}.
+\end{aligned}
+$$
+
+Практический смысл: shape можно тестировать аналитически (по формулам) в "своей" удобной локальной системе, независимо от того, как он повернут и где расположен в документе.
+
+### 6.3. Рисование линии: отсечение + дискретизация + толщина
+
+Алгоритм в `line.zig` состоит из трёх частей.
+
+#### 6.3.1. Отсечение Liang-Barsky
+
+Перед рисованием линия отсекается расширенным прямоугольником буфера.  
+Параметрическая форма отрезка:
+
+$$
+P(t)=P_0+t(P_1-P_0),\quad t\in[0,1].
+$$
+
+Для каждого ограничения (`x >= left`, `x <= right`, `y >= top`, `y <= bottom`) обновляется допустимый интервал `[t0, t1]`.  
+Если после обработки ограничений `t0 > t1`, отрезок полностью вне экрана и пропускается.
+
+Преимущество: вместо "шагать по пикселям и каждый проверять границы" рендер сразу работает только с видимым отрезком.
+
+#### 6.3.2. Дискретизация линии (Bresenham-подобный проход)
+
+После отсечения используются целочисленные приращения:
+
+- `dx = abs(x1 - x0)`, `dy = -abs(y1 - y0)`;
+- `sx = sign(x1 - x0)`, `sy = sign(y1 - y0)`;
+- ошибка `err = dx + dy`.
+
+На каждом шаге:
+
+- вычисляется `e2 = 2*err`;
+- если `e2 >= dy`, двигаемся по `x`;
+- если `e2 <= dx`, двигаемся по `y`.
+
+Это классическая идея целочисленного интегрирования ошибки для аппроксимации идеального непрерывного отрезка на пиксельной сетке.
+
+#### 6.3.3. Толщина и коррекция по углу
+
+Если просто расширять линию равномерно, визуальная толщина может "плыть" при разных углах.  
+В проекте вычисляется поправка по длине проекций:
+
+- `cos(theta) = |dx| / len`;
+- `sin(theta) = |dy| / len`;
+- выбирается базис (по X или Y), где ошибка толщины минимальна;
+- итоговая толщина пересчитывается через деление на `max(sin, eps)` или `max(cos, eps)`.
+
+Далее вокруг центрального пикселя проводится полоса ширины `thickness_corrected`.
+
+Дополнительно есть режим `draw_when_outside`:
+
+- внутри viewport рисуется полная толщина;
+- за пределами viewport — только 1px, чтобы контур не "взрывался" по ширине за экраном.
+
+### 6.4. Растрирование эллипса и дуги
+
+Алгоритм `ellipse.zig` не использует инкрементальные midpoint-формулы, а работает через аналитическую проверку каждого пикселя в ограничивающем прямоугольнике.
+
+#### 6.4.1. Нормализация координат
+
+Для пикселя вычисляются локальные координаты `loc = (x_l, y_l)` и нормализуются:
+
+$$
+n_x = \frac{x_l}{r_x},\quad n_y = \frac{y_l}{r_y},\quad d=n_x^2+n_y^2.
+$$
+
+- `d = 1` соответствует идеальному контуру эллипса;
+- `d < 1` внутри;
+- `d > 1` снаружи.
+
+#### 6.4.2. Полоса обводки заданной толщины
+
+Толщина `thickness` переводится в нормированное пространство через меньшую полуось:
+
+- `half_norm = thickness / (2*min(rx, ry))`;
+- внутренний радиус: `inner = max(0, 1 - half_norm)`;
+- внешний радиус: `outer = 1 + half_norm`.
+
+Пиксель принадлежит обводке, если:
+
+$$
+inner^2 \le d \le outer^2.
+$$
+
+Это даёт геометрически корректную полосу вокруг эллипса при произвольном повороте/масштабе объекта.
+
+#### 6.4.3. Дуга через угловой фильтр
+
+Если `arc_percent < 100`, из полного эллипса берётся только часть:
+
+- вычисляется длина дуги в радианах: `arc_len = 2*pi*arc_percent/100`;
+- для пикселя находится угол через `atan2(ny, nx)` (с поправкой на экранную систему);
+- точка принимается только если её угловая позиция не превышает `arc_len`.
+
+Если `closed = true`, концы дуги соединяются с центром двумя радиальными отрезками (используется общий алгоритм линии).
+
+### 6.5. Ломаная, выделение границы и заливка
+
+В `broken.zig` ломаная строится как цепочка сегментов `P0->P1->...->Pn`, а при `closed` добавляется `Pn->P0`.
+
+Для корректной заливки применяется двухфазный алгоритм.
+
+#### 6.5.1. Фаза 1: сбор пикселей границы
+
+Во временном `FillCanvas` при каждом `blendPixelAtBuffer` сохраняется координата пикселя как граничная точка (`border_set`).
+
+Смысл: сначала зафиксировать "жёсткий" контур, затем независимо заполнить внутренность.
+
+#### 6.5.2. Фаза 2: поиск внутренних сегментов по строкам
+
+Граничные пиксели сортируются по `(y, x)`. Для каждой строки:
+
+1. выделяются последовательности рёбер;
+2. строятся интервалы между соседними рёбрами;
+3. из подходящих интервалов выбираются seed-точки (середина интервала).
+
+Это снижает риск старта flood fill с внешней стороны фигуры.
+
+#### 6.5.3. Фаза 3: flood fill (4-связность)
+
+От каждого seed выполняется стековый обход соседей:
+
+- влево, вправо, вверх, вниз;
+- граничные пиксели не пересекаются;
+- уже посещённые пиксели пропускаются.
+
+Каждый найденный внутренний пиксель окрашивается в `fill_color`.
+
+Почему используется отдельный буфер: при полупрозрачности иначе одна и та же область может смешаться несколько раз из-за пересечения сегментов.
+
+### 6.6. Альфа-смешивание в Premultiplied Alpha (PMA)
+
+Для каждого канала цвета применяется модель:
+
+$$
+C_{out} = C_{src} + (1-\alpha_{src})C_{dst},
+\quad
+\alpha_{out} = \alpha_{src} + (1-\alpha_{src})\alpha_{dst}.
+$$
+
+В коде `C_src` уже premultiplied (или домножается на opacity трансформа в момент смешивания).
+
+Пошагово:
+
+1. берётся альфа источника `a = src_a/255 * transform.opacity`;
+2. вычисляется `inv_a = 1 - a`;
+3. каналы `r,g,b` источника масштабируются на `transform.opacity`;
+4. формируется новый `dst` по PMA-формуле.
+
+`replace_mode = true` отключает смешивание и просто заменяет пиксель.  
+Этот режим используется во временных буферах shape-рендера, а затем результат один раз композится в целевой буфер.
+
+### 6.7. Численная устойчивость и ограничения
+
+В алгоритмах предусмотрены защиты от деградации вычислений:
+
+- защита от деления на ноль в обратных преобразованиях (`scale == 0 -> 1.0`);
+- использование `eps` в коррекции толщины линий;
+- ограничение минимальных размеров рендер-буфера (`>= 1 px`);
+- отсечение слишком больших выходов за viewport до начала растрирования;
+- явное округление float->int в точках, где нужна стабильная пиксельная привязка.
+
+Это снижает число визуальных артефактов при малых масштабах, сильных поворотах и частичной видимости объектов.
+
+## 7. Работа с данными и сериализация
+
+Модуль `src/persistence/json_io.zig` поддерживает:
+
+- `saveToFile(...)` - сериализация в JSON (pretty-print);
+- `loadFromFile(...)` - чтение JSON и восстановление структуры.
+
+Для `Document` после парсинга выполняется клонирование, чтобы избежать проблем владения памятью (парсер выделяет память из арены).
+
+## 8. Сборка, запуск и тестирование
+
+### 8.1. Сборка и запуск
+
+```bash
+zig build
+zig build run
+```
+
+### 8.2. Запуск тестов
+
+```bash
+zig build test
+```
+
+Файл `src/tests.zig` подключает модули с `test`-блоками, чтобы они выполнялись в составе общего тестового шага.
+
+## 9. Автоматическое формирование приложения с исходным кодом
+
+Чтобы не вставлять исходники вручную в конец отчёта, используется скрипт `Report/append_sources_to_report.py`.
+
+Скрипт:
+
+- читает исходный `.md` отчёт;
+- добавляет раздел с кодом файлов проекта;
+- перед каждым листингом вставляет путь файла;
+- сохраняет результат в новый `.md` файл;
+- исходный отчёт не изменяет.
+
+Пример запуска:
+
+```bash
+python3 Report/append_sources_to_report.py \
+  --input Report/zivro-open-project-report.md \
+  --output Report/zivro-open-project-report-with-code.md \
+  --base .
+```
+
+## 10. PlantUML-диаграммы
+
+Для отчёта подготовлены диаграммы в формате PlantUML (`.puml`) и сгенерированы их PNG-версии для прямой вставки в документ.
+
+### 10.1. Архитектура проекта
+
+`Report/uml/zivro-architecture-components.puml` - компонентная архитектура приложения.
+
+![Компонентная архитектура Zivro](uml/zivro-architecture-components.png)
+
+`Report/uml/zivro-render-sequence.puml` - последовательность рендера кадра.
+
+![Последовательность рендера кадра](uml/zivro-render-sequence.png)
+
+### 10.2. Управление холстом и viewport
+
+`Report/uml/canvas-viewport-algorithm.puml` - вычисление видимой области, масштабирование по качеству, условия редроу.
+
+![Алгоритм управления viewport и redraw](uml/canvas-viewport-algorithm.png)
+
+### 10.3. Алгоритмы обработки данных и растризации
+
+`Report/uml/transform-compose-algorithm.puml` - композиция трансформаций в иерархии объектов.
+
+![Композиция трансформаций](uml/transform-compose-algorithm.png)
+
+`Report/uml/coordinate-pipeline.puml` - конвейер преобразований координат.
+
+![Конвейер преобразований координат](uml/coordinate-pipeline.png)
+
+`Report/uml/line-rasterization-flow.puml` - полный алгоритм отрисовки линии.
+
+![Полный алгоритм растрирования линии](uml/line-rasterization-flow.png)
+
+`Report/uml/liang-barsky-clip.puml` - шаги отсечения отрезка методом Liang-Barsky.
+
+![Алгоритм Liang-Barsky](uml/liang-barsky-clip.png)
+
+`Report/uml/ellipse-arc-rasterization.puml` - растрирование эллипса/дуги.
+
+![Алгоритм растрирования эллипса и дуги](uml/ellipse-arc-rasterization.png)
+
+`Report/uml/polyline-fill-algorithm.puml` - построение и заливка замкнутой ломаной.
+
+![Алгоритм ломаной и заливки](uml/polyline-fill-algorithm.png)
+
+`Report/uml/pma-alpha-blending.puml` - PMA alpha-композиция пикселей.
+
+![PMA alpha-композиция пикселя](uml/pma-alpha-blending.png)
+
+### 10.4. Скрипт генерации PNG-диаграмм
+
+Для повторной генерации PNG сохранён отдельный скрипт:
+
+- `Report/render_uml_png.py`
+
+Пример запуска в высоком качестве:
+
+```bash
+python3 Report/render_uml_png.py --input-dir Report/uml --dpi 360
+```
+
+## 11. Выводы
+
+В ходе работы изучен открытый проект `Zivro` и подготовлено структурированное описание его архитектуры. Проект реализует модульный подход: модель документа, иерархию объектов, CPU-рендер с преобразованиями координат и отдельные алгоритмы растеризации геометрии.
+
+Ключевые математические части - композиция трансформаций, отсечение и растеризация линий, рендер эллипсов/дуг, а также алгоритм заливки замкнутых контуров.  
+Текстовый отчёт подготовлен без встроенных листингов кода; для генерации версии с приложением исходников создан отдельный автоматизированный скрипт.