Aislo/docs/raw/plans/2026-07-26_plan_도엽_오버레이.md

수치지형도 도엽 오버레이 — 2D 배경지도/GIS 레이어 컨테이너 확장 (2026-07-26 협의)

배경

• 2D 배경지도/GIS 레이어 컨테이너(B04_wf1_Surface_UI_MapViewer.ts)에 국가 등고선 오버레이는 완료됨(전국 gpkg 크롭 방식).
• 수치지도 v2.0 도엽본(1:5,000)에는 등고선 외 하천중심선(세류)·표고점·성/절토·산산맥 등 29종 레이어가 있음을 실측 확인. 브이월드 데이터센터에서 도엽 zip(예: 36906042.zip)을 다운로드 버튼으로 받을 수 있음.
• 목표: gpkg 등고선 오버레이 + 도엽 zip 기반 추가 레이어 오버레이를 같은 컨테이너에서 제공.

확정된 사실 (2026-07-26 실측)

항목	내용
등고선 소스	전국 gpkg 재생성 완료 (resources/grobal_contours/national_contours.gpkg, 21.57GB, 1,884,844건, 속성 9개 보존, R-tree+속성 인덱스, 사업지 크롭 0.32초)
등고 간격	주곡선 5m / 계곡선 25m. 간곡선·조곡선 전국 0건 → 1m는 크롭 후 국소 보간으로만 생성
볼록지/오목지	TPGRPH_SE 전용 컬럼. 오목지=폐합 저지(웅덩이), 폐합률 99.4%. 계곡 아님
도엽본 스키마	한글 컬럼(구분/등고수치/명칭), EPSG:5187. 연속수치지형도(영문 DIVI/CONT/SCLS)와 다름 — 파서는 양쪽 자동 판별 필요
도엽 등고선	전국 gpkg와 지오메트리 완전 일치(최근접 0.000m). 도엽에서 등고선 무시 → 정정(2026-07-26 사용자 지시): gpkg 등고선과 별개로 도엽 등고선(N3L_F0010000)도 독립 오버레이로 제공 (도엽_등고선 레이어·토글 구현 완료, 9매 병합 3,413건)
하천중심선(E0020000)	"비 왔을 때 물흐름" = 세류. 도엽 표본 2곳에서 세류가 압도적(88%, 5~6천 m/km2). CAD 파란선의 정체
능선	국가 데이터에 실존 안 함(G0037216 정의만 있고 표본 2지역 0건). LAS 산출만 가능(별도 운영, 국가 데이터와 혼용 금지)
브이월드 다운로드	데이터센터 버튼 방식. 공식 API 없음 → 자동화는 URL 패턴 조사 필요, 실패 시 수동 다운로드+업로드
배경지도 API	국토정보맵 WMTS 키 유효(SDK 정상). NGII 검색API는 키 권한 없음(1002) → VWorld 지오코더로 대체 가능(실테스트 통과)

아키텍처 결정 (사용자 확정)

1. 등고선 = 전국 gpkg 유지(연 1회 수동 갱신). 그 외 레이어 = 1:5,000 수치지형도 도엽 zip 단위로 취득.
2. 국가 데이터는 참고·표지용 전용. 설계 계산은 LAS 계열만 사용. 두 계열 혼용 절대 금지(프로젝트 폴더 reference/ 분리 권장).
3. 크롭·1m 보간은 프로젝트 파일입력 후 전처리 단계에서 수행, 결과는 프로젝트 영구저장소에 저장. 이후 gpkg/도엽 원본은 다시 읽지 않음.
4. 대상 컨테이너 = B04 페이지 하단 2D 배경지도/GIS 레이어 컨테이너로 확정 (2026-07-26).
5. 도엽 원본 = 프로젝트 영구저장소 (2026-07-26 사용자 2회 정정 최종): 브이월드에서 받은 도엽 zip과 메타정보는 storage/{회사}/{사용자}/{프로젝트ID}/B04_wf1_Surface/processed/map_sheets/에 보관 — 위성지도·GIS 벡터 등 주변데이터와 동일한 프로젝트 processed 계층. resources/는 프로젝트 공통정보 폴더로 개별 프로젝트 영구저장소가 아님(사용 금지). 파일명 {도엽번호}.zip + map_sheets_index.json(취득일, 원본명, 도곽 범위, 교정 CRS). 같은 프로젝트 내 재다운로드 없음.

처리 순서 (사용자 확정 흐름, 2026-07-26 갱신)

B03 페이지: 사용자 파일 입력 + 업로드 버튼
  → 업로드된 파일 기준 전처리 분석 진행 (기존 WF1 파이프라인)
  → 전처리 중 파일 좌표(PRJ+bounds) 기준 1:5,000 도엽번호 산출 (중심+주변 8 = 3×3, 9매)
  → 9매 자동 다운로드 (브이월드 지도서비스, 세션 만료 시 자동 재로그인)
  → 프로젝트 영구저장소 저장 ({프로젝트}/B04_wf1_Surface/processed/map_sheets/)
  → 전처리 완료 시 B04 페이지로 전환
  → B04 하단 2D 배경지도/GIS 레이어 컨테이너에 기존 오버레이(gpkg 등고선·위성지도 등)와 함께
    도엽 기반 레이어(9매 병합)를 하나의 오버레이로 표시

구현 체크리스트 (승인 후 착수)

• 1. 좌표→도엽번호 산출 검증 (최우선 선행) — B04_wf1_Surface_Engine_MapSheet.py 구현 완료(2026-07-26). 보유 도엽 10매 실측 대조 10/10 정합(해안 도엽은 바다 쪽 도곽 잘림 감안해 "실측⊆예측 도곽" 기준). 3×3 인접 산출 및 구획 경계 이월(위도 1° 구획·1:50,000 경계) 검증 통과. 검증 스크립트: scratch/test_mapsheet_verification.py
• 2. 도엽 확보 경로 조사 — 결론(2026-07-26, 2차 정정): ① 도엽검색은 브이월드 지도서비스 내부 API로 완전 자동화 가능(무로그인): GET map.vworld.kr/ws3dmap/getDisitalMapList.do?type=M02&searchNum={도엽번호}&scale=5000&cod=1&version={1|2|3} → ds_sq/file_no/파일명/크기/갱신일 JSON. Ver2.0=zip(SHP), Ver1.0=dxf(zip 아님). 3×3 도엽 9매 조회 실테스트 통과. ② 다운로드는 로그인 세션 필요하나 완전 자동화 확정(2026-07-26 사용자 승인): 지도서비스 로그인은 SSO 아닌 단순 POST(/map/im_usrlogin_a004.do, Base64 id/pw, 캡차 없음 실측) → vworld_login() 구현. download_sheet()는 쿠키(인자>프로세스캐시>.env)로 시도 후 세션 만료 시 id/pw 자동 재로그인 1회 재시도 — 다른 사용자가 언제 요청해도 무인 동작. 자격증명은 .env VWORLD_LOGIN_ID/PW. 실검증: 실쿠키로 8매 + 무쿠키 자동로그인으로 2매(36906034·044) 다운로드→도곽검증→등록 성공. 폴백 = 수동 다운로드 + Ingest. ③ 데이터센터(dsId=30205)의 시군구 단위 zip(2MAP5000_SHP_*)은 다른 배포본으로 대상 아님. ④ 영구저장소 B04_wf1_Surface_Engine_SheetStore.py 구현(2026-07-26 프로젝트 저장소 기준으로 리팩토링 완료): 저장 위치 {프로젝트}/B04_wf1_Surface/processed/map_sheets/{도엽번호}.zip + map_sheets_index.json, ensure_sheets(store_dir, 도엽목록)가 미보유분 자동 다운로드. 인제스트 시 도곽 실측 검증 및 PRJ 오라벨 CRS 자동 교정(구 36902002.zip 경도 2° 오프셋 사례 실측·교정 확인). 테스트 프로젝트에 20매 확보, 보유 9매 즉시 반환 + 신규 1매 자동 다운로드 검증. 테스트: scratch/test_sheetstore_ingest.py
• 3. B03 전처리 훅 통합 — 구현 완료(2026-07-26): B04_wf1_Surface_Engine.py 3-3 단계 추가(주변데이터 다운로드 3-2 직후, progress 92%). PRJ EPSG 판별→bounds 중심 위경도→3×3 도엽번호→ensure_sheets 자동 확보, 실패는 경고 로깅만(분석 계속). 실프로젝트 검증: 중심 37816093, 위도 1° 구획 이월(37816↔36804) 포함 9매 전량 자동 다운로드·도곽검증·등록 성공
• 4. 도엽 zip 파서 모듈 — B04_wf1_Surface_Engine_SheetParser.py 구현 완료(2026-07-26). 레이어 코드 실측 확정: 하천중심선 N3L_E0020000(구분 세류/소하천/지방하천), 표고점 N3P_F0020000, 성절토 N3L_F0030000, 옹벽석축 N3L_F0040000, 유수방향 N3P_E0042326, 기준점 N3P_H0020000, 지명 N3P_H0040000. 좌표는 인덱스 교정 crs→WGS84. 벼랑바위·너덜바위·산산맥은 표본 도엽 2매에 미출현 — 코드 확정 시 SHEET_LAYERS에 추가(보류)
• 5. 9매 병합 모듈 — parse_and_merge_sheets(): 레이어별 concat + UFID dedup(없으면 WKB), processed/도엽_{레이어}.geojson 저장. Engine 3-3 훅에서 도엽 확보 직후 자동 실행. 실검증: 실프로젝트 9매 병합 → 하천중심선 1,558·표고점 1,529·성절토 255·옹벽석축 335·유수방향 29·기준점 11·지명 153건
• 6. 라우터 — _SHEET_GEOJSON_FILES(SHEET_LAYERS 파생, 정의 일원화)를 /geojson?layer= 및 MVT 타일 매핑에 추가(B04_wf1_Surface_Router_GIS.py). 도엽_하천중심선 등 7개 레이어 확인
• 7. 프론트 — B04 MapViewer GIS_LAYERS에 도엽_하천중심선(파란 #2563eb)·표고점·성절토·옹벽석축·유수방향 토글 5종 추가, Point/MultiPoint 렌더링(원형 마커) 신설, 로케일 5키 추가. typecheck 통과. 건천/세류 파선·실선 구분은 미구현(후속 — 렌더러가 feature properties 미전달 구조)
• 8. 세류-등고선 겹침 검증: 사업지 도엽으로 파란선이 CAD 참고 이미지 수준으로 나오는지 실화면 확인 (사용자/검증자)
• 9. 오버레이 정리(2026-07-26 사용자 지시): ① 수계망 제거 — VWorld 다운로드·라우터 매핑·프론트 토글 삭제(도엽 하천중심선으로 대체). ② 산사태 제거 확정 — 조사 결과 오픈 API(WMS/WFS)에는 시군구 예보등급(lt_c_kfdrssigugrade)뿐, 산림청 FGIS 상세 위험지도는 API 미제공(산림청 공식: 2028년 예정), 지도서비스 위험지도는 래스터 타일이라 벡터 취득 불가 → "자세히 볼 수 없으면 의미 없음"(사용자)으로 다운로드·라우터·프론트 전부 삭제. 2028년 API 개방 시 재검토. ③ 등고선 #fdba74·도엽 등고선 #a5b4fc·표고점 #f9a8d4 파스텔 변경. ④ 등고 라벨 토글 — gpkg(CTRLN_HG)·도엽(등고수치) 속성 기반, 계곡선(25m 배수)만 라벨, 기본 숨김. gpkg 크롭이 속성 미보존(구버전 산출물+Timestamp 직렬화 문제)이던 것을 필요 속성 3종만 유지하도록 수정하고 크롭·단순화본 재생성 완료

미결사항 (다음 세션에서 확정)

1. 좌표→도엽번호 알고리즘 정합 결과 → 해결(2026-07-26): 10/10 정합, 체크리스트 1 참조
2. 도엽 취득 자동화 가능 여부 → 해결(2026-07-26 최종): 완전 자동화 확정 — 검색 무로그인 + 다운로드는 id/pw 자동 재로그인(체크리스트 2 참조). 파서(체크리스트 4)는 내부 PRJ 대신 map_sheets_index.json의 crs 필드를 사용할 것(오라벨 교정값)
3. 사용자 좌표 입력 UI(B02 주소+핀): NGII 검색API 권한 신청 진행 여부, VWorld 지오코더 대체 여부
4. 국가 데이터 저장 위치 → 해결(2026-07-26): 주변데이터와 동일한 프로젝트 영구저장소 B04_wf1_Surface/processed/ 사용 확정(도엽은 하위 map_sheets/). resources/는 프로젝트 공통정보 폴더로 개별 프로젝트 데이터 저장 금지(사용자 2회 정정)
5. 크롭 범위(gpkg 등고선용): LAS bounds+고정 여유폭(자동) vs 범위 지정 UI(수동)