cli-anything-blender은(는) 무엇을 하나요?
GIMP CLI 하네스와 동일한 패턴을 따르는 3D 씬 편집용 상태 저장 명령줄 인터페이스입니다. 실제 Blender 렌더링을 위해 bpy 스크립트 생성을 포함한 JSON 씬 설명 형식을 사용합니다.
설치
이 CLI는 cli-anything-blender 패키지의 일부로 설치됩니다:
pip install cli-anything-blender
전제 조건:
- Python 3.10+
- 시스템에 Blender (>= 4.2)가 설치되어 있어야 합니다
사용법
기본 명령어
# 도움말 표시
cli-anything-blender --help
# 대화형 REPL 모드 시작
cli-anything-blender
# 새 씬 프로젝트 생성
cli-anything-blender scene new -o scene.blend-cli.json
# JSON 출력으로 실행 (에이전트 소비용)
cli-anything-blender --json --project scene.blend-cli.json scene info
REPL 모드
하위 명령어 없이 호출하면 CLI가 대화형 REPL 세션에 진입합니다:
cli-anything-blender
# 탭 완성 및 히스토리와 함께 대화형으로 명령어 입력
명령어 그룹
Scene (씬)
씬 관리 명령어입니다.
| 명령어 | 설명 |
|---|---|
new | 새 씬 생성 |
open | 기존 씬 열기 |
save | 현재 씬 저장 |
info | 씬 정보 표시 |
profiles | 사용 가능한 씬 프로필 목록 |
json | 원시 씬 JSON 출력 |
Object Group (오브젝트 그룹)
3D 오브젝트 관리 명령어입니다.
| 명령어 | 설명 |
|---|---|
add | 3D 기본 오브젝트 추가 |
remove | 인덱스로 오브젝트 제거 |
duplicate | 오브젝트 복제 |
transform | 오브젝트 변형 (이동, 회전, 크기 조절) |
set | 오브젝트 속성 설정 (이름, 가시성, 위치, 회전, 크기, 부모) |
list | 모든 오브젝트 나열 |
get | 오브젝트에 대한 상세 정보 가져오기 |
Material (재질)
재질 관리 명령어입니다.
| 명령어 | 설명 |
|---|---|
create | 새 재질 생성 |
assign | 오브젝트에 재질 할당 |
set | 재질 속성 설정 (색상, 금속성, 거칠기, 반사도, 알파 등) |
list | 모든 재질 나열 |
get | 재질에 대한 상세 정보 가져오기 |
Modifier Group (모디파이어 그룹)
모디파이어 관리 명령어입니다.
| 명령어 | 설명 |
|---|---|
list-available | 사용 가능한 모든 모디파이어 나열 |
info | 모디파이어에 대한 세부 정보 표시 |
add | 오브젝트에 모디파이어 추가 |
remove | 인덱스로 모디파이어 제거 |
set | 모디파이어 매개변수 설정 |
list | 오브젝트의 모디파이어 나열 |
Camera (카메라)
카메라 관리 명령어입니다.
| 명령어 | 설명 |
|---|---|
add | 씬에 카메라 추가 |
set | 카메라 속성 설정 |
set-active | 활성 카메라 설정 |
list | 모든 카메라 나열 |
Light (조명)
조명 관리 명령어입니다.
| 명령어 | 설명 |
|---|---|
add | 씬에 조명 추가 |
set | 조명 속성 설정 |
list | 모든 조명 나열 |
Animation (애니메이션)
애니메이션 및 키프레임 명령어입니다.
| 명령어 | 설명 |
|---|---|
keyframe | 오브젝트에 키프레임 설정 |
remove-keyframe | 오브젝트에서 키프레임 제거 |
frame-range | 애니메이션 프레임 범위 설정 |
fps | 애니메이션 FPS 설정 |
list-keyframes | 오브젝트의 키프레임 나열 |
Render Group (렌더 그룹)
렌더 설정 및 출력 명령어입니다.
| 명령어 | 설명 |
|---|---|
settings | 렌더 설정 구성 |
info | 현재 렌더 설정 표시 |
presets | 사용 가능한 렌더 프리셋 나열 |
execute | 씬 렌더링 (bpy 스크립트 생성) |
script | 렌더링 없이 bpy 스크립트 생성 |
Preview (미리보기)
실제 미리보기 번들 캡처 및 실시간 미리보기 세션 명령어입니다.
| 명령어 | 설명 |
|---|---|
preview recipes | 사용 가능한 미리보기 레시피 나열 |
preview capture | 활성 씬의 실제 미리보기 번들 렌더링 |
preview latest | 가장 최근의 기존 미리보기 번들 반환 |
preview live start | 실시간 미리보기 세션 시작 및 첫 번째 번들 게시 |
preview live push | 실시간 세션에 새로 고침된 번들 게시 |
preview live status | 렌더링 없이 현재 실시간 세션 상태 읽기 |
preview live stop | 아티팩트 삭제 없이 실시간 세션 중지 |
레시피 quick의 일반적인 번들 아티팩트:
hero.png(실제 Eevee 미리보기 렌더링)workbench.png(실제 Blender Workbench 렌더링)
실시간 세션 지속성:
session.json(변경 가능한 헤드)- 불변 번들 디렉터리
trajectory.json(추가 전용 명령-미리보기 히스토리)
뷰어 측:
cli-hub previews inspect <번들-또는-세션>cli-hub previews html <번들-또는-세션> -o page.htmlcli-hub previews watch <세션-디렉터리> --opencli-hub previews open <번들-또는-세션>
Session (세션)
세션 관리 명령어입니다.
| 명령어 | 설명 |
|---|---|
status | 세션 상태 표시 |
undo | 마지막 작업 실행 취소 |
redo | 마지막으로 취소한 작업 다시 실행 |
history | 실행 취소 기록 표시 |
예제
새 프로젝트 만들기
새 Blender 씬 프로젝트 파일을 만듭니다.
cli-anything-blender scene new -o myscene.blend-cli.json
# 또는 프로그램적 사용을 위한 JSON 출력
cli-anything-blender --json scene new -o myscene.blend-cli.json
대화형 REPL 세션
실행 취소/다시 실행 지원으로 대화형 세션을 시작합니다.
cli-anything-blender
# 대화형으로 명령어 입력
# 사용 가능한 명령어를 보려면 'help' 사용
# 기록 탐색을 위해 'undo' 및 'redo' 사용
상태 관리
CLI는 다음을 통해 세션 상태를 유지합니다:
- 실행 취소/다시 실행: 최대 50단계의 기록
- 프로젝트 지속성: JSON으로 프로젝트 상태 저장/로드
- 세션 추적: 수정 사항 및 변경 사항 추적
출력 형식
모든 명령어는 이중 출력 모드를 지원합니다:
- 사람이 읽을 수 있는 형식 (기본값): 표, 색상, 서식화된 텍스트
- 기계가 읽을 수 있는 형식 (
--json플래그): 에이전트 소비를 위한 구조화된 JSON
# 사람 출력
cli-anything-blender --project scene.blend-cli.json scene info
# 에이전트용 JSON 출력
cli-anything-blender --json --project scene.blend-cli.json scene info
미리보기 워크플로우
에이전트가 신뢰할 수 있는 시각적 체크포인트가 필요할 때 Blender 미리보기를 사용하세요:
# 미리보기 레시피 나열
cli-anything-blender --project scene.blend-cli.json preview recipes
# 실제 미리보기 번들 캡처
cli-anything-blender --json --project scene.blend-cli.json preview capture --recipe quick
# 실시간 미리보기 루프 시작
cli-anything-blender --json --project scene.blend-cli.json preview live start --recipe quick --mode poll --source-poll-ms 500
# 렌더링 없이 현재 실시간 헤드 쿼리
cli-anything-blender --json --project scene.blend-cli.json preview live status --recipe quick
에이전트의 경우, preview capture --json은 번들 메타데이터와 아티팩트 파일 경로를 반환합니다. preview live status --json은 세션 메타데이터와 간결한 trajectory_summary를 반환합니다.
AI 에이전트용
이 CLI를 프로그래밍 방식으로 사용할 때:
- 항상
--json플래그 사용 - 파싱 가능한 출력을 위해 - 반환 코드 확인 - 0은 성공, 0이 아니면 오류
- stderr 파싱 - 실패 시 오류 메시지 확인
- 필수: 모든 파일 작업에 절대 경로 사용 (렌더링, 프로젝트 파일). 상대 경로는 백그라운드 실행에서 실패하기 쉽습니다.
- 시각적 확인을 위해
preview capture또는preview live ...사용 - JSON만으로 씬 품질을 추론하지 마십시오 - 반환된 아티팩트 경로 읽기 (예:
hero.png및workbench.png); JSON 페이로드는 파일을 참조할 뿐, 이미지 바이트를 인라인으로 포함하지 않습니다 _bundle_dir을 하나의 스냅샷으로만 처리; 안정적인 실시간 기록을 위해서는_session_dir과_trajectory_path를 사용하십시오cli-hub previews ...는 기존 미리보기를 검사하거나 여는 데만 사용; 미리보기 생성 자체는 항상cli-anything-blender preview ...를 통해 이루어집니다
추가 정보
- 전체 문서: 패키지의 README.md 참조
- 테스트 적용 범위: 패키지의 TEST.md 참조
- 방법론: cli-anything-plugin의 HARNESS.md 참조
버전
1.0.0