# 地圖向量資料

這些是靜態背景與定位資料，與每小時更新的水庫水情快取分開。

| 檔案 | 內容 |
| --- | --- |
| `land.geojson` | 22 縣市的陸地面合併後外形，保留澎湖、金門、馬祖及其他離島與內部洞 |
| `coastline.geojson` | 合併後各陸地面的外環線；不含縣市內界與湖泊洞邊線 |
| `rivers.geojson` | 水利署河道面，保留名稱、河川代碼、原始列號與河道類別 |
| `reservoirs.geojson` | 本頁 21 座水庫的官方堰壩點位，依名稱一對一對應 |
| `manifest.json` | 來源、授權可確認情況、座標系、簡化設定、幾何數量與 SHA-256 |

所有輸出為 EPSG:4326，座標順序是 `[經度, 緯度]`。水庫點是官方堰壩位置，不是水面中心；`sourceId` 對應官方 `SHP_ID`，`reservoirCode` 對應非零 `COMPARE_ID`。湖山的官方 `COMPARE_ID` 為 0，因此其 `reservoirCode` 為 `null`，請用 `name` 與水情資料配對。

陸地資料包含遠端離島，不能直接用整份資料的 bounds 設定初始視窗；manifest 的 `defaultViewBounds` 僅是本島與澎湖主視窗建議，金門、馬祖等可另設定位／小圖。

## 重新產製

需要 Python 3.10+、系統 GDAL/OGR Python bindings、pyproj 與 Shapely 2；不需安裝 Node 套件或啟動 GIS 伺服器。從任何工作目錄執行：

```bash
python3 /var/www/html/demo/php/3waTacticalWaterReliefMap/scripts/build_map_data.py
```

正式輸出及程式預設使用國土測繪中心官方縣市 SHP。河道優先沿用本機既有官方 `RIVERPOLY.zip`，不存在時下載官方 SHP；水庫點位由官方小型 SHP ZIP 取得。下載快取位於系統暫存目錄 `3wa-water-map-geodata-v1`，不加入 Git；每次下載有 timeout、時間與大小上限，拒絕非 ZIP 回應。可以指定 `--cache-dir`，清除相應 ZIP 後才會重新抓取；既有快取可重複產製同一版本，SHA-256 記在 manifest。`--local-counties` 才會明確選擇 `/var/www/html/data/city.json` 備案，並在 manifest 標示其來源授權未驗證。

```bash
# 明確指定官方來源（與預設相同）
python3 scripts/build_map_data.py --official-counties

# 依需要調整在投影座標系中的簡化容許值（公尺）
python3 scripts/build_map_data.py --land-tolerance 35 --river-tolerance 15
```

陸地先合併消除縣市內界，再做最多 35m 的保留拓樸簡化；河道從 EPSG:3826 做最多 15m 簡化後轉成經緯度。若細小離島簡化後產生巢狀／相交外環或改變洞數，程式減半容許值重試，仍無法通過時保留原形；實際使用值記在 manifest。簡化值是 EPSG:3826 投影中的幾何容許值，不能當作現地測量精度。程式檢查島嶼／洞數、輸出幾何有效性、21 座水庫唯一匹配，失敗時不產出新 manifest。座標一般保留六位小數，極細小圖形必要時增加精度，避免小島或洞因四捨五入消失。

## 來源與授權

- 陸地正式來源為[國土測繪中心縣市界線資料集](https://data.gov.tw/dataset/7442)、[官方下載頁](https://maps.nlsc.gov.tw/pro/download.jsp)，原始 EPSG:3824，適用政府資料開放授權條款第 1 版。備案 `city.json` 沒有附版本／來源／授權欄位，只有明確使用 `--local-counties` 時才讀取，並標示為未驗證，不能僅由相似欄位宣稱其授權。
- 河道：[經濟部水利署「河川河道」](https://data.gov.tw/dataset/25781)，[官方 SHP](https://gic.wra.gov.tw/gis/gic/API/Google/DownLoad.aspx?fname=RIVERPOLY&filetype=SHP)。本地 ZIP 的來源另有既存雨量圖專案建置紀錄支持。官方資源 metadata 標示統計年度 2000；入口網頁近期更新不是重新測繪年份。
- 水庫點：[經濟部水利署「水庫堰壩位置圖」](https://data.gov.tw/dataset/25776)，[官方 SHP](https://gic.wra.gov.tw/gis/gic/API/Google/DownLoad.aspx?fname=SWRESOIR&filetype=SHP)。官方資料包含 98 個點，本頁選用 21 個；不以 ZIP 修改時間冒稱測繪年份。
- 水利署兩份資料適用[政府資料開放授權條款第 1 版](https://data.gov.tw/license)，保留來源標示。河道為公開參考圖資，不代表法定河川界點；資料面亦不是河川中心線。

下載與轉換不需 API key。地理資料不需跟隨每小時水情 cron 重複下載；來源改版時才重新產製並檢查 manifest。


## 官方燈塔／航標

`lighthouses.geojson` 來自交通部航港局「燈塔燈質表」，[資料集 28142](https://data.gov.tw/dataset/28142)，授權為[政府資料開放授權條款第1版](https://data.gov.tw/license)。原始 CP950 CSV 保存於 `source/lighthouses-mpb.csv`，於 2026-10-15 下載，資料集詮釋資料更新日為 2026-07-23（非逐站觀測時間）。輸出 metadata 包含固定下載 URL、SHA-256、授權與數量；不使用 mapped.earth 的素材或整理後資料，該頁僅作視覺參考。

共 79 筆燈塔與航標，包含臺灣、澎湖、金門、馬祖及太平島。全台預設視窗不因遠端離島而縮小；港口燈杆在 zoom 8.5 起顯示。原始表未標明座標基準，本頁直接將其經緯度 DMS 轉十進位作展示，不宣稱測量精度。燈高並非塔身高度，保留原始文字與多燈內容。來源未列編號的太平島採 `local-` 名稱雜湊作程式識別碼，bubble 仍顯示來源編號未提供。

```bash
python3 scripts/build_lighthouses.py
python3 tests/lighthouses_test.py
```

轉換器只讀本地 CSV，不自動抓網路。若更新來源，先取得同一官方下載 URL 的 CSV，重新轉換並檢查差異後發布；沒有高頻排程需求。明暗秒數加總必須符合週期且燈色可確定才建立動畫，目前 62 筆符合；球子山有「暫停發光」註記，保持灰色靜態。只有週期、缺明暗細節、多色扇區無法判定方向及定光不模擬明暗節奏。淡水港僅展示完整列明的主燈節奏，導燈原文留在 bubble。白沙岬按明列的紅／白交替節奏顯示。

動畫使用來源明暗時長，加入短暫柔化邊緣；另加持續 360° 旋轉扇形光束，每 12 秒一圈；畫面半徑隨縮放調整並限制於 48–240px，不代表公稱光程、實際方向或地形遮蔽。起始相位與光暈為示意，不能表示現地是否亮燈或作航行導航。暫停發光也是來源表快照，非即時狀態。既有 DEM 山脈陰影保持不變，地圖移動與隱藏頁面時停止特效。