ENIG/Cs_HMI/AGVLogic/PROJECT_SUMMARY.md

프로젝트 요약 (AGVMapEditor, AGVNavigationCore, AGVSimulator)

📊 프로젝트 개요

3개의 주요 프로젝트가 AGVNavigationCore 라이브러리를 공유하며 연동되는 구조입니다.

┌─────────────────────────────────────────────────────────────┐
│              AGVNavigationCore (공유 라이브러리)              │
├─────────────────────────────────────────────────────────────┤
│  • Models: MapNode, MapLoader, Enums, IMovableAGV, VirtualAGV
│  • Controls: UnifiedAGVCanvas (통합 UI 렌더링)
│  • PathFinding: A*, AGVPathfinder, DirectionChangePlanner
└─────────────────────────────────────────────────────────────┘
     ▲                    ▲                        ▲
     │ 참조                │ 참조                    │ 참조
     │                    │                        │
  ┌──────────────┐   ┌──────────────┐   ┌──────────────┐
  │ AGVMapEditor │   │ AGVSimulator  │   │  AGV4 (미사용)
  │ (맵 편집)    │   │ (시뮬레이션) │   │  (메인앱)
  └──────────────┘   └──────────────┘   └──────────────┘

---

🎯 각 프로젝트의 기능

1️⃣ AGVMapEditor (맵 편집 도구)

목적: AGV 맵 데이터를 시각적으로 생성/편집

제공 기능

기능	설명
노드 생성	맵 상에 AGV 네비게이션 노드 추가
노드 편집	노드 이름, RFID, 타입, 도킹방향 설정
노드 이동	드래그로 노드 위치 변경 (그리드 스냅 지원)
연결 관리	노드 간 경로 연결 생성/삭제
노드 삭제	선택된 노드 제거
라벨 추가	맵에 텍스트 라벨 추가
이미지 추가	맵에 배경 이미지 추가
맵 저장/로드	JSON 형식 맵 파일 저장/로드

기술 구성

MainForm (WinForms)
└─ UnifiedAGVCanvas (UI 렌더링)
   ├─ MapNode 목록 관리
   ├─ 편집 모드 (Select, Move, AddNode, Connect, Delete, DeleteConnection, AddLabel, AddImage)
   └─ MapLoader 사용 (JSON 저장/로드)

주요 UI 요소

• 메뉴바: File (Open/Save), Edit, View
• 툴바: 편집 모드 전환 버튼 (선택, 이동, 노드추가, 연결, 삭제, 라벨, 이미지)
• 속성 패널: 선택된 노드 정보 표시/편집
• 캔버스: 맵 시각화 및 편집

---

2️⃣ AGVNavigationCore (경로 계산 엔진 라이브러리)

목적: AGV 경로 계산 및 네비게이션 핵심 로직 제공

제공 기능

영역	모듈	기능
Models	MapNode	AGV 네비게이션 노드 데이터
	MapLoader	맵 파일 로드/저장
	IMovableAGV	AGV 동작 인터페이스
	VirtualAGV	가상 AGV 시뮬레이션 로직 ⚠️ 미완성
Controls	UnifiedAGVCanvas	맵 렌더링/편집/모니터링 UI
PathFinding	AStarPathfinder	기본 A* 경로 탐색
	AGVPathfinder	AGV 제약 고려 경로 계산 ⚠️ 미완성
	DirectionChangePlanner	방향 전환 경로 계획 ⚠️ 미완성

핵심 기능 (구현 상태)

✅ 완성
├─ MapNode 데이터 모델
├─ MapLoader (파일 I/O)
├─ UnifiedAGVCanvas (UI 렌더링/편집)
└─ AStarPathfinder (기본 경로 탐색)

❌ 미완성 (개발 대상)
├─ VirtualAGV.ExecutePath()  - 경로 실행
├─ VirtualAGV.Update()       - 프레임 업데이트
├─ AGVPathfinder 핵심 로직   - 경로 상세화, 마그넷 방향 계산
└─ DirectionChangePlanner    - 4단계 방향 전환 알고리즘

기술 구성

AGVNavigationCore (Class Library)
├── Models/
│   ├── MapNode.cs
│   ├── MapLoader.cs
│   ├── VirtualAGV.cs (← 경로 추적 미완성)
│   ├── IMovableAGV.cs
│   └── Enums.cs
├── Controls/
│   ├── UnifiedAGVCanvas.cs (메인 UI)
│   ├── UnifiedAGVCanvas.Designer.cs
│   ├── UnifiedAGVCanvas.Events.cs
│   ├── UnifiedAGVCanvas.Mouse.cs (← 줌 기능)
│   ├── UnifiedAGVCanvas.Rendering.cs
│   └── UnifiedAGVCanvas.Utilities.cs
├── PathFinding/
│   ├── Core/
│   │   ├── AStarPathfinder.cs ✅
│   │   ├── PathNode.cs
│   │   └── AGVPathResult.cs
│   ├── Planning/
│   │   ├── AGVPathfinder.cs (❌ 미완성)
│   │   ├── DirectionChangePlanner.cs (❌ 미완성)
│   │   └── NodeMotorInfo.cs
│   ├── Analysis/
│   │   └── JunctionAnalyzer.cs
│   └── Validation/
│       ├── PathValidationResult.cs
│       └── DockingValidationResult.cs
└── Utils/
    └── LiftCalculator.cs

---

3️⃣ AGVSimulator (AGV 시뮬레이터)

목적: AGV 경로 계산 및 동작을 시각적으로 검증

제공 기능

기능	설명
맵 로드	저장된 맵 파일 로드
AGV 시뮬레이션	가상 AGV 생성 및 경로 따라 이동
경로 계산	시작점/목적지 선택 후 경로 자동 계산
경로 시각화	계산된 경로 맵에 표시
실시간 상태 모니터링	AGV 위치, 방향, 상태 실시간 표시
도킹 검증	AGV 도킹 방향 검증

기술 구성

SimulatorForm (WinForms)
├─ UnifiedAGVCanvas (맵 렌더링)
├─ VirtualAGV 리스트 (가상 AGV들)
├─ MapLoader (맵 파일 로드)
├─ AGVPathfinder (경로 계산)
└─ 시뮬레이션 타이머 (매 프레임 AGV 업데이트)

주요 UI 요소

• 메뉴바: File (Open Map)
• 경로 제어 그룹: 시작RFID, 목적지RFID, 타겟계산 버튼
• 시뮬레이션 제어: 시작, 일시정지, 정지 버튼
• 캔버스: 맵 + AGV + 경로 시각화

---

🎨 UnifiedAGVCanvas (통합 UI 컨트롤)

위치: AGVNavigationCore/Controls/UnifiedAGVCanvas.cs (4개 파일)

핵심 기능

기능	설명
맵 렌더링	노드, 연결선, 그리드, AGV, 경로 표시
편집 기능	노드 추가/이동/삭제, 연결 관리 (AGVMapEditor)
모니터링	실시간 AGV 상태 표시 (AGVSimulator)
줌/팬	마우스 휠 줌, 좌클릭 드래그 팬
선택/호버	노드 선택, 호버 표시
경로 시각화	계산된 경로를 색상으로 표시

모드 및 상태

// CanvasMode
Edit  // 편집 모드 (맵 에디터)

// EditMode (Edit 모드에서만 적용)
Select              // 노드 선택
Move                // 노드 이동
AddNode             // 노드 추가
Connect             // 연결 생성
Delete              // 노드/연결 삭제
DeleteConnection    // 연결 삭제
AddLabel            // 라벨 추가
AddImage            // 이미지 추가

---

🖱️ 줌/팬 기능 (현재 상태)

현재 구현

// UnifiedAGVCanvas.Mouse.cs : 171-188

private void UnifiedAGVCanvas_MouseWheel(object sender, MouseEventArgs e)
{
    // 줌 처리
    var mouseWorldPoint = ScreenToWorld(e.Location);
    var oldZoom = _zoomFactor;

    if (e.Delta > 0)
        _zoomFactor = Math.Min(_zoomFactor * 1.2f, 5.0f);  // 확대 (1.2배)
    else
        _zoomFactor = Math.Max(_zoomFactor / 1.2f, 0.1f);  // 축소 (1.2배)

    // 마우스 위치를 중심으로 줌
    var zoomRatio = _zoomFactor / oldZoom;
    _panOffset.X = (int)(e.X - (e.X - _panOffset.X) * zoomRatio);
    _panOffset.Y = (int)(e.Y - (e.Y - _panOffset.Y) * zoomRatio);

    Invalidate();
}

문제점 및 개선 사항

⚠️ 현재 문제

1. 줌 계산 로직: 수식이 복잡하고 정확하지 않을 수 있음
2. 좌표계 혼동: 스크린 좌표와 월드 좌표 변환이 일관성 없음
3. 매끄러움: 줌 비율 계산에서 부자연스러운 동작 가능

✅ 개선 방안

마우스 커서 위치를 기준점으로 하는 스무스한 줌을 구현:

private void UnifiedAGVCanvas_MouseWheel(object sender, MouseEventArgs e)
{
    // 현재 마우스 위치를 월드 좌표로 변환
    var mouseWorldBefore = ScreenToWorld(e.Location);

    float oldZoom = _zoomFactor;

    // 줌 팩터 계산 (휠 델타 기반)
    if (e.Delta > 0)
        _zoomFactor = Math.Min(_zoomFactor * 1.15f, 5.0f);   // 확대 (부드러움)
    else
        _zoomFactor = Math.Max(_zoomFactor / 1.15f, 0.1f);   // 축소 (부드러움)

    // 마우스 위치가 같은 월드 좌표를 가리키도록 팬 오프셋 조정
    var mouseWorldAfter = ScreenToWorld(e.Location);

    _panOffset.X += (int)((mouseWorldBefore.X - mouseWorldAfter.X) * _zoomFactor);
    _panOffset.Y += (int)((mouseWorldBefore.Y - mouseWorldAfter.Y) * _zoomFactor);

    Invalidate();
}

주요 개선점

1. 더 부드러운 줌: 1.2배 → 1.15배로 조정
2. 명확한 로직: 마우스 위치 기준으로 명시적으로 계산
3. 정확한 좌표 변환: ScreenToWorld() 사용으로 일관성 보장
4. 자연스러운 동작: 마우스 아래의 점이 같은 위치를 가리킴

---

📂 파일 구조 (48개 C# 파일)

AGVMapEditor (10개 파일)

AGVMapEditor/
├── Forms/
│   ├── MainForm.cs              (메인 폼, 편집 로직)
│   └── MainForm.Designer.cs     (UI 디자인)
├── Models/
│   ├── EditorSettings.cs        (에디터 설정)
│   ├── MapImage.cs              (맵 이미지 데이터)
│   ├── MapLabel.cs              (맵 라벨 데이터)
│   └── NodePropertyWrapper.cs   (노드 속성 래퍼)
├── Program.cs                    (진입점)
└── Properties/
    └── AssemblyInfo.cs          (어셈블리 정보)

AGVNavigationCore (30개 파일)

AGVNavigationCore/
├── Models/ (8개)
│   ├── MapNode.cs, MapLoader.cs, VirtualAGV.cs, IMovableAGV.cs, etc.
├── Controls/ (6개)
│   ├── UnifiedAGVCanvas.cs, UnifiedAGVCanvas.Designer.cs, etc.
├── PathFinding/ (13개)
│   ├── Core/ (AStarPathfinder, PathNode, AGVPathResult)
│   ├── Planning/ (AGVPathfinder, DirectionChangePlanner, etc.)
│   ├── Analysis/ (JunctionAnalyzer)
│   └── Validation/ (PathValidationResult, DockingValidationResult)
└── Utils/ (3개)
    ├── LiftCalculator.cs, DockingValidator.cs, etc.

AGVSimulator (8개 파일)

AGVSimulator/
├── Forms/
│   ├── SimulatorForm.cs         (시뮬레이터 메인 폼)
│   └── SimulatorForm.Designer.cs
├── Models/
│   └── (VirtualAGV는 AGVNavigationCore에서 참조)
├── Program.cs
└── Properties/
    └── AssemblyInfo.cs

---

🔄 데이터 흐름

맵 편집 → 저장 흐름

AGVMapEditor.MainForm
  ↓
UnifiedAGVCanvas (편집 모드)
  ↓
MapLoader.SaveMapToFile()
  ↓
NewMap.agvmap (JSON 파일)

맵 로드 → 시뮬레이션 흐름

NewMap.agvmap (JSON 파일)
  ↓
MapLoader.LoadMapFromFile()
  ↓
AGVSimulator.SimulatorForm
  ↓
UnifiedAGVCanvas (모니터링 모드)
  ↓
VirtualAGV (경로 실행) ⚠️ 미완성

---

⚠️ 현재 미완성 부분

🔴 우선순위 높음

1. VirtualAGV.ExecutePath() - 경로 실행 로직
2. VirtualAGV.Update() - 매 프레임 위치 업데이트
3. AGVPathfinder 핵심 - 경로 상세화, 마그넷 방향 계산

🟡 우선순위 중간

4. DirectionChangePlanner - 4단계 방향 전환 알고리즘
5. UnifiedAGVCanvas 줌 개선 - 마우스 기준 스무스 줌

---

📝 참고 문서

• CLAUDE.md - 개발 가이드 및 AGV 하드웨어 설명
• CHANGELOG.md - 변경 로그
• Data/NewMap.agvmap - 실제 맵 데이터 샘플