markoboskoauroville/blender-control

Blender 제어 스킬 (라이브 GUI + 헤드리스 CLI)

이 워크스페이스는 Blender 5.2.1 LTS (/Applications/Blender.app/Contents/MacOS/Blender, Python 3.13, Apple M1 Pro 16코어 Metal GPU)를 두 가지 상호 보완적인 모드로 제어합니다:

1. 라이브 GUI 모드 (기본 및 권장): 127.0.0.1:9876을 통해 열려 있는 Blender.app 창 내에서 실행 중인 blender_control_bridge.py로 명령을 전송합니다. 객체, 셰이더, 애니메이션, 카메라 프레이밍이 사용자 앞에 즉시 나타납니다.
2. 헤드리스 CLI 모드: 활성 GUI 세션에 영향을 주지 않고 격리된 배치 렌더링이나 무거운 백그라운드 작업을 위해 /Applications/Blender.app/Contents/MacOS/Blender --background를 실행합니다.

Blender 5.2용 bpy 스크립트를 작성하기 전에 blender_5_2_api_guide.md에서 중요한 5.2 API 변경 사항(Principled BSDF 소켓 이름, Slotted Actions channelbag, media_type = 'VIDEO', Metal GPU 설정)을 검토하세요.

---

1단계: 열려 있는 Blender 애플리케이션 확인 또는 연결

항상 먼저 라이브 브리지 연결을 확인하세요:

python3 .agents/skills/blender-control/scripts/blender_cli.py ping

ping이 실패하면(예: Blender가 아직 열려 있지 않거나 시작 브리지 설치 전에 시작된 경우), 설치/연결 스크립트를 실행하세요:

bash .agents/skills/blender-control/scripts/install_bridge.sh

• blender_control_bridge.py를 ~/Library/Application Support/Blender/5.2/scripts/startup/에 복사하여 모든 GUI 실행 시 브리지가 자동으로 127.0.0.1:9876에서 시작되도록 합니다.
• 창 포커스를 빼앗지 않고 Blender.app에 안전하게 연결하거나 실행합니다(open -g -a Blender).
• Blender.app에 브리지가 로드되지 않은 저장되지 않은 .blend 파일이 이미 열려 있는 경우, macOS 메뉴 표시줄에서 Blender -> 시스템 -> 스크립트 다시 로드를 클릭하도록 사용자에게 요청합니다.

---

2단계: blender_cli.py를 통해 라이브 장면 검사 및 제어

모든 라이브 작업에는 blender_cli.py를 사용하세요:

# 1. 현재 객체, 카메라, 재질, 프레임 범위, 렌더 엔진 검사
python3 .agents/skills/blender-control/scripts/blender_cli.py info

# 2. 라이브 장면을 깔끔하게 지우기(모든 객체 및 고립 데이터 블록 제거)
python3 .agents/skills/blender-control/scripts/blender_cli.py reset

# 3. Blender의 기본 UI 스레드에서 장면 빌더 Python 스크립트 라이브 실행
python3 .agents/skills/blender-control/scripts/blender_cli.py run projects/my_scene/build.py

# 4. 빠른 인라인 Python 표현식/조각 실행
python3 .agents/skills/blender-control/scripts/blender_cli.py exec "RESULT = [o.name for o in bpy.data.objects]"

# 5. 사용자의 라이브 Blender 3D 뷰포트를 재질 미리보기 또는 렌더링된 카메라 뷰로 전환
python3 .agents/skills/blender-control/scripts/blender_cli.py viewport --shading MATERIAL

# 6. 라이브 GUI에서 .blend 프로젝트 파일 저장 또는 열기
python3 .agents/skills/blender-control/scripts/blender_cli.py save projects/my_scene/scene.blend
python3 .agents/skills/blender-control/scripts/blender_cli.py open projects/my_scene/scene.blend

---

3단계: 정지 이미지, 뷰포트 미리보기 및 애니메이션 렌더링

빠른 뷰포트 미리보기 (<0.2초)

전체 레이트레이스 렌더를 실행하기 전에 카메라 프레이밍, 객체 배치, 클리핑을 확인하려면 먼저 뷰포트 스크린샷을 사용하세요:

python3 .agents/skills/blender-control/scripts/blender_cli.py screenshot /tmp/preview.png

read_file로 /tmp/preview.png를 검사하여 구도와 조명을 시각적으로 확인하세요!

고품질 정지 이미지 렌더 (Cycles Metal GPU 또는 EEVEE)

# 자동 Apple M1 Pro 16코어 Metal GPU 가속을 사용하는 Cycles
python3 .agents/skills/blender-control/scripts/blender_cli.py render projects/my_scene/render.png \
  --engine CYCLES --samples 64 --width 1920 --height 1080

# EEVEE를 사용한 빠른 실시간 PBR 렌더
python3 .agents/skills/blender-control/scripts/blender_cli.py render projects/my_scene/render.png \
  --engine BLENDER_EEVEE --samples 32 --width 1920 --height 1080

MP4 (H.264) 애니메이션 렌더

python3 .agents/skills/blender-control/scripts/blender_cli.py render-anim projects/my_scene/animation.mp4 \
  --engine BLENDER_EEVEE --samples 32 --width 1280 --height 720 --start 1 --end 120 --fps 30

헤드리스 배치 모드 (격리 프로세스)

라이브 GUI 뷰포트를 차단하지 않고 무거운 작업을 렌더링할 때:

python3 .agents/skills/blender-control/scripts/blender_cli.py run projects/my_scene/build.py --headless

---

4단계: 장면 구성 및 검증 체크리스트

1. 자체 포함된 빌더 스크립트: 각 프로젝트를 projects/<project_name>/build.py에 저장하여 장면이 100% 재현 가능하고 Git 친화적이며 렌더링된 결과물 및 .blend 파일과 함께 사용될 수 있도록 합니다.
2. 카메라 조준 (TRACK_TO 또는 쿼터니언): 항상 (target - cam.location).to_track_quat('-Z', 'Y')를 사용하여 카메라를 대상 빈(Empty) 또는 월드 좌표에 안정적으로 향하게 하고 scene.camera = cam을 설정합니다.
3. 3점 조명 / 스튜디오 조명 및 월드: 어두운 기본 회색 배경을 남겨두지 마십시오. 월드 셰이더 노드 + 영역/태양광을 사실적인 와트(100W–1500W, 장면 규모에 따라 다름)와 AgX 또는 Filmic 색상 관리(scene.view_settings.view_transform = 'AgX', look = 'AgX - Medium High Contrast')로 구성합니다.
4. 시각적 확인: 작업을 마치기 전에 항상 read_file을 사용하여 렌더링된 .png 또는 .mp4 출력물을 검사하여 프레이밍, 노출, 재질, 모션을 확인합니다.
5. GitHub 동기화: 프로젝트나 스킬을 생성/업데이트한 후 ./scripts/sync_github.sh "<커밋 메시지>"를 실행하여 로컬 및 origin/main을 동기화 상태로 유지합니다.