🌐 English|한국어

문제 해결 안내서

이 안내서는 Modan2를 사용하면서 마주칠 수 있는 흔한 문제와 오류의 해결 방법을 제공합니다.

Modan2가 파일을 보관하는 위치

아래 문제들 중 상당수는 파일이 없거나 쓸 수 없어서 생기므로, 각 파일의 위치를 알아 두면 도움이 됩니다. ~ 는 홈 폴더입니다(Windows에서는 예를 들어 C:\Users\<사용자>).

항목

위치

데이터베이스

~/PaleoBytes/Modan2/Modan2.db

이미지, 3D 모델

~/PaleoBytes/Modan2/data/

로그 파일

~/PaleoBytes/Modan2/logs/

백업

~/PaleoBytes/Modan2/backups/

설정

운영체제의 설정 폴더 (아래 참조)

설치 관련 문제

애플리케이션이 시작되지 않음

Windows

  • Windows Defender나 SmartScreen이 서명되지 않은 설치 프로그램을 차단할 수 있습니다. 신뢰할 수 있는 출처라면 “추가 정보” → “실행”을 선택하세요.

  • 설치 프로그램 자체가 실행되지 않으면, 내려받은 ZIP에서 먼저 압축을 풀었는지 확인하세요. 압축 파일 안에서 바로 실행하면 실패할 수 있습니다.

macOS

  • 첫 실행 시에는 앱을 오른쪽 클릭한 뒤 “열기”를 선택해, 서명되지 않은 애플리케이션에 표시되는 Gatekeeper 경고를 넘어가세요.

Linux

  • AppImage에 실행 권한이 있는지 확인하세요: chmod +x Modan2-Linux-*.AppImage

  • FUSE 관련 오류로 종료된다면, FUSE를 설치하거나(Ubuntu/Debian에서는 sudo apt-get install libfuse2) --appimage-extract-and-run 옵션으로 실행하세요.

참고

충분히 테스트된 것은 Windows 빌드뿐입니다. macOS나 Linux 패키지가 여기에 없는 방식으로 실패한다면 이슈 페이지 에 알려 주세요.

권한 문제

문제: 데이터베이스를 열거나 파일을 저장할 때 “Permission denied”

Windows 해결 방법:

  1. Modan2.exe 오른쪽 클릭 → “관리자 권한으로 실행” (평상시 사용에는 권장하지 않음)

  2. 또는 폴더 권한을 변경합니다:

    • 폴더 오른쪽 클릭 → 속성 → 보안

    • 사용자 계정에 “모든 권한”이 있는지 확인

Linux/macOS 해결 방법:

# Check permissions
ls -la ~/PaleoBytes/Modan2

# Fix permissions if needed
chmod -R u+rw ~/PaleoBytes/Modan2

문제: 설정이 저장되지 않음

설정은 애플리케이션을 종료할 때 운영체제의 설정 폴더에 기록됩니다:

플랫폼

위치

Windows

%LOCALAPPDATA%\PaleoBytes\Modan2\preferences.json

macOS

~/Library/Application Support/PaleoBytes/Modan2/preferences.json

Linux

~/.config/PaleoBytes/Modan2/preferences.json

해결 방법:

  1. 해당 디렉터리의 쓰기 권한을 확인하세요

  2. 손상된 설정 파일을 삭제해 기본값을 다시 만듭니다 — Modan2를 먼저 종료하세요:

    # Windows (PowerShell)
rm "$env:LOCALAPPDATA\PaleoBytes\Modan2\preferences.json"

# macOS
rm ~/Library/Application\ Support/PaleoBytes/Modan2/preferences.json

# Linux
rm ~/.config/PaleoBytes/Modan2/preferences.json

데이터베이스 문제

데이터베이스 파일 손상

문제: “Database is locked” 또는 “Database disk image is malformed”

증상:

  • Modan2를 열 수 없음

  • 데이터베이스 관련 오류 메시지

  • 데이터가 저장되지 않음

해결 1: 다른 인스턴스 종료

실행 중인 다른 Modan2 프로세스가 없는지 확인하세요:

# Windows
tasklist | findstr Modan2
# If found: taskkill /F /IM Modan2.exe

# Linux/macOS
ps aux | grep Modan2
# If found: kill <pid>

해결 2: 백업 후 복원

# 1. Locate database
# Database: ~/PaleoBytes/Modan2/Modan2.db

# 2. Make backup
cp Modan2.db Modan2.db.backup

# 3. Try SQLite repair
sqlite3 Modan2.db "PRAGMA integrity_check;"

# 4. If corrupted beyond repair, restore from backup
cp Modan2.db.backup Modan2.db

해결 3: 내보낸 뒤 다시 가져오기

최근 백업이 있다면:

  1. 백업 데이터베이스를 사용

  2. 모든 데이터셋을 JSON+ZIP으로 내보내기

  3. 새 데이터베이스 생성 (Modan2.db 삭제)

  4. JSON+ZIP에서 데이터셋 가져오기

데이터베이스에 접근할 수 없음

문제: “Unable to open database file” 오류

원인:

  • 데이터베이스 파일 없음

  • 권한이 올바르지 않음

  • 디스크 공간 부족

  • 다른 프로세스가 파일을 잠금

해결 방법:

  1. 파일 존재 확인:

    # Linux/macOS
ls -la ~/PaleoBytes/Modan2/Modan2.db

  2. 디스크 공간 확인:

    # Linux
df -h ~

# Windows (PowerShell)
Get-PSDrive C

  3. 디렉터리가 없으면 생성:

    mkdir -p ~/PaleoBytes/Modan2

  4. Modan2가 새 데이터베이스를 만들도록 하기:

    • Modan2 시작

    • 새 데이터베이스가 자동으로 생성됨

    • 백업에서 데이터 가져오기

데이터 로딩 및 가져오기 문제

가져올 파일 형식을 인식하지 못함

문제: “Unknown file format” 또는 “Failed to import” 오류

지원 형식:

  • 랜드마크 데이터: TPS, NTS, X1Y1, Morphologika, JSON+ZIP

  • 3D 모델: OBJ, PLY, STL

  • 이미지: JPG, PNG, BMP, TIF

해결 방법:

  1. 파일 형식 확인:

    • 확장자가 실제 내용과 일치하는지 확인

    • 텍스트 편집기로 열어 형식 확인

  2. TPS 파일 문제:

    # Valid TPS format
LM=5
100.5 200.3
150.2 180.9
...
ID=specimen1
IMAGE=path/to/image.jpg

    흔한 문제:

    • LM= 줄 누락

    • 좌표 형식 오류

    • ID= 또는 IMAGE= 줄 누락

  3. 다른 형식으로 시도:

    • tpsUtil로 TPS로 변환

    • 또는 Morphologika 형식 사용

가져온 뒤 데이터가 보이지 않음

문제: 객체는 들어왔는데 랜드마크가 보이지 않음

원인:

  • 랜드마크 좌표가 모두 0

  • 차원이 맞지 않음 (2D와 3D)

  • 축척 불일치

해결 방법:

  1. 표에서 좌표 확인:

    • 객체 대화상자 열기

    • 랜드마크 표 보기

    • 좌표가 0이 아닌지 확인

  2. 차원 확인:

    • 데이터셋 차원이 파일과 일치해야 함 (2D/3D)

    • 올바른 차원으로 데이터셋을 다시 생성

  3. 축척 확인:

    • 랜드마크가 보이는 범위 밖에 있을 수 있음

    • “화면에 맞추기” 또는 축소를 시도

    • 좌표 값이 합리적인지 확인

이미지/모델이 로드되지 않음

문제: “Failed to load image” 또는 “Model file not found”

해결 방법:

  1. 파일 경로 확인:

    • 이미지/모델 경로는 데이터베이스에 저장됨

    • 파일을 옮겼다면 경로를 갱신

    • 가능하면 상대 경로 사용

  2. 파일 무결성 확인:

    # Check file size
ls -lh image.jpg

# Try opening in another program
# Images: Image viewer
# 3D models: MeshLab, Blender

  3. 지원 형식:

    • 이미지: JPG, PNG, BMP, TIF (RGB 또는 회색조)

    • 3D 모델: OBJ, PLY, STL (텍스트 또는 바이너리)

  4. 파일 다시 첨부:

    • 객체 오른쪽 클릭 → 속성

    • 이미지/모델을 다시 첨부

    • 올바른 파일 찾아 선택

분석 오류

PCA/CVA/MANOVA 실패

문제: 분석이 오류 메시지와 함께 실패함

흔한 원인:

  1. 객체 수 부족:

    • PCA: 객체가 최소 3개 필요

    • CVA/MANOVA: 각각 3개 이상의 객체를 가진 그룹이 최소 2개 필요

  2. 결측 랜드마크:

    • 일부 랜드마크가 결측으로 표시됨

    • 완전한 배열이 충분하지 않음

    • 해결: 결측 랜드마크를 추정하거나 해당 객체를 제외

  3. 그룹화 변수 없음 (CVA/MANOVA):

    • 그룹을 정의할 범주형 변수가 필요

    • 해결: 객체에 그룹화 변수를 추가

  4. 변이 부족:

    • 모든 객체가 동일하거나 거의 동일함

    • 해결: 데이터 품질 확인

해결 방법:

  1. 객체 수 확인:

    • 데이터셋 선택

    • 상태 표시줄에서 객체 수 확인

    • 객체가 충분한지 확인

  2. 결측 데이터 확인:

    • 객체들에 결측 랜드마크가 있는지 검토

    • 결측 추정 기능을 쓰거나 해당 객체를 제외

  3. 그룹화 변수 확인:

    • CVA/MANOVA에는 범주형 변수가 필요

    • 데이터셋 대화상자에서 변수 생성

    • 객체에 값 지정

프로크루스테스 정렬 문제

문제: “Procrustes failed” 또는 정렬이 잘못됨

원인:

  • 공선 랜드마크 (모두 한 직선 위에 있음)

  • 랜드마크 부족 (2D는 3개 미만, 3D는 4개 미만)

  • 모든 랜드마크가 같은 위치에 있음

  • 축척 문제

해결 방법:

  1. 랜드마크 품질 확인:

    • 뷰어에서 객체 확인

    • 랜드마크가 고르게 분포했는지 확인

    • 같은 위치에 중복된 점이 없는지 확인

  2. 다른 방법 시도:

    • 북스틴 정합 시도 (데이터셋에 베이스라인이 필요)

    • 또는 잘못 찍힌 랜드마크 몇 개에 강한 강건적합 시도

  3. 이상치 확인:

    • 일부 객체가 나머지와 크게 다름

    • 정렬 문제를 일으킬 수 있음

    • 이상치를 제외해 보세요

분석 결과가 이상해 보임

문제: PCA/CVA 결과가 예상과 다름

가능한 원인:

  • 중첩정렬 방식이 적절하지 않음

  • 그룹화 변수가 잘못됨

  • 이상치가 결과에 영향

  • 결측 랜드마크가 제대로 처리되지 않음

해결 방법:

  1. 중첩정렬 설정 확인:

    • 어떤 중첩정렬을 썼는지 확인

    • 다른 방법을 시도

  2. 이상치 확인:

    • 주성분 점수 플롯 보기

    • 극단적인 점을 찾기

    • 이상한 표본을 조사

  3. 그룹화 확인:

    • CVA: 올바른 그룹화 변수를 선택했는지 확인

    • 그룹 배정 확인

  4. 표본 크기 확인:

    • 표본이 적으면 결과가 불안정할 수 있음

    • 안정적인 분석을 위해서는 더 큰 표본이 필요

3D 시각화 문제

3D 뷰어가 검은 화면

문제: 3D 뷰어가 검은 화면이거나 아무것도 보이지 않음

해결 방법:

  1. 시점 초기화:

    • 3D 뷰어에서 더블클릭

    • 또는 View → Reset Camera 사용

  2. OpenGL 확인:

    # Linux - verify OpenGL working
glxinfo | grep "OpenGL version"

# Install if needed
sudo apt-get install mesa-utils libglu1-mesa

  3. 그래픽 드라이버 업데이트:

    • Windows: NVIDIA, AMD 또는 Intel 웹사이트

    • Linux: 배포판의 드라이버 관리자 사용

    • macOS: 소프트웨어 업데이트 사용

  4. 모델이 로드되었는지 확인:

    • 3D 모델 파일이 첨부되었는지 확인

    • 다른 모델로 시도

    • 파일이 올바른 OBJ/PLY/STL인지 확인

OpenGL 오류

문제: “OpenGL error” 또는 “Failed to initialize OpenGL context”

Linux 해결 방법:

# Install OpenGL libraries
sudo apt-get install mesa-utils libglu1-mesa-dev \
  freeglut3-dev mesa-common-dev

# Test OpenGL
glxinfo | grep "OpenGL version"

Windows 해결 방법:

  1. 그래픽 드라이버를 업데이트하세요

  2. 소프트웨어 렌더링을 강제해 보세요 (느리지만 동작합니다):

    set LIBGL_ALWAYS_SOFTWARE=1
Modan2.exe

macOS 해결 방법:

  • macOS 10.14 이상에서는 OpenGL이 기본적으로 동작합니다

  • 문제가 있으면 macOS를 최신 버전으로 업데이트하세요

랜드마크 구체가 보이지 않음

문제: 3D 뷰어에서 랜드마크 구체가 보이지 않음

해결 방법:

  1. 구체 크기 키우기:

    • 환경 설정 → 뷰어 외형 → 랜드마크 크기

    • 값을 키우세요

  2. 조명 확인:

    • 구체가 너무 어두울 수 있습니다

    • 설정에서 조명을 조정하세요

  3. 확대:

    • 현재 배율에서 구체가 너무 작을 수 있습니다

    • 스크롤해서 가까이 확대하세요

  4. 와이어프레임 확인:

    • 와이어프레임이 구체를 가릴 수 있습니다

    • 와이어프레임 표시를 껐다 켜 보세요

성능 문제

애플리케이션 시작이 느림

문제: Modan2가 시작하는 데 오래 걸림

원인:

  • 데이터베이스가 큼

  • 데이터셋/객체가 많이 로드됨

  • 디스크 I/O 문제

해결 방법:

  1. 데이터베이스 크기 확인:

    • 위치: FAQ 참조

    • 데이터베이스가 크면(1GB 초과) 시작이 느려질 수 있습니다

  2. 데이터베이스 최적화:

    sqlite3 Modan2.db "VACUUM;"

  3. SSD로 이동:

    • HDD의 데이터베이스는 더 느립니다

    • 성능을 위해 SSD로 옮기세요

  4. 로드되는 데이터 줄이기:

    • 사용하지 않는 데이터셋을 닫으세요

    • 오래된 분석을 정리하세요

분석이나 시각화가 느림

문제: 분석이 매우 오래 걸리거나 UI가 멈춤

예상 성능:

  • 객체 100개: 1초 미만

  • 객체 1000개: 1~5초

  • 객체 2000개: 5~15초

이보다 훨씬 느리다면:

  1. 객체 수 확인:

    • 데이터셋 선택 → 객체 수 확인

    • 예상 범위 안인지 확인

  2. 다른 애플리케이션 닫기:

    • RAM 확보

    • 웹 브라우저 닫기

    • 백그라운드 프로세스 중지

  3. 시스템 자원 확인:

    • 작업 관리자 / 활성 상태 보기

    • CPU나 메모리 사용량이 높은 항목 확인

    • 자원을 많이 쓰는 앱 닫기

  4. 시각화 단순화:

    • 3D 모델의 폴리곤 수 줄이기

    • 와이어프레임 끄기

    • 사용하지 않는 객체 뷰어 닫기

메모리 부족 오류

문제: 큰 데이터셋에서 “Out of memory” 또는 크래시

해결 방법:

  1. RAM 사용량 확인:

    • 작업 관리자 / 활성 상태 보기

    • 충분한 RAM이 남아 있는지 확인

  2. 다른 애플리케이션 닫기:

    • 웹 브라우저는 RAM을 많이 사용합니다

    • 불필요한 프로그램을 닫으세요

  3. 하위 집합으로 작업:

    • 더 작은 그룹으로 분석

    • 데이터의 하위 집합을 내보내기

  4. RAM 증설:

    • 4GB: 작은 데이터셋만

    • 8GB: 대부분의 작업에 권장

    • 16GB 이상: 큰 데이터셋

UI 및 화면 표시 문제

UI 요소가 제대로 표시되지 않음

문제: 버튼, 메뉴, 대화상자가 깨지거나 잘려 보임

해결 방법:

  1. 디스플레이 배율 확인 (Windows):

    • 바탕화면 오른쪽 클릭 → 디스플레이 설정

    • 배율을 100% 또는 125%로 설정

    • Modan2 다시 시작

  2. 창 위치·크기 초기화:

    • 설정 파일을 삭제 (위 참조)

    • Modan2 다시 시작

    • 창이 기본 위치로 돌아갑니다

글꼴 문제

문제: 글자가 너무 작거나 큼

해결 방법:

  1. 시스템 글꼴 크기 조정:

    • Windows: 설정 → 디스플레이 → 배율

    • macOS: 시스템 설정 → 디스플레이

    • Linux: 데스크톱 환경의 디스플레이 설정

  2. 애플리케이션 자체 설정 (예정):

    • 글꼴 크기 설정은 계획 중입니다

    • 현재는 시스템 글꼴을 사용합니다

고해상도(High DPI) 디스플레이 문제

문제: 4K/고해상도 디스플레이에서 UI 요소가 아주 작게 보임

해결 방법:

  1. 고해상도 배율 조정 활성화 (Windows):

    • Modan2.exe 오른쪽 클릭 → 속성

    • 호환성 → 높은 DPI 설정

    • 배율 조정 동작 재정의

  2. Modan2를 실행하기 전에 Qt 배율 환경 변수를 설정 하세요:

    # Windows (PowerShell)
$env:QT_AUTO_SCREEN_SCALE_FACTOR=1

# Linux/macOS
export QT_AUTO_SCREEN_SCALE_FACTOR=1

    이는 Modan2가 아니라 Qt의 설정이며, 애플리케이션을 실행하는 것과 같은 셸에서 설정해야 합니다.

고급 문제 해결

디버그 정보 수집

문제를 보고할 때는 다음 정보를 포함해 주세요:

  1. 시스템 정보:

    • 사용 중인 OS와 버전 (Windows: winver, macOS: sw_vers, Linux: lsb_release -a)

  2. Modan2 버전:

    • Help → About Modan2

    • 버전과 빌드 번호를 적어 주세요. 내려받은 패키지 이름에도 들어 있습니다

  3. 로그 파일:

    • ~/PaleoBytes/Modan2/logs/ — 가장 최근 파일을 첨부해 주세요

디버그 로깅 켜기

상세 로깅을 원하면 --debug 옵션으로 Modan2를 실행하세요. 터미널에서 실행하면(또는 Windows 바로가기에 옵션을 덧붙이면) 시작 시 출력되는 오류도 함께 볼 수 있습니다:

# Linux (AppImage)
./Modan2-Linux-v<version>-build<build>.AppImage --debug

# macOS
/Applications/Modan2.app/Contents/MacOS/Modan2 --debug

# Windows (PowerShell), from the installation folder
.\Modan2.exe --debug

로그를 실시간으로 보기:

# Linux/macOS
tail -f ~/PaleoBytes/Modan2/logs/*.log

# Windows PowerShell
Get-Content -Path "$env:USERPROFILE\PaleoBytes\Modan2\logs\*.log" -Wait

그 밖의 시작 옵션

  • --db <경로> — 다른 데이터베이스를 엽니다. 문제가 데이터에 있는지 애플리케이션에 있는지 확인할 때 유용합니다

  • --config <경로> — 다른 설정 파일을 사용합니다. 자신의 설정을 지우지 않고 설정 문제를 배제할 때 유용합니다

  • --no-splash — 스플래시 화면을 건너뜁니다

  • --lang <en|ko> — 인터페이스 언어를 강제합니다

흔한 오류 메시지

“Failed to connect to database”

원인: 데이터베이스 파일이 잠겨 있거나 접근할 수 없음

해결: 위의 “데이터베이스 문제” 절 참조

“Procrustes superimposition failed”

원인: 랜드마크가 부족하거나 공선임

해결: 위의 “프로크루스테스 정렬 문제” 절 참조

“Not enough objects for analysis”

원인: 표본 수 부족

해결 방법:

  • PCA: 객체가 최소 3개 필요

  • CVA/MANOVA: 각각 3개 이상의 객체를 가진 그룹이 최소 2개 필요

“Invalid landmark count”

원인: 객체의 랜드마크 개수가 데이터셋과 맞지 않음

해결 방법:

  1. 데이터셋의 랜드마크 개수 확인

  2. 객체의 랜드마크가 일치하는지 확인

  3. 필요하면 객체를 다시 디지타이징

추가 도움 받기

이 안내서로 문제가 해결되지 않으면:

  1. FAQ 확인:

    자주 묻는 질문에 대한 간단한 답

  2. GitHub Issues 확인:

    https://github.com/jikhanjung/Modan2/issues

    비슷한 문제가 이미 해결되었을 수 있으니 검색해 보세요

  3. 새 이슈 생성:

    다음을 포함해 주세요:

    • 운영체제와 버전

    • Modan2 버전과 빌드 번호

    • 오류 메시지 또는 상황 설명

    • 재현 단계

    • 로그 파일 (위의 “디버그 정보 수집” 참조)

  4. GitHub Discussions:

    질문과 일반적인 논의:

    https://github.com/jikhanjung/Modan2/discussions

  5. 이메일 문의:

    연락처: jikhanjung@gmail.com

    (위의 방법들을 먼저 시도해 주세요)

알려진 문제와 제한 사항

현재 제한 사항

  1. 준랜드마크 곡선은 2D 전용입니다:

    • 곡선 추적은 2D 표본에서만 가능하며, 3D 곡선 추적은 아직 구현되지 않았습니다

    • 프로크루스테스 정렬 중에 준랜드마크를 미끄러뜨리지(sliding) 않습니다

  2. 플랫폼별 테스트 수준:

    • 충분히 테스트된 것은 Windows 빌드뿐입니다

    • macOS 빌드는 코드 서명이 되어 있지 않습니다 (첫 실행 시 수동 승인 필요)

    • Linux AppImage는 FUSE 설치가 필요할 수 있습니다

  3. GUI 전용:

    • 일괄/헤드리스 모드는 없습니다. 시작 옵션은 일반적인 GUI 세션을 설정하기 위한 것이지, GUI 없이 분석을 실행하기 위한 것이 아닙니다

  4. 언어:

    • 영어와 한국어 인터페이스를 제공합니다

    • 일부 최신 대화상자(특히 Curve 모드)는 한국어 인터페이스에서도 아직 영어로 표시됩니다

계획된 개선 사항

계획된 기능은 CHANGELOG와 GitHub 마일스톤을 참조하세요:

  • 3D 준랜드마크 곡선 추적

  • 정렬 중 준랜드마크 슬라이딩

  • 이미지 기반 랜드마크 제안

  • 크로스 플랫폼 지원 개선

기여하기

버그를 발견했거나 제안할 내용이 있나요? 기여를 환영합니다!

자세한 기여 지침은 CONTRIBUTING.md를 참조하세요 (준비되는 대로).