日月潭環湖自行車道(主線,閉合一圈)

狀態:2026-09-25 完成主線、地形接合、Blender 母檔 blender/lake-bikeway-v01.blend、網頁分塊與碰撞、walk/bikeway.js。 2026-09-25 已接進 walk/main.js 並上線;2026-09-26 加上路邊植被與近地面質感(§11)。

座標一律是 walk 執行期座標:x 往東、y 向上、z 往南(公尺);原點 向山 E240030.107 N2638540.908(TWD97),y=0 為 TWVD2001 763.55 m,湖面 y = -15.55。

1. 路線

來源

項目 來源
環潭約 30 km、順時針、經頭社、「自行車道尚未串接完成,建議沿環潭公路騎乘」 日月潭國家風景區管理處「日月潭自行車道-環潭路線」(page_updated 2025-12-03,2026-09-25 取回,.cache/bikeway-review/sources/smla-134.md)
向山段 3.4 km、水上自行車道 0.4 km、永結橋與同心橋「以白色橋墩和木製步道組成」 管理處「日月潭自行車道-向山段」(smla-18.md)
各段長度、水社壩木棧道「禁止騎乘,請牽行」、月潭段牽行、險升降坡 日月潭自行車旅遊網 ComeBikeDay(觀光署日月潭管理處)comebike-323~328.md
路線線形、橋隧與鋪面標籤、名稱 OpenStreetMap(ODbL),walk/assets/region-osm.json,快照 2026-09-22T08:45Z
縱斷面參考高程 內政部 20 m DTM(2020-07 LiDAR),data/processed/sun-moon-lake-dtm20.npz
抓網頁一律 curl -s https://r.jina.ai/<url>,User-Agent 不含任何個資。照片只當參考。

推估(全部也列在 bike-loop.json 的 estimates)

2. 縱斷面

3. 地形接合(scripts/terrain_edits.py,通用工具)

工具做什麼

從原始地形層一次套用所有編輯規格,產生衍生檔(不覆寫原檔): - 讀:walk/assets/campus-ecology.glb(區域地形 terrain-upland/terrain-shore 主網格、向山園區草坪 ground)、walk/assets/region-town.glb(舊 OSM 路面 asphalt/paving/road-line/rail)、walk/assets/region-town-collision.bin。 - 寫:campus-ecology-<suffix>.glb、region-town-<suffix>.glb、region-town-<suffix>-collision.bin、terrain-<suffix>.json(規格、改動面數、原檔與新檔 SHA-256)。 - 做法:各規格決定範圍與約束 → 在「全部範圍的聯集」重新做受約束 Delaunay 三角化、依約束求高程、平面簡化 → 切開原網格並用原網格邊界高程接回(共點、不留縫)→ 同一批三角面寫進碰撞(視覺與碰撞一起改)。範圍內的舊 OSM 路面剔除,其餘舊路面依新地形重貼。 - 不可改:水社精修地形小塊(< 8000 面的 terrain 小塊)、各 Blender 精修地面(dellago、waterfront、ecology-ground…)、建築。

輸入格式

規格檔是含 "terrain_edits" 陣列的 JSON(或直接一個陣列),可以一次給多檔。y 為 walk 座標。

{"terrain_edits": [
  {"kind": "pad", "name": "文武廟前庭", "polygon": [[2540, -2039], [2593, -2039], [2593, -2003], [2540, -2003]],
   "height": 55.0, "cut_slope": 1.0, "fill_slope": 1.5, "extent": 30, "owner": "temple"}
]}

執行方式(總腦一次跑全部)

.venv/Scripts/python.exe scripts/terrain_edits.py --suffix edited data/processed/terrain-edits/bike-loop.terrain.json <寺廟 pad 規格.json> [...]

約 1–1.5 分鐘。之後重跑驗收:node scripts/audit_bike_loop.mjs --sim --walk --out <報告>、.venv/Scripts/python.exe scripts/audit_bikeway_visual.py、node --test walk/tests/bikeway.test.mjs。 實測:路廊+一塊 36×20 m 測試 pad(文武廟南側、55.05 m、延伸 25 m)一起跑,pad 內高程全為 55.05、外圍填方 1:1.5、挖方 1:1 都對,矛盾 0(測試輸出已刪)。 路廊本身要重算(路線或縱斷面改了)時:scripts/build_bike_loop.py → scripts/build_bikeway_terrain.py(產生路廊資料、規格並呼叫 terrain_edits)→ scripts/export_bikeway_collision.py → Blender 母檔(新版號)→ scripts/finalize_bike_loop.py。

本次改動(walk/assets/terrain-edited.json)

檔案 原檔 SHA-256(位元組) 衍生檔 SHA-256(位元組)
campus-ecology.glb → campus-ecology-edited.glb 47f44e4a…2e53e(33,048,392) 0bb9b523…99a9(36,906,656)
region-town.glb → region-town-edited.glb 20448aed…20f8(53,898,364) 48200160…0fa0(53,199,680)
region-town-collision.bin → region-town-edited-collision.bin 31697d7f…7e16(8,863,380;246,205 面) c1b79517…4f0f(14,823,612;411,767 面)
- 改動範圍 1.65 km²;新地形 185,228 面/96,454 點(平面簡化後);原地形/草坪移除 13,900 面、切邊補片 8,809 面。
- 舊 OSM 路面:視覺剔除 176,913 面、重貼 65,130 面;碰撞剔除 14,559 面、重貼 4,781 面。三角面比對改成「質心+逐點 4 mm」(碰撞檔是 1 mm 捨入,舊的 2 cm 分箱會漏掉約 1/6,曾造成舊路面浮在新路面上)。
- 水社碼頭:區域層有 16 片只有碰撞、沒有視覺的碼頭邊護牆橫跨水社步道(精修步道後來蓋過去),騎到會撞停,已從衍生碰撞刪除。
- 擋土牆(長度 m,最高):挖方左 2,800(8.0 m)、挖方右 479(5.5 m)、填方左 1,000(7.0 m)、填方右 5,709(5.75 m)。護欄:左 9,412 m、右 23,779 m。

4. 障礙清理

5. Blender 母檔與網頁資產

6. 驗收結果(2026-09-25 最後一輪,全部前景跑完)

7. 整合(walk/bikeway.js 檔頭有完整 API)

  1. 世界檔:campus-ecology.glb → campus-ecology-edited.glb、region-town.glb → region-town-edited.glb;COLLISION_ASSETS 的 region-town-collision.bin → region-town-edited-collision.bin,再加 bikeway-collision.bin(完整清單 bike-loop.json integration.collision_assets_after)。
  2. 單車與步行的湖面(必接):bindBikeWater(bike, loop)(BikePhysics 把低於湖面的地面都當湖岸擋住)、bindWalkerLake(walker, loop)(Walker 在 y < -15.1 一律擋住)。不接的話頭社盆地 4.8 km 騎不進去也走不進去。湖面範圍 = 園區湖面網格聯集(bike-loop.json lake_cover)。為此在 walk/physics.js 加了 Walker.lakeFloorAt 掛鉤(預設 null=原本 -15.1 行為;備份 walk/physics.js.bak_20260925);walk/bicycle.js 未改(包 step)。
  3. 樹:loop.treeBlocked(x, z, r) 加在 cullTreesOnRoads/園區樹實例剔除旁。
  4. 場景:new Bikeway(scene, loop, {renderer, install: installScene, quality: tier}),每幀 update(camera.position, tier),暮色 setNight。
  5. 小地圖 loop.mapRoute();環湖進度 loop.progress(x, z, heading)、loop.tracker();上車點 loop.places、loop.stationAt(s)。
  6. 注意 seams.js 的 cullRegionalOverlaps 在執行期還會剔除園區範圍內的區域路面,對衍生檔一樣適用(稽核未模擬這一步,新路面碰撞在 bikeway-collision.bin,不受影響)。

8. 已知缺口(誠實列)

9. 授權

10. 檔案

11. 路邊植被與近地面質感(2026-09-26)

12. 對照實景:外觀、湖面、出生點(2026-09-26 晚)

出生點與名稱

外觀(scripts/bikeway_geometry.py)

地形:水社壩平鋪、橋下是水(scripts/bike_corridor.py)

轉角:修圓+外側加寬(bike_corridor.widen_bends())

路邊植物(scripts/place_roadside.py)

產物

驗收

缺口

13. 路口支線與湖底(2026-09-27,v07)

老闆在 5.28 km 水社段截圖問「步道到這邊就斷掉了?正常嗎?」。

路線本身是對的

錯的是路口

做法(bike_corridor.road_stubs() → terrain_edits.StubEdit)

湖底加深(scripts/deepen_lake_bed.py,同時為了游泳)

驗收

缺口

14. 效能大優化與向山路板(2026-09-27,v08)

為什麼

做法

驗收

項目 前 後
JS heap(載入完,強制 GC) 2,450 MB 61 MB
載入到可玩(本機) 70 秒以上 約 18 秒
碰撞建樹 約 70 秒 約 2.5 秒
300 km/h 一圈:>100 ms 的幀 60 16
300 km/h 一圈:最長一幀 3.3 秒 0.28 秒
測試整套 約 20 分鐘 約 2.5 分鐘
整圈騎乘稽核 67 秒 8 秒

14.1 載入再加速(2026-09-27 夜;2026-09-28 上線)

項目 舊(v08 閘門+載入中照畫) 新
載入到可玩 18.5–27.0 秒 9.2–11.4 秒(建站壓縮版 10.3 秒)
一圈 >100 ms 的幀(中位數) 約 29 約 21–24
文武廟一帶顯示卡記憶體(全機) 6.7 GB 5.8 GB

14.2 載入第三輪(2026-09-28 已上線)

項目 v09 新
到可玩 19.9–21.3 秒 18.5–19.1 秒
可以騎後第一幀(畫面能回應) 22.4–23.8 秒 19.4–20.0 秒
「準備碰撞 → 可以騎」 約 3.7–3.9 秒 約 2.4 秒
顯示卡編譯執行緒在上面那段的工作量 41 秒 CPU 20 秒 CPU

14.3 載入第四輪(2026-09-28 上線)

項目 v10(線上) 新
到可玩(40 MB/s) 7.39 秒 6.86 秒
畫面能回應(40 MB/s) 8.13 秒 7.02 秒
到可玩(10 MB/s) 18.6–19.0 秒 18.1–18.3 秒
畫面能回應(10 MB/s) 19.3–19.8 秒 18.2–18.5 秒
結尾要編的著色器 43 支、約 1.6 秒 12 支、約 0.7 秒
可以騎後第一幀的貼圖上傳 0.66 秒 0.14 秒

14.4 第四輪續:偶發數秒停頓(2026-09-28 上線)

項目 舊 新
畫質選單切到 low 的最長一幀 5.0 秒 0.18 秒(約 2 秒後生效)
機器被佔滿時 300 km/h 一圈的最長停頓(各 2 趟,都掉到 low) 19.0、8.0 秒 1.1、0.75 秒
同上,超過 3 秒的停頓 6、2 次 0、0 次
文武廟那段超過 150 ms 的幀(各 1 趟) 6 2

14.5 文武廟效能大優化(2026-09-29 上線)

視點(高畫質 1600×900) 線上版 新版
牌樓前 11 fps 90 fps
廟埕巨獅 18 fps 111 fps
拜殿內 15 fps 100 fps
武聖殿內 25 fps 109 fps
大成殿內 30 fps 125 fps
後山櫺星門 12 fps 68 fps
觀景台 32 fps 120 fps
項目 線上版 新版
跳到後山到細節模型合併完成 70 秒 20 秒
40 km/h 騎過文武廟,超過 50 ms 的幀 302 25
同上,最長一幀 591 ms 152 ms
同上,第二趟(都載好了) 242 1
300 km/h 整圈的幀數 26,644 38,412
同上,超過 100 ms 的幀 11 4

14.6 文武廟效能第二輪(2026-10-01 做,10-02 上線)

項目 線上版 新版
跳到拜殿,細節模型到齊 5.3–5.5 秒 3.6–5.0 秒
同上,合併完成 16.9–18.0 秒 10.5–12.1 秒
近景多佔的顯示卡記憶體 約 1,030 MB 約 600 MB
40 km/h 騎過文武廟,超過 100 ms 的幀 5–7 1
同上,最長一幀 162–169 ms 101–115 ms
同上,平均每秒格數 97–107 113–121

缺口