Imervue 사용 설명서

GPU 가속 이미지 작업 스튜디오. 네 개의 최상위 탭 을 제공합니다. 이 가이드의 대부분은 이 네 개의 탭을 중심으로 구성되어 있습니다.

탭	기능
Imervue	이미지 라이브러리 탐색·표시·정리·검색·일괄 처리. 「Imervue 탭 — 이미지 뷰어 및 라이브러리」를 참조하세요.
Modify	비파괴 현상 파이프라인 — 슬라이더, 커브, LUT, 마스크, 리터치, 다중 이미지 합성. 「Modify 탭 — 비파괴 현상」을 참조하세요.
Paint	래스터 페인팅 스튜디오. 브러시, 레이어, 애니메이션, 만화 도구, PSD I/O. 「Paint 탭 — 페인팅」을 참조하세요.
Puppet	처음부터 만든 2D 리깅 퍼펫 애니메이터 — 메시, 디포머, 매개변수, 모션, 물리. 「Puppet 탭 — 2D 리깅 퍼펫 애니메이션」을 참조하세요.

뒤따르는 「시작하기」「레퍼런스」「플러그인 시스템」「MCP 서버」는 모든 탭에 공통되는 횡단 섹션입니다.

시작하기 

Imervue를 실행하면 세 가지 영역이 표시됩니다:

┌──────────┬──────────────────────┬──────────┐
│  폴더    │                      │  EXIF    │
│  트리    │   이미지 뷰어        │ 사이드바 │
│          │                      │          │
└──────────┴──────────────────────┴──────────┘

왼쪽: 폴더 트리. 폴더를 클릭하면 안의 이미지를 탐색할 수 있습니다
가운데: 이미지 표시 영역. 썸네일 그리드로 모든 이미지를 표시합니다
오른쪽: EXIF 사이드바. 촬영 정보를 표시합니다

이미지 열기 

방법	조작
폴더 열기	`파일` > ``폴더 열기``에서 디렉토리 선택
이미지 열기	`파일` > ``이미지 열기``에서 파일 선택
드래그 앤 드롭	이미지나 폴더를 창에 직접 드롭
탐색기에서 열기	이미지 우클릭 > `Open with Imervue` (파일 연결 등록 필요)
최근 파일	`파일` > `최근 파일`

지원 이미지 형식 

일반: PNG, JPEG, BMP, TIFF, WebP, GIF, APNG, SVG
RAW: CR2 (Canon), NEF (Nikon), ARW (Sony), DNG (Adobe), RAF (Fujifilm), ORF (Olympus)

이미지 탐색 

썸네일 그리드 모드 

폴더를 열면 모든 이미지가 썸네일 그리드로 표시됩니다.

조작	방법
스크롤	마우스 휠
패닝 (이동)	마우스 중간 버튼을 누른 채 드래그
확대 보기로 전환	썸네일 좌클릭
썸네일 크기 변경	메뉴 `썸네일 크기` > 128 / 256 / 512 / 1024 선택
썸네일 밀도	`썸네일 크기` > `썸네일 밀도` > 좁게 / 표준 / 넓게
호버 미리보기	썸네일 위에 커서를 500 ms 유지하면 큰 미리보기 표시
여러 이미지 선택	좌클릭으로 드래그하여 사각형 선택
키보드로 이동	방향키로 패닝, ``Shift``를 누르면 미세 조정

썸네일에는 상태 배지가 표시됩니다: 왼쪽 가장자리의 색상 스트립 (색상 라벨), 왼쪽 위 ❤ (즐겨찾기), 오른쪽 위 ★ (북마크), 왼쪽 아래 평점 별. 아직 로드되지 않은 썸네일은 회전하는 점 플레이스홀더로 표시됩니다.

Ctrl + L 으로 썸네일 그리드와 정렬 가능한 리스트 뷰를 전환합니다. 열: 미리보기 · 라벨 · 이름 · 해상도 · 크기 · 종류 · 수정 시간 · 별점 (클릭으로 0 – 5 설정). 행을 더블클릭 (또는 Enter) 하면 확대 보기로 들어가고, Esc 로 리스트로 돌아갑니다. 썸네일과 메타데이터는 워커 스레드에서 지연 로드되므로 대용량 폴더에서도 응답성을 유지합니다.

확대 보기 모드 (Deep Zoom)

썸네일을 클릭하면 확대 보기 모드로 들어가 고화질로 이미지를 볼 수 있습니다.

조작	방법
확대/축소	마우스 휠 / 터치패드 핀치
패닝	마우스 중간 버튼 드래그
이전 이미지	`←` 왼쪽 방향키 (또는 터치패드 오른쪽 스와이프)
다음 이미지	`→` 오른쪽 방향키 (또는 터치패드 왼쪽 스와이프)
폴더 간 이동	`Ctrl + Shift + ←` / `→` 이전/다음 이미지 있는 형제 폴더로
기록 뒤로/앞으로	`Alt + ←` / `Alt + →` (브라우저 스타일)
번호로 이동	`Ctrl + G`
랜덤 이미지	`X`
너비에 맞춤	`W`
높이에 맞춤	`Shift + W`
줌 초기화	`Home`
썸네일로 돌아가기	`Esc`
전체 화면	`F` (다시 누르면 해제)
극장 모드	`Shift + Tab` 모든 메뉴 / 상태 바 / 트리 숨김
OSD 정보 오버레이	`F8` 파일 정보, `Ctrl + F8` 디버그 HUD (VRAM / 캐시 / 스레드)
픽셀 보기	`Shift + P` — 400 % 이상 확대 시 픽셀 격자와 커서 아래 RGB / HEX 표시
색상 모드	`Shift + M` 일반 / 그레이스케일 / 반전 / 세피아 순환 (GLSL, 비파괴)

분할 뷰 및 듀얼 페이지 읽기 

Compare 대화상자를 열지 않고도 메인 창에서 두 이미지를 나란히 표시:

조작	단축키
분할 뷰 (임의의 두 이미지)	`Shift + S`
듀얼 페이지 (현재 + 다음)	`Shift + D`
듀얼 페이지 (우→좌, 만화용)	`Ctrl + Shift + D`
이전 모드로 복귀	`Esc`

듀얼 페이지 모드에서 방향키는 한 번에 두 장을 진행합니다. RTL 변형은 두 패널을 교환하여 1페이지를 오른쪽에 표시합니다.

다중 모니터 창 

Ctrl + Shift + M 를 누르면 보조 디스플레이에 프레임리스 두 번째 창이 열려 메인 뷰어에 표시된 이미지를 미러링합니다. 메인 창은 독립적으로 계속 탐색할 수 있어 전시, 듀얼 스크린 편집 워크플로우, 클라이언트 프레젠테이션에 유용합니다. Ctrl + Shift + M 를 다시 누르거나 두 번째 창에서 Esc 를 눌러 닫습니다.

이미지 정리 

평가 및 즐겨찾기 

확대 보기 모드에서 이미지에 빠르게 평가를 매길 수 있습니다:

조작	키
즐겨찾기 추가 ❤	`0`
1~5점 평가	`1` `2` `3` `4` `5` (다시 누르면 해제)

색상 라벨 (F1 – F5)

별점과 독립된 플래그 기반 색상 플래그. 빠른 분류에 유용 (예: 빨강=삭제 후보, 초록=채택, 파랑=보정 필요).

조작	키
빨강 / 노랑 / 초록 / 파랑 / 보라	`F1` / `F2` / `F3` / `F4` / `F5` (같은 키로 해제)
선택 항목에 일괄 적용	여러 썸네일을 선택 후 해당 F 키 누르기
색상별 필터링	`필터` > `색상 라벨로 필터` > 색상 / 라벨 있음 / 라벨 없음

상태 바에 현재 이미지의 색상 칩, 썸네일 왼쪽 가장자리에 색상 스트립, 리스트 뷰에는 정렬 가능한 「라벨」 열이 표시됩니다.

북마크 

자주 사용하는 이미지를 북마크에 추가하여 나중에 빠르게 접근할 수 있습니다.

조작	방법
북마크 추가/해제	확대 보기 모드에서 `B`
북마크 관리	`파일` > `북마크`

태그 및 앨범 

태그와 앨범으로 이미지를 분류 관리할 수 있습니다.

조작	방법
관리 화면 열기	T``를 누르거나 ``파일 > `태그 및 앨범`
이미지에 태그 추가	이미지 우클릭 > `태그에 추가`
앨범에 추가	이미지 우클릭 > `앨범에 추가`
단일 태그 / 앨범으로 필터링	`필터` > `태그별` / `앨범별`
다중 태그 필터 (AND / OR)	`필터` > `다중 태그 필터…` — 여러 태그/앨범 선택 후 「아무거나 (OR)」 또는 「모두 (AND)」

정렬 및 필터링 

기능	메뉴 위치
이름순 정렬	`정렬` > `이름순`
수정일순 정렬	`정렬` > `수정일순`
파일 크기순 정렬	`정렬` > `파일 크기순`
해상도순 정렬	`정렬` > `해상도순`
오름차순/내림차순	`정렬` > `오름차순` / `내림차순`
확장자별 필터링	`필터` > `JPEG` / `PNG` / `RAW` 등
평가별 필터링	`필터` > `평가별`
색상 라벨별 필터링	`필터` > `색상 라벨로 필터` (모두 / 라벨 있음 / 라벨 없음 / 빨강 / 노랑 / 초록 / 파랑 / 보라)
고급 필터	`필터` > `고급 필터…` — 해상도 범위, 파일 크기 범위, 방향 (가로/세로/정방형), 수정일 범위
필터 해제	`필터` > `필터 해제`

탐색 모드 (그리드 / 리스트)

썸네일 그리드와 정렬 가능한 상세 리스트 간 전환:

Ctrl + L — 그리드 ↔ 리스트
메뉴: 썸네일 크기 > 탐색 모드 > 그리드 / 리스트
리스트 모드에서 라벨을 포함한 모든 열 정렬 가능; 행 더블클릭이나 Enter 로 확대 보기

이미지 편집 (수정 탭)

상단의 “수정” 탭으로 전환하면 편집 모드로 들어갑니다. 확대 보기 모드에서 ``E``를 누르거나, 우클릭 > ``수정``으로도 진입할 수 있습니다.

┌────────┬──────────────────────┬────────────┐
│  도구  │                      │  속성      │
│  바    │ 캔버스 (직접 그리기)  │ 브러시, 색 │
│        │                      │ 현상 조정  │
└────────┴──────────────────────┴────────────┘

주석 도구 (왼쪽 패널)

도구	아이콘	설명
선택	⬚	기존 주석을 선택하고 드래그로 이동
사각형	▢	사각형 그리기
타원	◯	타원 또는 원 그리기
직선	╱	직선 그리기
화살표	→	화살표 그리기
프리핸드	✎	자유롭게 선 그리기
텍스트	T	이미지에 텍스트 추가
모자이크	▦	선택 영역에 모자이크 처리
블러	◌	선택 영역에 블러 처리

Tip

수정 탭에서 ← ``→``를 누르면 편집기를 닫지 않고 이미지를 전환할 수 있습니다.

브러시 종류 (오른쪽 패널)

브러시	효과
펜	표준 가는 선, 가장 많이 사용하는 브러시
마커	두껍고 반투명한 스트로크
연필	가늘고 옅은 선
형광펜	넓고 투명도가 높음, 실제 형광펜 같은 효과
스프레이	흩뿌리기 점 효과
캘리그라피	스트로크 방향에 따라 두께 변화
수채화	부드럽게 번지는 효과
목탄	거친 질감의 스트로크
크레용	왁스 같은 질감

그리기 속성 (오른쪽 패널)

속성	설명
색상	색상 패치를 클릭하여 그리기 색상 선택
선 굵기	슬라이더로 선 두께 조정 (1~40)
불투명도	투명도 조정 (0%~100%)
글꼴	텍스트 도구에서 사용할 글꼴 선택
글꼴 크기	텍스트 크기 조정 (6~200 px)

이미지 조정 (오른쪽 패널 하단)

슬라이더	기능
노출	전체적인 밝기 조정
밝기	밝고 어두움 미세 조정
대비	명암 대비 조정
채도	색상 선명도 조정
화이트 밸런스 — 색온도	차가움 / 따뜻함 이동 (파랑 ↔ 노랑). 혼합 조명이나 실내 촬영에 유용
화이트 밸런스 — 틴트	마젠타 / 그린 이동. 형광등 색조 보정
섀도	어두운 영역 디테일을 살리거나 억누르기
중간톤	검정과 흰색은 건드리지 않고 중간 톤만 조정
하이라이트	날아간 하이라이트 복구 또는 밝은 영역 추가 강화
생동감 (Vibrance)	채도 인식 증강 — 피부톤과 이미 채도가 높은 색상은 보호

이러한 조정은 비파괴적 입니다. 각 슬라이더는 이미지별 Edit Recipe에 기록되며 초기화 또는 ``Ctrl + Z``로 언제든지 복구할 수 있습니다. Recipe는 재시작 후에도 유지되며 XMP sidecar를 통해 내보내기 / 동기화할 수 있습니다 (메타데이터 섹션 참조).

저장 및 실행취소 

버튼	설명
저장	주석과 조정을 원본 파일에 기록
실행취소	마지막 작업 취소
다시실행	취소한 작업 다시 실행
초기화	모든 이미지 조정 초기화

페인트 워크스페이스 (페인트 탭)

세 번째 최상위 탭인 페인트 는 의 페인팅 워크스페이스로, 다중 문서 탭, 벡터 및 래스터 레이어, 만화 도구, 애니메이션 프레임, PSD 가져오기/내보내기를 지원합니다. 탭 막대에서 전환하거나 딥줌 모드에서 E 를 누르면 현재 이미지가 새 페인트 탭으로 보내집니다.

+------+----------------------+----------------+
| 도구 |                      | 색상 · 브러시  |
| 막대  |    캔버스 (그리기)    | 레이어 · 내비  |
|      |                      | 소재 · …       |
+------+----------------------+----------------+

오른쪽 도크 (색상, 브러시, 레이어, 내비게이터, 소재 라이브러리, 히스토리, 스와치, 참고, 히스토그램, 애니메이션) 는 단일 열에 탭으로 묶여 있어 캔버스가 표시 가능한 전체 높이를 유지합니다. 도크 제목을 끌어 재배치하거나 띄울 수 있고, 설정 > 워크스페이스 레이아웃… 으로 이름을 붙여 저장할 수 있습 니다.

도구 팔레트 (왼쪽)

도구	단축키	용도
브러시	`B`	현재 브러시 종류로 그리기
지우개	`E`	활성 레이어를 알파 지우기
채우기	`G`	허용치 / 연속 영역 / 모든 레이어 샘플링 채우기
스포이트	`I`	캔버스에서 전경색 추출
이동	`V`	활성 레이어 또는 선택 영역 이동
사각 / 올가미 / 마술봉 / 빠른 선택	`M` / `L` / `W`	교체 / 추가 / 빼기 / 교차 모드의 선택 도구
텍스트	`T`	인라인 텍스트 편집 (글꼴 / 크기 / 굵게 / 기울임)
그라디언트	`U`	선형 / 방사 / 각도 / 다이아몬드 그라디언트
흐림 / 손가락	`R`	국소 픽셀 조작
펜 (베지어)	`P`	앵커 / 핸들 편집이 가능한 벡터 패스
복제 도장	`S`	Shift+클릭으로 소스 설정, 클릭으로 페더 도장
말풍선	`Ctrl + B`	만화 / 코믹 풍선과 자동 꼬리
사각 / 타원 / 직선 / 다각형	`Shift + R/E/I/P`	윤곽 + 채우기 벡터 도형
자르기	`C`	가로세로 비율 프리셋이 있는 대화형 자르기
변형	`Ctrl + T`	자유 / 크기 / 회전 / 기울이기 핸들
손	`H`	캔버스를 끌어 이동
줌	`Z`	클릭으로 확대, Alt+클릭으로 축소

브러시 

브러시	효과
펜	선명한 안티앨리어싱 선, 일상용
마커 / 형광펜	누적되는 반투명 굵은 획
연필	가늘고 약간 거친 연필 선
스프레이	밀도와 흐름에 따라 흩어지는 점
캘리그래피	획 방향에 따라 굵기 변화
수채	젖은 가장자리 번짐과 부드러운 혼합
목탄 / 크레용	압력 기울기에 따라 거친 텍스처

각 브러시는 브러시 도크 와 상단 옵션 막대 에서 크기 / 불투명도 / 경도 / 밀도 / 블렌드 모드를 제공합니다. 설정 > 압력 곡선… 으로 태블릿 압력을 굵기 또는 불투명도에 매핑하고, 편집 > 브러시 끝 캡처… 로 선택 영역을 사용자 정의 브러시 끝으로 변환할 수 있습니다.

레이어 

레이어 도크 는 썸네일, 표시 토글, 즉시 이름 변경, 드래그 정렬, 활성 레이어 블렌드 모드 및 불투명도를 제공합니다. 레이어 메뉴에는 추가로:

새로 / 벡터 / 복제 / 아래 병합 (Ctrl + Shift + N / Ctrl + Shift + V / Ctrl + J / Ctrl + E)
마스크 — 추가 / 선택에서 / 반전 / 적용 / 삭제 (Ctrl + Shift + M 추가; Ctrl + Alt + Shift + M 선택에서)
클리핑 마스크 — 위 레이어를 현재 알파에 클립 (Ctrl + Alt + G)
레이어 효과 — 그림자 / 외부 광선 / 윤곽; 효과 지우기
참조 레이어 — 한 레이어를 스포이트 소스로 고정
1-bit 레이어 — 라인 아트용 이진 레이어로 전환
색상으로 레이어 분할 — 단색 평면을 색상별로 분할해 다시 칠하기 쉽게
그라디언트 맵 — 프리셋 (세피아 / 노을 / 청사진 …)

선택 영역 

사각 / 올가미 / 마술봉 / 빠른 선택 도구 사용 후 편집 메뉴의 선택 영역 윤곽… 으로 현재 브러시로 가장자리를 그릴 수 있습니다. Q 는 빠른 마스크 모드 를 토글합니다 — 임의의 브러시로 빨간 영역에 가장자리를 다듬고 Q 를 다시 눌러 선택 영역으로 변환합니다.

애니메이션 

애니메이션 도크 는 문서를 프레임 시퀀스로 만듭니다:

프레임 추가 가 현재 레이어 상태를 키프레임으로 저장합니다.
프레임 썸네일을 클릭해 점프합니다.
양파 껍질 (보기 메뉴) 이 인접 프레임을 낮은 알파로 겹칩니다.
파일 > 페이지 내보내기 로 만화 뷰어용 CBZ / 인쇄용 PDF 로 내보내거나, 애니메이션 내보내기 로 MP4 / GIF 출력.

만화 메뉴 

동작	설명
컷 분할	`Ctrl + Shift + P` — 캔버스를 행 / 열 / 간격 / 테두리 / 여백 으로 분할
톤 레이어 토글	활성 레이어를 스크린톤(하프톤) 레이어로 변환
페이지 번호 스탬프	다중 페이지 문서에 페이지 번호 추가
집중선	방사형 / 평행 / 폭발 세 가지 집중선 생성기
액션 플래시	만화풍 폭발 / 충격 플래시 오버레이
말풍선 도구	풍선을 끌어 놓고 말하는 사람 쪽으로 꼬리를 떨어뜨림

필터 

필터 는 각 효과의 실시간 미리보기 대화상자를 엽니다:

레벨 — 채널별 검정 / 감마 / 흰색 슬라이더
곡선 — 드래그 가능한 점 (RGB / R / G / B), 단조 3차 보간
포스터화 — 색상을 N 단계로 양자화
임계값 — 컷오프에서 순수 흑백으로 변환
자동 색상 균형 — 그레이 월드 / 화이트 패치로 색조 제거
필름 그레인 — 크기와 양 조정 가능한 휘도 노이즈
하프톤 변환 — 신문풍 점 스크린

보기 보조 

픽셀 격자 (Ctrl + Shift + ') — 고배율에서 1 픽셀 격자 표시
픽셀 / 가장자리에 스냅 — 서브픽셀 위치를 정수 좌표에 고정
양파 껍질 — 애니메이션 인접 프레임 겹침
재단 가이드 — 인쇄 재단 / 안전 영역 가이드
캔버스 회전 (Ctrl + Shift + H) — 래스터화 없는 보기 회전

파일 I/O 

PSD 열기… (Ctrl + O) 와 PSD 로 저장… (Ctrl + S) — 마스크, 블렌드 모드, 레이어 효과를 포함한 Photoshop 레이어 라운드트립
이미지 내보내기… — 평면화하여 PNG / JPEG / WebP / BMP / TIFF 로 저장
페이지 내보내기 → CBZ / → PDF — 다중 프레임 만화 문서 내보내기
브러시 프리셋 가져오기 / 내보내기, 팔레트 가져오기 — 설치 간 리소스 공유
자동 저장 스냅샷 — 백그라운드 주기 스냅샷, 파일 메뉴에서 최신 복원

워크스페이스 레이아웃 

설정 > 워크스페이스 레이아웃… 은 도크 배치, 도구 옵션 상태, 활성 패널을 이름으로 저장하고 한 번의 클릭으로 전환합니다 — 예를 들어 “그리기” 레이아웃은 브러시와 색상 도크를 강조하고 “합성” 레이아웃은 레이어와 히스토리 도크를 확장합니다.

회전 및 뒤집기 

조작	단축키	메뉴
시계 방향 90° 회전	`R`	우클릭 > 수정 > 시계 방향 회전
반시계 방향 90° 회전	`Shift + R`	우클릭 > 수정 > 반시계 방향 회전
좌우 뒤집기	–	우클릭 > 수정 > 좌우 뒤집기
상하 뒤집기	–	우클릭 > 수정 > 상하 뒤집기
무손실 회전 (JPEG)	–	우클릭 > 무손실 회전

이미지 내보내기 

단일 내보내기 

이미지 우클릭 > 내보내기 / 다른 이름으로 저장

형식 선택: PNG, JPEG, WebP, BMP, TIFF
품질 조정 (손실 형식의 경우)
파일 크기 미리보기
저장 위치 선택

내보내기 프리셋 

자주 쓰는 용도를 위해 파일 > 프리셋으로 내보내기 에서 리사이즈 / 형식 / 품질을 원클릭으로 적용할 수 있습니다:

프리셋	파이프라인
Web 1600	긴 변 1600 px, JPEG 품질 85, sRGB. 블로그 / 포럼 업로드용.
Print 300 dpi	풀 해상도 TIFF / 고품질 JPEG, 300 dpi 메타데이터 포함, 컬러 관리. 인쇄 전문.
Instagram 1080	정사각형 (1080 × 1080) 또는 세로 (1080 × 1350) 크롭, 품질 90 JPEG.

프리셋은 아래 워터마크 오버레이와 함께 사용할 수 있습니다 — 한 번 활성화하면 모든 프리셋 출력에 자동으로 포함됩니다.

워터마크 오버레이 

파일 > 워터마크… 에서 비파괴 오버레이를 설정합니다. 내보낼 때만 적용되며 원본 픽셀은 변경되지 않습니다.

모드: 텍스트 또는 이미지. 이미지 워터마크는 알파 PNG를 지원합니다.
위치: 9-앵커 그리드 (모서리, 가장자리, 중앙).
불투명도: 0 – 100 %.
크기: 내보낼 긴 변의 % 단위. 프리셋 크기에 맞춰 자동 리사이즈.

일괄 내보내기 

여러 이미지를 선택 후, 우클릭 > 일괄 내보내기

일괄 형식 변환
최대 너비/높이 설정 (종횡비 유지 자동 축소)
품질 조정
실시간 진행률 바

GIF / 동영상 만들기 

여러 이미지를 선택 후, 우클릭 > GIF / 동영상 만들기

GIF 및 MP4 지원
드래그로 프레임 순서 변경
초당 프레임 수 (FPS) 설정
사용자 지정 크기
반복 재생 옵션

애니메이션 재생 

GIF, APNG, 애니메이션 WebP를 열면 자동으로 애니메이션이 재생됩니다.

키	조작
`Space`	재생/일시정지
`,`	이전 프레임
`.`	다음 프레임
`]`	속도 증가
`[`	속도 감소

이미지 비교 

썸네일 모드에서 2~4장의 이미지를 선택하고, 우클릭 > 이미지 비교.

대화상자에는 네 개의 탭이 있습니다:

탭	용도
나란히	2장 또는 4장을 동시에 표시. 각 패널에서 자동 맞춤.
오버레이	두 이미지를 α 슬라이더로 혼합 (0 → A만, 100 → B만). 정확히 2장 선택 필요.
차이	픽셀 단위 `\|A − B\|` 시각화. 게인 슬라이더 (0.10×–20×) 로 미세한 차이 증폭.
A \| B 분할	before / after 분할 뷰. 드래그 가능한 세로 분할선으로 좌우를 훑을 수 있습니다. Develop 조정이나 내보내기 결과 비교에 적합. 정확히 2장 선택 필요.

크기가 다를 때 Lanczos 로 B를 A 크기에 리샘플링합니다. 매우 큰 이미지는 내부적으로 긴 변을 2048 px로 축소해 실시간 반응성을 유지합니다.

슬라이드쇼 

``S``를 누르거나 우클릭 > ``슬라이드쇼``로 자동 재생을 시작합니다.

이미지별 표시 시간 조정 가능
페이드 전환 효과 (선택 사항)

이미지 검색 

Ctrl + F 또는 ``/``를 눌러 키워드를 입력하면, 현재 폴더에서 파일 이름으로 이미지를 검색합니다.

검색은 퍼지 매칭 (접두사 > 부분 문자열 > 부분 순서 3단계 랭크) 과 부분 문자열 하이라이트 를 지원합니다. Enter 또는 결과를 더블클릭하면 해당 이미지로 이동합니다.

번호로 이동하려면 Ctrl + G 로 이동 대화상자를 엽니다.

복사 및 붙여넣기 

조작	방법
이미지를 클립보드에 복사	확대 보기 모드에서 `Ctrl + C`
클립보드 이미지 붙여넣기	`파일` > `클립보드에서 붙여넣기`, 또는 `Ctrl + V`
클립보드 자동 감시	`파일` > `클립보드 이미지 자동 주석` 체크

Note

자동 감시를 활성화하면 새 이미지가 클립보드에 나타날 때마다 (스크린샷 도구 등) 자동으로 주석 편집기가 열립니다.

이미지 삭제 

조작	방법
현재 이미지 삭제	`Delete` 키
선택한 여러 이미지 삭제	선택 후 `Delete` 또는 우클릭 > `선택한 이미지 삭제`

이미지는 시스템 휴지통으로 이동되며, 거기에서 복원할 수 있습니다.

일괄 작업 

썸네일 모드에서 여러 이미지를 선택 후, 우클릭으로 다음 작업이 가능합니다:

기능	설명
일괄 이름변경	템플릿 `{name}`, `{n}`, ``{ext}``로 자동 명명
이동/복사	이미지를 다른 폴더로 이동 또는 복사
전체 회전	선택한 모든 이미지를 한 번에 회전
일괄 내보내기	형식과 크기를 일괄 변환
태그에 추가	선택한 모든 이미지에 같은 태그 부여
앨범에 추가	선택한 모든 이미지를 앨범에 추가

RGB 히스토그램 

확대 보기 모드에서 ``H``를 누르면 이미지 위에 RGB 히스토그램이 표시됩니다. 다시 누르면 숨깁니다.

배경화면 설정 

확대 보기 모드에서 우클릭 > ``배경화면으로 설정``으로 현재 이미지를 데스크톱 배경화면으로 설정합니다.

Windows, macOS, Linux (GNOME)를 지원합니다.

멀티 윈도우 

파일 > ``새 창``으로 독립적인 Imervue 창을 추가로 열 수 있습니다. 각 창에서 다른 폴더를 탐색할 수 있습니다.

터치패드 제스처 

제스처	동작
핀치	확대 보기에서 확대/축소 (핀치 중심 기준)
수평 스와이프	이전 / 다음 이미지

파일 연결 (Windows)

Windows 탐색기에서 직접 Imervue로 이미지를 열 수 있게 합니다:

파일 > 파일 연결 > Open with Imervue 등록
관리자 권한이 필요합니다
등록 후 이미지를 우클릭하면 Open with Imervue 옵션이 표시됩니다

해제하려면: 파일 > 파일 연결 > 파일 연결 해제

플러그인 시스템 

Imervue는 플러그인을 통한 기능 확장을 지원합니다.

조작	메뉴 위치
설치된 플러그인 보기	`플러그인` > `플러그인 관리`
새 플러그인 다운로드	`플러그인` > `플러그인 다운로드`
플러그인 폴더 열기	`플러그인` > `플러그인 폴더 열기`
플러그인 다시 로드	`플러그인` > `플러그인 다시 로드`

언어 전환 

언어 메뉴에서 인터페이스 언어를 전환할 수 있습니다:

English
繁體中文
简体中文
한국어
日本語

전환 후 재시작이 필요합니다.

키보드 단축키 목록 

탐색 

키	기능
`←` / `→`	이전/다음 이미지
방향키	썸네일 모드에서 패닝
`Shift + 방향키`	미세 패닝
`Ctrl + Shift + ←` / `→`	이전/다음 이미지 있는 형제 폴더로 이동
`Alt + ←` / `Alt + →`	탐색 기록 뒤로/앞으로 (브라우저 스타일)
`Ctrl + G`	번호로 이미지 이동
`X`	랜덤 이미지로 이동
마우스 휠 / 핀치	확대/축소
수평 스와이프	이전 / 다음 이미지
마우스 중간 버튼 드래그	패닝
`F`	전체 화면
`Shift + Tab`	극장 모드 (모든 UI 숨김)
`Ctrl + L`	그리드 ↔ 리스트 (상세) 전환
`Shift + S`	분할 뷰 (두 이미지 나란히)
`Shift + D` / `Ctrl + Shift + D`	듀얼 페이지 / 우→좌 (만화)
`Ctrl + Shift + M`	보조 디스플레이 미러 창
`Esc`	썸네일로 돌아가기 / 전체 화면 해제 / 듀얼 또는 리스트 모드 닫기
`W`	너비에 맞춤
`Shift + W`	높이에 맞춤
`Home`	줌 초기화

편집 

키	기능
`E`	수정 탭 열기
`R`	시계 방향 회전
`Shift + R`	반시계 방향 회전
`Ctrl + Z`	실행취소
`Ctrl + Shift + Z`	다시실행
`Delete`	이미지 삭제

정리 

키	기능
`0`	즐겨찾기 추가/해제
`1` ~ `5`	평가 (다시 누르면 해제)
`F1` ~ `F5`	색상 라벨: 빨강/노랑/초록/파랑/보라 (다시 누르면 해제)
`P`	컬링: Pick (보관 표시)
`Shift + X`	컬링: Reject (탈락 표시)
`U`	컬링: 플래그 해제
`B`	북마크 추가/해제
`T`	태그 및 앨범 관리

도구 및 오버레이 

키	기능
`Ctrl + F` / `/`	퍼지 검색 (부분 문자열 하이라이트)
`Ctrl + C`	이미지를 클립보드에 복사
`Ctrl + V`	클립보드에서 붙여넣기
`H`	RGB 히스토그램
`F8` / `Ctrl + F8`	OSD 정보 / 디버그 HUD (VRAM, 캐시, 스레드)
`Shift + P`	픽셀 보기 (400 % 이상 시 격자와 커서 아래 RGB 값 표시)
`Shift + M`	색상 모드 순환 (일반/그레이스케일/반전/세피아)
`S`	슬라이드쇼

애니메이션 

키	기능
`Space`	재생/일시정지
`,`	이전 프레임
`.`	다음 프레임
`[`	속도 감소
`]`	속도 증가

라이브러리 및 메타데이터 관리 

Imervue는 %LOCALAPPDATA%/Imervue/library.db (Windows) 또는 ~/.cache/imervue/library.db (POSIX)에 SQLite 인덱스를 유지하여 폴더 간 검색, 계층 태그, 스마트 앨범, 지각 해시, 메모, 컬링 플래그를 관리합니다. 아래 기능은 대부분 Extra Tools 메뉴에 있습니다. 찾기 쉽도록 메뉴는 기능별 8개 하위 메뉴로 구성됩니다: Batch``(일괄 처리), ``Library & Metadata``(라이브러리 및 메타데이터), ``Views``(보기), ``Workflow``(워크플로), ``Export``(내보내기), ``Develop (Non-Destructive)``(현상), ``Retouch & Transform``(리터치 및 변형), ``Multi-Image``(다중 이미지). 아래 경로는 모두 ``Extra Tools > <하위 메뉴> > <도구> 형태로 표기합니다.

라이브러리 검색 

Extra Tools > Library & Metadata > ``Library Search``에서 하나 이상의 **루트 폴더**를 글로벌 인덱스에 추가하면 백그라운드에서 크롤링됩니다. 확장자, 최소 너비/높이, 크기 범위, 파일명 부분 일치로 검색하고 결과를 가상 앨범으로 뷰어에 불러올 수 있습니다.

스마트 앨범 

Extra Tools > Library & Metadata > ``Smart Albums``는 필터 규칙(확장자, 최소 크기, 색상 라벨, 평점, 즐겨찾기, 컬링 상태, 계층 태그, 파일명 부분 일치)을 친숙한 이름으로 저장합니다. 다시 적용하면 현재 폴더가 규칙대로 필터링됩니다.

유사 이미지 검색 

Extra Tools > Library & Metadata > ``Find Similar Images``는 현재 Deep Zoom 이미지(또는 첫 번째 선택 타일)의 64비트 DCT pHash를 계산하여 해밍 거리 순으로 인덱스 내 유사 이미지를 보여줍니다. ``Max distance``로 범위를 조절할 수 있습니다.

자동 태그 

Extra Tools > Library & Metadata > Auto-Tag Images``는 휴리스틱 태그를 ``auto/... (photo / document / screenshot / landscape / portrait) 아래에 부여합니다. ``onnxruntime``과 ``models/clip_vit_b32.onnx``가 있으면 CLIP 기반 콘텐츠 라벨도 추가됩니다. 작업 스레드에서 실행되며 실시간 진행률 표시줄을 제공합니다.

계층 태그 

Extra Tools > Library & Metadata > Hierarchical Tags``는 트리 구조 태그(예 ``animal/cat/british)를 관리합니다. 노드를 선택하면 자손 태그까지 포함한 이미지 목록을 볼 수 있으며, 현재 선택을 한 번에 태그/해제할 수 있습니다. 우클릭 메뉴의 평면 태그와 공존합니다.

Token 일괄 이름 변경 

Extra Tools > Batch > Token Batch Rename``은 실시간 미리보기 표를 제공합니다. ``{date:yyyymmdd}_{camera}_{counter:04}{ext} 같은 템플릿을 입력하면 각 파일의 새 이름이 즉시 표시되며 충돌은 강조됩니다. 지원 토큰: {name} {ext} {counter[:NN]} {date[:fmt]} {width} {height} {wxh} {size_kb} {camera} {year} {month} {day} {hour} {minute}.

메타데이터 내보내기 

Extra Tools > Library & Metadata > ``Export Metadata (CSV / JSON)``은 현재 뷰의 각 이미지를 한 행으로 출력하며 EXIF, 크기, 색상 라벨, 평점, 즐겨찾기, 계층 태그, 컬링 상태, 메모를 포함합니다. 스프레드시트나 외부 워크플로에 유용합니다.

XMP Sidecar (other XMP-aware photo managers 연동)

Imervue는 Adobe XMP sidecar 파일 (photo.jpg ↔ photo.xmp) 읽기/쓰기를 지원하여 평점, 제목, 설명, 키워드, 색상 라벨을 other XMP-aware photo managers, other XMP-aware photo managers, Bridge 등 XMP 인식 도구와 양방향으로 동기화할 수 있습니다.

현재 이미지용 XMP 가져오기 — sidecar에서 평점 / 제목 / 키워드 / 색상 라벨을 내부 DB로 가져옵니다.
현재 이미지용 XMP 내보내기 — 현재 평점 / 제목 / 키워드 / 색상 라벨을 이미지 옆 sidecar에 기록합니다.
일괄 가져오기 / 내보내기 — 현재 선택 또는 폴더 전체에 동일 작업 적용.

XML 파싱은 ``defusedxml``을 거쳐 XXE / billion-laughs 공격을 방지합니다. ``defusedxml``이 설치되지 않은 경우 XMP 메뉴 항목은 숨겨지고 sidecar는 작성되지 않습니다.

EXIF 사이드바 의 클릭 가능한 별점 스트립 에서 설정한 평점이 그대로 XMP 내보내기의 값으로 사용됩니다.

컬링 (Pick / Reject)

플래그 기반의 3상태 플래그. P``는 현재 이미지나 모든 선택 타일을 Pick, ``Shift + X``는 Reject, ``U``는 해제합니다. ``Filter > By Cull State``로 특정 상태만 표시할 수 있고, ``Extra Tools > Workflow > Culling 대화 상자에는 Delete all rejects 버튼이 있어 Reject 플래그된 파일을 디스크 에서 영구 삭제할 수 있습니다.

스테이징 트레이 

Extra Tools > Workflow > ``Staging Tray``는 폴더를 가로지르는 바구니입니다. 임의의 타일을 트레이에 담고(재시작 후에도 유지) 전체를 대상 폴더로 한 번에 이동/복사할 수 있습니다. 여러 촬영에서 Pick을 모아 내보낼 때 유용합니다.

듀얼 페인 파일 관리자 

Extra Tools > Workflow > ``Dual-Pane File Manager``는 듀얼 페인의 두 트리 뷰를 제공하여 두 폴더 간에 선택을 직접 이동/복사할 수 있습니다.

타임라인 뷰 

Extra Tools > Views > ``Timeline View``는 현재 이미지 집합을 일/월/년 단위로 그룹화합니다 (Google 포토 스타일). 날짜는 EXIF ``DateTimeOriginal``을 우선 사용하며, 없으면 파일 수정 시간을 사용합니다. 이미지를 더블 클릭하면 Deep Zoom에서 열립니다.

외부 앱으로 드래그 아웃 

선택된 타일에서 누르고 드래그하면 파일 URL을 받는 탐색기, Chrome, Discord 등에 파일을 드롭할 수 있습니다. 드래그 미리보기는 타일 썸네일입니다.

이미지별 메모 

EXIF 사이드바에는 자유 텍스트 Notes 필드가 있습니다. 입력은 짧은 디바운스 후 자동 저장되고, 메모는 이미지 경로에 연결되므로 폴더 재스캔 후에도 유지됩니다.

고급 현상 및 합성 

톤 커브 

Extra Tools > Develop (Non-Destructive) > Tone Curve 에서 RGB·R·G·B 4 채널의 드래그 가능 포인트 커브 편집기를 엽니다. 빈 공간을 좌클릭하면 포인트 추가, 드래그 로 이동, 우클릭으로 삭제합니다. 포인트 사이는 monotone cubic 으로 보간되며, 커브는 recipe 에 저장되어 렌더링 시 비파괴적으로 적용됩니다.

.cube LUT 적용 

Extra Tools > Develop (Non-Destructive) > Apply .cube LUT 에서 Adobe .cube 파일(1D / 3D, 최대 64³)을 선택할 수 있습니다. LUT 는 경로 + mtime 키로 lru_cache 에 유지되고, 삼선형 보간으로 적용되며 강도 슬라이더로 원본과 블렌딩됩니다. LUT 경로와 강도는 recipe 에 저장됩니다.

가상 복사본 

Extra Tools > Workflow > Virtual Copies 은 한 이미지에 대해 이름이 붙은 여러 recipe 스냅샷을 유지합니다. 현재 편집을 저장한 뒤 실험을 계속하고, 언제든 다른 버전으로 전환할 수 있습니다. 배리언트는 마스터 recipe 와 함께 저장되어 마스터를 identity 로 리셋해도 남아 있습니다.

HDR 병합 

Extra Tools > Multi-Image > HDR Merge 는 OpenCV Mertens 노출 합성으로 브라케팅 촬영을 한 장으로 합칩니다. Align 체크박스를 켜면 먼저 cv2.AlignMTB 로 흔들림을 보정합니다. 결과는 지정 파일에 저장 되며 원본은 건드리지 않습니다.

파노라마 스티치 

Extra Tools > Multi-Image > Panorama Stitch 는 OpenCV Stitcher 를 이용해 겹치는 프레임을 이어 붙입니다. 풍경 / 도시경관은 Panorama, 평평한 문서 / 작품은 Scans 모드를 사용합니다. 합성으로 생기는 검은 테두리는 자동 크롭할 수 있습니다.

포커스 스태킹 

Extra Tools > Multi-Image > Focus Stacking 은 초점 거리가 다른 여러 장을 합성합니다. Laplacian 분산으로 각 픽셀의 선명도를 측정해 가장 선명한 프레임을 채택하고, 선택 마스크를 가우시안으로 부드럽게 블렌딩합니다. ECC 정렬이 기본으로 활성화되어 약간의 핸드헬드 오프셋을 보정합니다.

복원 브러시 

Extra Tools > Retouch & Transform > Healing Brush 는 현재 이미지를 최대 720px 길이의 미리보기로 보여 줍니다. 좌클릭으로 원형 스팟 추가, 우클릭으로 제거, 반경 슬라이더로 새 스팟 크기를 조정합니다. 적용 시 OpenCV inpainting (Telea / Navier-Stokes)으로 영역을 채우고 새 파일로 저장합니다.

렌즈 보정 

Extra Tools > Retouch & Transform > Lens Correction 은 순수 numpy 기반 4 슬라이더를 제공합니다: 방사 왜곡 k1 (배럴 / 핀쿠션), 비네트 보정, 빨강 / 파랑 채널 색수차 방사 스케일. 출력 크기가 바뀔 수 있어 recipe 가 아닌 새 파일로 저장됩니다.

지도 보기 

Extra Tools > Views > Map View 는 Leaflet + OpenStreetMap (PySide6.QtWebEngineWidgets 필요)로 라이브러리의 GPS 태그된 이미지를 모두 지도에 표시합니다. WebEngine 이 없으면 좌표 목록으로 대체됩니다.

달력 보기 

Extra Tools > Views > Calendar View 는 QCalendarWidget 에서 사진이 있는 날짜를 강조합니다(EXIF DateTimeOriginal → DateTimeDigitized → 파일 mtime 순). 날짜를 선택하면 해당일 사진이 나열되고, 더블클릭으로 메인 뷰어에서 엽니다.

얼굴 검출 

Extra Tools > Retouch & Transform > Face Detection 은 OpenCV Haar 정면 얼굴 분류기로 현재 이미지를 스캔하고 사각형으로 표시합니다. 목록 항목을 더블클릭해 이름을 입력하고 저장하면 recipe 의 extra['face_tags'] 에 기록 됩니다. 고전적 기법이라 “얼굴 위치 파악”에는 충분하지만 최신 CNN 기반 인식의 대체물은 아닙니다.

로컬 조정 마스크 

Extra Tools > Develop (Non-Destructive) > Local Adjustment Masks 는 브러시 / 방사형 / 선형 그라디언트 마스크를 쌓을 수 있습니다. 각 마스크에는 노출, 밝기, 대비, 채도, 색온도, 틴트 델타와 페더 슬라이더가 있으며, recipe.extra['masks'] 에 저장되어 로드 시 비파괴적으로 적용됩니다.

스플릿 토닝 

Extra Tools > Develop (Non-Destructive) > Split Toning 은 섀도와 하이라이트에 각각 색조 와 채도를 적용하고 밸런스로 경계를 결정합니다. recipe.extra 에 저장되며 톤 커브 이후에 적용됩니다.

복제 도장 

Extra Tools > Retouch & Transform > Clone Stamp 은 소스 영역을 페더와 함께 대상 으로 복제합니다. 복구 브러시의 하드 엣지 버전입니다. Shift+클릭으로 소스 지정, 클릭으로 스탬프, 우클릭으로 취소. 결과는 새 파일로 저장됩니다.

자르기 / 수평 맞춤 

Extra Tools > Retouch & Transform > Crop / Straighten 은 0..1 정규화 자르기 사각형과 임의 각도 수평 맞춤을 결합합니다. 출력은 최대 내접 사각형으로 자동 잘려 검은 모서리가 없습니다.

자동 수평 맞춤 

Extra Tools > Retouch & Transform > Auto-Straighten 은 Hough line 으로 주요 수평 또는 수직선을 검출해 회전 각도를 제안합니다. 적용 전에 각도를 조정할 수 있습니다.

노이즈 감소 / 선명도 

Extra Tools > Retouch & Transform > Noise Reduction / Sharpening 은 엣지 보존 bilateral 노이즈 감소와 언샤프 마스크 선명화를 결합합니다. “휘도 만” 옵션은 컬러 노이즈는 유지하면서 휘도 노이즈만 평탄화합니다.

하늘 / 배경 

Extra Tools > Retouch & Transform > Sky / Background 는 검출된 하늘을 그라디언트 로 교체하거나 배경을 투명 / 흰색으로 제거합니다. rembg (U²-Net) 가 설치되어 있으면 신경망 전경 분할이 자동으로 사용 됩니다.

소프트 프루핑 

Extra Tools > Develop (Non-Destructive) > Soft Proof 는 ICC 프로파일을 로드해 이미지를 대상 색 공간으로 변환했다 되돌린 뒤, 왕복에서 클립된 픽셀을 마젠타로 강조합니다. 인쇄 전 빠른 색 영역 체크용 도구입니다.

GPS 지오태그 

Extra Tools > Library & Metadata > GPS Geotag 은 기존 EXIF GPS 를 읽고 10 진도 단위로 편집 / 설정합니다. piexif 가 필요하며 JPEG 에 직접 기록합니다.

인쇄 레이아웃 

Extra Tools > Export > Print Layout 은 여러 이미지를 멀티 페이지 PDF 로 배치합니다. 페이지 크기, 방향, 그리드, 여백, 간격, 재단 표시를 설정할 수 있습니다. reportlab 이 필요합니다.

Puppet 작업 공간 (Puppet 탭)

네 번째 최상위 탭 — Puppet — 은 처음부터 만든 2D 리깅 퍼펫 애니메이션 시스템입니다. Live2D 가 하는 것 (메시 변형 리깅, 매개변수, 모션, 물리, 표정, 포즈 그룹, 립싱크, 웹캠 추적) 을 독점 SDK 없이, ``live2d-py`` 없이, 완전히 개방된 .puppet 파일 포맷으로 구현합니다.

Note

엔드 투 엔드 튜토리얼 (새 설치부터 OBS 라이브 스트림 또는 MP4 출력까지) 은 저장소 루트의 puppet_guide.md 에 있습니다 (중국어판은 puppet_guide.zh-TW.md / puppet_guide.zh-CN.md). 이 장은 레퍼런스이고, 가이드는 단계별 안내입니다.

엔드 투 엔드 워크플로우 

PNG 가져오기 — 도구 모음 Import PNG… 가 puppet.auto_mesh.puppet_from_png 실행: 알파 기반 삼각화, 단일 drawable, 즉시 렌더링 가능.
디포머 추가 — Add Rotation Deformer (앵커 + 각도) 또는 Add Warp Deformer (행 × 열 Bezier 격자; 경계 외 정점은 그대로).
매개변수 추가 — Add Parameter 가 오른쪽 Parameters 도크에 슬라이더 추가 (자동 명명 Param1、Param2 …).
키 설정 — 슬라이더를 한쪽 극단으로 이동, 디포머 form 편집 후 Set key. 중립값과 반대 극단에서 반복. 런타임이 슬라이더 이동 시 인접 키 사이를 보간합니다.
저장 — Save As… 로 rig + 텍스처 + 모션 + 표정 + 물리를 단일 .puppet zip 으로 출력.

예제 

저장소 동봉: examples/puppet/march_7th.puppet — 트리 내 변환된 307-drawable Cubism Live2D 캐릭터. 텍스처와 매개변수별 정점 morph 가 모두 .puppet zip 에 굽혀져 있어, 기본 requirements.txt 만으로 열 수 있습니다 (Cubism SDK 재배포 없음).

203 개의 Cubism 표준 매개변수가 있어 (ParamAngleX/Y/Z、ParamEyeLOpen/ROpen、ParamBreath、ParamMouthOpenY …), 표준 입력 드라이버 (웹캠, 깜빡임, 립싱크, 커서 추적) 가 rig 별 설정 없이 동작합니다. 18 개의 루프 모션 동봉: 작자 변환된 Cubism idle 루프 + Idle 그룹 / Gesture 그룹의 참조 제스처.

Puppet 탭 도구 모음 → Examples ▾ 드롭다운에서 직접 March 7Th 또는 자신의 .puppet 을 열 수 있습니다. 하단 Motions 도크의 모션을 클릭하면 재생됩니다.

동봉 예제 실행 — 단계별 가이드:

Imervue 실행. 소스에서: python -m Imervue. 패키지 빌드: Imervue 실행 파일 / app bundle 을 직접 실행. examples/ 디렉터리는 wheel 과 Nuitka EXE 양쪽에 번들되어 있어 설치 경로 어디에서나 rig 파일을 사용할 수 있습니다.
창 상단의 Puppet 탭을 클릭.
도구 모음 → File > Examples > March 7Th (또는 도구 모음의 Examples ▾ 드롭다운). 307-drawable rig 가 중앙에 로드되고, 매개변수 도크는 203 개의 Cubism 표준 매개변수 슬라이더로 채워집니다.
하단 Motions 도크에서 모션 항목 (zhaiyan、zhaoxiang、idle_breath、tap_head …) 을 싱글 클릭. 즉시 재생 시작; 다시 클릭하면 정지, 다른 모션 선택 시 크로스페이드.
도구 모음의 실시간 입력 토글로 자신의 입력으로 rig 를 구동 — Drag-track head (커서 추적), Auto-blink (자동 깜빡임), Auto idle + Idle motions (호흡 + 무작위 idle 모션), Mic lip-sync (마이크 RMS 로 입 벌림), Webcam tracking (MediaPipe FaceLandmarker 로 머리 / 눈 / 입 추적).
도구 모음의 Reset to rest 는 모든 모션 중지, 모든 실시간 드라이버 끄기, expressions / pose 오버라이드 제거, 모든 매개변수를 기본값으로 되돌리기 — 표준 “처음부터 다시” 버튼.
나중에 다른 rig 열기: File > Open Puppet… 디스크에서 임의의 .puppet zip 선택; File > Examples ▾ 은 항상 동봉 목록에 바인딩됩니다.

OBS 라이브 스트리밍 

두 개의 출력 경로. 둘 다 캐릭터만 off-screen framebuffer 에 렌더링하여 (체커보드 배경도 에디터 chrome 도 포함되지 않음) 스트리밍 표면에 전달합니다. 출력의 가장 긴 변은 1080 px 까지 캡 (Cubism 네이티브 3503×7777 이 DirectShow 가상 카메라 드라이버에 거부되는 것을 방지).

A. 가상 카메라 — OBS 의 “비디오 캡처 장치” 소스 목록에 웹캠으로 표시. pip install pyvirtualcam + 플랫폼별 드라이버: OBS Studio 26+ (Windows / macOS) 에 OBS Virtual Camera 드라이버 동봉 (OBS 첫 실행 시 Start Virtual Camera 클릭하여 등록); Linux 는 v4l2loopback-dkms + modprobe v4l2loopback exclusive_caps=1 card_label="Imervue". 도구 모음 Output > Virtual camera 로 스트림 시작.

DirectShow / AVFoundation / v4l2loopback 모두 RGB 만, 알파 채널 없음 이므로, Imervue 는 캐릭터 외부 영역을 마젠타 ``#FF00FF`` 로 채워 크로마키 역할을 합니다. OBS 에서 제거:

비디오 캡처 장치 소스 우클릭 → 필터
이펙트 필터 > + > Color Key
Key Color Type = Custom Color、Custom Color = HEX FF00FF、Similarity = 80–300、Smoothness = 30–50

필터는 소스에 부착되어, 가상 카메라를 재개할 때마다 자동으로 적용됩니다.

B. NDI 출력 — LAN 상 < 50 ms 지연, 네이티브 RGBA, OBS / vMix 가 자체 장면에 직접 합성, 크로마키 패스 불필요. pip install ndi-python + NDI Tools 런타임 + obs-ndi 플러그인. 도구 모음 Output > NDI output 으로 방송 시작 (기본 소스 이름 Imervue Puppet).

ndi-python 은 소스 배포만 있어 pip 가 C++ 에서 빌드합니다. Windows 사용자는 Visual Studio Build Tools 2022 (C++ 워크로드), CMake 를 PATH 에, NDI SDK (<https://ndi.video/for-developers/ndi-sdk/> 에서 받음, NDI Tools 와 별개) 를 기본 위치에 설치, 환경 변수 NDI_SDK_DIR 을 SDK 로 설정해야 합니다.

자세한 단계 및 문제 해결은 puppet_guide.md § 1.2 참조.

커스텀 모션 녹화 

수동으로 키프레임을 찍는 대신 라이브 take 를 녹화:

도구 모음의 Record motion 켜기 — 이름 다이얼로그 표시.
녹화 중 슬라이더 드래그、Webcam tracking 활성화、물리 실행 — 매개변수 값을 쓰는 모든 작업 OK.
Record motion 끄기 — 레코더가 30 Hz 스트림을 베이크하여 Motion 화 (실제로 움직인 매개변수마다 하나의 linear-segment 트랙, 변동 없는 트랙은 폐기). 새 모션이 하단 Motions 도크에 즉시 표시.

커스텀 모션은 수동 작성된 모션과 동일한 motions/<name>.json JSON 페이로드로 저장됩니다.

도구 모음 레퍼런스 

액션	용도
Open Puppet… / Examples ▾	디스크에서 `.puppet` 로드, 또는 `examples/puppet/` 의 동봉 rig 를 도구 모음에서 직접 선택
Import PNG… / Import PSD… / Import Cubism…	PNG 자동 메시, PSD 레이어 분할, Cubism rig 의 sample-and-reconstruct. Cubism 파일 선택기는 `.moc3` 와 `.model3.json` 둘 다 받으며, 작업 공간에 rig 가 열려 있지 않을 때는 어느 경로든 완전한 `.moc3 → .puppet` 변환이 실행됩니다 (SDK 는 사용자 제공). rig 가 이미 열려 있는 상태에서 `.model3.json` 을 고르면 JSON 메타데이터 (motions / expressions / physics) 가 활성 문서에 병합됩니다
Save As…	현재 rig 을 `.puppet` zip 으로 출력
Add Rotation Deformer / Add Warp Deformer / Add Parameter	도구 모음에서 rig 작성
Drag-track head	커서 오프셋 → `ParamAngleX` / `ParamAngleY` + `ParamEyeBallX` / `ParamEyeBallY`
Auto-blink	`ParamEyeLOpen` / `ParamEyeROpen` 에서 약 4.5 초마다 cosine close→open (force-write 경로로 canvas 의 no-change-skip 우회, 다른 드라이버에 막히지 않음)
Mic lip-sync	마이크 RMS → `ParamMouthOpenY` (`sounddevice` 필요)
Webcam tracking	MediaPipe Tasks API FaceLandmarker → 머리 yaw / pitch / roll + 눈 + 입 (`opencv-python` + `mediapipe` 필요; 감지된 랜드마크를 표시하는 실시간 미리보기 dialog 열림)
Auto idle / Idle motions	표준 매개변수의 호흡 + 드리프트, Idle 그룹 모션의 랜덤 사이클러
Edit mesh	canvas 정점을 드래그하여 메시 미세 조정
Record motion	매개변수 변화를 새 `Motion` 으로 녹화하여 문서에 추가 — take 베이크, 수동 키 작성 불필요
Capture frame… / Record… / Export all motions…	단일 PNG 저장, GIF / WebM / MP4 녹화 토글, 각 모션을 개별 파일로 일괄 렌더링 (모두 스트리밍과 동일한 캐릭터 단독 off-screen render 경로 사용)
Output > Virtual camera / NDI output	라이브 스트리밍 표면 — 위의 “OBS 라이브 스트리밍” 참조
Reset to rest	모션 플레이어 즉시 정지, 모든 라이브 드라이버 끄기, 표정 / 포즈 그룹 비우기, 매개변수 기본값 복원
Fit to Window	canvas 에서 rig 을 재중앙 정렬 + 재스케일

선택적 의존성 

sounddevice — 립싱크용 마이크
opencv-python + mediapipe — 웹캠 얼굴 추적
imageio-ffmpeg — MP4 / WebM 녹화 (이미 슬라이드쇼 비디오용으로 동봉)
pyvirtualcam — 가상 카메라 출력 (“OBS 라이브 스트리밍” 참조)
ndi-python — NDI 출력 (“OBS 라이브 스트리밍” 참조)
사용자 제공 Cubism Native SDK DLL — .moc3 → .puppet 변환 (Live2D Free Material License 가 재배포 금지; <cwd>/sdk/ 에 두거나 CUBISM_CORE_DLL 환경 변수 설정)

누락 시 우아하게 다운그레이드 — 해당 도구 모음 토글이 자동 꺼지고 “install <package>” 힌트 표시. File > Install dependencies… 로 모든 Python 선택적 패키지를 한 번에 설치.

데스크톱 펫 작업 공간 (Desktop Pet 탭)

탭 5 — Desktop Pet 은 임의의 .puppet 캐릭터를 프레임 없는 투명 오버레이로 데스크톱 위에 띄웁니다. 탭 자체는 제어 패널이며, 실제 캐릭터는 별도의 최상위 창으로 전체 Puppet 런타임 (모션, 표정, 물리, idle 드라이버, 마이크 / 웹캠 입력) 을 공유합니다. 펫은 클릭에 반응하고, 타이머 기반 애니메이션을 실행하며, 커서를 따라가고, 다른 앱이 전체화면일 때 숨고, JSON 파일에 직접 작성한 대사를 말할 수 있습니다.

이 장은 해당 탭에 대한 완전한 레퍼런스이며 다음과 같이 구성됩니다:

빠른 시작 — “Imervue 를 막 열었음” 에서 “데스크톱에 퍼펫이 있음” 까지의 5단계 경로.
rig 불러오기 — 파일 선택기, 동봉 예제, 실행 간 복원.
오버레이 창 — 모든 창 수준 동작 (드래그 이동, 가장자리 스냅, 클릭 통과, 앵커 잠금, 항상 아래, 전체화면 시 숨기기, 숨김 시 일시정지, 불투명도, 크기, 멀티 모니터 복원).
상호 작용 모델 — 좌클릭 히트 영역, 전체 우클릭 컨텍스트 메뉴, 시스템 트레이.
라이브 드라이버 — 옵트인 입력 드라이버 6종과 선택적 의존성.
펫 스크립트 — 펫의 목소리를 사용자 대사로 교체하고, 알림을 예약하며, 히트 영역별 / 모션별 응답을 바인딩하는 JSON 파일.
영속성 — 실행 간 기억되는 항목과 정확한 설정 스키마.
새 펫 제작 — Puppet 탭 + .puppet 파일 형식 안내.
문제 해결 — 흔한 의외의 상황과 대처법.

빠른 시작 

Desktop Pet 탭으로 전환.
Load bundled March 7th 을 클릭해 동봉된 캐릭터를 사용하거나, Open Puppet… 으로 자신의 .puppet 파일을 선택.
오버레이가 데스크톱에 나타나고 Show pet on desktop 체크박스가 자동으로 켜집니다. (Imervue 를 닫지 않고 펫만 숨기고 싶다면 체크박스를 해제하거나 시스템 트레이 아이콘을 사용.)
캐릭터를 원하는 위치로 드래그. 화면 가장자리 근처에서 놓으면 그 가장자리에 밀착됩니다.
워크스페이스 탭이나 펫의 우클릭 메뉴에서 원하는 라이브 드라이버 — idle 호흡, 깜빡임, 커서 추적, 마이크 립싱크, 웹캠 추적 — 를 선택.

설정한 모든 항목은 다음 실행에서도 유지되므로 5단계는 rig / 페르소나당 한 번만 결정하면 됩니다.

rig 불러오기 

탭은 세 가지 불러오기 경로를 제공합니다:

Open Puppet… — 디스크의 임의 .puppet 파일을 선택.
Load bundled March 7th — examples/puppet/march_7th.puppet 에 포함된 rig 을 엽니다. 리졸버는 먼저 examples_dir() 을 검색하고 (패키지된 Nuitka / pip 설치 빌드에서 frozen-safe), 그다음 리포지토리 루트 상대 경로로 폴백하므로 두 실행 모드 모두에서 버튼이 동작합니다.
마지막 rig — 이전에 불러왔던 rig 은 last_rig_path 설정 필드를 통해 Imervue 시작 시 자동 복원됩니다. Desktop Pet 탭이 오버레이를 보이지 않게 재인스턴스화하므로, 펫은 종료한 상태 그대로 한 번의 클릭이면 다시 나타납니다.

불러오기에 성공하면 Show pet on desktop 이 자동으로 켜져 펫이 즉시 나타납니다. 실패 경로는 체크박스를 그대로 두고 탭의 상태 라벨에 오류를 기록합니다.

오버레이 창 

캐릭터는 Imervue 메인 창과 분리된 최상위 창에 존재합니다. 이 창은 프레임이 없고 작업 표시줄 항목이 없으며, (기본값으로) 다른 모든 창 위에 머무릅니다.

창 동작
동작	상세
프레임 없는 오버레이	창 chrome 없음, 최소화 / 닫기 버튼 없음, 작업 표시줄 항목 없음. 캐릭터 자체가 보이는 전체 표면.
투명 배경	캐릭터가 가리지 않는 영역은 완전히 투명. 펫 뒤의 데스크톱 / 앱이 픽셀 단위로 그대로 비침.
드래그로 이동	본체 어디서나 좌클릭 누르고 드래그한 후 놓기. 커서가 6 px 미만으로 움직였을 때만 클릭으로 인식 — 그보다 멀리 움직이면 이동 제스처로 처리되어 클릭 핸들러가 발화하지 않음.
가장자리 스냅	화면 가장자리 근처 (기본값: 24 px 이내) 에서 놓으면 펫이 해당 가장자리에 밀착. 임계값은 0 (끔) 부터 200 (매우 끈끈함) 까지 설정 가능. 스냅은 축별로 독립적으로 작동하므로 모서리로 드래그하면 두 가장자리에 동시에 도킹.
오버슈트 클램프	화면 가장자리를 넘어가는 드래그는 화면 안쪽으로 다시 잡힘. 다시 잡을 수 없는 화면 밖으로 펫을 두고 올 수 없음.
클릭 통과 모드	활성화 시 모든 마우스 이벤트가 펫을 통과해 그 뒤의 대상으로 전달됨. 캐릭터는 여전히 보이지만 드래그 / 우클릭 / 모션 트리거 불가. 펫이 순수 장식용일 때 사용.
위치 잠금	클릭 통과에 영향을 주지 않고 드래그 이동만 비활성화. 펫을 정확한 위치에 두고 실수 이동을 막고 싶을 때 유용.
항상 아래	펫을 항상 위 대신 항상 아래로 전환. 펫이 데스크톱 위젯처럼 다른 모든 창 뒤에 위치. 포커스 수용 플래그도 해제되어 펫을 클릭해도 앞으로 올라오지 않음.
전체화면 시 숨기기	1 Hz 백그라운드 폴링이 펫이 있는 모니터의 전경 창을 감시. 해당 창이 화면의 99 % 이상을 가장자리별 허용 오차 4 px 이하로 덮으면 (실제 전체화면과 borderless windowed 게임 모두 캐치), 펫이 자동으로 숨음. 전체화면이 끝나면 펫이 이전 위치에 다시 나타남. 검출기는 Windows 에서 Win32 `GetWindowRect` API 를 사용. macOS / Linux 에서는 우아하게 no-op (펫이 그대로 보임).
숨김 시 일시정지	`hideEvent` 에서 약 30 FPS 페인트 틱과 1 Hz 스크립트 틱이 모두 멈춰 숨겨진 펫은 CPU 비용이 0. 다음 `showEvent` 에서 재시작.
크기 프리셋	작게 (200 × 300), 보통 (320 × 480), 크게 (480 × 720). 펫이 현재 중심을 기준으로 크기가 변하므로 크기 변경이 위치를 이동시키지 않음. 크기 변경 후 스냅이 다시 실행됨.
불투명도 슬라이더	10 – 100 %. 창 수준에서 동작 (`setWindowOpacity`) 하므로 텍스처뿐 아니라 펫 전체가 페이드. 펫을 항상 보고 잡을 수 있도록 최소 10 % 바닥값 존재 — 완전히 투명하면 잃어버릴 수 있기 때문.
위치 기억	매 릴리스 후 스냅된 `(x, y)` 가 영속화됨. 다음 실행 시 펫이 그 화면 좌표로 돌아옴. 저장된 위치가 더 이상 연결된 화면 내부에 들어가지 않으면 (지난 실행 이후 모니터를 분리한 경우) 펫이 주 화면의 우하단 모서리로 폴백.

상호 작용 모델 

펫은 세 개의 독립적인 채널을 통해 마우스 입력에 반응합니다.

본체 좌클릭

클릭 위치가 (캔버스 팬 / 줌을 되돌려) 퍼펫 캔버스 좌표로 매핑되어 기존 hit_test 파이프라인을 통과합니다. 결과는 다음 순서로 동작을 구동합니다:

HitArea 가 클릭된 drawable 을 덮고 있고, 해당 영역에 모션이 연결되어 있으면 그 모션이 재생됨.
모션 재생 여부와 무관하게 펫이 말풍선을 띄울 수 있음 — 대사 선택 우선순위는 펫 스크립트 절 참고.
어떤 히트 영역도 클릭을 덮지 않으면 펫이 인사 (스크립트의 greetings 리스트 또는 내장 폴백) 로 처리.

드래그 이동 제스처는 클릭 핸들러를 억제하므로, 펫을 이동하는 동작은 모션 / 발화를 트리거하지 않습니다.

본체 우클릭

다음 구조의 컨텍스트 메뉴를 엽니다:

Hide pet — 오버레이를 닫는 최상위 동작.
Live drivers 서브메뉴 — 체크 가능한 토글 6개 (Auto idle, Idle motions, Auto-blink, Drag-track head, Mic lip-sync, Webcam tracking). 체크 상태가 라이브 드라이버 상태를 반영하므로 현재 실행 중인 항목이 메뉴에 보임.
Play motion 서브메뉴 — 활성 rig 의 document.motions 리스트로 채워짐. 항목을 선택하면 해당 모션이 재생 (스크립트가 모션에 대사를 바인딩했다면 펫의 목소리도 트리거됨).
Apply expression 서브메뉴 — rig 의 document.expressions 로 채워짐. 선택하면 표정의 파라미터 오버레이가 토글됨.
최상위 체크 가능 토글 5개: Lock position, Click-through, Always on bottom, Hide on fullscreen, Speech bubble — 워크스페이스 탭의 동일한 토글에 대한 빠른 접근.
Size 서브메뉴 — Small / Medium / Large. 현재 프리셋이 체크됨.

rig 이 로드되어 있지 않으면 모션 / 표정 서브메뉴는 비활성화됩니다.

시스템 트레이 아이콘

(트레이 지원을 보고하는 플랫폼에서만 인스턴스화되는) 트레이 아이콘이 가장 자주 쓰는 동작을 위한 네 번째 표면을 제공합니다:

좌클릭은 펫 표시를 토글.
우클릭은 Show pet (체크 가능), Click-through, Open puppet…, Hide pet 메뉴를 엽니다.
체크 가능한 Show / Click-through 항목은 sync_visibility / sync_click_through 를 통해 워크스페이스의 체크 상태를 미러링하므로, 사용자가 어디서 토글하든 동기화가 유지됨.

라이브 드라이버 

각 라이브 드라이버는 처음 활성화될 때 lazy 생성되므로, 휴면 상태의 펫은 켜두지 않은 드라이버에 대해 타이머 / 스레드 비용이 0 입니다. 각 드라이버의 상태는 영속화됩니다 — 켜 두고 Imervue 를 닫은 후 다시 실행하면 같은 드라이버가 실행 중인 상태로 펫이 다시 열립니다.

드라이버	기능	선택적 의존성
Auto idle	표준 파라미터 (`ParamBreath` 등) 에 호흡 + 미세한 드리프트를 주어 다른 애니메이션이 없을 때도 캐릭터가 살아있어 보이게 함.	없음
Idle motions	몇 초마다 rig 의 `Idle` 그룹에서 모션을 랜덤으로 선택해 재생. 현재 진행 중인 모션이 있으면 중단.	없음
Auto-blink	약 4.5 초마다 부드러운 코사인 곡선으로 눈을 감았다 뜸. 드라이버가 파라미터를 강제 기록하여, 눈뜸 값을 만지는 다른 드라이버가 깜빡임을 억제하지 않음.	없음
Drag-track head	커서가 펫 위에 있지 않더라도 머리 + 눈이 전역 커서 위치를 향함. `ParamAngleX` / `ParamAngleY` / `ParamEyeBallX` / `ParamEyeBallY` 를 구동.	없음
Mic lip-sync	마이크 RMS 진폭이 `ParamMouthOpenY` 를 구동.	`sounddevice`
Webcam tracking	MediaPipe FaceLandmarker 가 약 30 FPS 로 웹캠을 읽어 머리 포즈 + 눈뜸 + 입벌림 파라미터를 구동. 카메라가 얼굴을 인식 하는지 확인할 수 있는 작은 라이브 미리보기 창이 열림.	`opencv-python` + `mediapipe`

선택적 의존성이 필요한 두 드라이버는 우아하게 다운그레이드됩니다: 필요한 패키지가 설치되어 있지 않으면 체크박스를 켜도 다시 꺼지고, 워크스페이스의 상태 라벨에 “install sounddevice” / “install opencv-python + mediapipe” 힌트가 표시됩니다.

펫 스크립트 — 사용자 음성 및 예약 이벤트 

펫의 말풍선은 직접 작성한 후 탭의 Pet script 그룹에서 불러올 수 있는 JSON 파일을 사용합니다. 스크립트는 네 가지를 제어합니다:

인사말 — 더 구체적인 매칭이 없을 때 사용되는 기본 클릭 대사.
히트 영역 응답 — HitArea.id 별 대사 버킷.
모션 대사 — 모션 이름별 대사 버킷. 펫이 (히트 영역 또는 컨텍스트 메뉴에서) 해당 모션을 시작할 때 발화.
예약된 챠임 — 모노토닉 wall-clock 시간 기준 every_seconds 마다 발화하는 타이머 기반 대사.

스키마 (버전 관리됨 — 미래 필드는 forward-compatible):

{
  "version": 1,
  "name": "March 7th — playful voice",
  "greetings": [
    "Hi!", "Hello hello!", "Need a break?"
  ],
  "hit_responses": {
    "HitAreaHead": ["Hey, my head!", "Stop poking!"],
    "HitAreaBody": ["Hehe~", "Pat pat?"]
  },
  "motion_lines": {
    "wave": ["Hi!", "Hello!"],
    "curtsy": ["Cheers!"]
  },
  "scheduled": [
    {"every_seconds": 1800, "messages": ["Stretch break!"]}
  ]
}

로딩 규칙:

리스트는 버킷별 라운드 로빈으로 샘플링되어, 같은 대사가 연속으로 나오지 않음.
알 수 없는 최상위 키는 무시됨 (forward-compat — 향후 v2 파일도 v1 런타임에서 그대로 로드됨).
잘못된 리스트 항목 (타입 불일치, 형식이 깨진 예약 항목, 0 또는 음수 every_seconds) 은 건너뜀 — 한 줄이 잘못되었다고 전체 로드가 실패하지 않음. 완전히 파싱 불가능한 JSON 만 오류를 발생시키고 상태 라벨에 경로를 표시.
히트 영역 / 모션 / 인사말 캐스케이드는 계층적으로 동작: 좌클릭은 먼저 hit_responses[area.id] 를 참조한 다음, motion_lines[area.motion], 그다음 greetings, 마지막으로 내장 기본 인사말 세트를 바닥으로 사용.
시간 추적은 time.monotonic 을 사용하므로 노트북을 절전 모드에 넣거나 시스템 시계가 점프해도 큐에 쌓인 이벤트가 폭주하지 않음.

Reset to default 는 사용자 스크립트를 버리고 내장 인사말 세트로 되돌립니다. 영속화된 스크립트 경로도 지워지므로 다음 실행 시 다시 로드되지 않습니다.

동작하는 샘플은 examples/desktop_pet/march_7th.petscript.json 에 있습니다 — 인사말 6개, 히트 영역 버킷 2개 (head / body), 모션 대사 3개 (wave / curtsy / cheer), 30분 스트레칭 알림 포함.

영속성 

모든 Desktop Pet 상태는 user_setting_dict["desktop_pet"] (표준 Imervue 사용자 설정 파일의 슬롯) 을 통해 라운드 트립됩니다. 각 필드는 로드 시 기본값 + 범위 클램프가 있어, 손상된 설정 파일이 실행을 중단시키지 못합니다.

영속화되는 필드
필드	기본값	비고
`last_rig_path`	`""`	파일이 아직 존재하면 실행 시 자동 복원.
`script_path`	`""`	스크립트가 여전히 파싱되면 실행 시 자동 복원. 읽을 수 없는 스크립트는 조용히 기본값으로 되돌림.
`position`	`[-1, -1]`	마지막 드래그 릴리스의 화면 좌표 `(x, y)`. `-1, -1` 은 “주 화면의 우하단 사용” 을 의미. 세션 간 멀티 모니터 분리도 같은 방식으로 폴백.
`size_preset`	`"medium"`	`small` / `medium` / `large` 중 하나.
`opacity`	`1.0`	`[0.1, 1.0]` 으로 클램프. 범위 밖 값은 기본값으로 리셋.
`click_through`	`false`
`anchor_locked`	`false`
`always_on_bottom`	`false`	항상 위와 상호 배타적.
`hide_on_fullscreen`	`true`	전체화면 동안 펫을 계속 보이게 하려면 `false` 설정.
`snap_threshold`	`24`	`[0, 200]` px 로 클램프.
`drivers`	전부 `false`	드라이버 id (`auto_idle`, `idle_motion`, `auto_blink`, `drag_track`, `mic_lipsync`, `webcam_tracking`) 를 키로 하는 서브 dict. 알 수 없는 키는 forward-compat 을 위해 그대로 라운드 트립됨.
`show_on_launch`	`false`	Imervue 시작 시 오버레이 자동 표시.
`speech_enabled`	`true`	false 일 때 말풍선이 절대 뜨지 않음.

설정 dict 의 병합 동작은 한 단계 깊이입니다: 새 키가 없는 오래된 설정 파일도 로드 시 완전한 상태 dict 를 생성하며 (기본값이 빈 곳을 채움), 저장한 새 키는 그 키를 모르는 이전 런타임으로 다운그레이드해도 살아남습니다.

새 펫 제작 

모든 .puppet 파일은 Desktop Pet 캐릭터로 동작합니다 — Desktop Pet 탭은 순수 렌더러 + 상호 작용 쉘이며, rig 저작은 Puppet 탭에서 이루어집니다 ( Puppet 작업 공간 (Puppet 탭) 참조).

자신의 펫 rig 을 만들려면:

Puppet 탭으로 전환하고 File > Import PNG… 또는 File > Import PSD… 로 아트워크를 가져오거나, File > Import Cubism… 으로 Cubism 모델을 가져옴.
회전 / 워프 디포머, 파라미터, 모션, 표정을 작성하고, (선택적으로) 바디 파츠에 연결된 히트 영역을 만들어 Desktop Pet 의 좌클릭 핸들러가 모션을 발화할 수 있도록 함.
File > Save As… 로 rig 을 .puppet 으로 저장.
Desktop Pet 탭으로 돌아와 Open Puppet… 으로 새 파일 로드.

rig 이 HitArea 항목을 정의하고 있다면, hit_responses 키가 영역 id 와 일치하는 .petscript.json 에서 히트 영역별 말풍선 대사를 작성할 수 있습니다.

문제 해결 

펫이 완전히 투명하지 않고 회색 사각형 안에 표시됨. OS 수준의 반투명 배경 속성은 알파 인식 GL 표면과 임베디드 GL 위젯의 일치하는 속성이 모두 필요합니다. 서드 파티 창 관리 도구가 오버레이 창의 WA_TranslucentBackground 속성을 덮어쓰지 않도록 확인하세요 (일부 Linux 사용자 정의 창 관리자가 그렇게 함). Windows / macOS 에서는 “그냥 동작” 해야 합니다.

“Load bundled March 7th” 가 파일을 찾을 수 없다고 보고함. 리졸버는 먼저 examples_dir() (패키지된 빌드가 사용하는 frozen-safe 위치) 을 참조한 후 CWD 상대 경로로 폴백합니다. 둘 다에 rig 이 없으면 상태 라벨이 기대 경로를 표시합니다. 설치본과 함께 동봉된 examples/ 디렉터리가 있는지 확인 — 소스 체크아웃의 경우 리포지토리 루트에서 Imervue 를 실행하세요.

클릭해도 펫이 말하지 않음. 세 가지 확인:

Speech bubble on click 토글이 켜져 있는지 확인 (탭 또는 우클릭 메뉴).
사용자 정의 스크립트를 로드했다면 JSON 이 파싱되는지 확인 — 탭의 상태 라벨에 로드 오류가 표시됨.
히트 영역 클릭이 아무 일도 하지 않았다면, 그 영역에 일치하는 모션이 없고 스크립트에도 해당 영역 id 에 대한 hit_responses 항목이 없을 가능성이 높음. Puppet 탭에서 영역에 모션을 바인딩하거나 영역 id 를 스크립트의 hit_responses 에 추가.

웹캠 추적 체크박스가 다시 꺼짐. 웹캠 추적에는 Imervue 가 실행 중인 동일한 Python 환경에 opencv-python 과 mediapipe 가 설치되어 있어야 합니다. pip install opencv-python mediapipe 로 설치. 설치 후 체크박스를 토글하면 검출된 얼굴 랜드마크가 표시되는 작은 미리보기 창이 떠야 합니다.

전체화면 앱에서 펫이 자동으로 숨지 않음. 전체화면 검출기는 전경 창을 1 Hz 로 폴링합니다. Windows 에서는 GetWindowRect Win32 API 를 사용하며, macOS / Linux 에는 신뢰할 만한 크로스 플랫폼 대체가 없어 no-op 처리 (펫이 그대로 보임). Windows 의 경우: Hide when other app is fullscreen 이 체크되어 있는지 확인하고, 전체화면 창이 펫과 동일한 모니터의 99 % 이상을 실제로 덮는지 검증.

실행 간 펫 위치가 화면 밖으로 흘러감. 이는 펫이 있던 화면이 다음 실행에서 더 이상 연결되어 있지 않을 때 (노트북 도크, 두 번째 모니터 분리) 발생합니다. 이 경우 펫이 주 화면의 우하단 모서리로 자동 폴백 — 원하는 위치로 드래그하면 다음 저장이 오래된 위치를 덮어씁니다.

명령줄 실행 

imervue                        # 일반 실행
imervue /path/to/image         # 지정한 이미지 열기
imervue /path/to/folder        # 지정한 폴더 열기
imervue --debug                # 디버그 모드 활성화
imervue --software_opengl      # 소프트웨어 렌더링 사용 (GPU 미지원 시)