eomsangdon/Aislo
1
0
Fork 0
Code Issues Pull Requests 2 Actions Packages Projects Releases Wiki Activity
Files
ccd1ec2a50a3101ac82c185eb3e4c7a00e3d3bd9
Aislo/docs/wiki/pages/B04_PreProcess/B04_frontend.md
T
eomsangdonandClaude Opus 5 eb30b774f8 chore(docs): docs 폴더 git 추적 전환 · PLAN·OWNERS 최상위 이관 
- `docs/` 를 .gitignore 에서 빼 git 추적 대상으로 전환 (위키·완료 이력·검증 기록)
- `docs/raw/PLAN.md` · `docs/raw/OWNERS.md` 를 저장소 최상위로 이동 후 .gitignore 에 등록
  — 창끼리 공유하되 저장소에는 안 올리는 장부
- 살아 있는 경로 참조 7개 파일 정정 (아카이브 107건은 그때 사실이라 그대로 둠)
- graphify 날짜별 산출물(`docs/wiki/graphify-out/20*/`) 제외 — `graphify update` 가 다시 만듦

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-09-09 18:19:07 +09:00

88 lines
9.0 KiB
Markdown
Raw Blame History

---
status: stable
page_id: B04_PreProcess
related_pages: ["[[B04_PreProcess/B04_backend]]", "[[B04_PreProcess/B04_api]]", "[[B04_PreProcess/B04_dependencies]]", "[[las_free_sheet_surface]]", "[[ui_templates]]", "[[concepts/drainage_watershed]]", "[[architecture/project_map]]", "[[architecture/workflow_data_flow]]"]
last_updated: 2026-08-30
source: ["docs/raw/verification/2026-07-19_verify_b04_gis_theme.md", "docs/raw/verification/2026-07-26_verify_도엽_오버레이.md", "docs/raw/verification/2026-07-28_verify_B04_Map_Performance.md", "docs/raw/verification/2026-08-01_verify_B04_B05_drainage_ui_improvements.md", "docs/raw/verification/2026-08-02_verify_B04_B05_drainage_unification.md", "docs/raw/verification/2026-07-17_verify_B04_contour.md", "docs/raw/verification/2026-07-17_verify_B04_Surface_Reorganization.md", "docs/raw/verification/2026-07-18_verify_b04_confirm_b05_rebuild.md"]
---
# B04_PreProcess — Frontend
WF1 지표면 분석 화면. **엔지니어링 레이아웃(상단 헤더 제거, 전체 화면 폭, 좌측 상세 옵션 패널 + 우측 메인 3D 뷰어 2열 배치(포인트클라우드 & 5종 지표면 모델 비교) + 양방향 카메라 동기화)** 및 하단 2D 배경 지도 인터페이스.
LAS 유무와 별개로 도엽등고 3D 서피스를 별도 컨테이너에서 비교하며, 6개 보간 방식과 확정 계약은 [[las_free_sheet_surface]]에서 관리한다.
## 파일 구조
| 파일 | 위치 | 역할 |
|---|---|---|
| `B04_PreProcess_UI_Page.ts` | `B04_PreProcess_UI_Page.ts:1-378` | 페이지 조립(`createWorkflowLayout` 사용) + 2열 뷰어 및 옵션 통합 제어, 모델 확정(Confirm) 및 초기화 |
| `B04_PreProcess_UI_Viewer.ts` | `B04_PreProcess_UI_Viewer.ts:1-346` | 포인트클라우드 3D 뷰어(three.js) 및 카메라 상태 브로드캐스트 |
| `B04_PreProcess_UI_TerrainViewer.ts` | `B04_PreProcess_UI_TerrainViewer.ts:1-647` | 지형 메시 3D 뷰어(three.js) 및 카메라 상태 동기화 수신, 표시 옵션 제공 |
| `B04_PreProcess_UI_Camera.ts` | `B04_PreProcess_UI_Camera.ts:1-43` | 3D 뷰어 공통 카메라 동기화, 축척 계산, 뷰 피팅 등 유틸리티 정의 |
| `B04_PreProcess_UI_MapViewer.ts` | `B04_PreProcess_UI_MapViewer.ts:1-423` | 하단 2D 지도 UI 및 이벤트 제어 (마우스 커서 줌 중심, 휠 드래그 브라우저 기본 간섭 차단, rAF 스로틀 렌더링 요청) |
| `B04_PreProcess_UI_MapRender.ts` | `B04_PreProcess_UI_MapRender.ts:1-359` | **[신설]** 하단 2D 지도 Canvas 렌더링 전용 엔진 (GeoJSON 0~1 정규화 사전 투영, 프레임당 1회 어파인 계수 재사용, bbox 뷰포트 컬링, Douglas-Peucker 오차 0.75px 연속 LOD 렌더링) |
| `B04_PreProcess_UI_MapOverlays.ts` | `B04_PreProcess_UI_MapOverlays.ts` | **[신설/2026-08-02]** 지도 위 오버레이 기하 도형(`drawFilledRing`, `drawRingBadge`, `drawUpstreamLines` 등) 렌더러 분리 모듈 (149줄, 700줄 제약 준수). |
| `B04_PreProcess_UI_Basins.ts` | `B04_PreProcess_UI_Basins.ts` | **[신설/2026-08-01]** 관 매설 지점 편집(스냅, 드래그, 추가/삭제, 우클릭 컨텍스트) 및 세부유역 분할 렌더러/이벤트 핸들러. (559줄) |
| `B04_PreProcess_UI_FlowRamp.ts` | `B04_PreProcess_UI_FlowRamp.ts` | **[신설/2026-08-01]** 도로 유입 흐름 강도 램프(FlowRamp) 공용 렌더링 및 범례(`createFlowLegend`) 렌더링 컴포넌트. |
| `B04_PreProcess_UI_FlowStrength.ts` | `B04_PreProcess_UI_FlowStrength.ts` | **[신설/2026-08-01]** 계획노선 1m 레인보우 흐름 강도 오버레이 및 유입 집중점 클릭 렌더러. |
| `B04_PreProcess_Api_Fetch.ts` | `B04_PreProcess_Api_Fetch.ts:1-224` | surface API 클라이언트 (지면 필터 쿼리 파라미터 연동, geojson layer 엔드포인트 연동) |
| `B04_PreProcess_UI_Style.css` | `B04_PreProcess_UI_Style.css` | 폼 그룹/모델 카드/2열 뷰어/2D 지도/관 매설 및 세부유역 관련 스타일 |
## ⚠️ 계획서와 실 코드 불일치 (3D 뷰어)
이전 wiki(계획서 기반)는 **"WebCAD 3D 뷰어 미구현"**으로 기재했으나,
실 코드에는 three.js(WebGL) 기반 뷰어가 **구현되어 있음**:
- `createSurfacePointCloudViewer` (`B04_PreProcess_UI_Viewer.ts:187` WebGLRenderer, OrbitControls, THREE.Points)
- `createSurfaceTerrainViewer` (`B04_PreProcess_UI_TerrainViewer.ts`)
- UI_Page에서 import·인스턴스화(`B04_PreProcess_UI_Page.ts:37,38,110,356`)
→ 규칙6, 실 코드 채택. dependencies도 three.js 반영 → [[B04_PreProcess/B04_dependencies]]
## 3D 뷰어 DOM 마운트 버그 수리
* **증상**: 3D 뷰어가 생성된 직후 DOM에 완전히 연결(`isConnected`)되기 전에 애니메이션 루프의 프레임이 실행되면서, 파괴 프로세스(`cancelAnimationFrame` 및 `dispose`)가 오동작하여 뷰어가 화면에서 영구적으로 사라지는 문제가 보고됨.
* **조치**: `hasConnected` 플래그를 신설하여 DOM에 1회 이상 정상적으로 마운트된 이후에만 `isConnected` 해제 시 소멸 로직이 격발하도록 뷰어 수명 주기를 제어하여 오류를 정상 복구함 (`B04_PreProcess_UI_Viewer.ts`, `_TerrainViewer.ts`).
## 3D 뷰어 테마 연동 및 가독성 개선
* **3D 뷰어 테마 연동**: `B04_PreProcess_UI_Camera.ts`에 추상화된 `bindSurfaceViewerTheme` 공통 유틸을 신설하여 뷰어(`Viewer.ts`, `TerrainViewer.ts`)가 개별적으로 테마 감지를 구현하지 않고 통일된 방식으로 배경 갱신을 동기화함. 다크 모드 시 `--color-surface-raised` 값을 computed style로 조회하여 Three.js `scene.background`에 적용하며, 로딩 전 상태에 대비해 안전한 다크 폴백(`0x251f38`)을 채택. `dispose` 시 MutationObserver 및 이벤트 리스너 리소스를 완벽히 제거함.
* **척도 가독성 확보**: `B04_PreProcess_UI_Style.css`에서 기존 하드코딩된 `--color-text` 계열 변수를 CSS 표준 토큰인 `--color-text-body`로 통합 매핑하고, 다크 모드 배경 및 복잡한 지형 메시 위에서 척도 식별이 수월하도록 `filter: drop-shadow(...)` 및 `text-shadow: 0 1px 2px var(--color-surface-raised)` 스타일 처리를 추가해 가독성을 확보함.
## 컴포넌트 & API 함수
| 함수 / API | 위치 | 역할 / 대응 API |
|---|---|---|
| `renderB04Surface()` | `_UI_Page.ts:95` | 페이지 조립 및 뷰어 로드 |
| `createSurfacePointCloudViewer()` | `_UI_Viewer.ts:187` | 포인트클라우드 three.js 뷰어 생성 |
| `createSurfaceTerrainViewer()` | `_UI_TerrainViewer.ts` | 지형 메시 three.js 뷰어 생성 |
| `createSurfaceMapViewer()` | `_UI_MapViewer.ts:44` | 2D 위성/지적 배경지도 뷰어 생성 |
| `initDrainageBasinsUI()` | `_UI_Basins.ts` | 관 매설 드래그/스냅/편집 및 세부유역 렌더링 |
| `confirmSurfaceModel()` | `_Api_Fetch.ts:139` | `POST /surface/confirm` (모델 확정) |
| `fetchDetailPipePoints()` | `_Api_Fetch.ts` | `GET /drainage/pipe-points` (관/세부유역 조회) |
| `computeDetailBasins()` | `_Api_Fetch.ts` | `POST /drainage/detail-basins` (유역분할 계산) |
| `saveDetailPipePoints()` | `_Api_Fetch.ts` | `PUT /drainage/pipe-points` (관/세부유역 확정) |
| `deleteDetailPipePoints()` | `_Api_Fetch.ts` | `DELETE /drainage/pipe-points` (관/세부유역 삭제) |
## 처리 흐름
1. 레이아웃 조립 후 프로젝트의 15개 지표면 모델 목록 및 입력파일 로드.
2. 좌측 패널에서 LAS 파일, 지면 필터, 표현 방식(dtm 등) 선택 및 3D 뷰어에 50만 샘플 렌더링.
3. 2열 뷰어 간 양방향 카메라 동기화(Orbit Target, Distance)로 시점 정합.
4. 모델 확정 시 ID를 백엔드로 보내 stage 1 확정하고 WF2 진입 권한 획득.
5. 초기화 시 입력값을 복원하고 `DELETE /drainage/pipe-points`로 관 매설 정보 물리 삭제.
6. 하단 2D 지도에서 6종 도엽 레이어(하천, 옹벽 등)를 위성사진 위에 탑뷰 정사 정합 렌더링.
## 3D 카메라 커서 피봇 & 2D 오버레이 UI 개선 (2026-08-01~02 일원화)
* **커서 피봇**: pointerdown 지점을 회전 축으로 삼고 줌 시 커서 지점 고정 dolly 처리.
* **조작 보정**: PAN(가운데 버튼 할당), 수직 회전 부호 반전, 뷰셋 버튼 그룹 좌상단 이동.
* **SSOT 일원화**: B05 사본 폴더를 폐지하고 B04의 `drainage/` 정본 경로로 연동 일원화.
* **2D 휠 줌 반전**: 당기면 확대, 밀면 축소로 줌 방향 통일.
* **가독성**: 2D 지도 우측 흐름램프 게이지 범례 신설, 2D 배관 라벨 흰 테두리 헤일로 입힘.
* **성능 최적화**: 등고선 LineSegments 2개로 드로우콜 병합, ETag/304 HTTP 및 IndexedDB asset 캐시 적용.
* **흐름 강도 분석**: 1m 간격 계획선 색상 오버레이 렌더링, 집중점 클릭 시 기여 셀 외곽선 실선 하이라이트.
## 의존성
- [[a00_app_shell_framework]] — `navigateTo`, `workflowSteps`
- `config_frontend.ts` — `API_BASE_URL`, `CURRENT_PROJECT_ID_KEY`, `ROUTES`
- [[ui_templates]] — `createWorkflowLayout`, `createProgressCircle`
- **three.js** (WebGL 3D 뷰어) → [[B04_PreProcess/B04_dependencies]]
- 백엔드 API → [[B04_PreProcess/B04_api]]
Reference in New Issue View Git Blame Copy Permalink