🌐 English|한국어

설치

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

시스템 요구사항

최소 요구사항:

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

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

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

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

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

  • OpenGL 3.3+ 호환 그래픽 카드

  • 최신 그래픽 드라이버

설치 방법

Modan2는 각 플랫폼별로 미리 빌드된 패키지 형태로 릴리스 페이지 에서 배포됩니다. 모든 파일 이름에는 버전과 빌드 번호가 들어 있어 릴리스마다 이름이 달라집니다. 아래의 <version> 과 <build> 는 실제로 내려받는 릴리스에 표시된 값을 뜻합니다(예: v0.1.12, build672).

각 릴리스에는 다운로드 무결성을 확인할 수 있도록 SHA256SUMS.txt 도 함께 게시됩니다.

경고

충분히 테스트된 것은 Windows 빌드뿐입니다. macOS와 Linux 패키지도 동일한 자동 빌드로 만들어지지만 같은 수준의 테스트를 거치지 않았으므로, Windows에서는 발생하지 않는 문제가 나타날 수 있습니다. 문제가 발생하면 이슈 페이지 에 알려 주세요.

Windows

  1. 릴리스 페이지에서 Modan2-Windows-Installer-v<version>-build<build>.zip 을 내려받습니다.

  2. ZIP 파일의 압축을 풉니다. 안에는 설치 프로그램 Modan2_v<version>_build<build>_Installer.exe 하나가 들어 있습니다.

  3. 설치 관리자를 실행하고 마법사를 따릅니다. 현재 사용자에게만 설치되며 관리자 권한을 요구하지 않습니다.

  4. 시작 메뉴에서 Modan2를 실행합니다.

참고

Windows Defender가 서명되지 않은 실행 파일에 대해 경고를 표시할 수 있습니다. 신뢰할 수 있는 출처라면 “추가 정보” → “실행”을 클릭하세요.

참고

0.2.0-beta.2 이전 버전이 설치돼 있으면 설치 관리자가 이를 감지해 먼저 제거할지 물어봅니다. 둘 다 유지할 이유가 없다면 수락하십시오 — Modan2 업데이트 를 참고하십시오.

참고

설치가 필요 없는 포터블 Windows 빌드는 현재 제공하지 않습니다. Windows용 패키지는 설치 프로그램뿐입니다.

macOS

  1. 릴리스 페이지에서 Modan2-macOS-Installer-v<version>-build<build>.dmg 를 내려받습니다.

  2. DMG 파일을 엽니다.

  3. Modan2.app 을 응용 프로그램 폴더로 끌어다 놓습니다.

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

참고

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

Linux

Linux용은 설치 없이 실행되는 AppImage로 배포됩니다.

# Download Modan2-Linux-v<version>-build<build>.AppImage from the releases page
chmod +x Modan2-Linux-v<version>-build<build>.AppImage
./Modan2-Linux-v<version>-build<build>.AppImage

참고

AppImage가 실행되지 않는다면 배포판에 FUSE가 없을 수 있습니다. FUSE를 설치하거나(Ubuntu/Debian에서는 sudo apt-get install libfuse2), AppImage를 --appimage-extract-and-run 옵션과 함께 실행하세요.

문제 해결

Windows: 시작할 때 DLL 누락

증상: 애플리케이션이 시작되지 않고 DLL이 없다는 오류가 표시됩니다.

패키지 빌드가 의존하는 Microsoft Visual C++ 재배포 가능 패키지(x64)를 설치하십시오. 갓 설치한 Windows에는 없는 경우가 있습니다: https://aka.ms/vs/17/release/vc_redist.x64.exe

macOS: “Modan2이(가) 손상되어 열 수 없습니다”

실제로 손상된 것이 아니라, 서명되지 않은 애플리케이션에 Gatekeeper가 붙인 격리 속성입니다. 제거하십시오:

sudo xattr -rd com.apple.quarantine /Applications/Modan2.app

Linux: “Could not load the Qt platform plugin xcb”

Qt는 자체 libqxcb.so 를 포함하는데, 이것이 시스템 XCB 라이브러리에 링크됩니다. 하나라도 없으면 플러그인을 로드할 수 없습니다.

sudo apt-get install -y libxcb-xinerama0 libxcb-icccm4 libxcb-image0 \
  libxcb-keysyms1 libxcb-randr0 libxcb-render-util0 libxcb-xfixes0 \
  libxcb-shape0 libxcb-cursor0 libxkbcommon-x11-0

어느 것이 없는지는 Qt에게 물어보면 됩니다:

QT_DEBUG_PLUGINS=1 ./Modan2-Linux-<version>.AppImage

OpenGL / 3D 렌더링 오류

증상: 3D 뷰어가 비어 있거나, 시작할 때 OpenGL 오류가 표시됩니다.

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

  • GPU가 OpenGL 3.3 이상을 지원하는지 확인하세요.

  • Linux에서는 헤드리스 또는 원격 세션(SSH, VNC, 일부 WSL 환경)이 사용 가능한 OpenGL 컨텍스트를 제공하지 않을 수 있습니다. 일반 데스크톱 세션에서 Modan2를 실행하세요.

성능 문제

시작 또는 렌더링이 느림:

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

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

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

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

높은 메모리 사용량:

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

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

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

설치 확인

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

  1. 애플리케이션 실행

    • Windows: 시작 메뉴 → Modan2

    • macOS: 응용 프로그램 → Modan2

    • Linux: AppImage 실행

  2. 테스트 데이터셋 생성

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

    • “Test”로 이름 지정

    • 확인 클릭

  3. 예제 데이터 가져오기

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

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

  4. 간단한 분석 실행

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

    • PCA 선택

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

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

Modan2 업데이트

새 릴리스의 패키지를 내려받아 이전과 같은 방법으로 설치합니다:

  • Windows: 새 설치 프로그램을 실행하면 이전 버전을 대체합니다.

  • macOS: 새 DMG를 열고 응용 프로그램 폴더의 Modan2.app 을 교체합니다.

  • Linux: 새 AppImage를 내려받아 이전 것 대신 실행합니다.

데이터베이스, 데이터 파일, 설정은 애플리케이션과 별도로 보관되므로 업데이트해도 영향을 받지 않습니다.

0.2.0-beta.1 이하에서 업데이트 (Windows)

0.2.0-beta.2 에서 Modan2의 설치 위치와 식별 방식이 바뀌었기 때문에, 설치 관리자는 이전 릴리스가 남긴 설치를 인식하지 못합니다. 대신 이를 감지해 제거할지 물어보며, 수락하는 것이 간단한 방법입니다.

거절하고 둘 다 유지한다면, 구버전은 새 버전을 설치한 뒤가 아니라 설치하기 전에 제거하십시오. 시작 메뉴 바로가기와 예제 데이터셋은 두 설치가 공유하는 고정 경로에 있습니다. 새 버전을 설치하면 이 경로를 넘겨받지만 구버전 언인스톨러는 여전히 자기 것으로 알고 있어서, 나중에 실행하면 새 버전을 가리키는 바로가기를 지우고 예제 데이터셋도 삭제합니다.

어느 경우든 사용자의 데이터는 영향을 받지 않습니다 — 두 프로그램 폴더 바깥에 있기 때문입니다.

Modan2 제거

  • Windows: 설정 → 앱 → Modan2 → 제거.

  • macOS: 응용 프로그램 폴더의 Modan2.app 을 휴지통으로 끌어다 놓습니다.

  • Linux: AppImage 파일을 삭제합니다.

이렇게 하면 데이터는 그대로 남으며, 보통은 그것이 바라는 바입니다. 데이터셋, 이미지, 3D 모델, 로그, 백업, 설정은 모두 ~/PaleoBytes/Modan2/ (Windows에서는 C:\Users\<사용자>\PaleoBytes\Modan2) 에 있습니다. 전부 제거하려면 이 폴더도 삭제하십시오 — 다만 데이터셋의 유일한 사본이 여기 있다는 점에 유의하십시오.

도움말

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

  1. GitHub Issues 페이지 확인

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

  3. 다음 정보와 함께 새 이슈를 생성하세요: - 사용 중인 OS와 버전 - 내려받은 Modan2의 버전과 빌드 번호 - 전체 오류 메시지 - 재현 단계

다음 단계