Aislo/docs/wiki/pages/B04_PreProcess/B04_frontend.md

status, page_id, related_pages, last_updated, source

status	page_id	related_pages	last_updated	source
stable	B04_PreProcess	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	2026-08-30	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