knowledge(요구): 요구 496 분석 기록 — 등고선 줌별 벡터 조각 실측 · 설계 · 결정 거리

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015uTVHHDv583hbLQAFeBmd9

docs/raw/요구_1025/_분석_496_등고선_줌별조각.md

@@ -0,0 +1,166 @@
+# 496 등고선 줌별 조각 — 분석 · 실측 (요구 496)
+
+결론 — **가능 · 권함.** 웹 메르카토르 z/x/y 벡터 조각(MVT)을 위성처럼 서버가 만들어 공용 창고에 기억 · MapLibre 가 보이는 조각만 받음. 12 도엽 화면 기준 받는 양 약 1/100 이하 · 그림 5.8 s → 0.3~0.5 s(실측). 새 라이브러리 = 없음(파이썬 `mapbox-vector-tile` 은 requirements 에 이미 있으나 venv 에 안 깔림 → 설치만).
+
+실측 조건 — 전국 파일 읽기만 · 612 일괄(일꾼 7 · CPU 약 33 %)이 같이 도는 중 → 읽기 시간은 부풀려진 값. 자리 = 산지 용화(36901074) · 험산 지리산 · 평지 김제. 화면 = 1557×1087 px.
+
+## 1. 지금 606 방식 한계
+
+| 항목 | 값 | 근거 |
+|---|---|---|
+| 단위 | 1:5,000 도엽(2.25×2.78 km) · 원형 5 m 전부 · 단순화 없음 | `D03_PlanAnalysis_SheetTiles.py:166-215` |
+| 줌아웃 | 12 장 이하 = 다 · 13~30 = 계곡선만 · 넘음(≈ 줌 12.7 아래) = 숨김 | `SheetTiles.py:44` · `UI_SheetTiles.ts:88-89,138` |
+| 도엽 하나 크기 | 등고선 3.0~6.1 MB(가운데 4.6) · 계곡선 0.66~1.3 MB | 공용 창고 18 장 실측 |
+| 12 장 받는 양 | 56.3 MB(gzip 1 = 17.2 MB) · 2,384 가닥 · **227만 꼭짓점** | 실측 |
+| 12 장 그림 | **5.6~5.9 s**(로컬 · 서버 계산 없이) · 606-2 실측 4.8 s | 브라우저 실측 |
+| 처음 받기 | 조각 하나 2.0~2.9 s · 하나씩 차례로(`pull` 한 줄) | `UI_SheetTiles.ts:108-128` · 606-1 |
+| 실제로 그리는 선 | 12 장 = 25 m 만 보임(화면 안 350 가닥 예산 → 주곡선 간격 50 m) — 5 m 를 받고도 안 그림 | `B04_..._UI_MapRender.ts:563-597` · `UI_Layers.ts:639-640` |
+
+## 2. 조각 피라미드 설계
+
+- 조각 = 웹 메르카토르 z/x/y · 512 px(MapLibre 벡터 기본) · 범위 4096 · 여유 8 px(이음 끊김 없음 — z16.5 겹쳐 그림에서 원본 GeoJSON 과 어긋남 0 확인).
+- 만드는 꼴 = SQL 간격 거름(`CTRLN_HG % 간격 = 0` · 높이 색인 있음) → 5179 에서 자르고 단순화 → 3857 → 조각 자름 → MVT. 단순화를 먼저 하면 좌표 바꿈 1.7 s → 5~11 ms.
+- 겹 이름 `contour` · 속성 `h`(높이) · `k`(굵은 선 = 1). 굵은 선 기준을 서버가 줌마다 정함 → 화면은 줌 셈 없음.
+- 줌 넘김 — 소스 maxzoom 15 · 16 이상 = z15 늘려 씀(0.25 px 단순화 = 실제 약 0.5 m · z18 에서도 2 px 안쪽).
+
+밀도 기준 — 산지 평균 5 m 선 간격 약 9.5 m(용화) · 8 m(지리산) → 화면 선 간격(px) = 간격 × 1.9 ÷ (62,930 ÷ 2^줌).
+
+| 조각 z | 화면 폭(1557 px) | **보통(권함)** 담는 선 | 촘촘 안 | 굵은 선 `k` | 단순화 | 보통 선 간격(z 처음 → 끝) |
+|---|---|---|---|---|---|---|
+| ≤8 | 380 km~ | 숨김 | 숨김 | — | — | — |
+| 9 | 190 km | 500 m | 200 m | 2,500 m(사실상 없음) | 1 px | 약 7 → 15 px |
+| 10 | 96 km | 200 m | 100 m | 1,000 m | 1 px | 6 → 12 |
+| 11 | 48 km | 100 m | 50 m | 500 m | 1 px | 6 → 12 |
+| 12 | 24 km | 50 m | 25 m | 250 m | 1 px | 6 → 12 |
+| 13 | 12 km | 25 m(계곡선) | 10 m + 25 m | 25 m | 1 px | 6 → 12 |
+| 14 | 6 km | 10 m + 25 m | 5 m | 25 m | 0.5 px | 5 → 10 |
+| 15~ | 3 km~ | 5 m 전부 | 5 m | 25 m | 0.25 px | 5 → 10 |
+
+- 보통 = 지금 606 화면 밀도와 비슷(12 장 화면 = 25 m · 도엽 1~2 장 = 5 m). 촘촘 = 같은 줌에 선 두 배(간격 3 px 안팎 · 산지는 거의 칠한 면).
+- 높이 글 = 굵은 선(`k=1`)에 `symbol-placement: line` 그대로(`UI_MapGl.ts:199-219`) · 조각마다 따로 놓여 이음 근처 겹 글은 MapLibre 가 뺌.
+
+### 조각 크기 · 시간 실측(보통 규칙 · 조각 하나)
+
+| z | 용화 KB / ms | 지리산 KB / ms | 김제 KB / ms | 꼭짓점(산지) |
+|---|---|---|---|---|
+| 15 (5 m) | 31.3 / 237 | 33.2 / 367 | 2.4 / 54 | 13.1~13.8 천 |
+| 14 (10 m) | 20.9 / 170 | 28.6 / 325 | 2.8 / 46 | 8.2~11.5 천 |
+| 13 (25 m) | 15.3 / 124 | 18.7 / 390 | 1.4 / 29 | 5.6~6.9 천 |
+| 12 (50 m) | 21.5 / 284 | 21.1 / 376 | 0.1 / 25 | 8.2~8.5 천 |
+| 11 (100 m) | 24.7 / 435 | 21.2 / 407 | 0 / 28 | 8.8~9.9 천 |
+| 10 (200 m) | 26.2 / 810 | 23.3 / 987 | 0.3 / 87 | 9.2~9.6 천 |
+| 9 (500 m) | 10.4 / 1,759 | 12.5 / 1,724 | 4.6 / 1,006 | 3.5~4.5 천 |
+
+- 시간 = 읽기가 60~95 % · 나머지 MVT 묶기. gzip 1 = 0.85~0.88 배(줄임 적음).
+- 촘촘 안(참고) — z13 5 m 75.7 / 93.6 KB(0.4 / 1.0 s) · z12 25 m 42.4 / 42.7 KB · z14 5 m 41.7 / 56.9 KB.
+- 단순화 효과(용화 z15 5 m) — 원형 53.9 천 꼭짓점 110 KB → 0.25 px 13.1 천 31 KB → 1 px 5.9 천 18.7 KB.
+
+### 화면 하나 실측(브라우저 · 조각 미리 만듦 · 로컬)
+
+| 보기 | 받는 양 | 그림(멈출 때까지) |
+|---|---|---|
+| 606 GeoJSON 12 도엽(지금) | 56.3 MB · 227만 꼭짓점 | **5,607~5,857 ms** |
+| 벡터 줌 12.8(같은 12 도엽 화면) | 6~12 조각 | **308 ms** |
+| 벡터 줌 13.5(촘촘 5 m 조각 · 무거운 쪽) | 6~12 조각 · 약 0.5~0.9 MB | 522 ms |
+| 벡터 줌 14.5 · 15.5 | 6~12 조각 | 306~308 ms |
+| 벡터 줌 11.5 · 12.0 | 6~12 조각 | 507~538 ms |
+
+- 보통 규칙 화면 하나 = 조각 6~12 × 15~33 KB ≈ 0.1~0.4 MB · 꼭짓점 3.4~16.5 만.
+- 처음 보는 곳 = 조각마다 서버 0.05~0.4 s(z13~15) · 병렬 → 화면 약 0.5~1.5 s · 다시 오면 즉시. z9·z10 첫 조각 0.8~1.8 s → 미리 만듦 권함.
+
+## 3. 만드는 방식
+
+전국 조각 수(전국 등고선 도엽 17,646 장이 닿는 조각) · 크기 어림(보통 · 전국 길이 676.5 만 km × 실측 바이트/km):
+
+| z | 조각 수 | 크기 | 한 줄 시간(어림) |
+|---|---|---|---|
+| 9 | 54 | 0.6 MB | 1.4 분 |
+| 10 | 172 | 2.1 MB | 2.3 분 |
+| 11 | 584 | 6 MB | 3.4 분 |
+| 12 | 2,087 | 20 MB | 10 분 |
+| 13 | 7,829 | 64 MB | 33 분 |
+| 14 | 29,967 | 0.37 GB | 1.8 h |
+| 15 | 116,569 | 1.59 GB | 8.1 h |
+| **합** | **157,262** | **약 2.05 GB** | **약 10.6 h(일꾼 넷 약 3 h)** |
+
+| 안 | 내용 | 장단 |
+|---|---|---|
+| **A 권함** | 처음 볼 때 만들어 공용 창고 영구 저장(606 `ensure_tile` 과 같은 꼴 · 잠금 · `.part`→바꿈) + z9~z12 만 미리(2,897 조각 · 약 29 MB · 약 17 분) | 줌아웃 즉시 · 파일 수 적음 · 쓰는 곳만 쌓임 |
+| B | 전국 z9~z15 다 미리(612 처럼 · 612 끝난 뒤) | 처음도 즉시 · 15.7 만 파일 · 2 GB 시놀로지 동기 |
+| C | 위성 길 그대로(프로젝트별 `_derived` · 한도 지움) | 프로젝트마다 같은 조각 중복 — 비권함 |
+
+- 위성 조각 길과 같은 꼴 가능 — 경로 `GET …/plan/contour/{z}/{x}/{y}.pbf`(위성 `D03_PlanAnalysis_Router.py:595-635` 옆) · 다만 창고 = 공용 `storage/_shared/contour_tiles/v1_<전국 파일 지문>/{z}/{x}/{y}.pbf`(606 `_gpkg_tag` 그대로 · `SheetTiles.py:68-86`) · 프로젝트 DB 조회 없음 · 한도 지움 없음(전국 상한 2 GB).
+- 빈 조각(바다 · 평지 z11 등) = 16 바이트 빈 MVT 저장(다시 안 셈) · 소스 `bounds` = 국내 경위도(밖은 요청 안 함).
+- 섬 셋(연평 · 대청 · 백령)은 전국 파일에도 브이월드 1:5,000 에도 없음(607-3) → 빈칸 · 606 zip 길 필요 없음.
+- 612 단계 2 「도엽 조각(등고 · 계곡) 미리」(요구서_486 6장)는 이것으로 필요 없어짐.
+
+## 4. 화면 쪽
+
+| 할 일 | 자리 |
+|---|---|
+| 벡터 소스 = `fixed` 로 위성처럼 늘 올림(`{type:"vector", tiles, minzoom 10(결정 3), maxzoom 15, bounds}`) · 공용 `contourTileSource(projectId)` 하나 | `ui_template_gl_map.ts:57-66`(위성 옆) · `:100-110` `fixed` 길 그대로 씀 |
+| 등고 겹 셋 = `"source-layer":"contour"` · 가는 선 `k=0` · 굵은 선 `k=1` · 글 `k=1` · 색 `--draw-map-contour` 그대로 | `D03_PlanAnalysis_UI_MapGl.ts:181-219` |
+| 켬끔 = 지금 `setVisible("contour")` 그대로 · 밝음 · 어두움 = 겹 다시(소스는 고정이라 안 다시 받음) | `ui_template_gl_map.ts:121-144` |
+| 서클 = 등고 소스 받는 동안 `track`(MapLibre `dataloading` → `idle` 까지 약속 하나) | `UI_MapGl.ts` 에 약 10 줄 |
+| 604 영역 루틴 = 등고는 이미 받은 범위와 무관(606 부터) · 단추 막음(`!meta`)만 그대로 | `UI_Layers.ts:222` |
+| 지도 돌림 · 줌 = 지금 `camera()` 그대로(512 세계 줌 · `UI_Map.ts:309-319`) | 바뀜 없음 |
+
+606 등고 · 계곡을 바꾸면 걷을 코드(GL 기준):
+
+| 걷음 | 자리 |
+|---|---|
+| 주곡선 간격 셈 · 거름 바꿈(`setContourStep` · `minorFilter` · `INDEX`) | `UI_MapGl.ts:41,59-63,365-370` · `UI_Layers.ts:639-640` |
+| 등고 GeoJSON 받아 GL 에 얹기(`put("contour")`) · 등고 조각 요청 | `UI_Layers.ts:456-460` · `UI_SheetTiles.ts:19`(`contour` 줄) |
+| 「계곡선만」 모드(13~30 장) — 등고가 빠지면 다른 선 겹엔 뜻 없음 → 12 장 이하 / 숨김 둘로 | `UI_SheetTiles.ts:33,88-89,138` · `SheetTiles.py:44` |
+| 서버 등고 · 계곡 조각 만들기(`_gpkg_contours` · `_build_contours` · `CONTOUR`·`INDEX`) | `SheetTiles.py:39-42,166-215,228-235` |
+| 창고 `storage/_shared/sheets/*/layers/등고선_*·계곡선_*`(18 장 약 100 MB) | 사용자 판단 |
+
+- ⚠ 옛 캔버스(그래픽 카드 끔 · WebGL 없음)는 GeoJSON 이 필요 — `UI_LayerPaint.ts:132-145` 가 `data.contour` 로 그림. 걷으면 옛 캔버스 = 등고선 없음(위성 「옛 그림 = 위성 없음」 590-2 와 같은 꼴). 아니면 606 등고 길을 캔버스 전용으로 남김(GL 일 때만 등고 조각 요청 뺌).
+- 세류 · 도로 · 건물 · 지명 · 물 면 = 606 도엽 조각 그대로(이번 범위 밖 · 같은 꼴로 나중 가능).
+
+## 5. 다른 페이지
+
+| 페이지 | 지도 | 쓸 수 있나 |
+|---|---|---|
+| B04 하단 지도 · B05 평면 노선 편집 · 배수유역도 | 같은 공용 부품 `createGlMap`(`B04_PreProcess_UI_MapGl.ts:69` · `B05_Profile_UI_*_Gl.ts`) | 가능 — `contourTileSource` 를 `fixed` 에 넣고 겹 꼴 셋만. B05 는 고른 등고선 · 집기가 GeoJSON(위 캔버스) 이라 바탕 그림으로만. B 안 고침 · 나중 선택 |
+| E04 · E07 평면 지도 | 자체 캔버스(MapLibre 아님) | 바로는 못 씀 — GL 바탕을 먼저 들여야 함 |
+| B04 옛 MVT 길(`/tiles/{project}/{layer}/{z}/{x}/{y}.pbf`) | 화면 TS 에 `.pbf` 부르는 곳 0 · 패키지 없어 `generate_mvt_tile` 은 빈 바이트 | 안 씀(B 그대로) — 새 길은 D · 공용에 |
+
+## 6. 라이선스 · 라이브러리
+
+| 것 | 판 | 라이선스 | 상태 |
+|---|---|---|---|
+| mapbox-vector-tile | 2.2.0 | MIT | `requirements.txt:23` 에 있음 · **venv 에 안 깔림**(import 실패) → 두 PC `pip install -r requirements.txt` |
+| └ protobuf · pyclipper(딸림) | 6.33.6 · 1.4.0 | BSD-3 · MIT | 같이 깔림 |
+| maplibre-gl | 5.24.0 | BSD-3 | 있음 · 벡터 소스 기본 기능 |
+| shapely · pyogrio · pyproj | 2.0.6 · 0.13.0(GDAL 3.12.4) · 3.7.2 | BSD-3 · MIT · MIT | 있음 |
+| (대안) GDAL MVT 쓰기 | pyogrio GDAL 3.12.4 `MVT rw` | MIT | 설치 없이 가능하나 줌마다 간격 다른 피라미드는 겹을 나눠 여러 번 · 조각 하나 즉석 만들기엔 번거로움 → 비권함 |
+| (대안) 손 MVT 묶기 | numpy 약 60 줄 | — | 묶기 시간(전체의 30~40 %) 줄일 때만 |
+
+## 7. 파일 경계 · 단계 · 위험 · 결정
+
+창 둘(먼저 이음 고정 — 주소 `GET /api/projects/{id}/plan/contour/{z}/{x}/{y}.pbf` · 겹 `contour` · 속성 `h`·`k` · z9~15 · 빈 조각 = 빈 MVT):
+
+| 창 | 파일 | 일 |
+|---|---|---|
+| 서버 | 새 `common_util/common_util_contour_tiles.py`(조각 만들기 · 창고 · 잠금 · 지문) · `D03_PlanAnalysis_Router.py`(길 하나 · 지금 635 줄 → 약 665) · 새 `tools/precompute_contour_tiles.py`(z9~12) · 시험 `resources/tester/test_496_*.py`(풀어 읽기 · 간격 규칙 · 빈 조각 · 두 번째 = 파일) | ① ③ |
+| 화면 | `ui_template/ui_template_gl_map.ts`(`contourTileSource`) · `D03_PlanAnalysis_UI_MapGl.ts`(겹 꼴 · 서클) · `D03_PlanAnalysis_UI_SheetTiles.ts`(GL 이면 등고 빼기) · `D03_PlanAnalysis_UI_Layers.ts`(⚠ 692 줄 · 늘리지 말고 줄이기만) | ② ④ |
+
+단계 — ① 서버 조각 + 시험 → ② 화면 GL 등고 = 벡터 · ORCA 수치(줌별 그린 가닥 · 받은 양 · 멈춤 시간) → ③ z9~12 미리 → ④ 606 등고 길 걷기(결정 4 대로).
+
+| 위험 | 대응 |
+|---|---|
+| 시놀로지 동기 — 작은 파일 많음 · 두 PC 가 같은 조각 동시 만듦 → 충돌 사본 | 안 A(쓰는 곳만) · 미리 만들기는 한 PC |
+| 612 일괄과 CPU · 디스크 다툼 | 미리 만들기는 612 끝난 뒤 · 낮은 우선순위 |
+| 전국 파일 바뀜 | 폴더 이름에 지문 → 새로 쌓임 · 옛 폴더 손으로 지움 |
+| `UI_Layers.ts` 700 줄 턱 | 새 줄은 `UI_MapGl.ts`(384 줄)에 |
+| 옛 캔버스와 GL 등고 모양 다름 | 결정 4 |
+
+사용자 결정 거리:
+
+| # | 물음 | 권함 |
+|---|---|---|
+| 1 | 밀도 — 보통(지금 화면과 비슷 · 5 m 는 줌 15 = 도엽 1~2 장부터) / 촘촘(한 단계 더) | **보통** |
+| 2 | 만들기 — A 처음 볼 때 + z9~12 미리 / B 전국 다 미리(2 GB · 약 3 h) | **A** |
+| 3 | 줌아웃 끝 — z9(화면 약 190 km) / z10(약 96 km) | **z10**(z9 는 500 m 라 쓸모 적음) |
+| 4 | 옛 캔버스 등고 — 606 길 남김 / 없앰(위성처럼) | **남김**(걷기는 나중) |