Blender 파이썬 자동화: 반복 작업을 스크립트로

기준: Blender 5.2 LTS 공식 Python API 문서와 매뉴얼(영어 화면, 기본 단축키)

Blender에서 버튼으로 바꿀 수 있는 설정은 거의 모두 파이썬(Python) 코드로도 바꿀 수 있습니다. 그래서 같은 클릭을 수십 번 반복해야 하는 일, 예를 들어 물체 50개를 줄 세우기, 여러 파일의 렌더 설정 맞추기, 밤새 렌더링 돌리기 같은 일은 짧은 스크립트(명령을 적어 둔 글)에 맡길 수 있습니다. 프로그래밍이 처음인 여러분도 따라 할 수 있게 썼습니다.

이 글을 마치면 아래를 할 수 있습니다.

1. 스크립트를 돌리는 곳을 찾습니다.
2. Blender 파이썬의 세 기둥(bpy.data, bpy.context, bpy.ops)을 구분합니다.
3. 짧은 예시 세 개를 그대로 복사해 돌려 봅니다.

스크립트: 요리 레시피

손으로 작업하는 것은 요리를 매번 기억에 의존해 만드는 것과 같습니다. 스크립트는 그 과정을 레시피 카드로 적어 둔 것입니다. 한 번 적어 두면 Blender가 그 순서를 그대로, 몇 번이든, 실수 없이 따라 합니다. 재료 양(숫자)만 바꾸면 다른 결과도 쉽게 만들 수 있습니다.

스크립트로 할 수 있는 일 가운데 몇 가지는 이렇습니다.

• 화면에서 바꿀 수 있는 모든 데이터(장면, 메시, 파티클 등) 편집
• 도구를 원하는 설정으로 실행
• 메뉴, 패널 같은 화면 요소 만들기
• 새로운 도구 만들기

이 글은 첫 번째와 두 번째, 즉 이미 있는 기능을 자동으로 돌리는 것에 집중합니다.

시작 준비: 세 가지만 켜고 열기

1. Scripting 작업 공간 열기: 화면 맨 위 탭에서 Scripting을 누르면 코드를 쓰는 텍스트 편집기(Text Editor)와 한 줄씩 시험하는 파이썬 콘솔(Python Console)이 함께 열립니다. 따로 화면을 꾸미지 말고 이 작업 공간을 쓰면 됩니다.
2. Python Tooltips 켜기: Edit ‣ Preferences ‣ Interface에서 Developer Extras와 Python Tooltips를 켭니다. 그러면 버튼에 마우스를 올렸을 때 그 설정의 파이썬 이름이 함께 보입니다. "이 버튼은 코드로 뭐라고 부르지?"라는 질문에 Blender가 직접 답해 줍니다.
3. Info 창 보기: 도구를 쓰면 Info 창에 그 동작이 파이썬 명령 형태로 기록됩니다. 모든 동작이 남지는 않고 일부 도구(Blender는 이를 "연산자"라고 부릅니다)만 기록됩니다. 그래도 처음 코드를 만들 때 좋은 힌트가 됩니다.

스크립트를 실행하는 곳은 두 군데입니다.

텍스트 편집기의 Templates 메뉴에는 공식 예시 스크립트가 많이 들어 있어 참고하기 좋습니다.

Blender 파이썬의 세 기둥: data, context, ops

Blender의 파이썬 모듈 이름은 bpy입니다. 처음에는 아래 세 가지만 알면 됩니다.

앞의 레시피 비유를 이어 가겠습니다. 부엌에는 재료 창고가 있고, 지금 도마 위에 올린 재료가 있고, 칼과 냄비 같은 조리 도구가 있습니다.

아래 규칙을 함께 알아 두면 오류를 줄일 수 있습니다.

• bpy.data의 항목은 이름(["Cube"])이나 번호([0])로 꺼낼 수 있지만, 번호는 작업 중에 바뀔 수 있습니다. 이름을 쓰는 편이 안전합니다.
• 새 데이터는 bpy.data.meshes 같은 목록의 new()로 만들고(예: bpy.data.meshes.new("이름")), 같은 목록의 remove()로 지웁니다.
• bpy.context는 읽기 전용입니다. bpy.context.active_object = obj는 오류가 나고, 활성 물체를 바꾸려면 bpy.context.view_layer.objects.active = obj를 씁니다.
• bpy.ops의 도구는 알맞은 상황(모드, 창)에서만 돌아갑니다. 조건이 안 맞으면 "context is incorrect" 오류가 납니다. 이 오류가 나면 먼저 지금 모드(Object/Edit)와 마우스가 올라간 창이 맞는지 확인하세요. 코드 안에서 미리 확인하려면 도구 이름 뒤에 .poll()을 붙입니다. 예를 들어 bpy.ops.object.mode_set.poll()은 지금 모드를 바꿀 수 있으면 True, 아니면 False를 돌려줍니다.

예시 1: 한 줄로 해상도 % 바꾸기

파이썬 콘솔에 아래 한 줄을 입력해 보세요. 파이썬 콘솔에는 bpy가 미리 불러와져 있어서 import bpy 없이 바로 쓸 수 있습니다. 반면 텍스트 편집기에서 돌리는 스크립트는 예시 2처럼 첫 줄에 import bpy를 적는 것이 기본입니다.

bpy.context.scene.render.resolution_percentage = 50

속성 편집기 출력(Output) 탭의 Resolution % 칸이 50으로 바뀝니다(새 파일의 기본 1920×1080이라면 960×540으로 렌더됩니다). render.resolution_percentage는 버튼 툴팁에 보이는 이름과 같습니다. 이 설정이 무엇인지는 렌더 설정 입문에서 설명합니다.

예시 2: 상자 5개를 줄 세우고 차례로 뛰어오르게 하기

텍스트 편집기에서 New를 누르고 아래 코드를 붙여 넣은 뒤 Run Script를 누릅니다.

import bpy

# 기본 장면의 큰 Cube가 있으면 먼저 지운다 (새 상자와 겹치지 않게)
if "Cube" in bpy.data.objects:
    bpy.data.objects.remove(bpy.data.objects["Cube"])

for i in range(5):
    bpy.ops.mesh.primitive_cube_add(size=1, location=(i * 2, 0, 0))
    cube = bpy.context.object          # 방금 만든 상자
    cube.name = f"Box_{i}"
    start = 1 + i * 5                  # 상자마다 5프레임씩 늦게 시작
    cube.keyframe_insert(data_path="location", frame=start)        # 바닥
    cube.location.z = 2                                            # 2m 위로
    cube.keyframe_insert(data_path="location", frame=start + 10)   # 꼭대기
    cube.location.z = 0                                            # 다시 바닥으로
    cube.keyframe_insert(data_path="location", frame=start + 20)   # 착지

한 줄씩 풀면 이렇습니다.

• if "Cube" in bpy.data.objects: 새 파일에 처음부터 있는 큰 Cube(한 변 2m, 원점)를 지웁니다. 이 줄이 없으면 첫 상자가 그 Cube 안에 파묻혀 상자가 네 개처럼 보입니다.
• for i in range(5): 아래 내용을 5번 반복합니다(i는 0, 1, 2, 3, 4).
• primitive_cube_add: 메뉴의 Add ‣ Mesh ‣ Cube와 같은 도구입니다. 한 변 1m 상자를 2m 간격으로 놓습니다.
• keyframe_insert(data_path="location", ...): 키프레임을 넣는 함수입니다. 여기서는 위치에만 키를 넣습니다(화면에서 I를 누르면 보통 위치·회전·크기에 한꺼번에 키가 들어가는 것과 다릅니다).
• 키는 상자마다 세 개입니다: 바닥 → 10프레임 뒤 2m 위 → 다시 10프레임 뒤 바닥.

Space로 재생하면 상자들이 왼쪽부터 차례로 한 번씩 뛰어올랐다가 내려옵니다. 마지막 상자는 41프레임에 내려앉고, 그 뒤 재생 끝(기본 250프레임)까지는 모두 바닥에 멈춰 있습니다. 손으로 하면 상자마다 추가, 이동, 키 넣기를 반복해야 하지만, 여기서는 숫자 5를 50으로 바꾸기만 하면 됩니다.

같은 스크립트를 한 번 더 돌리면 Box_0.001처럼 이름이 붙은 상자가 겹쳐 생깁니다. 다시 돌리기 전에 먼저 만든 상자를 지우세요. Ctrl+Z로 되돌리거나, 3D 뷰포트에 마우스를 올리고 A(전체 선택) → X → Delete를 누르면 됩니다. A는 카메라와 조명까지 고르니, 둘을 남기려면 아웃라이너(Outliner)에서 Box_로 시작하는 것만 골라 지웁니다. 키프레임과 보간이 무엇인지는 Blender 키프레임 애니메이션 입문에서 다룹니다.

예시 3: 미리보기 설정을 한 번에 맞추기

여러 파일을 열 때마다 같은 렌더 설정을 넣는 일도 스크립트로 줄일 수 있습니다. 아래 파일을 preview_settings.py로 저장해 둡니다.

import bpy

render = bpy.context.scene.render
render.resolution_x = 1920
render.resolution_y = 1080
render.resolution_percentage = 50      # 테스트는 960x540 (1920x1080의 50%)
render.fps = 30
render.filepath = "//preview/frame_"   # // = blend 파일이 있는 폴더

이 설정 이름들은 모두 공식 API의 RenderSettings 문서에 있습니다. 최종 렌더링 때는 resolution_percentage만 100으로 올립니다. 작게 확인하고 최종본만 키우는 순서는 렌더 설정 입문에서 설명합니다.

저장한 preview_settings.py를 다른 blend 파일에 쓰는 방법은 두 가지입니다. 그 파일을 연 뒤 텍스트 편집기의 Open으로 스크립트를 불러와 Run Script를 누르거나, 바로 아래 명령줄 절처럼 -P로 실행합니다.

창 없이 돌리기: 명령줄과 배경 렌더링

스크립트는 Blender 창을 열지 않고도 돌릴 수 있습니다. 터미널(명령을 글자로 입력하는 창)에 이렇게 씁니다. 터미널이 낯설다면 GUI와 CLI, 무엇이 다를까를 먼저 읽어 보세요.

blender -b scene.blend -P preview_settings.py -f 1

위는 모양만 보여 주는 기본형입니다. Windows에서는 설치 프로그램이 Blender를 명령 검색 경로(PATH)에 넣지 않아서, blender라고만 치면 "인식되지 않는 명령" 오류가 나기 쉽습니다. 그럴 때는 blender 자리에 실행 파일의 전체 경로를 적습니다.

폴더 이름의 버전 숫자(5.2)는 설치한 버전에 맞춥니다. scene.blend와 preview_settings.py도 터미널이 지금 있는 폴더에 없다면 전체 경로로 적습니다.

처음에는 -f 1로 한 장만 시험하세요. -a는 장면의 시작부터 끝 프레임까지 모두 렌더하므로 새 파일 기준 250장을 만듭니다. 한 장이 원하는 대로 나오면 -f 1을 -a로 바꿉니다. 또 -P로 바꾼 설정은 이번 실행에만 쓰이고 blend 파일에 저장되지는 않습니다. 파일에 남기려면 Blender에서 파일을 열어 스크립트를 돌린 뒤 저장합니다.

주의할 점은 순서입니다. 인수는 적힌 순서대로 실행됩니다. 파일을 연 다음에 설정 스크립트를 돌리고, 그 다음에 렌더해야 합니다. 파일보다 설정을 먼저 적으면 파일을 열면서 설정이 덮어써집니다. 컴퓨터 사용이 적은 시간에 이렇게 맡겨 두면 다른 작업과 겹치지 않습니다.

안전하게 쓰기

파이썬은 할 수 있는 일에 제한이 없습니다. 그래서 믿을 수 있는 출처의 스크립트만 실행해야 합니다.

• blend 파일 안의 스크립트 자동 실행은 기본으로 꺼져 있습니다. 파일을 열 때 실행 허락을 묻는 창이 뜨면, 출처를 모르는 파일이라면 무시(Ignore)를 고릅니다.
• 환경설정(Preferences)의 Auto Run Python Scripts를 켜더라도 다운로드 폴더처럼 믿기 어려운 폴더는 예외로 둘 수 있습니다.
• 인터넷에서 받은 코드는 실행 전에 내용을 읽어 보고, 중요한 파일은 복사본에서 먼저 시험합니다.

AI와 함께 스크립트 쓰기

요즘은 "상자 10개를 원형으로 놓는 Blender 파이썬 코드"처럼 AI에게 스크립트 초안을 부탁할 수도 있습니다. 이때도 위의 세 기둥과 공식 문서가 기준이 됩니다. AI가 쓴 코드가 오래된 API를 쓰면 오류가 날 수 있으니, 함수 이름을 공식 API 문서에서 찾아 확인하세요. AI가 Blender를 직접 다루게 하는 방식은 MCP란 무엇인가와 AI와 Blender, 작은 작업부터 함께 시작하기에서 이어서 볼 수 있습니다.

정리

함께 읽기

• GUI와 CLI, 무엇이 다를까
• AI와 Blender, 작은 작업부터 함께 시작하기
• MCP란 무엇인가: AI에 도구를 꽂는 USB-C 같은 표준

참고 자료

• Blender Python API, Quickstart: https://docs.blender.org/api/5.2/info_quickstart.html
• Blender Python API, Tips and Tricks: https://docs.blender.org/api/5.2/info_tips_and_tricks.html
• Blender Python API, Operators (bpy.ops): https://docs.blender.org/api/5.2/bpy.ops.html
• Blender Python API, BlendDataObjects (objects.remove): https://docs.blender.org/api/5.2/bpy.types.BlendDataObjects.html
• Blender Python API, bpy_struct.keyframe_insert: https://docs.blender.org/api/5.2/bpy.types.bpy_struct.html
• Blender Python API, Mesh Operators: https://docs.blender.org/api/5.2/bpy.ops.mesh.html
• Blender Python API, RenderSettings: https://docs.blender.org/api/5.2/bpy.types.RenderSettings.html
• Blender Manual, Text Editor: https://docs.blender.org/manual/en/5.2/editors/text_editor.html
• Blender Manual, Python Console: https://docs.blender.org/manual/en/5.2/editors/python_console.html
• Blender Manual, Launching from the Command Line (Windows): https://docs.blender.org/manual/en/5.2/advanced/command_line/launch/windows.html
• Blender Manual, Launching from the Command Line (macOS): https://docs.blender.org/manual/en/5.2/advanced/command_line/launch/macos.html
• Blender Manual, Command Line Arguments: https://docs.blender.org/manual/en/5.2/advanced/command_line/arguments.html
• Blender Manual, Scripting & Security: https://docs.blender.org/manual/en/5.2/advanced/scripting/security.html