160 lines
16 KiB
Markdown
160 lines
16 KiB
Markdown
# Улучшение графики локальной нейросетью (дизайн)
|
||
|
||
Клиент у себя поднимает генератор изображений (SwarmUI; также ComfyUI и A1111), браузер ходит к нему
|
||
напрямую — как к `local-translator` ([LOCALIZATION.md](LOCALIZATION.md)). Сервер библиотеки о генераторе
|
||
не знает; он получает только готовые файлы через уже существующую замену ассетов в моде
|
||
(`PUT /api/versions/{id}/asset`, [MODDING.md](MODDING.md)).
|
||
|
||
Два режима поверх одного движка задач:
|
||
|
||
| Режим | Что делает | Где хранится результат | Видят другие |
|
||
|---|---|---|---|
|
||
| **На лету** | плеер подменяет картинку при показе на улучшенную | IndexedDB браузера, на сервер ничего не уходит | нет |
|
||
| **В исходниках** | редактор «Улучшение графики» массово обрабатывает файлы мод-форка | блобы мода (через замену ассета) | да, как обычный мод |
|
||
|
||
## Схема
|
||
|
||
```
|
||
Браузер ──► SwarmUI / ComfyUI / A1111 (127.0.0.1, разрешён CORS для сайта)
|
||
│
|
||
├─ IndexedDB: кэш результатов key = версия|путь|хэш оригинала|хэш пресета
|
||
├─ плеер: engine.fileUrl() → кэш, если есть улучшение
|
||
└─ редактор: результат → PUT /asset (мод-форк), по одному файлу
|
||
```
|
||
|
||
## Модули клиента (`frontend/src/imager/`)
|
||
|
||
* `backends/` — интерфейс `ImageBackend { health(), models(), process(png, preset, signal) → Blob }`
|
||
и адаптеры `swarm.ts` (основной: `GetNewSession`, `GenerateText2Image` с `initimage`,
|
||
`refinerupscale`/`refinerupscalemethod`, `ListT2IParams`), `comfy.ts`, `a1111.ts`.
|
||
* `presets.ts` — пресет = бэкенд + режим (`upscale` | `img2img`) + параметры (модель, апскейлер,
|
||
множитель, creativity, prompt/negative, steps, cfg). Хранится в localStorage, экспорт в JSON.
|
||
`hash(preset)` входит в ключ кэша.
|
||
* `queue.ts` — очередь задач: параллелизм 1 (GPU), отмена, повтор, возобновление после
|
||
перезагрузки (журнал в IndexedDB), прогресс.
|
||
* `cache.ts` — IndexedDB: `{key, blob, scale}`; очистка по версии.
|
||
* `ImagerSetup.tsx` — страница настройки, как `TranslatorSetup` (проверка связи, CORS-подсказка).
|
||
* `ImageEnhance.tsx` — редактор массовой обработки (ниже).
|
||
|
||
## Масштаб изображения (важно)
|
||
|
||
Плеер рисует `<img>` в натуральном размере (`renderer.ts`), поэтому ×2 апскейл без поправки покажется
|
||
вдвое больше. Решение: у каждой улучшенной картинки хранится `scale` (отношение новой ширины к исходной).
|
||
|
||
* на лету — `scale` лежит в записи кэша;
|
||
* в исходниках — `game.json → assetScale: { "images/bg room.webp": 2 }` (проверяется `mods.validate`);
|
||
* рендерер: после загрузки `width = naturalWidth / scale` для `<img>` без явного размера;
|
||
размеры из `def.size`, ATL и масок масштабом не затрагиваются.
|
||
|
||
Это единственное изменение плеера и схемы PGVN; без него замена файла на файл другого размера ломает вёрстку.
|
||
|
||
## Режим «на лету»
|
||
|
||
Хук в `Engine.fileUrl()`: если для `(версия, логический путь)` в кэше есть результат — возвращается
|
||
`blob:` URL (создаётся один раз, освобождается в `destroy`). Предзагрузка ближайших картинок уже
|
||
использует `fileUrl`, поэтому работает без изменений. Фоновая обработка: при показе картинки без улучшения
|
||
в очередь ставится её задача (опция «улучшать по ходу игры»), результат подхватывается при следующем показе.
|
||
Переключатель «оригинал / улучшенное» в меню плеера для сравнения.
|
||
|
||
## Режим «в исходниках» (редактор)
|
||
|
||
Страница доступна для `kind=mod` с `versions.fork`:
|
||
|
||
1. Список изображений версии (фильтр по папке/размеру/уже обработанные), миниатюры.
|
||
2. Выбор пресета, предпросмотр «до/после» на одном файле (слайдер).
|
||
3. Запуск пачки: для каждого файла — скачать оригинал → бэкенд → превью в списке → при «Применить»
|
||
загрузка в мод. Загрузка последовательная (каждая замена меняет `revision`; клиент берёт
|
||
актуальную из ответа). Для скорости позже — один пакетный эндпоинт `POST …/assets` с одной ревизией.
|
||
4. Откат — обычная история ревизий; «вернуть оригинал» = восстановление блоба из родителя.
|
||
|
||
## Что нужно поменять на сервере
|
||
|
||
* `converter/assets._image`: не пересжимать результат повторно в WebP q88 (потеря качества после
|
||
апскейла). Для замены из этого редактора принимать PNG/WebP без перекодирования лосслесс-веткой
|
||
(параметр `lossless=1` в `/asset`).
|
||
* лимит `WEBP_MAX = 16383`: при апскейле ×4 больших фонов результат уйдёт в PNG — предупреждать в UI.
|
||
* `assetScale` в `game.json` и его проверка в `mods.validate`.
|
||
* пакетный эндпоинт замены ассетов (вторая очередь работ).
|
||
|
||
## Риски и открытые вопросы
|
||
|
||
* **CORS**: проверить, какие заголовки отдают SwarmUI/ComfyUI/A1111 при запросах с чужого origin;
|
||
страница настройки должна объяснять флаг (`--enable-cors-header`, `--cors-allow-origins`, настройка Swarm).
|
||
Mixed content: сайт по https → локальный http; Chrome разрешает для `127.0.0.1`, Safari нет.
|
||
* **Качество**: img2img на персонажах с альфой — нейросеть не сохраняет прозрачность. Для спрайтов
|
||
режим «только апскейлер» (модель ESRGAN-типа) с отдельной обработкой альфа-канала (апскейл
|
||
маски обычным ресайзом, цвета — моделью). Это должно быть в первой версии, иначе спрайты получат ореол.
|
||
* **Анимации** (animated WebP) и видео — вне первой версии.
|
||
* **Права на результаты**: производные изображения остаются в моде пользователя, в публичные версии
|
||
не попадают без `versions.publish`.
|
||
|
||
## Этапы
|
||
|
||
1. Каркас: `imager/` (клиент SwarmUI, пресеты, очередь, кэш), `ImagerSetup`.
|
||
2. `assetScale` в схеме, рендерере и валидаторе; режим «на лету» в плеере.
|
||
3. Редактор массовой обработки + загрузка в мод + лосслесс-замена.
|
||
4. Адаптеры ComfyUI и A1111, обработка альфы, пакетный эндпоинт.
|
||
|
||
## Реализация (25 октября 2026)
|
||
|
||
Добавлены все четыре группы функций:
|
||
|
||
* `/imager` — настройка локального генератора, проверка API из браузера, список моделей и
|
||
апскейлеров, пресеты с импортом/экспортом JSON. Последний сохранённый пресет используется плеером.
|
||
* `frontend/src/imager/` — адаптеры SwarmUI, ComfyUI и A1111, общая очередь, журнал и кэш
|
||
IndexedDB. Ключ включает ID версии, логический путь, хэш исходного блоба и SHA-256 параметров
|
||
пресета (включая адрес генератора и фиксированный seed). Переименование пресета кэш не меняет.
|
||
* Плеер PGVN: Настройки → Графика → «Показывать улучшенные изображения» и отдельно
|
||
«Улучшать по ходу игры». Переключатели сохраняются по версии. По умолчанию оба выключены.
|
||
Завершённые задания подхватываются при следующем показе изображения; URL освобождаются при закрытии.
|
||
* `/versions/:versionId/enhance` — выбор картинок, фильтры пути/размера файла/готовности,
|
||
выбор пресета, сравнение слайдером, обработка выбранных файлов и отдельное применение.
|
||
Открывается из редактора мода или его карточки. Применять можно только в доступный для
|
||
редактирования черновик. Ошибки ревизий не удаляют локальные результаты.
|
||
* `PUT /api/versions/{id}/asset?lossless=1&scale=2` сохраняет проверенные статичные PNG/WebP
|
||
без повторного сжатия. `scale` — полный масштаб относительно исходных игровых координат,
|
||
поэтому повторный апскейл умножает прежний `assetScale`. Файл и метаданные пишутся одной ревизией.
|
||
Обычная ручная замена без `scale` сбрасывает прежний масштаб этого файла.
|
||
* `POST /api/versions/{id}/assets`: JSON `{revision, assets: [{path, filename, data, scale}]}`,
|
||
где `data` — base64 без префикса data URL. Максимум 32 картинки / 128 МБ запроса; редактор
|
||
дополнительно ограничивает группу 80 МБ исходных блобов. Каждый пакет атомарен и создаёт одну
|
||
ревизию. При ошибке файлы версии и её ревизия не меняются.
|
||
* `POST /api/versions/{id}/asset/restore`: `{revision, path}` возвращает файл **из замороженной
|
||
базовой ревизии форка**, вместе с прежним масштабом. Для отката пачки также доступна история мода.
|
||
* Альфа-канал масштабируется отдельно в браузере и возвращается в итоговый PNG. Img2img
|
||
прозрачных изображений отклоняется с предложением выбрать апскейлер. Анимации отклоняются,
|
||
а не превращаются незаметно в первый кадр. Изменение пропорций генератором также отклоняется.
|
||
|
||
Отмена активного задания отбрасывает его результат, но ждёт завершения запроса перед стартом
|
||
следующего: глобальный interrupt генератора мог бы остановить чужую работу. После перезагрузки
|
||
незавершённые задания видны в журнале и запускаются кнопкой «Повторить». При наличии Web Locks
|
||
очередь сериализует GPU-запросы также между вкладками этого сайта. При очистке кэша нужно закрыть
|
||
плеер, чтобы освободить уже загруженные в память blob-URL.
|
||
|
||
Текущие адаптеры рассчитаны на локальные API без обязательной авторизации. Прямые обращения
|
||
генератора не проксируются через сервер библиотеки. Для SwarmUI настройка CORS называется
|
||
`Network.AccessControlAllowOrigin`; для ComfyUI — `--enable-cors-header ORIGIN`,
|
||
для A1111 — `--api --cors-allow-origins ORIGIN`. Страница настройки проверяет доступ к API,
|
||
а скачивание результата проверяется первым пробным заданием. Реальный SwarmUI на
|
||
`127.0.0.1:7801` при разработке не отвечал: GPU-генерация и CORS установленного сервиса пока
|
||
не подтверждены. Протоколы адаптеров покрыты тестовыми HTTP-ответами.
|
||
|
||
Проверки: `frontend/tests/imager.test.mjs`, `frontend/tests/imager-browser.test.mjs`
|
||
(опциональный Playwright/Chromium, как существующие браузерные тесты),
|
||
`backend/tests/test_image_enhance.py`. Браузерный тест проверяет реальные пиксели альфы,
|
||
геометрию `<img>`, сохранность IndexedDB после перезагрузки, освобождение URL и отсутствие
|
||
загрузок на сервер в локальном режиме.
|
||
|
||
Результат проверки реализации: 9 клиентских тестов imager, 13 серверных тестов
|
||
imager/mods и отдельный тест Chromium проходят; production-сборка и Ruff проходят.
|
||
Интеграционный тест с PostgreSQL пропущен без `TEST_POSTGRES`. В полном клиентском
|
||
наборе отдельно воспроизводится сбой изменённого теста интерпретатора Ren'Py
|
||
`interpreted instances can own arguments without exposing host function properties`
|
||
(`frontend/tests/renpy-runtime.test.mjs`, неизвестное имя `list`); этот тест не импортирует imager.
|
||
|
||
Первичная документация протоколов:
|
||
[SwarmUI API](https://github.com/mcmonkeyprojects/SwarmUI/blob/master/docs/API.md),
|
||
[параметры SwarmUI](https://github.com/mcmonkeyprojects/SwarmUI/blob/master/docs/APIRoutes/T2IAPI.md),
|
||
[ComfyUI API](https://github.com/comfyanonymous/ComfyUI/blob/master/script_examples/basic_api_example.py),
|
||
[A1111 API](https://github.com/AUTOMATIC1111/stable-diffusion-webui/blob/master/modules/api/models.py).
|