fhd_rtk_ws/docs/SCAN-운용가이드.md

스캔 → 매핑 운용 가이드 (녹화: 트리플 카메라 GUI / 처리: fast_dual_ws)

전체 파이프라인: 녹화는 ~/fast_ws 의 스캔 GUI(+~/fhd_rtk_ws UM982 드라이버)로, 매핑(SLAM) 은 이 문서가 있는 ~/fast_dual_ws (FAST-LIVO2, 듀얼/트리플 카메라 지원 빌드)로 처리한다. 녹화 도구와 처리 애플리케이션이 서로 다른 워크스페이스이므로 이 문서는 fast_dual_ws/docs/ 에 둔다 (fast_ws 는 녹화 GUI 전용 워크스페이스라 전체 파이프라인 문서를 두기에 맞지 않음).

---

0. 워크스페이스 역할 정리

워크스페이스	역할	비고
~/fhd_rtk_ws	UM982 RTK GNSS 드라이버(파싱+NTRIP+/ublox_driver/receiver_pvt 발행)	녹화 전용 최소 빌드
~/fast_ws	LiDAR + cam1/cam2/cam3 시동 및 ros2 bag record GUI (scan_gui_triple.py)	fhd_rtk_ws/camera2_ws 를 함께 source
~/fast_dual_ws	FAST-LIVO2 매핑 엔진(dual/triple 카메라 VIO-LIO 빌드, fastlivo_mapping)	녹화된 bag 을 재생해서 SLAM 돌리는 애플리케이션
~/FAST-LIVO2-RTK-ROS2	GNSS-RTK 융합이 포함된 별도 FAST-LIVO2 소스(옵티마이저에 gpsHandler 있음)	아직 fast_dual_ws 에 통합 안 됨 — §4 참고

⚠️ 중요: fast_dual_ws/src 에 gnss_comm/um982_driver 패키지가 같이 들어있지만, 현재 fast_dual_ws 의 fast_livo (package.xml, LIVMapper.cpp 등)는 GNSS 토픽을 구독하지 않는다 (gnss_comm/GnssPVTSolnMsg 참조 없음). 즉 녹화 bag 에 /ublox_driver/receiver_pvt 를 같이 담아도 지금의 fast_dual_ws 매핑에는 아직 반영되지 않는다 — 순수 LiDAR-Inertial-Visual 매핑만 수행된다. GNSS 융합이 필요하면 ~/FAST-LIVO2-RTK-ROS2 통합 작업이 별도로 필요하다.

---

1부. 녹화 (fast_ws 스캔 GUI + fhd_rtk_ws UM982)

1.1 사전 준비

• LiDAR, cam1/2/3, UM982 USB 연결. UM982 안테나는 하늘이 트인 곳에 — 실내면 GNSS No Fix(SV 0) 가 정상.
• /dev/ttyUSB0 권한 확인:

  ls -la /dev/ttyUSB0
  # 그룹이 dialout 인데 미가입이면:
  sudo usermod -aG dialout $USER   # 이후 재로그인 필요(영구)
  sudo chmod a+rw /dev/ttyUSB0     # 임시(재부팅/재연결 시 초기화)
  

• UM982 최초 설정(또는 FRESET 후): rtk/config_all.py 로 BESTNAVB COM3 0.1, GPGGA COM3 1, baud 460800, MODE ROVER 저장 확인.
• 터미널에 남아있는 um982_driver_node 프로세스가 있으면 포트를 선점해 GUI GPS 시작이 실패한다:

  ps aux | grep um982_driver_node | grep -v grep && kill -INT <PID>
  

1.2 GUI 실행 및 녹화

바탕화면 "스캔 GUI (트리플 카메라)" 아이콘 실행 → 좌측 패널 순서대로:

1. 시동 — LiDAR 즉시 실행, 5초 후 cam1/cam2/cam3 자동 실행. 우측 미리보기 확인.

2. GPS 시작 — 상태 라벨/좌표 갱신 확인. 색상 의미:

   라벨	의미
   ● No Fix	위성 미포착 — 실내 정상
   ● GPS / ● DGPS	단독/차분 측위, RTK 아님
   ● RTK Float	보정 진행 중
   ● RTK Fixed	최고 정밀도(cm급) — 녹화는 이 상태 권장

3. 녹화 — 저장 경로/파일명 입력, "녹화에 GPS 포함" 체크(GPS 가 켜져 있어야 실제 포함됨) → 녹화 시작 → 종료 시 정지.

   • 저장 위치: ~/bags/<파일이름>/<파일이름>_0.db3

1.3 녹화 검증

source /opt/ros/humble/setup.bash
ros2 bag info ~/bags/<파일이름>/

• 토픽: /livox/lidar, /livox/imu, /cam1/image, /cam2/image, /cam3/image(+camera_info 3종), GPS 포함 시 /ublox_driver/receiver_pvt
• GNSS 메시지 수 ÷ Duration ≈ 10Hz 확인.

---

2부. 재생 + 매핑 실행 (fast_dual_ws)

2.1 빌드 확인 (최초 1회 / 소스 수정 시)

cd ~/fast_dual_ws
colcon build --packages-select fast_livo
source install/setup.bash

2.2 실행 (터미널 2개)

터미널 A — 매핑 노드 + RViz:

source /opt/ros/humble/setup.bash
source ~/fast_dual_ws/install/setup.bash
ros2 launch fast_livo mapping_mid360s_triplecam.launch.py use_rviz:=True

터미널 B — 녹화한 bag 재생 (스페이스바로 재생/일시정지):

source /opt/ros/humble/setup.bash
ros2 bag play -p ~/bags/<파일이름>/

• -p 는 일시정지 상태로 시작 → RViz 창에서 매핑 노드가 준비된 걸 확인한 뒤 스페이스바로 재생.
• 매핑 노드가 구독하는 토픽(/livox/lidar, /livox/imu, /cam1/image, /cam2/image, /cam3/image)은 scan_gui_triple.py 녹화 토픽명과 동일하므로 리매핑 불필요.

2.3 결과 확인

• RViz(fast_livo2.rviz)에서 포인트클라우드 누적/궤적 확인.
• /ublox_driver/receiver_pvt 는 bag 에 있어도 매핑 결과에 영향 없음(§0 참고) — GNSS 데이터 자체 품질만 따로 보고 싶으면 별도로 ros2 topic echo -b ... 또는 재생 중 ros2 topic echo /ublox_driver/receiver_pvt 로 확인.

---

3. 트러블슈팅

증상	원인	조치
GPS 시작 직후 "GPS 없음"으로 복귀 / gnss.log 에 시리얼 오픈 실패	권한 문제 또는 포트 중복 점유	§1.1 권한/프로세스 확인
실내에서 계속 No Fix	정상(위성 미포착)	옥외/창가 이동, 그래도 안 되면 안테나 케이블 확인
bag 재생해도 RViz 에 아무것도 안 뜸	-p 로 일시정지 상태 → 스페이스바 안 누름, 또는 토픽명 불일치	스페이스바로 재생 시작, ros2 bag info 로 토픽명 재확인
GNSS 데이터가 매핑에 반영 안 되는 것 같음	현재 fast_dual_ws 는 GNSS 미융합 (설계상 아직 없음)	§0 참고 — 필요 시 FAST-LIVO2-RTK-ROS2 통합 작업 별도 진행

---

4. GNSS 융합이 필요해지면

~/FAST-LIVO2-RTK-ROS2/FAST-LIVO2-RTK-ROS2 소스에는 optimization.cpp::gpsHandler 등 GNSS-RTK 융합 로직이 이미 구현돼 있다(원본 fhd_rtk_ws 문서가 가리키던 "FAST-LIVO2-RTK 백엔드"가 이것). 현재는 빌드된 워크스페이스가 아니라 압축 해제된 소스 상태(__MACOSX 잔재로 보아 zip 압축 해제본). fast_dual_ws 의 dual/triple 카메라 지원과 이 GNSS 융합을 합치려면 두 소스를 비교해 병합하는 별도 작업이 필요하다 — 착수 시 다시 요청.