fhd_fast_tri_ws/docs/Jetson-이관가이드.md

Jetson 이관 가이드 — fhd_fast_tri_ws / 캘리브레이션 툴 / 녹화 툴

이 문서가 다루는 범위: 매핑(~/fhd_fast_tri_ws — 3카메라 확장판, 이관 대상), 캘리브레이션 (~/dvlc_gui + ~/direct_visual_lidar_calibration + ~/dvlc_ws), 녹화(~/scan_web + ~/camera2_ws + ~/lidar2_ws + ~/rtk_ws) — 이 프로젝트에서 개발한 전체 파이프라인을 최종적으로 이 x86_64 데스크탑에서 Jetson(ARM64)으로 옮길 때 담당자가 확인해야 할 것들이다.

~/fast_ws는 이관 대상에서 제외한다 (2026-08-05 사용자 결정) — fhd_fast_tri_ws로 3카메라 확장되기 이전의 구버전 저장소이며, 담고 있던 녹화 GUI(scan_gui*.py)도 scan_web으로 대체됐다. fast_ws가 하던 유일한 실질적 역할(라이다 원시 드라이버 실행)도 사실 자체 구현이 아니라 lidar2_ws를 언더레이로 체이닝해서 쓴 것뿐이었다(§3에서 확인) — 그래서 scan_web도 이번에 fast_ws를 거치지 않고 lidar2_ws를 직접 source하도록 고쳤다(config.py/run_scan_web.sh). 즉 Jetson으로 옮기는 매핑 엔진은 fhd_fast_tri_ws(3카메라)이고, fast_ws는 옮길 필요도 없다.

아래 사실관계는 실제로 이 머신을 조사해서 확인한 것이다 (2026-08-05 기준). "일반적으로 고려할 사항"이라고 표시된 항목만 이 머신에서 직접 확인하지 않은 일반론이니, 그 부분은 Jetson 현장에서 재확인 필요.

---

0. 제일 먼저 알아야 할 것: "통째로 옮긴다"가 위험한 이유

"파일을 통째로 옮긴다"는 접근은 아래 두 가지 이유로 그대로 하면 안 된다.

1. build/, install/, log/ 는 x86_64 바이너리다. 각 ROS2 워크스페이스(camera2_ws, lidar2_ws, dvlc_ws, fhd_fast_tri_ws, rtk_ws)의 build//install/ 디렉터리 안 실행파일/라이브러리는 이 PC의 x86_64용으로 컴파일된 것이라 Jetson(ARM64)에서 그대로 실행 안 된다. 옮겨봐야 못 쓰는 죽은 용량이다. → src/만 옮기고, build/·install/·log/는 Jetson에서 colcon build로 새로 빌드한다.
2. 일부 소스가 git clone인데 로컬 수정사항이 있다 (§3 참고) — 파일 복사가 아니라 실수로 git clone을 새로 받으면 그 수정사항이 통째로 날아간다.

즉 실제로 옮길 대상은: fhd_fast_tri_ws, camera2_ws, lidar2_ws, dvlc_ws, rtk_ws의 src/ 디렉터리, config YAML/JSON, dvlc_gui/scan_web 전체(빌드 산출물이 없는 순수 Python/HTML), direct_visual_lidar_calibration 전체(git repo). fast_ws는 통째로 제외.

---

1. Jetson OS/JetPack 버전 — 제일 먼저 확인

이 PC는 Ubuntu 22.04.5 LTS (Jammy) + ROS 2 Humble(ros-humble-desktop, apt, amd64), Python 3.10.12다.

ROS2 Humble을 표준 apt 레포로 그대로 설치하려면 Jetson도 Ubuntu 22.04 기반이어야 한다 — 즉 JetPack 6.x. JetPack 5.x(Ubuntu 20.04)라면 표준 레포에 Humble이 없고 Foxy/Galactic으로 버전이 어긋난다 — 이 경우 소스 호환성부터 다시 검토해야 하는 큰 작업이 되므로, 이관 착수 전에 Jetson에 JetPack 6.x가 올라가 있는지(또는 올릴 수 있는지)부터 확인할 것. 이게 안 맞으면 나머지 항목은 다 무의미해진다.

---

2. 하드코딩된 /home/gardentech 경로

좋은 소식: camera2_ws, lidar2_ws, dvlc_ws, dvlc_gui, direct_visual_lidar_calibration, fhd_fast_tri_ws, rtk_ws, rtk 는 하드코딩된 절대경로가 하나도 없다 (dvlc_calib_gui.py는 이미 Path.home()을 씀 — 그대로 옮겨도 됨).

확인 필요한 것: scan_web의 open_scan_web.sh/run_scan_web.sh와 ~/Desktop/*.desktop 런처 5개(Exec= 줄)에 /home/gardentech가 문자 그대로 박혀있다 — Jetson 계정명이 gardentech가 아니면 깨진다. (구버전 fast_ws의 하드코딩 파일들은 이관 제외 대상이라 더 이상 고려 안 해도 됨.)

해결책 둘 중 하나:

• (권장) Jetson에도 계정명을 gardentech로 만든다 — 위 파일들을 하나도 안 고쳐도 됨, 가장 안전하고 빠름.
• 계정명을 다르게 써야 한다면, 위 파일들에서 /home/gardentech를 새 경로로 전부 치환 (grep -rl "/home/gardentech" <파일들> | xargs sed -i 's|/home/gardentech|/home/<new>|g' 식으로 하되, 치환 후 각 스크립트를 다시 열어서 확인할 것 — 자동 치환만 믿지 말 것).

---

3. Git 관련 위험 — 이 항목이 제일 중요함

dvlc_gui와 scan_web(이번 세션에서 만든 것 전부)은 git 저장소가 아예 아니다 — 버전관리 이력이 전혀 없다. 파일 복사로만 존재하는 상태라, 이관 중 실수로 덮어쓰면 되돌릴 방법이 없다. 이관 전에 최소한 git init + 첫 커밋 해두는 걸 권장 — 이관 작업 자체의 안전망도 되고, Jetson 쪽에서도 이후 변경사항을 추적할 수 있게 됨.

fhd_fast_tri_ws/src 안의 FAST-LIVO2, rpg_vikit은 git clone인데, 커밋 안 된 로컬 수정사항이 있다:

• FAST-LIVO2: 34개 파일 수정됨
• rpg_vikit: 4~5개 파일 수정됨

(참고: fast_ws/src에도 같은 이름의 FAST-LIVO2/rpg_vikit 사본이 있었지만 서로 다른 수정사항이 적용돼 있었다 — fast_ws가 이관 대상에서 빠지면서 이 혼동 자체가 사라졌다. Jetson엔 fhd_fast_tri_ws쪽 사본만 옮기면 되고, 절대 fast_ws 사본과 섞지 말 것.)

⚠️ 절대 하면 안 되는 것: Jetson에서 편하게 하려고 git clone https://github.com/.../FAST-LIVO2 를 새로 받는 것. 그러면 이 34개 파일의 로컬 수정사항이 전부 사라지고, 지금 이 PC에서 검증한 동작과 다르게 빌드됨 — 왜 안 되는지 원인 파악도 어려워짐. 반드시 rsync/tar로 파일 그대로 복사할 것.

direct_visual_lidar_calibration만 유일하게 완전히 깨끗한 git repo(106 커밋, 미커밋 변경 0) — 이건 그냥 정상적으로 clone하거나 복사해도 무방.

---

4. 빌드 순서

fast_ws가 빠지면서 예전에 있던 "lidar2_ws를 먼저 빌드해야 fast_ws가 동작한다"는 의존성 문제 자체가 없어졌다. 다만 lidar2_ws는 여전히 이관 대상이다 — scan_web과 dvlc_gui 둘 다 라이다 원시 드라이버(livox_ros_driver2) 실행을 위해 lidar2_ws를 직접 source한다 (scan_web/backend/config.py의 LIDAR2_WS_SETUP, dvlc_calib_gui.py의 ENV_SETUP).

권장 빌드 순서(의존관계상 안전한 순서, 엄격한 강제 순서는 아님): lidar2_ws → camera2_ws → dvlc_ws → fhd_fast_tri_ws → rtk_ws. 각 워크스페이스에서 build/·install/·log/ 삭제 후 Jetson에서 colcon build로 새로 빌드(x86_64 → ARM64이므로 기존 산출물은 재사용 불가).

---

5. Hikvision 카메라 SDK (/opt/MVS) — 반드시 별도 설치

hik_camera_ros2_driver는 CMakeLists.txt에서 /opt/MVS에 설치된 Hikvision MVS SDK의 MvCameraControl 라이브러리를 링크한다 (package.xml엔 안 잡히는 순수 CMake find_library라 빌드 전엔 존재조차 드러나지 않음 — 놓치기 쉬움).

이 PC의 /opt/MVS는 x86_64용 빌드다. Hikvision이 ARM64(Jetson)용 MVS SDK를 별도로 배포하니, Jetson에는 그 ARM64 버전을 따로 받아서 /opt/MVS에 설치해야 한다 — x86_64 SDK를 그대로 옮기면 카메라 드라이버가 아예 빌드조차 안 되거나, 빌드는 돼도 런타임에 심볼 로드가 실패한다. (SDK 다운로드는 Hikvision 머신비전 사이트/영업 채널에서 시리얼/모델 기준으로 받아야 함 — 이 부분은 담당자가 별도로 확인.)

---

6. Livox LiDAR 네트워크 설정

lidar2_ws/src/livox_ros_driver2/config/MID360_config.json에 고정 IP가 박혀있다:

• host_net_info(이 PC) = 192.168.1.5
• LiDAR = 192.168.1.192

인터페이스 이름이 아니라 IP만 보므로 NIC 이름이 달라도 상관없지만(Jetson이 보통 데스크탑과 다른 이더넷 인터페이스 이름을 씀 — 그건 문제 안 됨), Jetson 쪽에서 라이다와 연결되는 이더넷 포트를 정적 IP 192.168.1.5로 설정해야 하고(안 그러면 이 config를 고쳐야 함), 라이다가 여전히 192.168.1.192로 응답하는지도 실물 연결해서 확인 필요.

---

7. PyTorch / SuperGlue / CUDA — 이 PC와 정반대 상황이 됨

이 PC는 NVIDIA GPU가 전혀 없다 (nvidia-smi 자체가 없음) — 설치된 torch는 CPU 전용 빌드고 cuda.is_available()이 False다. 캘리브레이션 GUI에서 SuperGlue의 "force_cpu" 체크박스가 기본으로 켜져있는 이유가 바로 이거다 — GPU가 없어서 옵션이 아니라 필수였던 것. (requirements.txt엔 torch>=1.1.0이라고만 느슨하게 박혀있음.)

Jetson은 반대로 CUDA GPU가 있는 게 보통 쓰는 이유인데, 여기서 함정: PyPI의 일반 pip install torch는 Jetson의 aarch64+Tegra CUDA 조합을 지원하지 않는다. 그대로 설치하면 CPU 전용으로 깔리거나(이 PC와 같은 상태로 퇴화) 아예 설치가 안 된다. NVIDIA가 배포하는 Jetson 전용 PyTorch wheel(JetPack/L4T 버전에 맞는 것, Jetson Zoo 등)을 따로 설치해야 GPU를 실제로 쓸 수 있다 — 설치 방법이 데스크탑과 완전히 다르므로 별도로 검색/확인 필요. (일반적으로 고려할 사항) GPU를 제대로 물리면 SuperGlue를 TensorRT로 변환해서 쓰는 게 순수 PyTorch 추론보다 Jetson에서 훨씬 빠른 경우가 많음 — 성능이 아쉬우면 고려해볼 것.

---

8. 녹화 데이터(~/bags, ~/dvlc_data) — 옮길지 판단 필요

홈 디렉터리 전체가 89G인데, 그중 ~/bags가 68G, ~/dvlc_data가 9G로 대부분이 코드가 아니라 그동안 테스트로 찍은 실측 데이터다. Jetson으로 코드만 옮기는 거라면 이 데이터까지 통째로 옮길 필요는 보통 없다(저장공간도 아깝고) — 다만 SuperGlue 매칭 결과나 캘리브레이션 완료된 calib.json 등 앞으로도 계속 쓸 참조 데이터는 선별해서 옮기는 게 맞다. 담당자가 어떤 bag/캘리브레이션 결과를 계속 쓸지 판단해서 고를 것.

참고: 캘리브레이션 결과(calib.json의 T_lidar_camera 외부 파라미터)는 컴퓨팅 플랫폼이 아니라 물리적인 라이다-카메라 장착 형상에 종속된다 — 같은 실물 리그(카메라/라이다를 같은 위치에 같은 자세로 재장착)라면 Jetson으로 옮긴 뒤 재캘리브레이션할 필요 없이 기존 calib.json을 그대로 써도 됨.

---

9. 일반적으로 고려할 사항 (이 머신에서 직접 확인 안 한 항목 — Jetson 현장에서 재확인)

• USB/시리얼 권한: GNSS(/dev/ttyUSB0) 접근을 위한 dialout 그룹 가입, udev 규칙 등은 Jetson 쪽 사용자 계정에 다시 설정해야 함 (SCAN-운용가이드.md §1.1 참고).
• 전력/발열: Jetson 보드는 전력 예산이 데스크탑보다 빠듯함 — 라이다+카메라 3대+SLAM을 동시에 장시간 돌릴 때 스로틀링/발열 여유가 있는지 필드 조건에서 실측 확인 권장.
• 저장공간: Jetson 기본 내장 저장장치(eMMC)가 이 PC보다 훨씬 작을 수 있음 — scan_web의 디스크 여유공간 경고 임계값(backend/config.py의 DISK_LOW_WARNING_GB/DISK_LOW_DANGER_GB, 현재 10GB/2GB)이 Jetson 저장장치 크기 기준으로 여전히 적절한지 재검토.
• 연산 성능: 카메라 3대 VIO + LiDAR-Inertial 오도메트리가 Jetson에서 이 PC와 동등한 실시간 성능이 나오는지는 실측 전엔 알 수 없음 — 필요시 해상도/fps 하향, voxel filter 크기 조정 등으로 튜닝 여지를 열어둘 것.

---

10. 이관 후 검증

기본적으로 ~/scan_web/docs/운용가이드.md §4의 실기 테스트 체크리스트를 Jetson에서 그대로 한 번 더 돌리는 게 제일 확실하다. 추가로 이관 직후 특별히 확인할 것:

• 각 워크스페이스 colcon build 성공 (§4 순서 — fast_ws는 이제 없음)
• hik_camera_ros2_driver 빌드 시 /opt/MVS(ARM64판) 링크 성공 (§5)
• ros2 topic list로 /livox/lidar 등 기대 토픽이 실제로 뜨는지 (IP 설정, §6)
• SuperGlue 실행 시 torch.cuda.is_available()이 Jetson에서 True로 뜨는지 (GPU 실제 사용 여부, §7)
• ~/scan_web의 하드코딩 경로(§2)가 실제 Jetson 계정명과 맞는지
• 기존 calib.json 재사용 시 리그 형상이 실제로 동일한지 육안 확인 (§8)