프롬프트 하나로 편집 가능한 3D 장면을 구현하다: 로컬 우선 에이전트 워크플로우를 오픈 소스화하다

카메라 각도를 설명하는 것은 쉽습니다. 하지만 캐릭터, 소품, 카메라를 의도한 정확한 배열에 배치하는 것은 더 어렵습니다. 프롬프트만으로 AI 비디오를 직접 생성할 때, 작은 공간적 실수 하나가 여러분을 다시 처음부터의 생성 단계로 되돌릴 수 있습니다. 만약 레이아웃 자체를 다음 단계에 확정하기 전에 편집할 수 있다면 어떨까요?

저희는 이러한 질문을 바탕으로 Topview 3D Builder를 만들었습니다. 이 도구는 컴퓨터에서 장면을 구성(blocking out)하는 오픈 소스 도구입니다: 캐릭터와 간단한 소품을 배치하고, 포즈를 선택하며, 카메라 위치를 지정하고, 구도를 검사하여 나중에 AI 비디오 워크플로우에 정보를 제공할 수 있는 참고 이미지를 렌더링합니다. 호환 가능한 코딩 에이전트는 자연어 요청을 시작점으로 사용하여 로컬 CLI와 에이전트 스킬을 통해 장면을 구동할 수 있습니다.

본 게시물에서는 이 도구가 무엇을 하는지, 각 부분이 어떻게 결합되는지, 그리고 Topview 계정 없이 어떻게 사용해 볼 수 있는지 설명합니다. 또한 아직 구현하지 못한 기능도 설명합니다.

1분 만에 이해하는 워크플로우

두 사람이 작은 테이블을 사이에 두고 마주 보는 짧은 장면을 상상해 보세요. 오버-더-숄더 샷(over-the-shoulder shot)을 원하지만, 텍스트로 샷을 설명할 때마다 두 번째 사람이 계속 가려집니다.

편집 가능한 3D 스테이징 단계가 있다면, 두 가지 결정을 분리할 수 있습니다:

공간적 의도 (Spatial intent): 사람과 사물은 어디에 있나요? 어떤 캐릭터가 주 피사체인가요? 카메라는 어디에 있나요?
시각적 생성 (Visual generation): 완성된 영상은 어떻게 보이고 느껴져야 하나요?

호환 가능한 에이전트에서는 다음과 같은 설명적인 요청을 할 수 있습니다:

두 캐릭터가 테이블을 사이에 두고 마주 보는 간단한 대화 장면을 구성해 주세요. 첫 번째 캐릭터 뒤에 위치하고 두 번째 캐릭터를 겨냥하는 카메라를 사용하세요. 참고 뷰를 렌더링해 주세요. 나중에 제가 블로킹과 카메라 위치를 조정할 수 있도록 장면은 편집 가능하게 유지해 주세요.

이 에이전트는 비디오 모델이 문장에서 모든 공간적 결정을 추론하기를 기대하는 대신, 프로젝트의 스킬과 CLI를 사용하여 장면을 구성합니다. 그런 다음 참고 프레임을 검사하고, 스테이징을 변경하며, 다시 렌더링할 수 있습니다. 그 결과물은 완성된 AI 생성 영화 클립이 아니라, 스테이징 계획입니다.

실제로 당신의 기기에서 실행되는 것은 무엇인가?

이 저장소는 단순한 프롬프트 래퍼 그 이상을 포함합니다. 세 가지 명확하게 구분되는 부분이 있습니다:

에이전트 스킬 및 플러그인 매니페스트(agent skill and plugin manifests). 이들은 지원하는 에이전트들에게 장면 도구(scene tool)와 어떻게 상호작용해야 하는지 알려줍니다. 저장소에는 Codex, Cursor, Qwen, Claude Code 등과 통합에 대한 문서가 포함되어 있습니다.
Python CLI (topview-3d-cli). 이 클라이언트는 장면 프로젝트를 소유하고, 구조화된 편집을 검증하며, 에셋을 관리하고, 평가 및 렌더링을 오케스트레이션합니다.
로컬 스튜디오(Studio) 및 렌더러. 노드 기반 렌더링 경로(Node-based rendering path)는 Chromium을 사용하여 PNG 참조 프레임을 생성하며; 이 스튜디오는 로컬 장면 프로젝트를 열어 시각적 검사 및 수동 편집이 가능하게 합니다. 단순화된 정신 모델은 다음과 같습니다:

자연어 요청
        |
호환 가능한 AI 에이전트 + Topview 3D 스킬
...

장면(scene)은 로컬 프로젝트 내의 .topview-3d/ 디렉토리에 존재합니다. CLI 계약서(CLI contract)는 구조화된 장면 상태, 작업 배치(operation batches), 에셋 매니페스트, 카메라 뷰, 및 렌더 메타데이터를 문서화합니다. 이는 워크플로우가 기록되지 않은 프롬프트 재시도 체인보다 더 검사 가능하게 만듭니다.

시작하기: 설치, 확인, 그리고 생성

게시된 CLI는 현재 Python 3.11 이상, Node.js 20.6 이상, 그리고 관련 패키지 도구링을 요구합니다. 렌더링에는 일회성 Playwright/Chromium 설정도 필요합니다. 여기에 문서화된 릴리스는 topview-3d-cli 0.1.6이며, 게시하거나 설치하기 전에 최신 호환 버전을 확인하십시오.

독립적인 CLI 설치를 위해 저장소는 다음 경로를 문서화하고 있습니다:

pipx install topview-3d-cli==0.1.6
topview-3d-cli browser ensure
topview-3d-cli doctor

browser ensure는 렌더링 브라우저 종속성을 한 번 다운로드합니다. 핵심 장면 편집 및 렌더링은 로컬에서 이루어지지만, 초기 설치와 클라우드 호스팅 AI 에이전트는 인터넷 접속을 필요로 할 수 있습니다. 로컬 렌더링이

topview-3d-cli project init my-scene
topview-3d-cli project status my-scene
topview-3d-cli studio open my-scene

프로젝트는 기본 카메라로 시작합니다. studio open은 로컬 서버를 시작하고 해당 URL을 보고하며, 자동으로 열리지 않으면 브라우저에서 이 URL을 여십시오. 비어 있는 장면은 의도적입니다. 이는 에이전트나 CLI가 편집할 구체적인 프로젝트를 제공하기 위함입니다.

AI 코딩 에이전트를 사용하는 경우: 저장소의 문서화된 호환 에이전트용 플러그인/스킬을 설치하고, 새 세션을 시작한 다음, 위에 제시된 자연어 스테이징 요청을 제공하십시오. 정확한 플러그인 설치는 Codex, Cursor, Claude Code마다 다르므로, 다른 에이전트의 명령을 적용하기보다는 현재 저장소의 README를 따르십시오. 설치 명령을 게시하기 전에 저장소에서 현재 에이전트별 지침을 확인하십시오.

에이전트 없이 먼저 탐색하는 것을 선호한다면, 다음 명령들이 장면 도구(scene-tooling) 모델을 노출합니다:

topview-3d-cli asset list --kind character
topview-3d-cli camera presets
topview-3d-cli document get my-scene --summary

이들은 사용 가능한 캐릭터 에셋, 카메라 프리셋, 그리고 프로젝트의 현재 장면 요약을 나열합니다. 패키지의 에셋은 의도적으로 제한되어 있으므로, 무제한의 제작 준비가 된 배우나 환경 카탈로그를 기대해서는 안 됩니다.

유용한 부분은 첫 렌더링이 아니라 편집입니다

단일 자연어 프롬프트는 편리한 시작점이지만, 진정한 이점은 장면이 존재하는 후에 나옵니다. 예를 들어, 첫 번째 뷰가 기하학적으로는 정확하지만 시각적으로 약할 수 있습니다. 얼굴들이 겹치거나, 테이블이 화면을 가로지르거나, 카메라가 너무 높을 수 있습니다.

각도가 작동하는지 학습하기 위해 전체 비디오를 재생성하는 대신, 장면을 수정할 수 있습니다:

캐릭터와 소품들을 서로 상대적으로 재배치합니다.
내장된 카탈로그에서 다른 정적 포즈를 선택합니다.
카메라를 이동시키거나 그 목표점과 구도를 변경합니다.
동일한 장면 상태에서 다른 레퍼런스 뷰를 렌더링합니다. 문서화된 CLI는 그룹화된 노드 변경을 위한 노드 배치(node batch)와 포즈 변경을 위한 포즈 배치(pose batch)를 노출합니다. 또한 다음과 같은 검사 기능을 제공합니다:

topview-3d-cli evaluate my-scene
topview-3d-cli inspect views my-scene
topview-3d-cli renders show my-scene

evaluate는 구도(framing), 변환(transforms), 지면 관통 여부(ground penetration) 등 여러 측면을 수치적으로 검사합니다. inspect views는 뷰 검사를 렌더링과 결합합니다. renders show는 최신 렌더의 파일 경로를 보고합니다. 이 명령어들은 시네마틱한 판단을 보장하지 않으며, 다운스트림 생성에 시간을 쓰기 전에 측정 가능한 기하학적 또는 구도 문제를 포착하는 데 도움을 줍니다.

여기에는 실질적인 소프트웨어 엔지니어링상의 차이점도 있습니다. 즉, 장면(scene)은 단순히 이미지가 아니라 상태(state)라는 것입니다. CLI는 장면 시퀀스를 기록하고 작업을 검증하며, 실패한 쓰기 명령어는 부분적으로 적용되지 않도록 설계되었습니다. 에이전트가 변경을 제안할 때, 해당 스킬은 저장하기 전에 이를 검사하거나 드라이런(dry-run) 할 수 있습니다. 이는 사용자가 모델에게 전체 샷을 기억에서 재창조해 달라고 요청하는 대신 장면을 수정하고 싶어 할 때 중요합니다.

이 접근 방식이 도움이 되는 경우—그리고 멈추는 경우

우리는 세 가지 유망한 사용 사례를 확인했습니다.

구도 사전 시각화(Previsualizing composition). 비용이 많이 드는 샷을 생성하기 전에 상대적 위치와 카메라 방향을 설정합니다. 그 질감이 최종 비디오와 닮지 않았더라도 대략적인 3D 블록아웃은 유용합니다.
카메라 옵션 비교(Comparing camera options). 동일한 공간적 설정이 여러 카메라에서 볼 수 있습니다. 이는 구도의 변화를 콘텐츠의 변화와 분리합니다.
반복 작업 설명 가능화(Making iterations explainable). “두 번째 캐릭터를 왼쪽으로 반 걸음 이동시켜라”는 장면 내에서 공간적인 의미를 가집니다.

하지만 레퍼런스 프레임이 다운스트림 비디오 모델이 캐릭터의 정체성(identity), 구도(composition), 또는 움직임을 정확하게 보존할 것이라는 보장은 아닙니다. 모델 동작, 입력 제어, 이미지 조건화 충실도는 다양합니다. 프리비즈(previs) 워크플로우는 의도를 더 명확하게 만들 수 있지만, 생성형 비디오에서 불확실성을 완전히 제거할 수는 없습니다.

현재 스킬은 네 가지 내장 캐릭터, 121개의 정적 포즈, 단순 기본 도형(simple primitives), 정적 카메라, 그리고 루트 레벨 키프레밍을 설명합니다. 이번 릴리스에는 내장 워크 사이클이나 전신 모션 라이브러리는 없습니다. 위치 및 회전 키프레임은 움직임을 암시할 수 있지만, 완전히 애니메이션된 캐릭터 리그와는 다릅니다. 저희는 이 프로젝트를 완전한 3D 애니메이션 스위트로 마케팅하기보다는, 그 사실을 명확히 밝히고자 합니다.

개인 정보 보호, 비용, 라이선스는 어떨까요?

이 도구는 Topview 계정 로그인을 요구하거나 장면 파일을 Topview에 업로드할 필요 없이 로컬 장면 프로젝트를 생성하고 렌더링합니다. Topview Canvas로 렌더를 전송하는 것은 별도의 선택적 워크플로우이며, 로그인 절차를 거칩니다. 외부 AI 에이전트는 자체적인 클라우드 처리 및 개인 정보 보호 약관을 가질 수 있으므로, 사용자는 해당 제공업체를 독립적으로 평가해야 합니다.

로컬 3D 빌더를 사용하는 것이 Topview 계정 비용을 발생시키지는 않습니다. 최종 비디오 생성 시 돈을 절약할지 여부는 워크플로우, 사용하는 모델, 그리고 추가적인 프리비즈 작업이 피한 재시도(retries)를 상쇄하는지에 달려 있습니다. 저희는 여기서 측정된 비용 절감 비율을 주장하지 않습니다.

소스 코드, 스키마 및 문서는 Apache-2.0입니다. 번들된 캐릭터, 포즈 및 기타 지정된 내장 에셋은 출처 표기 의무(attribution obligations)를 포함하여 CC BY 4.0을 사용합니다. 에셋을 재배포하기 전에 두 공지 사항을 모두 검토하십시오.

사용해보고, 고장내 보고, 부족한 점을 알려주세요

이 프로젝트는 아직 초기 단계입니다. 저희는 특히 스테이징 도구가 도움이 되거나—혹은 방해가 되는—순간에 관심이 많습니다: 어색한 구도(awkward framing), 불완전한 에셋 선택, 도움이 되지 않는 유효성 검사 출력, 에이전트 설치 마찰(friction), 그리고 레퍼런스 이미지에서 비디오 생성으로의 인계 과정입니다.

소스 코드, 설치 지침 및 CLI 계약은 Topview 3D Builder 저장소에서 확인하세요. 워크플로우를 시도해 보신다면, 에이전트, 운영 체제, 관련 오류, 그리고 최소한의 재현 사례(개인 장면 데이터는 제거)와 함께 이슈를 열어주세요. 별점 개수보다 그 피드백이 저희에게 더 유용합니다.