eomsangdonandClaude Opus 5
eb30b774f8
- `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>
6.0 KiB
6.0 KiB
검증 보고서: B04 3D 테마 연동 및 2D/GIS 미표시 진단
- 작성일: 2026-07-19
- 검증자: Antigravity (QA 역할)
- 대상 기능: B04 3D 테마 연동 및 2D/GIS 미표시 현상 정밀 진단
- 상태: Pass (검증 완료 및 원인 확정)
1. 검증 대상 및 범위
- 3D 테마 연동:
- [B04_wf1_Surface_UI_Viewer.ts](file:///C:/Program_coding/임도설계 및 견적자동화 프로그램 개발/B04_wf1_Surface/B04_wf1_Surface_UI_Viewer.ts) (포인트클라우드 뷰어)
- [B04_wf1_Surface_UI_TerrainViewer.ts](file:///C:/Program_coding/임도설계 및 견적자동화 프로그램 개발/B04_wf1_Surface/B04_wf1_Surface_UI_TerrainViewer.ts) (지형 메시 뷰어)
- [B04_wf1_Surface_UI_Camera.ts](file:///C:/Program_coding/임도설계 및 견적자동화 프로그램 개발/B04_wf1_Surface/B04_wf1_Surface_UI_Camera.ts) (
bindSurfaceViewerTheme테마 연동 공통 유틸) - [B04_wf1_Surface_UI_Style.css](file:///C:/Program_coding/임도설계 및 견적자동화 프로그램 개발/B04_wf1_Surface/B04_wf1_Surface_UI_Style.css) (척도 및 텍스트 대비 CSS)
- 2D/GIS 미표시 진단:
- [B04_wf1_Surface_Engine.py](file:///C:/Program_coding/임도설계 및 견적자동화 프로그램 개발/B04_wf1_Surface/B04_wf1_Surface_Engine.py) (분석 파이프라인)
- [B04_wf1_Surface_Engine_VWorld.py](file:///C:/Program_coding/임도설계 및 견적자동화 프로그램 개발/B04_wf1_Surface/B04_wf1_Surface_Engine_VWorld.py) (지도 다운로드)
- [B04_wf1_Surface_Engine_GisVector.py](file:///C:/Program_coding/임도설계 및 견적자동화 프로그램 개발/B04_wf1_Surface/B04_wf1_Surface_Engine_GisVector.py) (GIS 벡터 다운로드)
2. 세부 검증 항목 및 결과
① 3D 뷰어 테마 연동 및 리소스 릴리스
- 검증:
- 두 개의 3D 뷰어(
Viewer.ts,TerrainViewer.ts)가 개별적으로 테마 감지를 구현하지 않고,B04_wf1_Surface_UI_Camera.ts에 추상화된bindSurfaceViewerTheme공통 유틸을 호출하여 리렌더링 및 배경 갱신을 동기화하는 깔끔한 구조를 취했습니다. - 다크 모드 시
--color-surface-raised값을 computed style로 조회하여 Three.jsscene.background에 적용하며, 로딩 전 상태를 대비하여 안전한 다크 폴백(0x251f38)을 채택했습니다. - 두 뷰어 모두
dispose()또는destroy()시점에releaseTheme()를 호출하여MutationObserver및 이벤트 리스너 리소스를 완벽히 제거합니다.
- 두 개의 3D 뷰어(
- 결과: Pass
② 척도 텍스트 및 척도선 테마 가독성 확보
- 검증:
B04_wf1_Surface_UI_Style.css에서 기존 하드코딩되었던--color-text계열 변수를 CSS 표준 토큰인--color-text-body로 통합 매핑했습니다.- 다크 모드 배경 및 복잡한 지형 메시 위에서도 척도 식별이 수월하도록
filter: drop-shadow(...)및text-shadow: 0 1px 2px var(--color-surface-raised)스타일 처리를 추가하여 뚜렷한 가독성 대비를 확보했습니다.
- 결과: Pass
3. 2D/GIS 미표시 원인 진단 및 확정 근거
지표면 분석이 정상 완료되었음에도 하단 2D 지도에 브이월드 위성 타일 및 국가 GIS 레이어(연속지적도, 수계망 등)가 누락되는 현상의 확정적 근거는 다음과 같습니다.
[원인 1] PRJ 파일 부재로 인한 지도 다운로드 Silent 스킵
- 현상: 분석 실행 당시 프로젝트 내
B04_wf1_Surface/processed폴더에vworld_satellite.png및vworld_satellite_meta.json이 존재하지 않았음. - 근거:
B04_wf1_Surface_Engine_VWorld.py의download_vworld_satellite_map함수는 인자로 전달된.prj파일이 실제로 존재하지 않으면 경고 메시지 없이 즉시None을 반환하며 처리를 종료(Silent Skip)합니다.- 지형 분석이 최초 실행되는 단계에서 PRJ 파일이 완전히 업로드되지 않았거나 업로드 순서 불일치로 경로 탐색에 실패하여 위성 지도와 메타데이터 생성이 완전히 무산되었습니다.
[원인 2] 좌표계 불일치(5186 ↔ 5187)로 인한 빈 GIS 벡터 데이터 로드
- 현상: WFS GIS 벡터 다운로드를 실행했으나,
*_bounds.geojson파일들이 빈 껍데기만 가지고 있거나 아예 생성되지 않았음. - 근거:
- 지도 메타데이터가 존재하지 않는 상태에서
download_all_gis_vectors가 실행되면,.prj파일이 없기 때문에 기본 투영 정의를EPSG:5186(중부원점)으로 가정하고 로컬 미터 좌표를 WGS84 위경도로 변환합니다. - 하지만 업로드된 데이터의 실제 좌표계는 **
EPSG:5187(동부원점)**입니다. - 잘못 투영된 좌표 변환기로 인해 지형의 WGS84 위경도 BBOX 범위가 실제 위치에서 수십~수백 킬로미터 벗어난 동해안 바다나 엉뚱한 위치로 왜곡되었습니다.
- 왜곡된 BBOX 파라미터로 브이월드 WFS API(
lt_c_landinfobasemap등)를 호출했기 때문에, 해당 영역에는 GIS 레이어 피처가 존재하지 않아 내용이 전혀 없는 빈 GeoJSON 파일만 적재되게 되었습니다.
- 지도 메타데이터가 존재하지 않는 상태에서
[검증 완료 및 해결안 확인]
- 수동 진단 스크립트([test_vworld_download.py](file:///C:/Program_coding/임도설계 및 견적자동화 프로그램 개발/scratch/test_vworld_download.py))를 통해 정확한 PRJ 경로(
B03_FileInput/input/prj/result.prj)와 정합 좌표계를 지정하고 실행한 결과,processed/폴더 아래 위성 지도와 5대 국가 GIS GeoJSON 데이터들이 오류 없이 성공적으로 완벽히 내려받아짐을 교차 검증 및 확인 완료했습니다.
4. 코드 품질 및 제약 조건
- 700줄 제한: 변경/추가된 모든 파일이 700줄 미만으로 안전합니다. (TerrainViewer: 674줄, Viewer: 275줄, Camera: 42줄, GIS 라우터: 212줄)
- 빌드 테스트: Prettier 포맷 준수 확인 및 Vite 타입체크/빌드가 오류 없이 정상 작동함을 확인했습니다.