428 lines
24 KiB
Markdown
428 lines
24 KiB
Markdown
# Лабораторная работа 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` - компонентная архитектура приложения.
|
||
|
||
|
||
|
||
`Report/uml/zivro-render-sequence.puml` - последовательность рендера кадра.
|
||
|
||
|
||
|
||
### 10.2. Управление холстом и viewport
|
||
|
||
`Report/uml/canvas-viewport-algorithm.puml` - вычисление видимой области, масштабирование по качеству, условия редроу.
|
||
|
||
|
||
|
||
### 10.3. Алгоритмы обработки данных и растризации
|
||
|
||
`Report/uml/transform-compose-algorithm.puml` - композиция трансформаций в иерархии объектов.
|
||
|
||
|
||
|
||
`Report/uml/coordinate-pipeline.puml` - конвейер преобразований координат.
|
||
|
||
|
||
|
||
`Report/uml/line-rasterization-flow.puml` - полный алгоритм отрисовки линии.
|
||
|
||
|
||
|
||
`Report/uml/liang-barsky-clip.puml` - шаги отсечения отрезка методом Liang-Barsky.
|
||
|
||
|
||
|
||
`Report/uml/ellipse-arc-rasterization.puml` - растрирование эллипса/дуги.
|
||
|
||
|
||
|
||
`Report/uml/polyline-fill-algorithm.puml` - построение и заливка замкнутой ломаной.
|
||
|
||
|
||
|
||
`Report/uml/pma-alpha-blending.puml` - PMA alpha-композиция пикселей.
|
||
|
||
|
||
|
||
### 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-рендер с преобразованиями координат и отдельные алгоритмы растеризации геометрии.
|
||
|
||
Ключевые математические части - композиция трансформаций, отсечение и растеризация линий, рендер эллипсов/дуг, а также алгоритм заливки замкнутых контуров.
|
||
Текстовый отчёт подготовлен без встроенных листингов кода; для генерации версии с приложением исходников создан отдельный автоматизированный скрипт.
|