image-blaster — скиллы для Claude, превращающие картинку в 3D-мир

Одна фотография комнаты — и из неё получается 3D-мир: с моделями мебели, со звуком шагов и фоновым гулом. Проект image-blaster делает именно это. Он не самостоятельная программа, а набор скиллов для Claude Code. Агент разбирает картинку на отдельные предметы, генерирует окружение и модели через внешние сервисы и раскладывает результат по папкам.

Заявленное время — меньше пяти минут от картинки до готовой 3D-сцены. Проект написан на TypeScript, распространяется под лицензией MIT, а в репозитории около 7000 звёзд.

Что это за проект

image-blaster — это репозиторий из двух слоёв. Первый слой: скиллы и вспомогательные агентские описания в каталоге .claude/. Второй слой: обычные Node.js-скрипты в .claude/scripts/, которые делают всю работу — ходят в API, следят за заданиями и скачивают файлы.

Внутри .claude/ лежат:

• skills/ — восемь скиллов, у каждого свой файл SKILL.md;
• agents/ — семь вспомогательных агентов, по одному на скилл;
• rules/project.md — общие правила: раскладка папок, порядок операций, правила запуска;
• hooks/ — два shell-скрипта, которые проверяют входные данные при старте;
• scripts/ — сами генераторы.

Рядом лежит каталог app/ с приложением на React — это просмотрщик готовых миров. Внутри .cursor/rules/ есть такие же правила для Cursor, так что набор можно использовать не только в Claude Code.

Быстрый старт

Установка занимает пять шагов. Нужен только Claude Code.

git clone https://github.com/neilsonnn/image-blaster
cd image-blaster

Дальше запускаем сам Claude Code:

claude

Если claude ещё не установлен, ставится одной командой:

curl -fsSL https://claude.ai/install.sh | bash

При первом запуске агенту нужны два ключа. Ключ World Labs — для генерации окружения, ключ FAL — для 3D-моделей, звука и правки картинок. Оба кладутся в файл .env, который создаётся копированием .env.example:

cp .env.example .env

В шаблоне файла два обязательных значения:

Ключи берутся на platform.worldlabs.ai и на fal.ai.

Осталось положить картинку в папку input/ и попросить агента начать. Фраза из README звучит так:

blast it and confirm each step with me

То есть агент будет спрашивать подтверждение на каждом шаге. Это полезный режим для первого прогона: видно, что именно уходит в платный API.

Что получается на выходе

По умолчанию из одной картинки собирается три вида файлов.

Окружение сохраняется не полигональной сеткой, а гауссовым сплатом. Это формат, где сцена хранится как облако раскрашенных точек с прозрачностью. Выглядит он не как обычная геометрия, зато грузится быстро и не требует ручной чистки топологии.

Разделение на подвижное и статичное — ключевая идея проекта. Мебель должна быть настоящей 3D-моделью, её можно двигать и ронять. А вот стены и пол лучше оставить «картинкой», потому что по ним никто не ходит.

Какие модели используются

Вся генерация идёт через внешние провайдеры. Своих моделей у проекта нет.

Восемь скиллов

Каждый скилл — это отдельный файл SKILL.md с описанием того, когда его звать и какие команды выполнять.

Последние шесть работают не напрямую, а через отдельных агентов в фоне. Это сделано, чтобы длинная генерация одного объекта не блокировала запуск остальных. При этом сам Node.js-скрипт внутри работает синхронно: он печатает результат в консоль и завершается. Запускать его в фоне и следить за логом не нужно.

Тексты всех восьми скиллов лежат в репозитории и открыты для чтения:

• image-blast-project
• image-blast-uncover
• image-blast-plate
• image-blast-world
• image-blast-3d
• image-blast-sfx
• image-blast-image-edit
• image-blast-wildcard

Общие правила лежат отдельно, в файле .claude/rules/project.md.

Порядок работы

Полный цикл описан в .claude/rules/project.md. Выглядит он так:

1. Смотрим состояние проекта и содержимое input/.
2. Создаём папку проекта с коротким именем и переносим входные картинки в worlds/<имя>/source/.
3. Поднимаем просмотрщик на порту 5173 командами bun install && bun run dev и открываем его пользователю.
4. Запускаем разбор картинки (image-blast-uncover).
5. Показываем пользователю найденные объекты и ждём подтверждения. После подтверждения пишем файл object.json на каждый объект.
6. Здесь же решаем, делать ли чистый план: если да, запускаем image-blast-plate и ждём результата.
7. Из самой свежей картинки (возможно, из чистого плана) генерируем мир через image-blast-world.
8. На каждый подтверждённый объект запускаем отдельного агента image-blast-3d.
9. Запускаем агентов звука: один на атмосферу и по одному на каждый объект.

Обычно на каждом шаге делается остановка и пользователю показывают результат. Если человек хочет всё сразу, шаги идут подряд без остановок — README называет этот режим «IMAGE-BLAST it».

Как выбираются объекты на картинке

Отдельная деталь: правила разбора картинки в скилле image-blast-uncover написаны строго. Именно поэтому результат получается пригодным для 3D.

• Описание должно быть буквальным, наблюдаемым. Не «уютная комната», а «серый диван у стены, слева от окна».
• Объект должен быть один и его можно отделить. В скилле есть тест: человек может этот предмет поднять руками или сдвинуть толчком. Ковёр под этот тест не проходит — он часть пола.
• Нельзя вытаскивать элементы поверхности сцены и встроенные части окружения: ковры, полы, стены, неподвижные архитектурные детали.
• Нельзя объединять предметы. Стол со стульями — это два разных объекта. Стол вместе с тем, что на нём лежит, — тоже два.

Так агент не пытается сделать одну гигантскую сцену и потом гадать, что в ней двигается.

Настройка 3D-моделей

По умолчанию для моделей используется Hunyuan 3D через FAL. У Hunyuan 3D есть четыре параметра, которые можно передать генератору.

Значения параметров означают следующее. Normal делает текстурированную модель. LowPoly уменьшает число полигонов. Geometry делает белую модель только из геометрии, без текстур — она удобна как основа, которую потом можно обложить своим материалом. polygon-type имеет смысл только в режиме LowPoly.

Перед генерацией 3D-модели агент делает промежуточный шаг: вырезает объект из исходной картинки в чистый PNG на белом фоне. В скилле задан базовый промпт для этого шага:

Isolate the <target object> from this image. Reproduce it exactly as shown --
same colors, materials, and proportions. White background, centered, tight crop,
studio lighting. No other objects, no scene, no people, no text, no shadows
on the ground. Isolate the object and remove all clustered, adjacent, overlapping,
or items resting on the target object. Create a clean render of that one single
object that is true to the source image.

Промпт требует один конкретный экземпляр предмета. Если на картинке пять одинаковых стульев, агент должен указать, какой именно нужен, и исключить остальные.

Второй провайдер — Meshy. Он включается только если попросить явно. У него своя линейка параметров: target-polycount (по умолчанию 30000), topology, symmetry-mode, should-remesh, should-texture, enable-animation, enable-rigging, enable-pbr.

Звук

Звуковые задачи делятся на три вида, и для каждого свои параметры.

С атмосферой всё просто: берутся только фоновые качества сцены из image.json — ветер, гул, шум. Звуки ударов строятся по описанию материала из object.json: дерево, стекло, металл.

Обработка тоже разная. Одиночные звуки после генерации прогоняются через ffprobe и ffmpeg: скрипт убирает тишину в начале и конце, срезает низкий шум, нормализует громкость и записывает результат анализа в служебный JSON. А вот зацикленную атмосферу оставляют как есть, без обработки. Причина простая: обрезка портит точку стыка, и петля начинает щёлкать.

Музыку и голос агенту запрещено добавлять, если его не попросили.

Куда складываются файлы

Проект строго придерживается идеи «сначала диск». Все файлы скачиваются на локальный диск, а просмотрщик читает только их. Адреса файлов на стороне провайдера сохраняются в JSON, но нужны лишь для того, чтобы возобновить прерванную загрузку.

worlds/
  <имя-проекта>/
    project.json
    scene.json
    image.json
    source/
      0-<короткое-имя>.<расширение>
      <картинка>.json
    output/
      world/
      sfx/
      <объект>/
        object.json
        sfx/

input/

scene.json хранит состояние редактора. В source/ лежат исходные картинки и разбор каждой из них. В output/ — всё сгенерированное.

У сгенерированных файлов единая схема именования:

N-короткое-имя.расширение
.N-короткое-имя-request.json

Число N — это номер поколения. Ноль означает исходник, большие числа — производные результаты. Одна генерация мира может дать сразу шесть файлов с одним номером: N-world.json, N-world-plate.png, N-world.glb, N-world-pano.png, N-world-thumbnail.webp и N-world-full_res.spz. Скрытый -request.json лежит рядом с тем файлом, который он создал.

Есть удобная проверка: если в служебном JSON прописаны адреса файлов, а самих файлов на диске нет, скрипт ensure-local-assets.mjs докачает их по этим адресам. Отдельная генерация при этом не запускается, деньги не списываются.

Встраивание в движки

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

• игровые движки — Unity, Unreal, Godot;
• программы для 3D — Blender, 3DS Max, Maya и другие;
• веб — приложение на Three.js или Electron.

Тот же каталог app/ с React-просмотрщиком можно расширять: в нём лежат компоненты панели управления, сайдбар миров, отладочная панель и модули звука. Чтобы агент мог редактировать этот код, README советует убрать строку /app из файла .claudeignore.

Что стоит знать перед запуском

Несколько вещей, о которых лучше знать заранее.

Платные запросы. Генерация идёт через платные API. Скилл image-blast-wildcard специально разделён на два режима: сначала агент находит подходящую модель через поисковый API FAL и показывает её пользователю. Платный запрос запускается только после подтверждения конкретной модели — например, после фразы confirm fal-ai/flux/dev. Это защита от случайных трат на лишние генерации.

Файлы в контекст агента. Правила запрещают читать сгенерированные картинки через Read ради проверки. Агент ориентируется на имена файлов и JSON. Визуально результат показывается открытием папки, а не загрузкой картинки в контекст.

Тон агента. В файле правил отдельным разделом прописано, что агент должен быть восторженным: подчёркивать слово IMAGE-BLASTER, сыпать сленгом про компьютерную графику, писать в основном строчными. Для личного использования это забавно. Для командного проекта понадобится правка.

Права на скрипты. Каждый скилл перечисляет в frontmatter, какие команды ему разрешено выполнять. Например, скилл звука умеет только звать три конкретных скрипта. Это ограничение удобно: агент не может случайно запустить что-то лишнее.

Итог

image-blaster интересен не самой генерацией, а тем, как он распределяет работу. Агент не пытается сделать всё сразу одной моделью. Он сначала разбирает картинку на части, потом отдельно чистит фон, отдельно строит окружение, отдельно делает каждый предмет и отдельно пишет звук. Каждая часть — отдельная модель, подходящая именно под эту задачу.

Сценарий из README звучит как шутка, но описан буквально: «IMAGE-BLAST» уровень для видеоигры, вашу детскую спальню, место для робота, локацию для кино или архитектурный рендер. С пятью минутами на результат.

Лицензия MIT, язык TypeScript, стек — Claude Code, Node.js, React. Ключи World Labs и FAL платные, но сам код открыт.