Hear I am

LiDAR로 스캔한 무대에 동선을 저장하고, 허리에 찬 iPhone이 그 동선을 따라 소리와 음성으로 방향·거리·장애물을 알려 주는 iOS 앱입니다.

Xcode에서 Hear-I-am.xcodeproj 를 열고 Hear-I-am scheme을 선택하세요. 앱 표시 이름은 Hear I am 히얼아이엠입니다.

• 무대 준비(가로): 공간 스캔 → 무대 범위(네 모서리) → 기물(장애물 · 의자 · 계단) → 동선 → 확인점 1·2 → 검토·저장. 동선은 출발점 + 최대 20개 지점(도착점 포함)입니다.
• 안내(세로): 무대 선택 → 공간 복원 · 확인점 1·2 측정 및 위치·회전 보정 → 허리띠 착용(「착용 완료」) → 출발 준비 → 안내 → 완료. 다음 단계 버튼은 설명이 나오는 중에도 누를 수 있고, 누르면 설명이 멈춥니다. 위치 · 확인점 · 출발점 조건은 그대로 지켜야 합니다.
• 공간 다시보기: 원본 회색 스캔과 정리한 공간(원목 바닥 · 웜그레이 기물), 전체 / 동선 위 시점, 준비 중 직접 찍은 현장 사진. 자세히는 Experiments/stage-replay-49.md, 기록 재생은 Experiments/replay-develop-integration-52.md.
• 위험 구역: 무대 준비에서 앞 · 뒤 · 왼쪽 · 오른쪽 변마다 0.5m / 1m 띠를 켤 수 있습니다. 지금은 화면 표시만 하고 안내 소리와는 연결하지 않았습니다.

진동은 쓰지 않습니다. 소리는 연결된 에어팟으로(없으면 폰 스피커로) 나가고, 설정에서 폰 스피커로 고정할 수 있습니다.

• 좌우 말이 먼저 나오고 톡톡톡은 그 말이 끝난 뒤에 납니다. 거리 음성이 나오는 중이면 끊고 좌우를 말하고, 의자 · 계단 음성은 끝날 때까지 기다립니다.
• 도착은 지점 0.35m 안에 0.8초 머무르면 인정합니다. 출발은 출발점 0.45m 안입니다.

• iOS 17 이상. 스캔 · 공간 복원 · 안내는 LiDAR가 있는 iPhone 실기기에서 확인합니다. 시뮬레이터에서는 홈 · 목록 · 도면 편집 정도만 볼 수 있습니다.
• Signing & Capabilities에서 각자 개발 팀을 고릅니다. 이 서명 변경은 커밋하지 않습니다.
• 코어 테스트: 저장소 루트에서 sh scripts/test-core.sh
• 다시보기 모델 변환 스크립트: scripts/convert-replay-models.swift · scripts/convert-replay-walker.swift. 실험 기록과 범위는 Experiments/에 있습니다.
• 파일을 더하거나 옮긴 뒤에는 저장소 루트에서 xcodegen generate를 실행합니다.

• 번들 ID(org.heariam.poc4.scanlab)와 앵커 이름 접두사(PoC4.reference.)는 기존 TestFlight 앱의 저장 무대를 잇기 위해 이전 이름을 유지합니다. 다른 번들 ID로 설치하면 그 무대가 보이지 않습니다.
• 옛 저장 형식(route v1 · manifest v1/v2)도 계속 읽습니다.

Hear-I-am/
├── App/Source/          # @main · 탭(HearRootView) · 화면 방향
├── Core/                # 여러 기능이 함께 쓰는 것
│   ├── AR/              #   ARKit 세션(준비·안내 공용), 스캔 메시·표식·위험 구역 그리기
│   ├── Audio/           #   GuidanceSpeech(TTS) · SignalPlayer(신호음) · HearAudioSession(출력·음량)
│   ├── Logging/         #   TrialLogger (Documents/Trials)
│   ├── Store/           #   StageLibrary (저장 무대 목록·고정)
│   └── DesignSystem/    #   색 · 버튼 · 무대 지도 등
├── Features/            # 기능별 Model / View(Screen·Parts·Sheet) / ViewModel
│   ├── Home/ · Preparation/ · Guidance/ · Planning/ · Records/ · StagePreview/
│   └── SoundTest/       #   임시 탭. 테스트가 끝나면 폴더와 HearRootView 줄을 지운다
└── Resources/         # Assets · ReplayModels.scnassets(다시보기 인물·기물 모델)

Packages/HearIAmCore/    # 화면과 무관한 규칙과 테스트 (UIKit·ARKit을 모름)
├── Geometry/ · Stage/ · Storage/
├── Guidance/            #   RouteGuide(도착·이탈 판정) · NarrationQueue · DepartureGate
└── Signal/              #   경고 · 톡톡톡 · 거리 · 의자·계단 규칙, ToneRenderer(소리 합성)

• 의존 방향은 View → ViewModel → Core → HearIAmCore 한쪽입니다.
• 저장 형식이나 판정 규칙은 HearIAmCore에 두고 테스트를 붙입니다. 두 기능 이상이 쓰면 Core/, 한 화면만 쓰면 그 기능 폴더에 둡니다.
• ViewModel은 단계마다 extension 파일로 나눕니다(예: GuidanceViewModel+Guiding).

이슈 · 브랜치 · PR 규칙은 CONTRIBUTING.md를 봅니다.

홈 → 저장 무대 → 경로점 선택에서 “도착 후 다음 지점 안내 대기” 시간을 0~3600초 정수로 입력하고 저장합니다. 설정은 무대 파일에 유지되고 다음 안내부터 적용됩니다. 이전 저장 무대의 기본값은 0초이며, 출발점과 최종 도착점을 제외한 중간 지점에만 설정할 수 있습니다. 설정 패널과 목록은 저장된 지점 이름(P1·의자1·계단1 등)을 동일하게 표시합니다.

도착 판정 직후 지점 이름을 한 번 알리고, 설정한 시간 동안 다음 방향·거리 음성과 방향 신호음을 쉬게 합니다. 현재 의자·계단에서 바라볼 방향 안내는 유지하고, 대기 중 다음 지점 도착/완료 판정은 보류하며, 화면에 남은 시간을 표시합니다. 정상 추적 표본으로 시간이 경과하고 일시정지·추적 중단 중에는 남은 시간이 유지됩니다. 다시 안내하면 잔여 대기를 마친 뒤 자동으로 다음 지점을 안내합니다. 종료 후 새 안내를 시작하면 새로 도착한 지점부터 설정이 적용됩니다. 설정 저장은 공간 지도·메시·경로 좌표를 변경하지 않습니다.

현장 확인: 0초/10초 설정 후 도착 지점 음성 1회, 대기 중 방향·거리·방향 신호음 없음, 타이머 종료 시 안내 재개, 일시정지/추적 중단 후 잔여 시간 유지, 앱 재실행 후 설정 유지.

저장과 현장 확인 모두 1번 → 2번 순서로 같은 바닥 표식을 선택합니다. 두 점은 수평으로 1m 이상 떨어져야 합니다. 저장된 좌표와 ARWorldMap은 유지하고, 해당 안내 세션에서 수평 이동과 yaw만 보정합니다. 높이·크기는 바꾸지 않습니다. 표시에는 정변환, 위치·방향 및 안내 판정에는 역변환을 적용합니다.

초기 실험 한계값은 중점 이동 50cm, 회전 10°, 두 점 간 거리 차이 15cm, 보정 후 각 점의 3D 잔여 오차 15cm입니다. 실제 정확도 보증값이 아니며 현장 검증이 필요합니다. 순서가 뒤바뀌거나 한계를 넘으면 1번부터 다시 확인합니다. 두 점 사이에 추적 제한·표본 만료가 발생해도 측정값을 버립니다.

기존 v1/v2 저장 무대는 열람할 수 있으나 두 점 보정 안내에는 사용할 수 없습니다. 현재 준비 화면은 저장 무대 재편집을 지원하지 않으므로 새로 준비해 두 확인점을 저장해야 합니다. v3부터 두 점을 저장합니다.

현장 확인: 정상 두 점 보정 후 근처와 먼 경로점 일치, 1·2 뒤바뀜, 같은 점 중복 선택, 1번 선택 후 추적 중단, 재복원 후 보정 중복 적용 여부를 점검합니다.

무대 범위를 지정한 뒤 기존 “사전 저장 동선 불러오기”로 도면을 선택하면, 기물 등록 단계부터 참고 잔상이 표시됩니다. 경로점·연결선·기물 윤곽은 옅은 파란색이며 실제 기물과 경로점은 현장에서 직접 등록해야 합니다. 잔상은 확정 데이터, 충돌 검사, 앵커 및 저장 파일에 포함되지 않습니다.

기물 단계와 경로 단계의 “참고 잔상 표시” 스위치는 각각 켜짐/꺼짐을 기억합니다. 다른 단계에서는 잔상이 숨겨집니다. 도면의 12×8 좌표를 실제 무대의 폭·깊이에 각각 맞추므로 종횡비가 달라도 맞춰집니다. 무대 범위 수정 시 잔상만 다시 계산하고, 직접 찍은 지점과 기물은 이동시키지 않습니다. 높이는 도면에서 가져오지 않고 실제 스캔을 기준으로 등록합니다.

현장 확인: 불러온 직후 확정 경로·기물이 비어 있는지, 기물/경로 단계에서 각각 잔상 on/off가 되는지, 등록한 점과 기물이 토글 후에도 유지되는지, 무대 비율 변경 후 잔상 위치가 맞는지 확인합니다.

홈의 최근 저장한 무대 → 스캔 공간 3D로 보기 → 경로점 버튼에서 “도착 후 바라볼 방향”과 대기 시간을 설정하고 “경로점 설정 저장”을 누릅니다. 무대 앞(관객 쪽)을 북, 앞을 바라봤을 때 오른쪽을 동으로 하는 8방위이며 나침반의 방위와 무관합니다. 출발·최종 도착점도 방향을 설정할 수 있고 대기는 기존처럼 중간 경로점만 지원합니다. “지정 안 함”은 기존 안내를 유지하며 의자·계단에 지정 방향이 있으면 기존 기물 방향을 사용합니다. 경로점 방향을 지정하면 기물 방향보다 우선합니다.

지점 도착 → 이름·바라볼 방향 음성 → 제자리 좌우 방향 안내 → 지정 방향 ±15° 안에서 1초 유지 → 설정한 공연 대기 → 다음 지점 안내 순서입니다. 8방위 정렬에는 이동 안내의 사용자 지정 허용 각도와 별도로 ±15°를 적용합니다. 정렬 중에는 다음 지점 도착 판정과 대기 타이머가 진행되지 않습니다. 일시정지·추적 중단 후에도 정렬할 지점을 유지하고, 재개 후 정렬 유지 시간을 다시 측정합니다. 마지막 지점은 정렬까지 마쳐야 완료합니다. 출발점 방향은 “안내 시작” 후 첫 이동 전에 맞춥니다. 방향을 지정하지 않은 기존 무대의 동작은 유지합니다. 위치·방향 확인은 허리 앞쪽에 고정한 휴대폰을 기준으로 하므로 고개만 돌리는 동작은 판정하지 않습니다.

두 확인점 검증 → 조력자가 휴대폰을 무용수의 허리 앞쪽에 세로로 부착(카메라는 바깥쪽) → 착용 완료 → “출발점까지 안내”를 누르면 현재 위치에서 출발점까지 방향·거리 소리를 제공합니다. 출발점에 도착하면 멈추고 “안내 시작”을 눌러 공연 동선을 시작합니다. 접근 구간은 공연 경로와 완료 기록에 추가하지 않습니다.

출발점 접근은 무대 직사각형과 경계 여유 설정에 관계없이, 현재 위치·출발점·둘 사이 직선 구간이 저장된 LiDAR 스캔 범위에 포함되고 등록된 통과 금지 기물이 막지 않을 때 가능합니다. 사용자와 출발점이 각각 무대 안 또는 밖에 있는 조합을 모두 지원합니다. 기물이 막으면 조력자에게 경로 확인을 요청하고 자동 우회 경로는 만들지 않습니다. 접근 중 LiDAR 스캔 범위 이탈·1m 경로 이탈·등록 기물 충돌 경로·추적 중단 시 멈춥니다. 스캔하지 않은 새 기물을 자동 인식하는 기능은 아닙니다. 스캔 범위는 저장된 메시의 수평 투영으로 확인하고, 수직 벽만 있는 곳과 스캔이 빠진 중간 구간은 포함시키지 않습니다. 메시 사이 5cm 이하의 틈만 허용합니다. 바닥 분류 데이터가 없는 기존 메시를 사용하므로 이 검사는 높이차나 통행 가능 여부를 보장하지 않습니다.

실기기 확인: 8방위 좌우 일치, 방향 지정 후 10초 대기, 방향 지정 해제, 출발·최종점 방향, 의자 방향보다 경로점 방향 우선, 정렬/대기 중 일시정지 및 재확인, 출발점 접근 중 일시정지·기물 차단·추적 중단, 접근 완료 뒤 첫 경로점 안내 및 완료 기록을 확인합니다.

출발 준비의 “출발점까지 안내”는 설명 음성 중에도 누를 수 있습니다. 누르면 진행 중인 설명을 즉시 멈추고 그 시점의 위치·경로를 검사합니다. 출발점 근처, LiDAR 스캔 범위 이탈/공백, 등록 기물 차단, 위치 미확인 상태는 버튼을 잠그는 대신 화면과 음성으로 사유를 알려줍니다. 무대 선택·확인점 확인·착용 완료·안내 시작 버튼도 설명 종료를 기다리지 않으며, 음성 오류 후 다시 눌러 재시도할 수 있습니다. 각 단계의 확인점·착용·출발 위치 검증은 그대로 적용합니다.