Files

Valentin Popov 18d4c6cf9f feat(render-parity): add deterministic frame comparison tool

- Introduced `render-parity` crate for comparing rendered frames against reference images.
- Added command-line options for specifying manifest and output directory.
- Implemented image comparison metrics: mean absolute difference, maximum absolute difference, and changed pixel ratio.
- Created a configuration file `cases.toml` for defining test cases with global defaults and specific parameters.
- Added functionality to capture frames from `render-demo` and save diff images on discrepancies.
- Updated documentation to include usage instructions and CI model for automated testing.

2026-02-19 05:02:26 +04:00

3.1 KiB

Raw Blame History

Рендер-паритет (кадровый diff)

Документ описывает процесс проверки соответствия рендера:
оригинальный движок -> эталонный кадр -> render-demo -> diff-метрики.

Цель

Зафиксировать объективный критерий "паритет достигнут / не достигнут".
Убрать субъективную визуальную оценку "похоже/не похоже".
Дать CI-проверку, которая ловит регрессии сразу после коммита.

Единица проверки

Один тест-кейс = один объект (одна модель) + фиксированная конфигурация:

архив ресурса;
имя модели;
lod;
group;
размер кадра (width, height);
угол камеры (angle);
PNG-эталон из оригинального рендера.

Инварианты детерминизма

Для корректного сравнения кадры должны быть сняты в одинаковых условиях:

одинаковый FOV и расстояние камеры до объекта;
одинаковый clear-color/фон;
одинаковые lod/group;
фиксированный угол (angle), без анимации;
фиксированное разрешение.

Метрики сравнения

Сравнение выполняется по RGB-каналам:

mean_abs: средняя абсолютная разница канала (0..255);
max_abs: максимальная разница канала;
changed_ratio: доля пикселей, где хотя бы один канал превышает diff_threshold.

Кейс считается пройденным, если:

mean_abs <= max_mean_abs;
changed_ratio <= max_changed_ratio.

Конфигурация кейсов

Файл: parity/cases.toml.

секция [meta]: глобальные дефолты;
[[case]]: параметры конкретной модели и путь к эталонному PNG.

Эталонные кадры хранятся в parity/reference/.

Локальный запуск

cargo run -p render-parity -- \
  --manifest parity/cases.toml \
  --output-dir target/render-parity/current

При расхождении утилита пишет diff-изображение в:

target/render-parity/current/diff/<case>.png

CI-модель

CI запускает render-parity на каждом push/PR:

собирает parkan-render-demo;
прогоняет кейсы из cases.toml;
при падении публикует текущие кадры и diff как артефакт.

Важно: оригинальный движок в CI обычно не запускается.
Эталонные PNG снимаются офлайн и версионируются в репозитории.

3.1 KiB Raw Blame History Unescape Escape