image-blaster: 이미지 한 장에서 3D 환경과 효과음을 만들어내는 Claude 스킬셋

읽을거리&정보공유
, , , , , ,
1

image-blaster: 이미지 한 장에서 3D 환경과 효과음을 만들어내는 Claude 스킬셋
image-blaster: 이미지 한 장에서 3D 환경과 효과음을 만들어내는 Claude 스킬셋1536×1024 380 KB

image-blaster 소개

사진 한 장을 3D 공간으로 옮기는 작업은 이미 여러 생성 모델이 각자 한 조각씩 담당하고 있습니다. 단일 이미지에서 메시를 뽑는 모델이 있고, 파노라마나 가우시안 스플랫으로 공간을 만드는 모델이 있고, 텍스트에서 효과음을 만드는 모델이 따로 있습니다. 문제는 그 사이를 잇는 일이 전부 사람 몫이라는 점입니다. 어떤 물체를 개별 오브젝트로 뽑을지 고르고, 그 물체를 지운 배경 이미지를 따로 만들고, 각 모델의 요청 형식과 폴링 코드를 쓰고, 결과 파일을 프로젝트 폴더에 정리하는 과정이 매번 반복됩니다. image-blaster는 그 접합부를 Claude Code 스킬로 고정해, 이미지 한 장을 넣으면 탐색 가능한 3D 환경과 3D 오브젝트, 효과음까지 한 흐름으로 만들어내는 저장소입니다.

Neilson Koerner-Safrata가 공개한 이 저장소는 라이브러리가 아니라 작업 환경 자체 입니다. 저장소를 클론한 뒤 그 안에서 claude 를 실행하면, 저장소에 들어 있는 여덟 개의 스킬과 에이전트 정의, 노드 스크립트가 Claude의 작업 지침이 됩니다. 사용자는 input/ 디렉토리에 이미지를 넣고 "blast it and confirm each step with me" 처럼 말하면 되고, 실제 모델 호출은 World Labs와 FAL 두 곳의 API 키로 이뤄집니다. 저자는 이미지 한 장에서 메시까지 갖춘 3D 환경에 5분 이내로 도달할 수 있다고 설명합니다.

기본 설정에서 만들어지는 산출물은 세 종류입니다. 움직일 수 있는 물체는 .glb·.obj 3D 모델로, 정적인 배경 공간은 가우시안 스플랫(Gaussian Splat) 형식인 .spz 로, 소리는 환경 앰비언스 루프와 물체별 충돌음 .mp3 로 각각 생성됩니다. 저장소에는 결과를 바로 확인할 수 있는 React·Three.js 기반 뷰어(app/)도 함께 들어 있어, 생성한 스플랫과 메시를 브라우저에서 걸어 다니며 볼 수 있습니다.

기존 방식의 한계와 image-blaster의 접근

단일 이미지 3D 생성 도구를 써 본 사람이라면 결과물이 대개 하나의 메시 로 끝난다는 점을 알고 있습니다. 방 사진을 넣으면 방 전체가 한 덩어리 메시가 되어, 의자를 집어 옮기거나 물체마다 다른 물리 재질을 주는 식의 후속 작업이 어렵습니다. 게임 엔진이나 DCC 소프트웨어로 가져가려면 결국 사람이 물체를 잘라내고 배경을 메우는 작업을 다시 해야 합니다.

image-blaster는 이 문제를 "분해 후 각각 생성"으로 풉니다. 먼저 이미지를 읽어 개별 오브젝트로 분리할 수 있는 물체 만 후보로 추립니다. 이때의 판단 기준이 구체적인데, "사람이 들어 올리거나 밀어서 옮길 수 있는가" 를 분리 가능성 테스트로 쓰고, 러그·바닥·벽처럼 환경에 붙어 있는 요소는 오브젝트로 뽑지 않습니다. 책상과 의자를 묶어 하나의 자산으로 만드는 복합 오브젝트도 금지합니다. 확정된 오브젝트는 원본 이미지에서 지워져 클린 플레이트(Clean Plate)가 되고, 그 빈 배경이 환경 생성의 입력이 됩니다. 결과적으로 배경 공간과 물체가 처음부터 분리된 자산으로 만들어집니다.

단계 생성 대상 사용 모델 출력 형식
이미지 분석 장면 설명, 오브젝트 후보 Claude 자체 이미지 이해 JSON
클린 플레이트 오브젝트를 지운 배경 이미지 nano-banana 또는 gpt-image-2 PNG
정적 환경 탐색 가능한 3D 공간 marble-1.1 (World Labs) .spz, 콜라이더 .glb, 파노라마
오브젝트 개별 3D 메시 hunyuan-3d (FAL) .glb, .obj
소리 환경 앰비언스, 충돌음 elevenlabs-sfx (FAL) .mp3

image-blaster는 누구에게 유용한가

3D 작업의 초기 단계, 그중에서도 참조 이미지가 이미 있는 상황에 가장 잘 맞습니다. 게임 레벨 컨셉이나 영화 로케이션 아이디어처럼 "이런 분위기의 공간"을 빠르게 세워 두고 판단하려는 경우, 그리고 로봇 시뮬레이션용 환경을 대충이라도 채워 두려는 경우가 저자가 직접 예로 든 용도입니다. 산출물이 표준 파일 형식이라 Unity·Unreal·Godot이나 Blender·Maya, Three.js 앱의 에셋 디렉토리에 그대로 넣을 수 있습니다.

반대로 정확한 치수나 정돈된 토폴로지가 필요한 작업에는 맞지 않습니다. 배경이 메시가 아닌 가우시안 스플랫으로 만들어지므로 정밀한 충돌 처리나 CAD 성격의 작업은 별도 정리가 필요하고, 생성 모델 특성상 결과의 재현성도 보장되지 않습니다. World Labs와 FAL 계정이 필요하고 생성마다 비용이 발생하므로, 완전히 로컬에서 무료로 돌리려는 경우에도 대안을 찾아야 합니다.

image-blaster를 구성하는 8개 스킬

image-blaster를 구성하는 8개 Claude 스킬의 역할 정리
image-blaster를 구성하는 8개 Claude 스킬의 역할 정리1536×1024 285 KB

저장소의 .claude/skills/ 디렉토리에는 여덟 개의 스킬이 들어 있고, 각 스킬은 자기 단계에서 쓸 수 있는 도구를 allowed-tools 로 좁혀 두었습니다. 예를 들어 오브젝트 생성 스킬은 Read·Write·Glob 과 정해진 노드 스크립트 세 개만 실행할 수 있습니다. 무거운 생성 단계인 환경·오브젝트·효과음·플레이트 스킬은 context: fork 로 선언되어 별도 컨텍스트에서 돌고, 각자 대응하는 에이전트 정의를 함께 가집니다.

여덟 번째 스킬인 image-blast-wildcard 는 성격이 다릅니다. 나머지 일곱 개가 정해진 모델을 호출하는 반면, 이 스킬은 FAL Platform Model Search API로 모델을 검색해 사용자가 원하는 임의의 엔드포인트를 실행합니다. 다만 유료 요청이라 사용자가 정확한 엔드포인트를 확인해 준 뒤에만 실행하도록 두 단계로 나뉘어 있고, 확정 모드는 프롬프트가 CONFIRMED_FAL_ENDPOINT: 로 시작할 때만 동작합니다.

image-blaster의 이미지 분석 규칙

파이프라인의 품질을 실제로 좌우하는 부분은 첫 단계인 이미지 분석입니다. 이 단계의 규칙은 .claude/skills/image-blast-uncover/IMAGE-BLAST.md 에 별도 문서로 분리되어 있는데, 요지는 장면을 기술 조사서(technical scene survey) 처럼 기록하라는 것입니다. "~처럼 느껴진다", "~을 암시한다", "쓸쓸한" 같은 해석적 표현을 금지하고, 확실하지 않은 것은 추측하지 말고 아예 적지 말라고 명시합니다. 생성 프롬프트로 그대로 쓰일 텍스트이므로 주제·배치·재질·색·형태·조명·시점만 남기는 편이 유리하기 때문입니다.

분석 결과는 이미지마다 JSON 파일로 저장되고, 여러 장을 넣었으면 그것들을 병합해 루트 image.json 을 만듭니다. 스키마는 다음과 같은 평면 구조입니다.

{
  "schema_version": 1,
  "world": "sterile-electronic-lab",
  "scene_name": "Sterile Electronic Lab",
  "short_caption": "A clinical room with glass display cases and ceramic vessels.",
  "literal_description": "A compact room contains rows of aluminum-framed glass enclosures...",
  "environment": "Compact indoor display or storage room with glass enclosures...",
  "visual_style": "photorealistic, clinical, documentary",
  "lighting": "Even overhead fluorescent lighting, cool color temperature, low contrast.",
  "atmosphere": "Clean indoor air with no visible fog, smoke, dust, haze, or weather.",
  "ambient_sound": "Low ventilation hum with faint fluorescent buzz.",
  "objects": [
    {
      "id": "terracotta-amphora",
      "name": "terracotta amphora",
      "description": "Tall two-handled terracotta ceramic vessel with a narrow neck.",
      "count_estimate": 3,
      "materials": ["terracotta ceramic"],
      "generate_as_3d_object": true
    }
  ]
}

같은 물체가 여러 개 보이면 각각을 따로 만들지 않고 하나의 오브젝트로 합치되 count_estimate 에 개수를 적습니다. 항아리 세 개가 보이는 장면에서 세 번 생성 비용을 치르지 않게 하는 장치입니다. ambient_sound 필드는 효과음 생성 단계로, environment·lighting·atmosphere 는 환경 생성 단계로 각각 넘어갑니다.

image-blaster의 환경 생성과 텍스트 클린 플레이트

image-blaster가 실내 사진 한 장에서 생성한 3D 환경 미리보기

환경 생성 단계에는 이미지 클린 플레이트와는 별개로 한 가지 장치가 더 있습니다. World Labs에 보낼 프롬프트를 만들 때, 원본 장면 설명에서 확정된 오브젝트를 빼서 다시 쓰는 규칙입니다. 저장소는 이를 텍스트 클린 플레이트로 부르는데, 설정·재질·조명·분위기·공간 배치는 그대로 두고 물체만 지운 빈 공간으로 서술하라고 지시합니다. 이미지에서 의자를 지웠는데 캡션에 "a chair by the window" 가 남아 있으면 생성 모델이 의자를 다시 그려 넣어 오브젝트와 배경이 겹치기 때문입니다.

생성 결과는 디스크 우선 원칙으로 관리됩니다. World Labs가 돌려준 URL은 이력과 재시도용 정보로만 JSON에 남고, 뷰어는 로컬 파일만 읽습니다. 스크립트가 .spz 와 콜라이더 .glb, 파노라마, 썸네일을 모두 내려받았는지 확인한 뒤에야 성공으로 보고하며, 파일이 빠졌으면 ensure-local-assets.mjs 로 기록된 메타데이터에서 채웁니다.

파일 이름은 인덱스 규칙을 따릅니다. 생성물은 N-slug.ext, 그 요청 기록은 같은 자리에 숨김 파일 .N-slug-request.json 으로 놓이고, 0 은 원본, 그보다 큰 숫자는 파생 생성입니다. 한 번의 환경 생성이 만드는 N-world.json·N-world.glb·N-world-pano.png·N-world-full_res.spz 는 같은 인덱스를 공유합니다.

worlds/
  <world-slug>/
    project.json
    scene.json
    image.json
    source/
      0-<slug>.<ext>
      <image>.json
    output/
      world/
      sfx/
      <object>/
        object.json
        sfx/

input/

image-blaster의 3D 오브젝트와 효과음 생성

오브젝트 생성은 이미지 편집으로 시작합니다. 원본에서 해당 물체만 흰 배경에 놓인 참조 이미지로 분리한 뒤 그것을 3D 모델 생성에 넣는데, 이때 쓰는 프롬프트에는 "쌍이나 세트, 범주 예시, 인접한 중복 물체가 아닌 하나의 물리적 개체만" 이라는 제약이 들어갑니다. 비슷한 물체가 여러 개 있으면 위치로 대상을 특정하고 나머지는 배제합니다. 한 번 만든 참조 이미지는 이후 재생성에서 그대로 재사용되므로, 모델만 다시 뽑을 때 편집 비용을 다시 치르지 않습니다.

3D 변환의 기본 제공자는 Hunyuan이며, 다음 매개변수를 조절할 수 있습니다.

  • --face-count: 목표 face 수로 40,000에서 1,500,000 사이. image-blaster의 기본값은 50,000으로, Hunyuan API 기본값인 500,000보다 훨씬 낮게 잡혀 있습니다.
  • --generate-type: Normal 은 텍스처가 입혀진 모델, LowPoly 는 폴리곤을 줄인 모델, Geometry 는 흰색 지오메트리만 있는 모델을 만듭니다. 기본값은 Normal 입니다.
  • --polygon-type: LowPoly 에서 쓸 폴리곤 종류로 triangle 또는 quadrilateral 을 지정합니다.
  • --enable-pbr: PBR 재질 생성 여부로 기본값은 true 입니다.

사용자가 요청하면 Meshy로 제공자를 바꿀 수 있고, 이 경우 목표 폴리곤 수 30,000과 리메시·텍스처링 활성화가 기본값으로 들어갑니다. 리깅과 애니메이션 옵션도 있지만 기본은 꺼져 있습니다.

효과음은 목적에 따라 호출 방식이 갈립니다. 환경 앰비언스는 10초 길이의 루프로 두 개를 만들고, 물체 충돌음은 1초 길이로 네 개를 만듭니다. 프롬프트 형식까지 고정되어 있는데, 충돌음은 impact one-shot, short-decay, <재질 설명> hitting a hard surface 형태로 오브젝트 JSON의 재질 정보를 끌어다 씁니다.

후처리에서 루프와 단발음의 처리가 갈리는 점이 눈에 띕니다. 단발음은 ffprobe·ffmpeg 로 앞뒤 무음을 잘라내고 음량을 정규화하지만, 루프 오디오는 제공자가 준 원본을 그대로 둡니다. 무음을 다듬는 순간 루프의 이음새가 깨져 반복 재생에서 딸깍거리는 소리가 생기기 때문입니다.

image-blaster 설치 및 사용법

저장소를 클론하고 그 디렉토리에서 Claude Code를 실행하는 것이 전부입니다.

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

Claude Code가 없으면 먼저 설치합니다.

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

API 키는 두 개가 필요합니다. .env.example 을 .env 로 복사한 뒤 환경 생성용 WORLD_LABS_API_KEY 와 3D·효과음·이미지 편집용 FAL_KEY 를 채웁니다. 저장소에는 세션 시작 시 설정을 점검하는 훅이 등록되어 있어, 키가 비어 있으면 첫 대화에서 알려줍니다.

준비가 끝나면 input/ 에 이미지를 넣고 요청합니다.

blast it and confirm each step with me

단계마다 확인을 받으라는 부분이 실질적으로 중요합니다. 이미지 분석 뒤 어떤 물체를 오브젝트로 만들지 사용자가 확정하는 지점이 있고, 그 승인 전까지는 유료 생성이 시작되지 않습니다. 결과를 브라우저에서 보려면 저장소 루트에서 bun run dev 로 뷰어를 띄우고, 뷰어 코드까지 Claude가 수정하게 하려면 .claudeignore 에서 /app 항목을 지웁니다.

image-blaster의 라이선스

image-blaster는 MIT 라이선스로 공개되어 있어 개인 및 상업적 목적으로 자유롭게 사용할 수 있습니다. 다만 저장소가 호출하는 World Labs와 FAL의 모델 사용 조건은 각 서비스의 약관을 따릅니다.

:github: image-blaster 프로젝트 GitHub 저장소

더 읽어보기



이 글은 GPT 모델로 정리한 초안을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 댓글로 알려주시기를 부탁드립니다. :hugs:

이 도구를 직접 설치해 사용해보셨다면, :pytorch:파이토치 한국 사용자 모임:south_korea: 회원들을 위해 경험이나 팁을 댓글로 남겨주세요! :folded_hands: