---
status: stable
page_id: B04_wf1_Surface
related_pages: ["[[B04_wf1_Surface/B04_backend]]", "[[B04_wf1_Surface/B04_api]]", "[[B04_wf1_Surface/B04_dependencies]]", "[[ui_templates]]"]
last_updated: 2026-07-12
---

# B04_wf1_Surface — Frontend

WF1 지표면 분석 화면. 워크플로우 레이아웃(필터/표현 폼 + 모델 목록) + **three.js 기반 3D 뷰어**(포인트클라우드/지형).

## 파일 구조

| 파일 | 위치 | 역할 |
|---|---|---|
| `B04_wf1_Surface_UI_Page.ts` | `B04_wf1_Surface_UI_Page.ts:1-377` | 페이지 조립 + 분석 실행/폴링/뷰어 렌더 |
| `B04_wf1_Surface_UI_Viewer.ts` | `B04_wf1_Surface_UI_Viewer.ts:1-567` | 포인트클라우드 3D 뷰어(three.js) |
| `B04_wf1_Surface_UI_TerrainViewer.ts` | `B04_wf1_Surface_UI_TerrainViewer.ts:1-637` | 지형 메시 3D 뷰어(three.js) |
| `B04_wf1_Surface_Api_Fetch.ts` | `B04_wf1_Surface_Api_Fetch.ts:1-174` | surface API 클라이언트 |
| `B04_wf1_Surface_UI_Style.css` | `B04_wf1_Surface_UI_Style.css` | 폼 그룹/모델 카드/뷰어 스타일 |

## ⚠️ 계획서와 실 코드 불일치 (3D 뷰어)

이전 wiki(계획서 기반)는 **"WebCAD 3D 뷰어 미구현"**으로 기재했으나,
실 코드에는 three.js(WebGL) 기반 뷰어가 **구현되어 있음**:
- `createSurfacePointCloudViewer` (`B04_wf1_Surface_UI_Viewer.ts:187` WebGLRenderer, OrbitControls, THREE.Points)
- `createSurfaceTerrainViewer` (`B04_wf1_Surface_UI_TerrainViewer.ts`)
- UI_Page에서 import·인스턴스화(`B04_wf1_Surface_UI_Page.ts:37,38,110,356`)

→ 규칙6, 실 코드 채택. dependencies도 three.js 반영 → [[B04_wf1_Surface/B04_dependencies]]

## 컴포넌트 / 함수

| 함수 | 위치 | 역할 |
|---|---|---|
| `renderB04Surface(root)` | `B04_wf1_Surface_UI_Page.ts:95` | 워크플로우 레이아웃+뷰어 조립(async) |
| `createSurfacePointCloudViewer()` | `B04_wf1_Surface_UI_Viewer.ts:187` | 포인트클라우드 뷰어 핸들 생성 |
| `createSurfaceTerrainViewer()` | `B04_wf1_Surface_UI_TerrainViewer.ts` | 지형 메시 뷰어 핸들 생성 |

## API 클라이언트 함수

| 함수 | 위치 | 대응 API |
|---|---|---|
| `analyzeSurface()` | `B04_wf1_Surface_Api_Fetch.ts:117` | `POST .../surface/analyze` |
| `listSurfaceModels()` | `B04_wf1_Surface_Api_Fetch.ts:128` | `GET .../surface/models` |
| `listSurfaceInputFiles()` | `B04_wf1_Surface_Api_Fetch.ts:134` | `GET .../surface/input-files` |
| `fetchSurfacePointCloud()` | `B04_wf1_Surface_Api_Fetch.ts:142` | `GET .../surface/point-cloud` |
| `fetchSurfaceGroundStats()` | `B04_wf1_Surface_Api_Fetch.ts:153` | `GET .../surface/ground-stats` |
| `fetchSurfaceStatus()` | `B04_wf1_Surface_Api_Fetch.ts:161` | `GET .../surface/status` |
| `getVWorldMapUrl()` / `fetchVWorldMeta()` | `B04_wf1_Surface_Api_Fetch.ts:182,186` | VWorld 배경지도 |
| `fetchGisGeoJson()` | `B04_wf1_Surface_Api_Fetch.ts:192` | `GET .../geojson` |

## 처리 흐름

1. 워크플로우 레이아웃(`createWorkflowLayout`) + 스텝(`workflowSteps`) 조립
2. 입력파일/모델 목록 로드 → 필터·표현 폼 구성
3. 분석 실행(`analyzeSurface`) → 상태 폴링(`fetchSurfaceStatus`)
4. 완료 시 포인트클라우드(`fetchSurfacePointCloud`) → `viewer.render()` (`B04_wf1_Surface_UI_Page.ts:356`)

## 의존성

- [[a00_app_shell_framework]] — `navigateTo`, `workflowSteps`(b_page_scaffold)
- `config_frontend.ts` — `API_BASE_URL`, `CURRENT_PROJECT_ID_KEY`, `ROUTES`, `RENDER_OPTIONS`, `API_TIMEOUT_MS`
- [[ui_templates]] — `createWorkflowLayout`(ui_template_workflow_layout) 등
- **three.js** (WebGL 3D 뷰어) → [[B04_wf1_Surface/B04_dependencies]]
- 백엔드 API → [[B04_wf1_Surface/B04_api]]