🌐 English|한국어

설치

이 가이드는 다양한 운영체제에서 Modan2를 설치하는 방법을 제공합니다.

시스템 요구사항

최소 요구사항:

  • 운영체제: Windows 10/11, macOS 10.14+, 또는 Linux (Ubuntu 20.04+, Fedora 34+)

  • Python: 3.11 이상 (소스 설치 시)

  • RAM: 4 GB (대용량 데이터셋의 경우 8 GB 권장)

  • 디스크 공간: 애플리케이션 500 MB + 데이터 저장 공간

  • 디스플레이: 1280x720 해상도 (1920x1080 권장)

3D 시각화를 위한 요구사항:

  • OpenGL 3.3+ 호환 그래픽 카드

  • 최신 그래픽 드라이버

설치 방법

Windows 설치

옵션 1: 설치 프로그램 사용 (권장)

  1. 릴리스 페이지 에서 최신 설치 프로그램 다운로드

  2. Modan2-Setup.exe 실행

  3. 설치 마법사 지시에 따라 진행

  4. 시작 메뉴 또는 바탕화면 바로가기에서 Modan2 실행

참고

Windows Defender가 서명되지 않은 실행 파일에 대한 경고를 표시할 수 있습니다. 신뢰할 수 있는 소스인 경우 “자세한 정보” → “실행”을 클릭하세요.

옵션 2: 포터블 버전

  1. Modan2-portable-windows.zip 다운로드

  2. 원하는 폴더에 압축 해제

  3. Modan2.exe 실행

설치가 필요 없으며 USB 드라이브나 제한된 환경에서 유용합니다.

옵션 3: 소스에서 설치

# Install Python 3.11+ from python.org
# Clone the repository
git clone https://github.com/jikhanjung/Modan2.git
cd Modan2

# Install dependencies
pip install -r requirements.txt

# Run the application
python Modan2.py

macOS 설치

옵션 1: 애플리케이션 번들

  1. 릴리스 페이지 <https://github.com/jikhanjung/Modan2/releases>`_에서 ``Modan2.dmg` 다운로드

  2. DMG 파일 열기

  3. Modan2.app 을 응용 프로그램 폴더로 드래그

  4. 응용 프로그램에서 실행

참고

첫 실행 시 앱을 우클릭하고 “열기”를 선택하여 서명되지 않은 애플리케이션에 대한 Gatekeeper 경고를 우회하세요.

옵션 2: 소스에서 설치

# Install Python 3.11+ (via Homebrew)
brew install python@3.11

# Clone the repository
git clone https://github.com/jikhanjung/Modan2.git
cd Modan2

# Install dependencies
pip3 install -r requirements.txt

# Run the application
python3 Modan2.py

Linux 설치

Ubuntu/Debian

# Install system dependencies
sudo apt-get update && sudo apt-get install -y \
  python3 python3-pip git \
  libxcb-xinerama0 libxcb-icccm4 libxcb-image0 \
  libxcb-keysyms1 libxcb-randr0 libxcb-render-util0 \
  libxcb-xfixes0 libxcb-shape0 libxcb-cursor0 \
  qt5-qmake qtbase5-dev libqt5gui5 libqt5core5a libqt5widgets5 \
  libglut-dev libglut3.12 python3-opengl

# Clone the repository
git clone https://github.com/jikhanjung/Modan2.git
cd Modan2

# Install Python dependencies
pip3 install -r requirements.txt

# Run the application
python3 Modan2.py

Fedora/RHEL

# Install system dependencies
sudo dnf install -y \
  python3 python3-pip git \
  qt5-qtbase qt5-qtbase-devel \
  freeglut freeglut-devel \
  libxcb libxcb-devel

# Clone the repository
git clone https://github.com/jikhanjung/Modan2.git
cd Modan2

# Install Python dependencies
pip3 install -r requirements.txt

# Run the application
python3 Modan2.py

Arch Linux

# Install system dependencies
sudo pacman -S python python-pip git qt5-base freeglut

# Clone the repository
git clone https://github.com/jikhanjung/Modan2.git
cd Modan2

# Install Python dependencies
pip install -r requirements.txt

# Run the application
python Modan2.py

WSL (Windows Subsystem for Linux)

Modan2는 X11 포워딩을 통해 WSL에서 실행할 수 있습니다:

# Install WSL2 with Ubuntu
# In WSL terminal, install dependencies (same as Ubuntu above)

# Install X server on Windows (e.g., VcXsrv, X410)
# Set DISPLAY environment variable
export DISPLAY=$(cat /etc/resolv.conf | grep nameserver | awk '{print $2}'):0

# Run Modan2
python3 Modan2.py

참고

Qt 플랫폼 플러그인 오류가 발생하면 다음을 사용하세요:

python3 fix_qt_import.py

문제 해결

Qt 플랫폼 플러그인 오류 (Linux/WSL)

오류: could not load the Qt platform plugin "xcb"

해결 방법:

# Option 1: Use the fix script
python3 fix_qt_import.py

# Option 2: Set environment variable
export QT_QPA_PLATFORM_PLUGIN_PATH=/usr/lib/x86_64-linux-gnu/qt5/plugins/platforms

# Option 3: Reinstall Qt packages
sudo apt-get install --reinstall libqt5gui5 libqt5core5a libqt5widgets5

OpenGL/GLUT 오류

오류: ImportError: Unable to load OpenGL library

해결 방법:

# Ubuntu/Debian
sudo apt-get install -y libglut-dev libglut3.12 python3-opengl

# Fedora
sudo dnf install -y freeglut freeglut-devel

# Reinstall PyOpenGL
pip3 install --upgrade --force-reinstall PyOpenGL PyOpenGL_accelerate

Python 의존성 누락

오류: ModuleNotFoundError: No module named 'PyQt5'

해결 방법:

# Ensure you're using Python 3.11+
python3 --version

# Reinstall all dependencies
pip3 install -r requirements.txt

# Or install individually
pip3 install PyQt5 numpy pandas scipy peewee trimesh opencv-python

데이터베이스 마이그레이션 문제

오류: peewee.OperationalError: no such column

해결 방법:

# Run database migration
python3 migrate.py

# If migration fails, backup your database and start fresh
cp modan.db modan.db.backup
rm modan.db
python3 Modan2.py

성능 문제

시작 또는 렌더링이 느림:

  • 그래픽 드라이버 업데이트

  • 데이터셋 크기 축소 (대용량 데이터셋 분할)

  • 다른 GPU 집약적 애플리케이션 종료

  • 대용량 3D 모델 작업 시 시스템 RAM 증설

높은 메모리 사용량:

  • 사용하지 않는 데이터셋 닫기

  • 동시에 로드되는 객체 수 제한

  • 미리보기용 저해상도 이미지 사용

설치 확인

설치 후 Modan2가 올바르게 작동하는지 확인하세요:

  1. 애플리케이션 실행

    • Windows: 시작 메뉴 → Modan2

    • macOS: 응용 프로그램 → Modan2

    • Linux: python3 Modan2.py

  2. 테스트 데이터셋 생성

    • “New Dataset” 클릭 (Ctrl+N)

    • “Test”로 이름 지정

    • 확인 클릭

  3. 예제 데이터 가져오기

    • examples/ 에서 예제 TPS 파일 다운로드

    • 데이터셋으로 드래그 앤 드롭

  4. 간단한 분석 실행

    • 데이터셋 선택 → “Analyze Dataset”

    • PCA 선택

    • 결과가 올바르게 표시되는지 확인

모든 단계가 오류 없이 완료되면 설치가 성공한 것입니다!

Modan2 업데이트

설치된 버전:

최신 설치 프로그램을 다운로드하여 실행하면 이전 버전을 대체합니다.

소스 설치:

cd Modan2
git pull origin main
pip3 install --upgrade -r requirements.txt

도움말

여기에서 다루지 않은 문제가 발생하면:

  1. GitHub Issues 페이지 확인

  2. 닫힌 이슈에서 유사한 문제 검색

  3. 다음 정보와 함께 새 이슈 생성: - OS 및 버전 - Python 버전 (python3 --version) - 전체 오류 메시지 - 재현 단계

다음 단계