Aislo/docs/wiki/concepts/drainage_watershed.md

---
status: stable
related_pages: ["[[B04_PreProcess/B04_backend]]", "[[B04_PreProcess/B04_frontend]]", "[[B05_Profile/B05_backend]]", "[[B05_Profile/B05_frontend]]", "[[B08_DesignDetail/B08_drawing_masshaul_watershed]]", "[[architecture/shared_resources]]"]
last_updated: 2026-08-30
---

# 배수유역 해석 및 세부설계 (Drainage Watershed)

배수유역 구조는 B04 지표면 분석 단계에서 무거운 1차 격자 해석(30초)을 거치고, 이후 관 매설 편집 및 세부유역 분할 설계는 B04/B05 두 워크플로우 화면에서 **단일 데이터 소스(SSOT) 및 공용 API**를 통해 실시간으로 처리되도록 통합 관리됩니다.

사용처: [[B04_PreProcess/B04_frontend|B04_PreProcess]], [[B05_Profile/B05_frontend|B05_Profile]], [[B08_DesignDetail/B08_drawing_masshaul_watershed|B08 유역도]]

## 1. B04 vs B05 역할 분담 및 일원화

| 구분 | B04 지표면 분석 & 세부유역 설계 | B05 배수유역도 패널 & 종단 연동 |
|---|---|---|
| 역할 | ①~⑧ 전 해석 수행 및 관 매설 편집/세부유역 계산(분할)을 담당 | B04와 **동일한 단일 데이터**를 로드하여 지도 2D 오버레이 시각화 및 종단 그래프 드래그/우클릭과 배관 위치 양방향 동기화 |
| 저장소 | `B04_PreProcess/drainage/` 내 **`pipe_points.json` 단일 정본**을 두 화면이 공용으로 바라봄 (B05 사본 폴더는 완전히 폐지됨) |
| API | 두 화면 모두 **B04 공용 API**를 호출 (`GET/POST/PUT/DELETE /drainage/pipe-points` 및 `POST /drainage/detail-basins`) |
| 노선 원본 | B03 업로드 원청 계획노선 CSV (`common_util_route_geometry.py`) | B03 업로드 원청 계획노선 CSV |

## 2. 공용 배수 엔진 및 WAMIS 강우량 연동 (Phase 1~2, 2026-08-13 관측소 전환)
- **WAMIS 전국 621개 관측소 확률강우량 연동 (본토)**: `common_util/common_util_wamis_station.py`를 통해 공사지 기준 반경 10km (`WAMIS_STATION_RADIUS_M = 10000`) 내 WAMIS 관측소 xlsx를 다운로드·파싱하여 100년/24hr 강우량이 가장 높은 지점을 안전측으로 탐색·선정합니다.
- **제주도 등우선도 존치 및 지역 분기**: 제주 지역 공사지는 기존 `common_util_wamis_rainfall.py` 등우선 내삽(96조합)을 유지하며, `value_at()`에 10km 커버리지 검사를 추가하여 본토 공사지에서 제주 등우선으로 무단 폴백되는 결함을 엄격히 차단했습니다.
- **강우강도(IDF) 이원화 (Mononobe 기본)**: Mononobe형 IDF($a=(R_{24}/24)\cdot 1440^{0.557}$, $n=0.557$, $b=0$)를 기본 적용하고 General형 선택적 지원을 유지하여 하류 수리계산 계약을 완전 보존합니다.
- **수리계산 체인**: 100년 빈도·5분 하한·IDF·합리식·설계유량 2배·Manning으로 유효직경을 산출한다. Kirpich·유출계수·조도계수·유효 통수비율·관 경사값의 기술정보DB 근거 승격과 재확정은 미결이다.
- **추천과 자동 주입**: 유효직경 1,500mm 이하=규격 스냅 배관, 초과~2,000mm=BOX암거 후보, 2,000mm 초과=세월교·물넘이 검토다. 자동 배치에는 추천 관경·시설만 주입하며 사용자 수정값은 덮어쓰지 않는다. 사용처: [[B04_PreProcess/B04_backend]], [[B05_Profile/B05_structures]].
- **공용 엔진 승격**: `common_util/common_util_drainage_detail.py`가 유역 분할 및 수리계산 코어 알고리즘을 전담.

## 3. 구조물 3단 옵션 체계 & UI (Phase 3~5)
- **3단 계층 드롭다운**: 구조물 대분류(배관/기성막이/대피로/기타), 세부 유형(콘크리트관/PE관 등), 관경/규격(D800, D1000 등) 선택 드롭다운 연동.
- **D800 법정 예외 하한**: 임도 구조물 기본 규격 하한 D800 적용 및 수리 계산 $D_{\text{eff}}$ 초과 시 규격 자동 상향 (수동 지정 `userSized` 보존).
- **컨텍스트 메뉴 & 캔버스/3D 핀 마킹**: 종단 그래프/배수유역도 우클릭 구조물 추가, 3D 수직 핀 마커(depthTest off) 동기화.
- **하단 패널 레이아웃**: 테이블 서브패널 오버레이, 행제목 우측 정렬, Y축 텍스트 13px, 드래그 포인터 추적으로 UX 안정화.

## 4. 해석 알고리즘 — 등고선 하강 (Contour Descent)

TIN 보간 표고면의 웅덩이(Sink) 문제를 원천 차단하기 위해 표고면을 생성하지 않고 등고선 자체를 격자에 구워 방향을 계산합니다.

1. 등고선을 격자에 굽고 각 셀에 가장 가까운 등고 라인의 표고(밴드)를 부여
2. 각 밴드에서 한 단 낮은 등고 라인까지의 거리를 EDT(Euclidean Distance Transform)로 측정
3. `potential = 밴드순위 × span + 거리` (`span = 최대거리 + 2.0`)
   - 흐름은 항상 potential이 낮은 방향으로 진행 (순환 및 웅덩이 원리적 부재)
4. 최하단 밴드는 Sink 셀(32)로 관리하며 방위는 32방위(0~31)로 저장 (1셀 1바이트)
5. 8이웃 중 화살표 방향에 가장 가까운 셀을 수신자로 지정하여 화살표/경로 불일치 0셀 달성

## 5. 적색/청색 판정 및 유역 확장

1. **세류선 지류 우선 확정**: 세류선과 겹치는 셀을 걷기 전 적색으로 선 확정
2. **수신자 사슬 추적**: 최외곽 셀에서 수신자 사슬을 추적
   - 도로 셀 또는 세류 셀에 도착 시 사슬 전체 **적색** (배수 영향 유역)
   - Sink 또는 영역 이탈 시 사슬 전체 **청색** (자연 유출 유역)
3. **세류망 노딩**: 세류망을 도로에서 절단하여 상류측만 남기고 `unary_union`으로 노딩
4. **확장 루프**: 최외곽 적색 셀 주변으로 50m(`DRAINAGE_RED_EXPAND_BAND_M`)씩 확장을 반복하다가 새로 붙은 셀에 적색이 없으면 멈춤 (2차 전체 배수유역 경계 닫힘)

## 6. 평균 흐름 화살표 (Flow Arrows) 및 흐름강도 램프
- **화살표**: 1m 격자 화살표 대신 10m 블록의 원형 평균 방위를 구하고 40m 간격으로 솎아서 백엔드가 산출합니다.
- **흐름강도 램프 (FlowRamp)**: 1m 구간별 유입 면적 강도 프로필 데이터를 B04/B05에 동일하게 표시하며, 이를 지도 우측 세로 눈금 범례(`createFlowLegend` in `_UI_FlowRamp.ts`)로 동적 시각화합니다.

## 7. 영구저장소 산출물 구조

`storage/{회사}/{사용자}/{프로젝트}/B04_PreProcess/drainage/`
- `00_watershed_response.json`: 백엔드 응답 전체 캐시
- `01_primary_region.geojson` / `.npz`: 1차 영역, 상/하류망, 격자 bbox
- `02_flow_direction.npz`: 방위, 도달여부, 수신자, 밴드 표고
- `03_road_routing.geojson` / `.npz`: 2차 유역 외곽선, 기본 관, 평균 흐름 화살표, 슬롯 정보
- `pipe_points.json` (정본): 사용자가 매설한 관의 지점 좌표 및 상세 속성 (구조물 유형, 관경 등)
- `04_detailed_basins.geojson`: 관 매설에 맞춰 분할 계산된 세부 배수유역 경계 정보
- `rainfall_table.json`: WAMIS 확률강우량 내삽 산출 테이블
- `manifest.json`: 단계별 실행 메타데이터

> [!NOTE]
> 유역 외곽선 편집기 및 오버라이드 코드(`boundary_overrides.json`)는 2026-08-01부로 전량 영구 제거되었습니다. B05 디렉토리 하위의 중복 복사본 폴더(`B05_Profile/drainage/`) 또한 완전히 폐지되었습니다.

## 8. B08 수리집수면적유역도

- B04 세부유역 GeoJSON과 등고선·하천중심선, 확정 종단 노선을 A1 1:6,000 도면으로 조립한다.
- 정보표에는 번호·측점·배수규격·유역면적·유역표고·유하거리만 표시하며 C·I·Q는 제외한다.
- 여러 도엽의 배경선은 합친 뒤 A1 작도영역으로 선분 절취한다. 상세는 [[B08_DesignDetail/B08_drawing_masshaul_watershed]]를 참조한다.