SOMA.DIGITAL HUMAN LAB
성능 모드
사용 매뉴얼Markdown 다운로드

SOMA 로컬 데모 설치·실행

갱신: 2026-09-13. 배포 폴더는 빌드된 전신·손목 시뮬레이터와 매뉴얼을 포함합니다. 원본 프로젝트, Blender, Python, Cloudflare 계정은 데모 실행에 필요하지 않습니다.

지원 환경

  • macOS 13.5 이상: Apple Silicon 또는 Intel.
  • Windows 11 이상: x64. ARM64 장치는 x64 실행 환경을 사용하며 별도 실기기 확인이 필요합니다.
  • Linux: glibc 2.35 이상, x64 또는 ARM64. Ubuntu 22.04 이상 권장. Alpine/musl은 지원하지 않습니다.

Node.js 24.21.0과 Wrangler 4.92.0을 고정합니다. Node는 공식 배포본의 SHA-256을 확인한 뒤 데모 폴더의 .runtime에 설치합니다. 전역 Node나 시스템 PATH는 변경하지 않습니다. 첫 설치에는 인터넷이 필요하며, 설치가 끝나면 데모 실행에 외부 계정이 필요하지 않습니다.

macOS

  1. ZIP을 쓰기 가능한 폴더에 완전히 풉니다.
  2. Install-macOS.command를 실행합니다.
  3. Start-macOS.command를 실행하고 표시되는 로컬 주소를 엽니다.
  4. Verify-macOS.command로 별도 검증 서버를 띄워 페이지·스크립트·3D 모델 파일을 검사할 수 있습니다.

터미널에서도 bash Install-macOS.command, bash Start-macOS.command --port 3000, bash Verify-macOS.command --port 3001로 실행할 수 있습니다. 다운로드 파일 실행이 macOS에서 차단되면 내용을 확인한 뒤 터미널에서 해당 명령을 사용하세요.

Windows

Install-Windows.cmd, Start-Windows.cmd, Verify-Windows.cmd 순으로 사용합니다. 포트를 바꾸려면 터미널에서 Start-Windows.cmd -Port 3001을 실행합니다.

Windows 기본 PowerShell 5.1 이상을 사용합니다. 실행 정책 예외는 해당 PowerShell 프로세스에만 적용하며 시스템 정책을 변경하지 않습니다. 설치 프로그램은 관리자 권한이나 MSI 설치 없이 ZIP 형식의 Node를 폴더 안에 준비합니다.

Linux

bash Install-Linux.sh, bash Start-Linux.sh, bash Verify-Linux.sh --port 3001을 실행합니다. 셸은 Bash입니다. curl·tar·gzip이 없으면 설치 스크립트가 apt/dnf/zypper/pacman으로 필요한 다운로드 도구를 설치하며, 이 경우에만 root 또는 sudo가 필요합니다.

주소·종료·재실행

기본 주소는 http://127.0.0.1:3000입니다. 서버가 준비될 때까지 잠시 기다린 뒤 접속합니다. 중지는 터미널에서 Ctrl+C입니다. 이후에는 Start만 실행하면 됩니다. 설치는 재실행해도 같은 버전과 잠금 파일이면 기존 패키지를 재사용합니다.

다른 장치에서 접속할 데모는 macOS/Linux에서 --host 0.0.0.0, Windows에서 -BindHost 0.0.0.0을 지정하고 해당 컴퓨터의 LAN IP와 포트를 사용합니다. 기본값은 로컬 컴퓨터만 허용합니다. 방화벽 허용 여부는 OS에서 확인합니다.

검증과 문제 해결

Verify는 서버를 직접 시작하고 홈·전신·손목·연구·매뉴얼·원본 실험 화면, 페이지 스크립트와 실제 GLB를 검사한 뒤 종료합니다. 결과는 .runtime/verification.json, 서버 출력은 .runtime/verification-server.log입니다. 브라우저에서 실제 WebGL 렌더링이나 FPS를 검사하는 절차는 아닙니다.

  • 포트 사용 중: 다른 포트를 지정합니다. 스크립트는 기존 서버를 종료하지 않습니다.
  • 체크섬/파일 손상: ZIP을 새 폴더에 다시 풉니다.
  • 설치 실패: 인터넷과 디스크 공간, 폴더 쓰기 권한을 확인한 뒤 Install을 다시 실행합니다.
  • 모델이 안 보임: 최신 브라우저의 WebGL/하드웨어 가속을 확인합니다.
  • 다른 OS로 이동: ZIP 원본을 사용하세요. 이미 설치된 node_modules와 .runtime을 OS 간 복사하지 않습니다.

모델 출처

모델의 출처와 이용 조건은 dist/client/models/ATTRIBUTION.md 및 동작 자산의 출처 문서에 보존됩니다. 이 패키지는 연구 데모이며 임상 정확도 또는 모든 자산의 상업 이용 권한을 보장하지 않습니다.

환경 근거

Node.js 24 공식 배포와 Wrangler 지원 환경을 기준으로 작성했습니다.

수면 센서 소켓 데모

설치가 끝난 데모 폴더에서도 npm run sleep:demo를 실행할 수 있다. 별도 터미널에서 실행한 뒤 수면무호흡 화면의 WebSocket / IP에 ws://localhost:8765/stream을 입력한다. 실제 장치는 npm run sleep:gateway의 /input으로 v1 JSON 패킷을 전송한다. 자세한 단위와 채널 형식은 웹 사용 매뉴얼의 수면무호흡 실험을 참고한다. 기본 게이트웨이는 이 컴퓨터에서만 접근하며 인터넷 공개용 인증 서비스가 아니다.