Imervue 사용 설명서
===================
GPU 가속 이미지 작업 스튜디오. **네 개의 최상위 탭** 을 제공합니다.
이 가이드의 대부분은 이 네 개의 탭을 중심으로 구성되어 있습니다.
.. list-table::
:header-rows: 1
:widths: 18 82
* - 탭
- 기능
* - **Imervue**
- 이미지 라이브러리 탐색·표시·정리·검색·일괄 처리.
「Imervue 탭 — 이미지 뷰어 및 라이브러리」를 참조하세요.
* - **Modify**
- 비파괴 현상 파이프라인 — 슬라이더, 커브, LUT, 마스크, 리터치, 다중 이미지 합성.
「Modify 탭 — 비파괴 현상」을 참조하세요.
* - **Paint**
- 래스터 페인팅 스튜디오. 브러시, 레이어, 애니메이션, 만화 도구, PSD I/O.
「Paint 탭 — 페인팅」을 참조하세요.
* - **Puppet**
- 처음부터 만든 2D 리깅 퍼펫 애니메이터 — 메시, 디포머, 매개변수, 모션, 물리.
「Puppet 탭 — 2D 리깅 퍼펫 애니메이션」을 참조하세요.
뒤따르는 「시작하기」「레퍼런스」「플러그인 시스템」「MCP 서버」는 모든 탭에 공통되는 횡단 섹션입니다.
.. contents:: 목차
:depth: 2
:local:
----
시작하기
--------
Imervue를 실행하면 세 가지 영역이 표시됩니다:
::
┌──────────┬──────────────────────┬──────────┐
│ 폴더 │ │ EXIF │
│ 트리 │ 이미지 뷰어 │ 사이드바 │
│ │ │ │
└──────────┴──────────────────────┴──────────┘
- **왼쪽**: 폴더 트리. 폴더를 클릭하면 안의 이미지를 탐색할 수 있습니다
- **가운데**: 이미지 표시 영역. 썸네일 그리드로 모든 이미지를 표시합니다
- **오른쪽**: EXIF 사이드바. 촬영 정보를 표시합니다
----
이미지 열기
-----------
.. list-table::
:header-rows: 1
:widths: 30 70
* - 방법
- 조작
* - 폴더 열기
- ``파일`` > ``폴더 열기``에서 디렉토리 선택
* - 이미지 열기
- ``파일`` > ``이미지 열기``에서 파일 선택
* - 드래그 앤 드롭
- 이미지나 폴더를 창에 직접 드롭
* - 탐색기에서 열기
- 이미지 우클릭 > ``Open with Imervue`` (파일 연결 등록 필요)
* - 최근 파일
- ``파일`` > ``최근 파일``
지원 이미지 형식
^^^^^^^^^^^^^^^^
- **일반**: PNG, JPEG, BMP, TIFF, WebP, GIF, APNG, SVG
- **RAW**: CR2 (Canon), NEF (Nikon), ARW (Sony), DNG (Adobe), RAF (Fujifilm), ORF (Olympus)
----
이미지 탐색
-----------
썸네일 그리드 모드
^^^^^^^^^^^^^^^^^^
폴더를 열면 모든 이미지가 썸네일 그리드로 표시됩니다.
.. list-table::
:header-rows: 1
:widths: 30 70
* - 조작
- 방법
* - 스크롤
- 마우스 휠
* - 패닝 (이동)
- 마우스 중간 버튼을 누른 채 드래그
* - 확대 보기로 전환
- 썸네일 좌클릭
* - 썸네일 크기 변경
- 메뉴 ``썸네일 크기`` > 128 / 256 / 512 / 1024 선택
* - 썸네일 밀도
- ``썸네일 크기`` > ``썸네일 밀도`` > 좁게 / 표준 / 넓게
* - 호버 미리보기
- 썸네일 위에 커서를 500 ms 유지하면 큰 미리보기 표시
* - 여러 이미지 선택
- 좌클릭으로 드래그하여 사각형 선택
* - 키보드로 이동
- 방향키로 패닝, ``Shift``를 누르면 미세 조정
썸네일에는 상태 배지가 표시됩니다: 왼쪽 가장자리의 색상 스트립 (색상 라벨),
왼쪽 위 ❤ (즐겨찾기), 오른쪽 위 ★ (북마크), 왼쪽 아래 평점 별. 아직 로드되지
않은 썸네일은 회전하는 점 플레이스홀더로 표시됩니다.
리스트 (상세) 모드
^^^^^^^^^^^^^^^^^^
``Ctrl + L`` 으로 썸네일 그리드와 정렬 가능한 리스트 뷰를 전환합니다. 열:
미리보기 · 라벨 · 이름 · 해상도 · 크기 · 종류 · 수정 시간 · 별점 (클릭으로 0 – 5 설정). 행을 더블클릭
(또는 ``Enter``) 하면 확대 보기로 들어가고, ``Esc`` 로 리스트로 돌아갑니다.
썸네일과 메타데이터는 워커 스레드에서 지연 로드되므로 대용량 폴더에서도 응답성을 유지합니다.
확대 보기 모드 (Deep Zoom)
^^^^^^^^^^^^^^^^^^^^^^^^^^
썸네일을 클릭하면 확대 보기 모드로 들어가 고화질로 이미지를 볼 수 있습니다.
.. list-table::
:header-rows: 1
:widths: 30 70
* - 조작
- 방법
* - 확대/축소
- 마우스 휠 / 터치패드 핀치
* - 패닝
- 마우스 중간 버튼 드래그
* - 이전 이미지
- ``←`` 왼쪽 방향키 (또는 터치패드 오른쪽 스와이프)
* - 다음 이미지
- ``→`` 오른쪽 방향키 (또는 터치패드 왼쪽 스와이프)
* - 폴더 간 이동
- ``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 대화상자를 열지 않고도 메인 창에서 두 이미지를 나란히 표시:
.. list-table::
:header-rows: 1
:widths: 35 65
* - 조작
- 단축키
* - 분할 뷰 (임의의 두 이미지)
- ``Shift + S``
* - 듀얼 페이지 (현재 + 다음)
- ``Shift + D``
* - 듀얼 페이지 (우→좌, 만화용)
- ``Ctrl + Shift + D``
* - 이전 모드로 복귀
- ``Esc``
듀얼 페이지 모드에서 방향키는 한 번에 두 장을 진행합니다. RTL 변형은 두 패널을 교환하여
1페이지를 오른쪽에 표시합니다.
다중 모니터 창
^^^^^^^^^^^^^^
``Ctrl + Shift + M`` 를 누르면 보조 디스플레이에 프레임리스 두 번째 창이 열려
메인 뷰어에 표시된 이미지를 미러링합니다. 메인 창은 독립적으로 계속 탐색할 수 있어
전시, 듀얼 스크린 편집 워크플로우, 클라이언트 프레젠테이션에 유용합니다.
``Ctrl + Shift + M`` 를 다시 누르거나 두 번째 창에서 ``Esc`` 를 눌러 닫습니다.
----
이미지 정리
-----------
평가 및 즐겨찾기
^^^^^^^^^^^^^^^^
확대 보기 모드에서 이미지에 빠르게 평가를 매길 수 있습니다:
.. list-table::
:header-rows: 1
:widths: 30 70
* - 조작
- 키
* - 즐겨찾기 추가 ❤
- ``0``
* - 1~5점 평가
- ``1`` ``2`` ``3`` ``4`` ``5`` (다시 누르면 해제)
색상 라벨 (F1 -- F5)
^^^^^^^^^^^^^^^^^^^^
별점과 독립된 플래그 기반 색상 플래그. 빠른 분류에 유용 (예: 빨강=삭제 후보,
초록=채택, 파랑=보정 필요).
.. list-table::
:header-rows: 1
:widths: 30 70
* - 조작
- 키
* - 빨강 / 노랑 / 초록 / 파랑 / 보라
- ``F1`` / ``F2`` / ``F3`` / ``F4`` / ``F5`` (같은 키로 해제)
* - 선택 항목에 일괄 적용
- 여러 썸네일을 선택 후 해당 F 키 누르기
* - 색상별 필터링
- ``필터`` > ``색상 라벨로 필터`` > 색상 / 라벨 있음 / 라벨 없음
상태 바에 현재 이미지의 색상 칩, 썸네일 왼쪽 가장자리에 색상 스트립, 리스트
뷰에는 정렬 가능한 「라벨」 열이 표시됩니다.
북마크
^^^^^^
자주 사용하는 이미지를 북마크에 추가하여 나중에 빠르게 접근할 수 있습니다.
.. list-table::
:header-rows: 1
:widths: 30 70
* - 조작
- 방법
* - 북마크 추가/해제
- 확대 보기 모드에서 ``B``
* - 북마크 관리
- ``파일`` > ``북마크``
태그 및 앨범
^^^^^^^^^^^^
태그와 앨범으로 이미지를 분류 관리할 수 있습니다.
.. list-table::
:header-rows: 1
:widths: 30 70
* - 조작
- 방법
* - 관리 화면 열기
- ``T``를 누르거나 ``파일`` > ``태그 및 앨범``
* - 이미지에 태그 추가
- 이미지 우클릭 > ``태그에 추가``
* - 앨범에 추가
- 이미지 우클릭 > ``앨범에 추가``
* - 단일 태그 / 앨범으로 필터링
- ``필터`` > ``태그별`` / ``앨범별``
* - 다중 태그 필터 (AND / OR)
- ``필터`` > ``다중 태그 필터…`` — 여러 태그/앨범 선택 후 「아무거나 (OR)」 또는 「모두 (AND)」
정렬 및 필터링
^^^^^^^^^^^^^^
.. list-table::
:header-rows: 1
:widths: 40 60
* - 기능
- 메뉴 위치
* - 이름순 정렬
- ``정렬`` > ``이름순``
* - 수정일순 정렬
- ``정렬`` > ``수정일순``
* - 파일 크기순 정렬
- ``정렬`` > ``파일 크기순``
* - 해상도순 정렬
- ``정렬`` > ``해상도순``
* - 오름차순/내림차순
- ``정렬`` > ``오름차순`` / ``내림차순``
* - 확장자별 필터링
- ``필터`` > ``JPEG`` / ``PNG`` / ``RAW`` 등
* - 평가별 필터링
- ``필터`` > ``평가별``
* - 색상 라벨별 필터링
- ``필터`` > ``색상 라벨로 필터`` (모두 / 라벨 있음 / 라벨 없음 / 빨강 / 노랑 / 초록 / 파랑 / 보라)
* - 고급 필터
- ``필터`` > ``고급 필터…`` — 해상도 범위, 파일 크기 범위, 방향 (가로/세로/정방형), 수정일 범위
* - 필터 해제
- ``필터`` > ``필터 해제``
탐색 모드 (그리드 / 리스트)
^^^^^^^^^^^^^^^^^^^^^^^^^^^
썸네일 그리드와 정렬 가능한 상세 리스트 간 전환:
- ``Ctrl + L`` — 그리드 ↔ 리스트
- 메뉴: ``썸네일 크기`` > ``탐색 모드`` > 그리드 / 리스트
- 리스트 모드에서 라벨을 포함한 모든 열 정렬 가능; 행 더블클릭이나 ``Enter`` 로 확대 보기
----
이미지 편집 (수정 탭)
---------------------
상단의 **"수정"** 탭으로 전환하면 편집 모드로 들어갑니다. 확대 보기 모드에서 ``E``를 누르거나, 우클릭 > ``수정``으로도 진입할 수 있습니다.
::
┌────────┬──────────────────────┬────────────┐
│ 도구 │ │ 속성 │
│ 바 │ 캔버스 (직접 그리기) │ 브러시, 색 │
│ │ │ 현상 조정 │
└────────┴──────────────────────┴────────────┘
주석 도구 (왼쪽 패널)
^^^^^^^^^^^^^^^^^^^^^
.. list-table::
:header-rows: 1
:widths: 15 15 70
* - 도구
- 아이콘
- 설명
* - 선택
- ⬚
- 기존 주석을 선택하고 드래그로 이동
* - 사각형
- ▢
- 사각형 그리기
* - 타원
- ◯
- 타원 또는 원 그리기
* - 직선
- ╱
- 직선 그리기
* - 화살표
- →
- 화살표 그리기
* - 프리핸드
- ✎
- 자유롭게 선 그리기
* - 텍스트
- T
- 이미지에 텍스트 추가
* - 모자이크
- ▦
- 선택 영역에 모자이크 처리
* - 블러
- ◌
- 선택 영역에 블러 처리
.. tip::
수정 탭에서 ``←`` ``→``를 누르면 편집기를 닫지 않고 이미지를 전환할 수 있습니다.
브러시 종류 (오른쪽 패널)
^^^^^^^^^^^^^^^^^^^^^^^^^
.. list-table::
:header-rows: 1
:widths: 25 75
* - 브러시
- 효과
* - 펜
- 표준 가는 선, 가장 많이 사용하는 브러시
* - 마커
- 두껍고 반투명한 스트로크
* - 연필
- 가늘고 옅은 선
* - 형광펜
- 넓고 투명도가 높음, 실제 형광펜 같은 효과
* - 스프레이
- 흩뿌리기 점 효과
* - 캘리그라피
- 스트로크 방향에 따라 두께 변화
* - 수채화
- 부드럽게 번지는 효과
* - 목탄
- 거친 질감의 스트로크
* - 크레용
- 왁스 같은 질감
그리기 속성 (오른쪽 패널)
^^^^^^^^^^^^^^^^^^^^^^^^^
.. list-table::
:header-rows: 1
:widths: 25 75
* - 속성
- 설명
* - 색상
- 색상 패치를 클릭하여 그리기 색상 선택
* - 선 굵기
- 슬라이더로 선 두께 조정 (1~40)
* - 불투명도
- 투명도 조정 (0%~100%)
* - 글꼴
- 텍스트 도구에서 사용할 글꼴 선택
* - 글꼴 크기
- 텍스트 크기 조정 (6~200 px)
이미지 조정 (오른쪽 패널 하단)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. list-table::
:header-rows: 1
:widths: 25 75
* - 슬라이더
- 기능
* - 노출
- 전체적인 밝기 조정
* - 밝기
- 밝고 어두움 미세 조정
* - 대비
- 명암 대비 조정
* - 채도
- 색상 선명도 조정
* - 화이트 밸런스 — 색온도
- 차가움 / 따뜻함 이동 (파랑 ↔ 노랑). 혼합 조명이나 실내 촬영에 유용
* - 화이트 밸런스 — 틴트
- 마젠타 / 그린 이동. 형광등 색조 보정
* - 섀도
- 어두운 영역 디테일을 살리거나 억누르기
* - 중간톤
- 검정과 흰색은 건드리지 않고 중간 톤만 조정
* - 하이라이트
- 날아간 하이라이트 복구 또는 밝은 영역 추가 강화
* - 생동감 (Vibrance)
- 채도 인식 증강 — 피부톤과 이미 채도가 높은 색상은 보호
이러한 조정은 **비파괴적** 입니다. 각 슬라이더는 이미지별 Edit Recipe에 기록되며
``초기화`` 또는 ``Ctrl + Z``로 언제든지 복구할 수 있습니다. Recipe는 재시작 후에도
유지되며 XMP sidecar를 통해 내보내기 / 동기화할 수 있습니다 (메타데이터 섹션 참조).
저장 및 실행취소
^^^^^^^^^^^^^^^^
.. list-table::
:header-rows: 1
:widths: 20 80
* - 버튼
- 설명
* - 저장
- 주석과 조정을 원본 파일에 기록
* - 실행취소
- 마지막 작업 취소
* - 다시실행
- 취소한 작업 다시 실행
* - 초기화
- 모든 이미지 조정 초기화
----
페인트 워크스페이스 (페인트 탭)
-------------------------------
세 번째 최상위 탭인 **페인트** 는 의 페인팅 워크스페이스로,
다중 문서 탭, 벡터 및 래스터 레이어, 만화 도구, 애니메이션 프레임,
PSD 가져오기/내보내기를 지원합니다. 탭 막대에서 전환하거나 딥줌 모드에서
``E`` 를 누르면 현재 이미지가 새 페인트 탭으로 보내집니다.
::
+------+----------------------+----------------+
| 도구 | | 색상 · 브러시 |
| 막대 | 캔버스 (그리기) | 레이어 · 내비 |
| | | 소재 · … |
+------+----------------------+----------------+
오른쪽 도크 (색상, 브러시, 레이어, 내비게이터, 소재 라이브러리, 히스토리,
스와치, 참고, 히스토그램, 애니메이션) 는 단일 열에 탭으로 묶여 있어 캔버스가
표시 가능한 전체 높이를 유지합니다. 도크 제목을 끌어 재배치하거나 띄울 수
있고, ``설정`` > ``워크스페이스 레이아웃…`` 으로 이름을 붙여 저장할 수 있습
니다.
도구 팔레트 (왼쪽)
^^^^^^^^^^^^^^^^^^
.. list-table::
:header-rows: 1
:widths: 25 15 60
* - 도구
- 단축키
- 용도
* - 브러시
- ``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+클릭으로 축소
브러시
^^^^^^
.. list-table::
:header-rows: 1
:widths: 25 75
* - 브러시
- 효과
* - 펜
- 선명한 안티앨리어싱 선, 일상용
* - 마커 / 형광펜
- 누적되는 반투명 굵은 획
* - 연필
- 가늘고 약간 거친 연필 선
* - 스프레이
- 밀도와 흐름에 따라 흩어지는 점
* - 캘리그래피
- 획 방향에 따라 굵기 변화
* - 수채
- 젖은 가장자리 번짐과 부드러운 혼합
* - 목탄 / 크레용
- 압력 기울기에 따라 거친 텍스처
각 브러시는 **브러시 도크** 와 상단 **옵션 막대** 에서 크기 / 불투명도 /
경도 / 밀도 / 블렌드 모드를 제공합니다. ``설정`` > ``압력 곡선…`` 으로
태블릿 압력을 굵기 또는 불투명도에 매핑하고, ``편집`` > ``브러시 끝
캡처…`` 로 선택 영역을 사용자 정의 브러시 끝으로 변환할 수 있습니다.
레이어
^^^^^^
**레이어 도크** 는 썸네일, 표시 토글, 즉시 이름 변경, 드래그 정렬, 활성
레이어 블렌드 모드 및 불투명도를 제공합니다. ``레이어`` 메뉴에는 추가로:
- **새로 / 벡터 / 복제 / 아래 병합** (``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 출력.
만화 메뉴
^^^^^^^^^
.. list-table::
:header-rows: 1
:widths: 25 75
* - 동작
- 설명
* - 컷 분할
- ``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** — 다중 프레임 만화 문서 내보내기
- **브러시 프리셋 가져오기 / 내보내기**, **팔레트 가져오기** — 설치 간 리소스 공유
- **자동 저장 스냅샷** — 백그라운드 주기 스냅샷, 파일 메뉴에서 최신 복원
워크스페이스 레이아웃
^^^^^^^^^^^^^^^^^^^^^
``설정`` > ``워크스페이스 레이아웃…`` 은 도크 배치, 도구 옵션 상태, 활성
패널을 이름으로 저장하고 한 번의 클릭으로 전환합니다 — 예를 들어 "그리기"
레이아웃은 브러시와 색상 도크를 강조하고 "합성" 레이아웃은 레이어와 히스토리
도크를 확장합니다.
----
회전 및 뒤집기
--------------
.. list-table::
:header-rows: 1
:widths: 30 20 50
* - 조작
- 단축키
- 메뉴
* - 시계 방향 90° 회전
- ``R``
- 우클릭 > 수정 > 시계 방향 회전
* - 반시계 방향 90° 회전
- ``Shift + R``
- 우클릭 > 수정 > 반시계 방향 회전
* - 좌우 뒤집기
- --
- 우클릭 > 수정 > 좌우 뒤집기
* - 상하 뒤집기
- --
- 우클릭 > 수정 > 상하 뒤집기
* - 무손실 회전 (JPEG)
- --
- 우클릭 > 무손실 회전
----
이미지 내보내기
---------------
단일 내보내기
^^^^^^^^^^^^^
이미지 우클릭 > ``내보내기 / 다른 이름으로 저장``
- 형식 선택: PNG, JPEG, WebP, BMP, TIFF
- 품질 조정 (손실 형식의 경우)
- 파일 크기 미리보기
- 저장 위치 선택
내보내기 프리셋
^^^^^^^^^^^^^^^
자주 쓰는 용도를 위해 ``파일`` > ``프리셋으로 내보내기`` 에서 리사이즈 / 형식 / 품질을
원클릭으로 적용할 수 있습니다:
.. list-table::
:header-rows: 1
:widths: 20 80
* - 프리셋
- 파이프라인
* - **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를 열면 자동으로 애니메이션이 재생됩니다.
.. list-table::
:header-rows: 1
:widths: 30 70
* - 키
- 조작
* - ``Space``
- 재생/일시정지
* - ``,``
- 이전 프레임
* - ``.``
- 다음 프레임
* - ``]``
- 속도 증가
* - ``[``
- 속도 감소
----
이미지 비교
-----------
썸네일 모드에서 2~4장의 이미지를 선택하고, 우클릭 > ``이미지 비교``.
대화상자에는 네 개의 탭이 있습니다:
.. list-table::
:header-rows: 1
:widths: 25 75
* - 탭
- 용도
* - **나란히**
- 2장 또는 4장을 동시에 표시. 각 패널에서 자동 맞춤.
* - **오버레이**
- 두 이미지를 α 슬라이더로 혼합 (0 → A만, 100 → B만). 정확히 2장 선택 필요.
* - **차이**
- 픽셀 단위 ``|A − B|`` 시각화. 게인 슬라이더 (0.10×–20×) 로 미세한 차이 증폭.
* - **A | B 분할**
- before / after 분할 뷰. 드래그 가능한 세로 분할선으로 좌우를 훑을 수 있습니다.
Develop 조정이나 내보내기 결과 비교에 적합. 정확히 2장 선택 필요.
크기가 다를 때 Lanczos 로 B를 A 크기에 리샘플링합니다. 매우 큰 이미지는 내부적으로
긴 변을 2048 px로 축소해 실시간 반응성을 유지합니다.
.. seealso::
대화상자 없이 메인 창에서 나란히 보려면 **분할 뷰** (``Shift + S``) 또는
**듀얼 페이지 읽기** (``Shift + D`` / ``Ctrl + Shift + D``) 를 사용하세요.
----
슬라이드쇼
----------
``S``를 누르거나 우클릭 > ``슬라이드쇼``로 자동 재생을 시작합니다.
- 이미지별 표시 시간 조정 가능
- 페이드 전환 효과 (선택 사항)
----
이미지 검색
-----------
``Ctrl + F`` 또는 ``/``를 눌러 키워드를 입력하면, 현재 폴더에서 파일 이름으로 이미지를 검색합니다.
검색은 **퍼지 매칭** (접두사 > 부분 문자열 > 부분 순서 3단계 랭크) 과 **부분 문자열 하이라이트**
를 지원합니다. ``Enter`` 또는 결과를 더블클릭하면 해당 이미지로 이동합니다.
**번호로** 이동하려면 ``Ctrl + G`` 로 이동 대화상자를 엽니다.
----
복사 및 붙여넣기
----------------
.. list-table::
:header-rows: 1
:widths: 40 60
* - 조작
- 방법
* - 이미지를 클립보드에 복사
- 확대 보기 모드에서 ``Ctrl + C``
* - 클립보드 이미지 붙여넣기
- ``파일`` > ``클립보드에서 붙여넣기``, 또는 ``Ctrl + V``
* - 클립보드 자동 감시
- ``파일`` > ``클립보드 이미지 자동 주석`` 체크
.. note::
자동 감시를 활성화하면 새 이미지가 클립보드에 나타날 때마다 (스크린샷 도구 등) 자동으로 주석 편집기가 열립니다.
----
이미지 삭제
-----------
.. list-table::
:header-rows: 1
:widths: 40 60
* - 조작
- 방법
* - 현재 이미지 삭제
- ``Delete`` 키
* - 선택한 여러 이미지 삭제
- 선택 후 ``Delete`` 또는 우클릭 > ``선택한 이미지 삭제``
이미지는 시스템 휴지통으로 이동되며, 거기에서 복원할 수 있습니다.
----
일괄 작업
---------
썸네일 모드에서 여러 이미지를 선택 후, 우클릭으로 다음 작업이 가능합니다:
.. list-table::
:header-rows: 1
:widths: 30 70
* - 기능
- 설명
* - 일괄 이름변경
- 템플릿 ``{name}``, ``{n}``, ``{ext}``로 자동 명명
* - 이동/복사
- 이미지를 다른 폴더로 이동 또는 복사
* - 전체 회전
- 선택한 모든 이미지를 한 번에 회전
* - 일괄 내보내기
- 형식과 크기를 일괄 변환
* - 태그에 추가
- 선택한 모든 이미지에 같은 태그 부여
* - 앨범에 추가
- 선택한 모든 이미지를 앨범에 추가
----
RGB 히스토그램
--------------
확대 보기 모드에서 ``H``를 누르면 이미지 위에 RGB 히스토그램이 표시됩니다. 다시 누르면 숨깁니다.
----
배경화면 설정
-------------
확대 보기 모드에서 우클릭 > ``배경화면으로 설정``으로 현재 이미지를 데스크톱 배경화면으로 설정합니다.
Windows, macOS, Linux (GNOME)를 지원합니다.
----
멀티 윈도우
-----------
``파일`` > ``새 창``으로 독립적인 Imervue 창을 추가로 열 수 있습니다. 각 창에서 다른 폴더를 탐색할 수 있습니다.
터치패드 제스처
---------------
.. list-table::
:header-rows: 1
:widths: 30 70
* - 제스처
- 동작
* - 핀치
- 확대 보기에서 확대/축소 (핀치 중심 기준)
* - 수평 스와이프
- 이전 / 다음 이미지
----
파일 연결 (Windows)
--------------------
Windows 탐색기에서 직접 Imervue로 이미지를 열 수 있게 합니다:
1. ``파일`` > ``파일 연결`` > ``Open with Imervue 등록``
2. 관리자 권한이 필요합니다
3. 등록 후 이미지를 우클릭하면 ``Open with Imervue`` 옵션이 표시됩니다
해제하려면: ``파일`` > ``파일 연결`` > ``파일 연결 해제``
----
플러그인 시스템
---------------
Imervue는 플러그인을 통한 기능 확장을 지원합니다.
.. list-table::
:header-rows: 1
:widths: 35 65
* - 조작
- 메뉴 위치
* - 설치된 플러그인 보기
- ``플러그인`` > ``플러그인 관리``
* - 새 플러그인 다운로드
- ``플러그인`` > ``플러그인 다운로드``
* - 플러그인 폴더 열기
- ``플러그인`` > ``플러그인 폴더 열기``
* - 플러그인 다시 로드
- ``플러그인`` > ``플러그인 다시 로드``
----
언어 전환
---------
``언어`` 메뉴에서 인터페이스 언어를 전환할 수 있습니다:
- English
- 繁體中文
- 简体中文
- 한국어
- 日本語
전환 후 재시작이 필요합니다.
----
키보드 단축키 목록
------------------
탐색
^^^^
.. list-table::
:header-rows: 1
:widths: 30 70
* - 키
- 기능
* - ``←`` / ``→``
- 이전/다음 이미지
* - 방향키
- 썸네일 모드에서 패닝
* - ``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``
- 줌 초기화
편집
^^^^
.. list-table::
:header-rows: 1
:widths: 30 70
* - 키
- 기능
* - ``E``
- 수정 탭 열기
* - ``R``
- 시계 방향 회전
* - ``Shift + R``
- 반시계 방향 회전
* - ``Ctrl + Z``
- 실행취소
* - ``Ctrl + Shift + Z``
- 다시실행
* - ``Delete``
- 이미지 삭제
정리
^^^^
.. list-table::
:header-rows: 1
:widths: 30 70
* - 키
- 기능
* - ``0``
- 즐겨찾기 추가/해제
* - ``1`` ~ ``5``
- 평가 (다시 누르면 해제)
* - ``F1`` ~ ``F5``
- 색상 라벨: 빨강/노랑/초록/파랑/보라 (다시 누르면 해제)
* - ``P``
- 컬링: Pick (보관 표시)
* - ``Shift + X``
- 컬링: Reject (탈락 표시)
* - ``U``
- 컬링: 플래그 해제
* - ``B``
- 북마크 추가/해제
* - ``T``
- 태그 및 앨범 관리
도구 및 오버레이
^^^^^^^^^^^^^^^^
.. list-table::
:header-rows: 1
:widths: 30 70
* - 키
- 기능
* - ``Ctrl + F`` / ``/``
- 퍼지 검색 (부분 문자열 하이라이트)
* - ``Ctrl + C``
- 이미지를 클립보드에 복사
* - ``Ctrl + V``
- 클립보드에서 붙여넣기
* - ``H``
- RGB 히스토그램
* - ``F8`` / ``Ctrl + F8``
- OSD 정보 / 디버그 HUD (VRAM, 캐시, 스레드)
* - ``Shift + P``
- 픽셀 보기 (400 % 이상 시 격자와 커서 아래 RGB 값 표시)
* - ``Shift + M``
- 색상 모드 순환 (일반/그레이스케일/반전/세피아)
* - ``S``
- 슬라이드쇼
애니메이션
^^^^^^^^^^
.. list-table::
:header-rows: 1
:widths: 30 70
* - 키
- 기능
* - ``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``). 이 장은 레퍼런스이고, 가이드는 단계별 안내입니다.
엔드 투 엔드 워크플로우
^^^^^^^^^^^^^^^^^^^^^^^
1. **PNG 가져오기** — 도구 모음 ``Import PNG…`` 가 ``puppet.auto_mesh.puppet_from_png`` 실행: 알파 기반 삼각화, 단일 drawable, 즉시 렌더링 가능.
2. **디포머 추가** — ``Add Rotation Deformer`` (앵커 + 각도) 또는 ``Add Warp Deformer`` (행 × 열 Bezier 격자; 경계 외 정점은 그대로).
3. **매개변수 추가** — ``Add Parameter`` 가 오른쪽 **Parameters** 도크에 슬라이더 추가 (자동 명명 ``Param1``、``Param2`` …).
4. **키 설정** — 슬라이더를 한쪽 극단으로 이동, 디포머 form 편집 후 **Set key**. 중립값과 반대 극단에서 반복. 런타임이 슬라이더 이동 시 인접 키 사이를 보간합니다.
5. **저장** — ``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** 도크의 모션을 클릭하면 재생됩니다.
**동봉 예제 실행 — 단계별 가이드:**
1. **Imervue 실행**. 소스에서: ``python -m Imervue``. 패키지 빌드: ``Imervue`` 실행 파일 / app bundle 을 직접 실행. ``examples/`` 디렉터리는 wheel 과 Nuitka EXE 양쪽에 번들되어 있어 설치 경로 어디에서나 rig 파일을 사용할 수 있습니다.
2. 창 상단의 **Puppet** 탭을 클릭.
3. 도구 모음 → **File > Examples > March 7Th** (또는 도구 모음의 **Examples ▾** 드롭다운). 307-drawable rig 가 중앙에 로드되고, 매개변수 도크는 203 개의 Cubism 표준 매개변수 슬라이더로 채워집니다.
4. 하단 **Motions** 도크에서 모션 항목 (``zhaiyan``、``zhaoxiang``、``idle_breath``、``tap_head`` …) 을 싱글 클릭. 즉시 재생 시작; 다시 클릭하면 정지, 다른 모션 선택 시 크로스페이드.
5. 도구 모음의 실시간 입력 토글로 자신의 입력으로 rig 를 구동 — **Drag-track head** (커서 추적), **Auto-blink** (자동 깜빡임), **Auto idle** + **Idle motions** (호흡 + 무작위 idle 모션), **Mic lip-sync** (마이크 RMS 로 입 벌림), **Webcam tracking** (MediaPipe FaceLandmarker 로 머리 / 눈 / 입 추적).
6. 도구 모음의 **Reset to rest** 는 모든 모션 중지, 모든 실시간 드라이버 끄기, expressions / pose 오버라이드 제거, 모든 매개변수를 기본값으로 되돌리기 — 표준 "처음부터 다시" 버튼.
7. 나중에 다른 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 에서 제거:
1. 비디오 캡처 장치 소스 우클릭 → **필터**
2. **이펙트 필터 > + > Color Key**
3. **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 ( 에서 받음, NDI Tools 와 별개) 를 기본 위치에 설치, 환경 변수 ``NDI_SDK_DIR`` 을 SDK 로 설정해야 합니다.
자세한 단계 및 문제 해결은 ``puppet_guide.md`` § 1.2 참조.
커스텀 모션 녹화
^^^^^^^^^^^^^^^^
수동으로 키프레임을 찍는 대신 라이브 take 를 녹화:
1. 도구 모음의 **Record motion** 켜기 — 이름 다이얼로그 표시.
2. 녹화 중 슬라이더 드래그、**Webcam tracking** 활성화、물리 실행 — 매개변수 값을 쓰는 모든 작업 OK.
3. **Record motion** 끄기 — 레코더가 30 Hz 스트림을 베이크하여 ``Motion`` 화 (실제로 움직인 매개변수마다 하나의 linear-segment 트랙, 변동 없는 트랙은 폐기). 새 모션이 하단 **Motions** 도크에 즉시 표시.
커스텀 모션은 수동 작성된 모션과 동일한 ``motions/.json`` JSON 페이로드로 저장됩니다.
도구 모음 레퍼런스
^^^^^^^^^^^^^^^^^^
.. list-table::
:header-rows: 1
:widths: 30 70
* - 액션
- 용도
* - 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 가 재배포 금지; ``/sdk/`` 에 두거나 ``CUBISM_CORE_DLL`` 환경 변수 설정)
누락 시 우아하게 다운그레이드 — 해당 도구 모음 토글이 자동 꺼지고 "install " 힌트 표시. **File > Install dependencies…** 로 모든 Python 선택적 패키지를 한 번에 설치.
----
데스크톱 펫 작업 공간 (Desktop Pet 탭)
--------------------------------------
탭 5 — **Desktop Pet** 은 임의의 ``.puppet`` 캐릭터를 프레임 없는 투명
오버레이로 데스크톱 위에 띄웁니다. 탭 자체는 제어 패널이며, 실제 캐릭터는
별도의 최상위 창으로 전체 Puppet 런타임 (모션, 표정, 물리, idle 드라이버,
마이크 / 웹캠 입력) 을 공유합니다. 펫은 클릭에 반응하고, 타이머 기반
애니메이션을 실행하며, 커서를 따라가고, 다른 앱이 전체화면일 때 숨고,
JSON 파일에 직접 작성한 대사를 말할 수 있습니다.
이 장은 해당 탭에 대한 완전한 레퍼런스이며 다음과 같이 구성됩니다:
#. **빠른 시작** — "Imervue 를 막 열었음" 에서 "데스크톱에 퍼펫이 있음"
까지의 5단계 경로.
#. **rig 불러오기** — 파일 선택기, 동봉 예제, 실행 간 복원.
#. **오버레이 창** — 모든 창 수준 동작 (드래그 이동, 가장자리 스냅,
클릭 통과, 앵커 잠금, 항상 아래, 전체화면 시 숨기기, 숨김 시 일시정지,
불투명도, 크기, 멀티 모니터 복원).
#. **상호 작용 모델** — 좌클릭 히트 영역, 전체 우클릭 컨텍스트 메뉴,
시스템 트레이.
#. **라이브 드라이버** — 옵트인 입력 드라이버 6종과 선택적 의존성.
#. **펫 스크립트** — 펫의 목소리를 사용자 대사로 교체하고, 알림을
예약하며, 히트 영역별 / 모션별 응답을 바인딩하는 JSON 파일.
#. **영속성** — 실행 간 기억되는 항목과 정확한 설정 스키마.
#. **새 펫 제작** — Puppet 탭 + ``.puppet`` 파일 형식 안내.
#. **문제 해결** — 흔한 의외의 상황과 대처법.
빠른 시작
^^^^^^^^^
1. **Desktop Pet** 탭으로 전환.
2. **Load bundled March 7th** 을 클릭해 동봉된 캐릭터를 사용하거나,
**Open Puppet…** 으로 자신의 ``.puppet`` 파일을 선택.
3. 오버레이가 데스크톱에 나타나고 **Show pet on desktop** 체크박스가
자동으로 켜집니다. (Imervue 를 닫지 않고 펫만 숨기고 싶다면 체크박스를
해제하거나 시스템 트레이 아이콘을 사용.)
4. 캐릭터를 원하는 위치로 드래그. 화면 가장자리 근처에서 놓으면 그
가장자리에 밀착됩니다.
5. 워크스페이스 탭이나 펫의 우클릭 메뉴에서 원하는 **라이브 드라이버**
— 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 메인 창과 분리된 최상위 창에 존재합니다. 이 창은
프레임이 없고 작업 표시줄 항목이 없으며, (기본값으로) 다른 모든 창
위에 머무릅니다.
.. list-table:: 창 동작
:header-rows: 1
:widths: 28 72
* - 동작
- 상세
* - 프레임 없는 오버레이
- 창 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 를 닫은 후
다시 실행하면 같은 드라이버가 실행 중인 상태로 펫이 다시 열립니다.
.. list-table::
:header-rows: 1
:widths: 22 50 28
* - 드라이버
- 기능
- 선택적 의존성
* - **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):
.. code-block:: json
{
"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 사용자 설정 파일의 슬롯) 을 통해 라운드 트립됩니다. 각
필드는 로드 시 기본값 + 범위 클램프가 있어, 손상된 설정 파일이
실행을 중단시키지 못합니다.
.. list-table:: 영속화되는 필드
:header-rows: 1
:widths: 28 18 54
* - 필드
- 기본값
- 비고
* - ``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 미지원 시)