Pixel Motion Lab

Локальное Windows-приложение, которое превращает сетку состояний пиксельного объекта, полученную через генерацию изображения в ChatGPT, в строгие кадры с общей палитрой и готовит их для Aseprite. Приложение не использует ChatGPT API.

Что это и какой результат получается

Pixel Motion Lab помогает превратить один пиксельный PNG и набор состояний, сгенерированных вручную через ИИ, в аккуратную анимацию. Программа создаёт шаблон с сеткой, принимает результат генерации, восстанавливает прозрачность и общую палитру, а затем экспортирует готовые кадры для Aseprite, sprite sheet или GIF.

Ниже — один и тот же пример по шагам: исходный спрайт, рабочее окно приложения и готовая GIF-анимация (экспорт с увеличением 8×).

1. Исходный спрайт

2. Шаблон для генерации состояний

Этот шаблон передаётся в ChatGPT вместе с техническим промптом: зелёный цвет — служебный фон-ключ, белые рамки разделяют рабочие ячейки и не являются частью объекта.

3. Работа в Pixel Motion Lab

4. Готовая анимация

Что уже работает

• создание переносимого мини-проекта и повторное открытие project.json;
• анализ прозрачности, непрозрачных границ и палитры исходного PNG;
• автоматический подбор сетки, холста и целочисленного масштаба;
• версионные шаблоны 1024×1024, 1536×1024 и 1024×1536;
• русский технический промпт, зависящий от настроек проекта;
• импорт PNG кнопкой или drag-and-drop без перезаписи предыдущих генераций;
• математическая нарезка, фон-ключ, бинарная прозрачность, RGB/OKLab mapping;
• central, majority и weighted-majority восстановление блоков и поиск фазы сетки;
• фоновая обработка, Raw/Processed preview и диагностика неоднозначных пикселей;
• порядок, включение, удаление, дублирование и hold frames в ленте;
• loop, reverse и ping-pong воспроизведение;
• отдельные PNG, horizontal/vertical/compact sprite sheet, GIF и .gpl/JSON-палитры;
• создание .aseprite через установленный Aseprite и Lua с реальными длительностями.

Запуск в Windows 11

Требуются Python 3.12 и PowerShell 7. Все команды выполняются из корня репозитория:

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e ".[dev]"
.\.venv\Scripts\python.exe -m pixel_motion_lab

После установки также доступна команда:

.\.venv\Scripts\pixel-motion-lab.exe

Открыть конкретный проект можно так:

.\.venv\Scripts\python.exe -m pixel_motion_lab --project "D:\Sprites\cat\project.json"

Рабочий процесс

1. Нажмите Новый проект, выберите исходный прозрачный PNG, затем в открывшемся нативном проводнике Windows создайте или выберите папку проекта. Рекомендуемое место: projects\<имя-анимации> внутри этого репозитория.
2. Укажите количество состояний и создайте шаблон. При масштабе Авто приложение выберет максимальный целочисленный масштаб и подходящий пресет холста.
3. Опишите движение, настройте ограничения и скопируйте готовый промпт.
4. Передайте PNG из templates/ и промпт в ChatGPT вручную.
5. Импортируйте результат через верхнюю кнопку или перетащите PNG в окно.
6. Нажмите Обработать. Несовпадающий размер никогда не исправляется молча.
7. Проверьте Raw/Processed, палитру, неоднозначные пиксели и цикл анимации.
8. Настройте порядок, активность и hold frames, затем экспортируйте PNG или sheet.
9. Кнопка Открыть в Aseprite создаст .aseprite, а Экспорт GIF предложит масштаб 1×–8× и сохранит анимацию с длительностями hold frames; при ошибке Aseprite подготовленные PNG останутся в exports/aseprite/.

hold frames материализуется повторением изображений в PNG/sprite sheet. В Aseprite логический кадр хранится один раз, а длительность равна базовой длительности, умноженной на hold frames.

Для новых проектов базовая длительность кадра по умолчанию — 100 мс. Масштаб предпросмотра можно задавать дробным значением от 0.1×; шаблон открывается в масштабе 1×.

Для новых проектов сопоставление цветов по умолчанию выполняется в RGB, а допуск фона равен 0.100.

Проверки и сборка

.\.venv\Scripts\python.exe -m pytest
.\.venv\Scripts\ruff.exe check src tests
.\.venv\Scripts\ruff.exe format --check src tests
.\.venv\Scripts\mypy.exe src
.\.venv\Scripts\python.exe -m build
$env:QT_QPA_PLATFORM = "offscreen"
.\.venv\Scripts\python.exe -m pixel_motion_lab --smoke-test

Сборка создаёт wheel и source archive в dist/. Standalone EXE пока не входит в MVP.

Формат мини-проекта

project-name/
├── original/
├── templates/
├── generated/
├── processed/
├── exports/
├── palettes/
├── previews/
└── project.json

Все пути в project.json относительные. Исходник и импортированные генерации не изменяются; каждый повторный запуск обработки получает отдельный каталог. Подробности: формат проекта, алгоритмы и интеграция с Aseprite.

Ограничения MVP

• свободная область движения ограничена исходным холстом W×H;
• результата с отличающимся размером можно только явно привести nearest-neighbour;
• нет встроенного пиксельного редактора, ChatGPT API, standalone EXE и сравнения двух генераций рядом;
• watcher папки и общие пресеты оставлены для следующего этапа.