# 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` 에 명령을 한꺼번에 넣어 **단일 헤드리스
프로세스**로 처리하는 게 가장 빠르다.

## 설치 / 등록

```powershell
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` 에 등록(경로는 설치 위치에 맞게):

```json
"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` 로 문서상의 어떤 명령이든 그대로 실행할 수 있다.