realityscan-mcp

MCP server for RealityScan (formerly RealityCapture) — drive the full photogrammetry pipeline (align → mesh → texture → export) from an AI agent, either headless or by live-driving a visible GUI instance. Includes a 360° video → perspective-frames converter (equirectangular / YouTube EAC).

Claude(또는 다른 MCP 클라이언트)가 RealityScan 포토그래메트리를 자동화한다 — 헤드리스 CLI 배치 또는 보이는 GUI 실시간 제어. 360 영상 전처리 포함.

• 실행파일 자동탐지: 환경변수 REALITYSCAN_EXE/REALITYSCAN_HOME → C:\Program Files\Epic Games\RealityScan*\RealityScan.exe(최고 버전 우선) → 레거시 RealityCapture. 상위 버전을 설치하면 코드 수정 없이 자동 승격.
• 개발·검증 환경: RealityScan 2.1.1 (Windows). CLI 는 2.x 공통이라 2.2 등 상위 버전도 그대로 동작(exe 경로만 자동 승격).
• 라이브 검증: 헤드리스 실행 → 명령 순차 실행 → 출력 캡처 → 정상 종료(exit 0). 실제 영상→텍스처 메시 복원, 360(EAC) 변환, 보이는 GUI 위임 모두 확인.

자동화 모델

RealityScan 은 하나의 헤드리스 프로세스에 CLI 명령을 나열해 순차 실행한다:

RealityScan.exe -headless -stdConsole -load p.rsproj -align -calculateNormalModel -save p.rsproj -quit

이 서버는 명령 토큰 리스트를 받아 -headless / -stdConsole / -silent / -quit 를 자동 부착하고 subprocess 로 실행, stdout/stderr/exit code 를 구조화해 반환한다. 모든 편의 도구는 결국 runner.run() 단일 경로로 귀결되며, execute_cli 가 전체 CLI 를 그대로 노출하는 탈출구다(어떤 명령도 도달 가능).

도구 (13종)

도구	설명
check_connection	설치/탐지 상태·버전·환경변수 스냅샷 (기동 안 함)
execute_cli	전체 CLI 탈출구 — 임의 토큰 시퀀스 실행. instance= 주면 보이는 GUI로 위임
launch_gui	보이는 GUI 상주 인스턴스 실행 (아래 라이브 모드)
get_instance_status	GUI 인스턴스 진행 상태 조회
new_project	새 프로젝트 + 이미지(폴더/개별) 추가 + 저장
add_inputs	기존 프로젝트에 이미지 추가
align_images	정렬(카메라 포즈). draft/detect_markers 옵션
build_model	영역 자동설정 + 메시(preview/normal/high) + 선택적 단순화
texture_model	UV 언랩 + 텍스처 계산
export_model	모델 내보내기(확장자로 형식 결정: obj/fbx/ply/glb…)
export_report	템플릿 기반 HTML 리포트
convert_360_video	360 등장방형 영상 → 원근 프레임(ffmpeg v360) + XMP 캘리브레이션. RealityScan 투입 전처리
run_pipeline	폴더→정렬→영역→메시→(단순화)→(텍스처)→저장→(내보내기)를 단일 실행으로

360 영상 워크플로

RealityScan 은 등장방형 360 영상을 그대로 못 쓴다(핀홀 왜곡모델 아님). 먼저 convert_360_video 로 원근 뷰(큐브 6면 90° 또는 링)로 재투영한 뒤, 그 폴더를 run_pipeline(또는 new_project+align_images+…)에 먹인다. 각 프레임에 초점거리 XMP 사이드카가 붙어 RealityScan 이 보정된 카메라로 인식한다(언디스토트 불필요). Epic 의 Pano2Views 와 동일한 접근을 로컬 ffmpeg 로 수행. 일반(비360) 영상엔 쓰지 말 것.

convert_360_video(video=eq.mp4, out_dir=persp/, mode=cube, interval=0.5)
run_pipeline(image_folder=persp/, project_path=scan.rsproj, output_model=model.obj)

입력 투영(input_projection): e=등장방형(기본) / eac=YouTube Equi-Angular Cubemap / c3x2·c6x1=큐브맵 / dfisheye=듀얼 피시아이. YouTube 360 은 등장방형이 아니라 EAC 인 경우가 많다(360 인데 화면비가 16:9면 EAC 의심 → 프레임을 떠서 v360=eac:e 로 확인). 그땐 input_projection="eac" 로 변환.

라이브 GUI 모드 (헤드리스 대신 보면서 제어)

헤드리스 배치가 기본이지만, 보이는 GUI 를 띄워두고 실시간 제어할 수 있다 (RealityScan 인스턴스 위임). 문서: "계산 중에도 평소처럼 GUI 로 조작 가능".

launch_gui(instance_name="LIVE1", project_path="C:/…/scan.rsproj")   # 창이 뜸(상주)
execute_cli(commands=["-addFolder","C:/imgs","-align"], instance="LIVE1")  # 그 창에 실시간 위임
get_instance_status(instance_name="LIVE1")                            # 진행 조회
execute_cli(commands=["-quit"], instance="LIVE1", wait=false)         # 닫기(또는 창 수동 종료)

내부적으로 헤드리스 courier 가 -delegateTo LIVE1 … -waitCompleted LIVE1 로 명령을 열린 인스턴스에 전달한다. 사용자는 GUI 에서 진행을 보며 직접 만질 수도 있다.

효율 팁

스텝 사이 프로젝트 재로드는 비용이 크다. 여러 스텝을 한 번에 돌릴 땐 run_pipeline 또는 execute_cli 에 명령을 한꺼번에 넣어 단일 헤드리스 프로세스로 처리하는 게 가장 빠르다.

설치 / 등록

uv venv --python 3.10 .venv
uv pip install --python .\.venv\Scripts\python.exe mcp

convert_360_video 는 외부 ffmpeg(v360 필터 포함)를 사용한다. PATH 에 있거나 환경변수 FFMPEG_EXE 로 지정. (Python 추가 의존성은 없음 — 표준 라이브러리만.)

MCP 클라이언트 설정(~/.claude.json 등)의 mcpServers 에 등록(경로는 설치 위치에 맞게):

"realityscan": {
  "command": "C:\\path\\to\\realityscan-mcp\\.venv\\Scripts\\python.exe",
  "args": ["C:\\path\\to\\realityscan-mcp\\src\\server.py"],
  "env": {}
}

등록/변경 후 클라이언트 재시작 필요.

주의

• 미인식 명령 = 모달 행(실측): 오타 등 미지원 CLI 명령은 -headless 여도 에러 모달창(unknown command ... [err:7180])을 띄워 프로세스를 멈춘다. 그래서 러너가 스폰 전에 KNOWN_COMMANDS(2.1 전체 명령) 화이트리스트로 검증해 즉시 거부한다(음수 인자 -1 등은 값이므로 통과). 상위 버전의 신규 명령을 쓰려면 execute_cli 에 validate=false.
• 라이선스: RealityScan 2.x(Epic)는 Epic 계정 로그인 기반 라이선스를 쓴다. 헤드리스는 캐시된 로그인 자격을 사용하므로, GUI 에서 한 번 로그인해 둔 상태여야 재구성 명령이 통과한다(빈 씬 저장 등은 로그인 없이도 동작 확인됨).
• 무거운 재구성은 오래 걸린다 → 기본 타임아웃 3600초. 필요 시 도구별 timeout 지정.
• params.xml 를 받는 명령(텍스처/내보내기 등)은 RealityScan 이 export 설정을 XML 로 받는 규약을 따른다. GUI 에서 export 설정을 저장해 그 xml 을 넘기면 된다.

전체 CLI

명령 전체 목록은 RealityScan CLI 문서 참고: https://rshelp.capturingreality.com/en-US/appbasics/allcommands.htm execute_cli 로 문서상의 어떤 명령이든 그대로 실행할 수 있다.