Project Status · Technical Review

APEX 프로젝트 현황 종합 점검

시뮬레이터·센서·ROS2·GridMap·굴착 제어·MPC와 저장소 상태를 직접 조사하고 교차 검증한 2026-08-11 기준 종합 기록.

apex unity agx ros2 gridmap mpc project-status devlog

한 줄 결론

APEX는 시뮬레이터·센서·ROS2·GridMap 통합 기반을 갖추고 논문 기반 굴착 경로 계획을 실제 AGX 굴착까지 연결한 연구 프로토타입이다. 다만 최신 Phase B 성과가 아직 Claude 로컬 브랜치에만 있고, 작업 트리 정리·자동 회귀시험·실시간 동역학 MPC·실차 안전 계층은 남아 있다.

이 문서는 2026-08-11 기준으로 다음을 직접 조사하고 교차 검증한 결과다.

  • /home/hmlee/dev/agx_test/APEX/claude, /home/hmlee/dev/agx_test/APEX/codex Git 상태와 이력
  • docs/plan.md, handoff.md, guideline.md
  • Unity/AGX, ROS2, LiDAR/GridMap, 굴착 제어/MPC의 실제 코드 흐름
  • Unity 패키지, Python/Shell 정적 검증, ROS2 의존성
  • offline paper planner 실제 실행

관련 기록

1. 현재 상태 요약

영역 현재 판단
Unity/AGX 기본 시뮬레이션구현 및 과거 실주행 검증 완료
굴착기 제어/토양 변형AutoScoop 및 MPC multi-pass 동작 확인
LiDAR/Camera/TF/RViz통합 기준선 확보
GridMapplanner 입력 계약까지 확정
논문식 굴착 계획Phase B 진입, global planner 동작
논문 등가 local MPCvendored 코드는 있으나 live loop 미연결
ML-Agents코드 골격만 존재, 학습 미실행
HIL/CAN/실차설계만 존재, T17~T22 미착수
저장소 상태Claude 15커밋 미통합 및 대량 미커밋 변경
현재 런타임Unity/ROS2/RViz/MCP 모두 정지 상태

현재 성숙도를 가장 정확히 표현하면 다음과 같다.

센서–지도–계획–제어–토양변형을 한 번에 검증할 수 있는 강한 연구 플랫폼이지만, 아직 재현 가능한 자동 회귀시험이 갖춰진 안정적 개발 baseline이나 실차 투입 가능한 제어 시스템은 아니다.

맨 위로 ↑

2. 시스템 아키텍처

2.1 Unity/AGX 씬 구성

Assets/Editor/APEXSceneSetup.cs가 MainSimulation 씬 구성의 생성 원형이다.

  • AGX Simulation 생성: APEXSceneSetup.cs:28-30
  • SimulationManager, ConfigManager: :33-37
  • ExcavatorController 생성 및 시작 모드 ROS2 설정: :40-46
  • AutoScoopController 부착: :46
  • AGX DeformableTerrain: :112-114
  • ROS2 bridge/state publisher/command subscriber/terrain publisher/JointStatePublisher: :162-188
  • AGX SensorEnvironment: :190-195

Unity Play 시 핵심 흐름은 다음과 같다.

MainSimulation
  ├─ AGXUnity.Simulation
  ├─ TerrainManager.Awake()
  ├─ ExcavatorController.Start()
  │    └─ E85 prefab spawn 및 AGX constraint 탐색
  ├─ ROS2Bridge.Initialize()
  └─ ROS2 publisher/subscriber Initialize()

ExcavatorController는 다음 작업을 수행한다.

  1. E85 프리팹 생성
  2. E85 기본 입력 컨트롤러 비활성화
  3. cabin/boom/arm/bucket AGX constraint 자동 탐색
  4. ExcavatorState, ROS2 state publisher, joint-state publisher 연결
  5. 동적 world → base_link TF 연결
  6. IMU·압력·GPS·카메라·LiDAR 동적 부착

주요 코드 위치:

  • Assets/APEX_Excavator/Scripts/ExcavatorController.cs:56-109
  • ExcavatorController.cs:116-164
  • ExcavatorController.cs:166-220

2.2 ROS2 명령과 상태 경로

명령 경로:

외부 planner/MPC
  → apex/excavator/command
  → ExcavatorCommandSubscriber
  → ExcavatorController.SetCommand()
  → AGX constraint target speed
  → E85/terrain 물리 상태 변화

상태 경로:

AGX constraint/body 상태
  → ExcavatorState
  → apex/excavator/state
  → 외부 planner/MPC/evaluator

/joint_states는 robot_state_publisher로 들어가 URDF 관절 TF를 만들고, Unity의 실제 하부체 pose는 BaseLinkTFPublisher가 동적 world → base_link로 별도 발행한다.

2.3 외부 ROS2 bringup

Assets/apex_description/launch/apex_bringup.launch.py:17-120이 일반 ROS2 엔트리포인트다.

동시에 실행되는 구성:

  • robot_state_publisher: :34-43
  • Unity TransformStamped → /tf bridge: :48-52
  • LiDAR 좌표계 relay: :60-64
  • fused GridMap mapper: :69-73
  • overhead/reference 정적 TF: :80-101

2.4 LiDAR와 GridMap

AGX LiDAR raw PointCloud2
  → apex_lidar_rh_relay.py
  → REP-103 _rh PointCloud2
  → apex_lidar_grid_mapper.py
  → /apex/grid_map/elevation
  → RViz 또는 planner

Planner-facing GridMap 계약:

항목 값
Topic/apex/grid_map/elevation
Layerelevation
Geometry20m × 28m
Resolution0.10m
Cell200 × 280
Rate약 5Hz
Frameworld
Stale 기준1초 이상 신규 메시지 없음
Persistent map 초기화 Persistent map은 /apex/grid_map/clear로 명시적으로 초기화한다. RViz reset만으로 mapper 내부 누적 상태는 지워지지 않는다.

2.5 현재 MPC 경로

현재 공식 명칭은 다음이 정확하다.

paper-style global dig planner + speed-command tracking MPC

현재 굴착기 자세 + 목표 깊이
  → apex_mpc_paper_planner.py
  → CasADi/IPOPT 3-phase 경로 최적화
  → E85 theta↔AGX affine calibration
  → joint sequence
  → apex_mpc_controller.py
  → apex/excavator/command
  → Unity/AGX

apex_mpc_paper_dig_runner.py는 pass마다 현재 자세를 읽고 재계획·실행·평가하는 상위 오케스트레이터다.

현재 live closed loop는 다음과 같다.

state feedback → tracking MPC → AGX plant

LiDAR/GridMap은 현재 실행 후 지형 관측·평가에 주로 사용되고 있으며, 다음 단계에서 planner의 실제 ground-profile 입력으로 연결할 예정이다.

맨 위로 ↑

3. 프로젝트 단계

3.1 Phase A: 사실상 마무리 단계

확보된 통합 baseline:

  • cabin/boom LiDAR _rh 변환
  • cabin/boom RGB camera
  • 동적 world → base_link
  • LiDAR 기반 fused GridMap
  • AGX terrain/granular soil 변형
  • GridMap persistence, clear service, self-filter
  • clean restart/check 자동화
  • AutoScoop 4-cycle smoke test

Phase A의 목적은 고급 planning 성능이 아니라 다음 E2E 흐름을 검증하는 것이었다.

명령
  → AGX 굴착기 동작
  → terrain 변형
  → cabin/boom LiDAR 관측
  → ROS2/GridMap/RViz 반영
Phase A 판단 이 baseline은 이미 확보되었다.

3.2 Phase B: 이미 진입

Claude 브랜치에서 완료된 핵심 성과:

  • 외부 excavator_mpc vendoring
  • E85 기하 파라미터화
  • theta→AGX 축별 affine calibration
  • paper-style global planner
  • velocity-aligned bucket curl
  • multi-pass 재계획/실행 runner
  • swing dump 합성
  • 굴착 pit과 dump pile 분리 평가
과거 최고 3-pass 0.7452m³
2026-07-27 재실행 3-pass 0.412m³
재현 비율 기록 최고치의 약 55%

과거 최고 기록:

  • 3-pass 누적 굴착량: 0.7452m³
  • pit below -0.10m cell: 19 → 48 → 92
  • command saturation: 0
  • chassis 이동: 약 1cm

2026-07-27 재실행:

  • 3-pass 누적 굴착량: 0.412m³
  • 기록 최고치의 약 55%
  • pass 1/2가 얕음
  • crest berm 누적과 run-to-run 편차 재현
현재 해석 알고리즘은 한 번 성공한 데모 수준은 넘어섰지만, 동일 조건에서 일관된 굴착 품질을 보장하는 단계는 아직 아니다.
맨 위로 ↑

4. 논문 반영 수준

구현됐다고 말할 수 있는 범위

  • 논문 §3.3의 global planning 구조
  • Phase 1 접근, Phase 2 굴착 최적화, Phase 3 인양/이동
  • 제약 하 굴착 궤적 생성
  • E85 실측 calibration을 통한 live joint sequence 변환
  • speed-command tracking MPC

아직 아닌 것

논문 §3.4의 다음 항목은 vendored 코드로만 존재하거나 미연결 상태다.

  • force limit
  • pump power limit
  • pump flow limit
  • 실린더 displacement 기반 동역학 MPC
  • momentum 기반 disturbance estimator
  • feedback linearization
  • DDP + augmented Lagrangian solver
명칭상 주의 현재 구현을 paper-equivalent dynamics MPC라고 부르면 안 된다. 현재 tracking layer는 paper-inspired constrained kinematic MPC에 가깝다.

이 구분은 [[260504_APEX 논문 등가 MPC 설계 검토]]의 초기 판단에서 상당 부분 진전됐지만 여전히 유효하다. 당시에는 global planner 자체가 미구현이었고, 현재는 global planning 계층이 실제 라이브 굴착에 연결된 상태라는 점이 가장 큰 변화다.

맨 위로 ↑

5. 직접 수행한 검증

5.1 Offline paper planner 실행

현재 코드로 apex_mpc_paper_planner.py를 직접 실행했다.

항목 결과
exit code0
solverSolve_Succeeded
acceptedtrue
solve time0.595초
excavation volume proxy0.218144m²
worst gated margin+0.09855
검증 결과 Global planner는 문서상 존재하는 스텁이 아니라 현재 환경에서도 실제 solve된다.

5.2 정적 검증

통과 항목:

  • Unity manifest/lock JSON 파싱
  • 직접 의존성 50개의 manifest/lock 버전 일치
  • Python 전체 스크립트 AST 파싱
  • Shell script bash -n
  • ROS2 Python 의존성/import
  • ROS2 launch 구조 생성
  • AGX ROS2 네이티브 라이브러리 링크
  • git diff --check
  • 기존 Unity Assembly-CSharp.dll, Assembly-CSharp-Editor.dll 존재

설치 상태:

Unity6000.1.6f1, revision d64b1a599cad
Unity MCP0.86.3
Input System1.14.0
ML-Agents2.0.1
URP17.1.0
Unity Test Framework1.5.1

5.3 현재 미검증 항목

2026-08-11 조사 시 다음 프로세스는 모두 정지 상태였다.

  • Unity
  • MCP server
  • ROS2 bringup
  • RViz
  • MPC controller

따라서 다음은 이번 조사에서 live로 재검증하지 않았다.

  • Unity Play 진입
  • ROS2 topic rate
  • TF 수신
  • LiDAR/GridMap 실시간 갱신
  • AutoScoop/MPC 실제 굴착
  • Unity batch smoke
  • Unity Test Framework

정적 구조와 offline planner는 통과했지만 현재 live 통합 상태는 미검증이다.

마지막 라이브 근거는 2026-07-30 handoff 기록이다.

관측 항목 마지막 기록
cabin LiDAR37.9Hz
boom LiDAR41.2Hz
GridMap5.0Hz
joint states50.0Hz
TF수신
Console Exception/Error0
terrain baseline정상
맨 위로 ↑

6. Git과 worktree 상태

6.1 브랜치 관계

baseline/2026-07-03 = d24d7a3
codex/r1            = d24d7a3
claude/r1           = d21ffa3
  • claude/r1은 baseline보다 15커밋 앞
  • codex/r1은 baseline과 동일
  • Codex 고유 커밋 0
  • Claude의 Phase B 성과는 baseline/Codex/main에 미통합
  • 원격 fetch는 수행하지 않았으므로 원격 관계는 로컬 remote-tracking ref 기준

현재 실질적인 최신 개발선은 claude/r1이며 이중 worktree 경쟁/병렬 운용은 멈춰 있다.

6.2 작업 트리 상태

Claude worktree:

수정    66
삭제   126
미추적 100
총 상태 항목 292

실제 diff 기준:

  • 192개 파일 변경
  • 약 +1700/-2051

주요 변경 그룹:

  • Assets/Plugins/NuGet/: 211개
  • .claude/skills/: 76개
  • Packages/manifest.json, packages-lock.json
  • handoff.md, guideline.md
  • mono_crash.mem.*

Unity MCP가 커밋 기준 0.66.1에서 현재 0.86.3으로 올라가면서 NuGet DLL 배치와 generated skill 구조가 대량 변경됐다.

커밋 위험 핵심 APEX 애플리케이션 소스에는 현재 미커밋 변경이 거의 없지만, 이 상태에서 전체 add/commit을 하면 생성물·DLL·크래시 덤프가 함께 들어갈 위험이 크다.

Codex worktree도 같은 계열의 MCP/NuGet 변경으로 오염돼 있다.

맨 위로 ↑

7. 품질과 기술 부채

7.1 자동 테스트 부족

Unity Test Framework는 설치돼 있지만 프로젝트 자체 NUnit/UnityTest는 발견되지 않았다.

현재 테스트 자산:

  • 정적 LiDAR test component
  • Assets/Editor/APEXBatchTest.cs
  • 수동/스크립트 기반 E2E 평가
  • handoff에 기록된 일회성 수치 테스트

APEXBatchTest는 씬 객체 존재 여부를 확인하는 smoke 수준이다.

  • 실제 물리 동작을 충분히 검증하지 않음
  • 모든 component 실패를 종료 코드에 반영하지 않음
  • 정상 완료 시 명시적 EditorApplication.Exit(0) 없음

현재 품질 보증은 자동 test suite보다 handoff 기반 실험 절차와 수치 로그에 크게 의존한다.

7.2 문서 불일치

확인된 문서 부채:

  1. docs/plan.md는 HDRP라고 쓰지만 실제 manifest는 URP 17.1.0이다.
  2. docs/plan.md 센서 토픽 표는 초기 generic 토픽이며 실제 cabin/boom _rh 토픽과 다르다.
  3. Claude worktree의 AGENTS.md 제목과 일부 실행 지침이 Codex worktree 기준이다.
  4. plan.md의 5월 Phase 설명과 7월 Phase B 추가 내용이 혼재한다.
  5. 7월 30일 최신 handoff/guideline 변경이 아직 미커밋이다.

7.3 운영상 리스크

  • Play 중 domain reload 시 AGX native 객체 파괴 및 NRE 폭주 가능
  • Terrain asset은 디스크가 clean이어도 Unity cache가 오염될 수 있음
  • Unity MCP 자동 업그레이드가 dependency/layout을 대규모 변경
  • bucket calibration sweep 범위가 실제 사용 범위보다 좁음
  • GridMap outlier gate의 live on/off A/B 미검증
  • 고정 ground profile이 매 run 지형 편차를 계획에 반영하지 못함
  • 실차 safety/deadman/E-stop 계약 미정
  • Python NumPy/SciPy 지원 범위 경고 존재
  • AGX FastDDS와 ROS Humble FastDDS의 ABI 민감성
  • ROS2Domain.Id가 sbyte라 128 이상 domain 처리에 취약
  • MCP server가 authorization=none으로 실행됨

7.4 라이선스

다음 실행 전 확인 필요 Assets/agx.lfx는 존재하며 마지막 수정 시각은 2026-07-27이다. 기존 기록에는 라이선스가 8월 10일 전후까지라고 적힌 사례가 있으므로 다음 Unity 실행 전에 현재 유효성을 다시 확인해야 한다.
맨 위로 ↑

8. 다음 우선순위

0순위: 저장소 안정화

새 기능 전에 먼저 처리해야 한다.

  1. Unity MCP 0.86.3 유지/rollback 결정
  2. NuGet DLL의 새 flat layout에서 실제 추적 대상 결정
  3. .claude/skills 자동 생성물을 커밋할지 ignore할지 결정
  4. mono_crash.mem.* 제거 및 ignore
  5. handoff/guideline 변경을 별도 문서 커밋
  6. Claude의 15커밋을 새 baseline으로 승격
  7. 최신 브랜치를 원격에 백업

현재 가장 큰 리스크는 알고리즘보다 검증된 Phase B 성과가 로컬 브랜치에만 있고 작업 트리가 generated 변경으로 오염된 상태라는 점이다.

1순위: GridMap 기반 실지형 재계획

현재 가장 중요한 알고리즘 작업이다.

  1. fused GridMap에서 굴착 평면 주변 cell 추출
  2. percentile clipping 등 robust outlier 제거
  3. 1~2차 지표면 다항식 fit
  4. fit residual과 사용 cell 수 기록
  5. pass마다 실제 지형으로 재계획
  6. pit 체적을 GridMap에서 직접 산출

이 작업이 2026-07-27에 재현된 run-to-run 편차와 crest berm 누적 문제를 해결할 가능성이 가장 크다.

2순위: 캘리브레이션과 자동 회귀시험

  • bucket 축을 물리 stop 근방까지 확장 sweep
  • calibration residual 자동 검증
  • offline planner acceptance test
  • GridMap outlier gate 단위/live A/B
  • clean restart + rate check
  • 1-pass/3-pass 정량 regression 자동화
  • Unity batch smoke를 명확한 exit code 기반으로 보강

3순위: 논문 등가 local MPC

그 다음 연결할 항목:

  • HydraulicPlant
  • 힘/유량/펌프 제약
  • 외란 추정
  • local dynamics MPC
  • swing ψ를 planner state로 승격

ML-Agents, HUD, Recording, HIL/CAN은 위 인터페이스가 안정된 뒤 재개하는 것이 적절하다.

맨 위로 ↑

9. 최종 판단

강점

  • 좌표계·TF·센서·토양·GridMap·planner의 어려운 통합 문제를 실제 실행으로 상당 부분 해결했다.
  • 실패 원인과 복구 절차가 handoff.md, guideline.md에 자세히 축적돼 있다.
  • Phase B global planner는 스텁이 아니라 현재 환경에서도 실제 solve된다.
  • AutoScoop과 MPC 모두 AGX terrain 변형 및 GridMap 관측까지 연결돼 있다.

약점

  • 성공한 실험이 자동 회귀시험과 clean baseline으로 굳어지지 않았다.
  • 최신 성과가 claude/r1 로컬 15커밋에만 존재한다.
  • 작업 트리가 대량의 MCP/NuGet generated 변경으로 오염돼 있다.
  • 실시간 제어는 아직 force/power/flow 기반 논문 등가 dynamics MPC가 아니다.
  • 실차 안전 계층과 HIL/CAN 구현이 미착수다.

권장 진행 순서

저장소 정리
  → 최신 baseline 통합·원격 백업
  → clean live smoke 재검증
  → GridMap surface fit 기반 pass별 재계획
  → 자동 회귀시험
  → HydraulicPlant 및 dynamics MPC

현재는 기능을 더 넓히기보다 이미 검증한 성과를 정리하고 재현 가능한 baseline으로 굳히는 것이 프로젝트 전체 성공 가능성을 가장 크게 높인다.

맨 위로 ↑