bigmap-plugin 1.0.6 → 1.0.8

package/README.md

@@ -937,7 +937,7 @@ const layers = getAllLayers()               // 获取全部图层
 
 ### 4.8 等高线显示
 
-**功能简介**：通过替换地表材质，在 **3D 模式** 下叠加彩色等高线（黑色描边 + 彩色主线 + 高程色带），并可按需在当前视区叠加固定高程标签。2D 模式自动关闭。
+**功能简介**：通过替换地表材质，在 **3D 模式** 下叠加彩色等高线（黑色描边 + 彩色主线 + 高程色带），并在开启时自动在等高线上标注高程数字（形如 `1,500 m`）。2D 模式自动关闭。
 
 等高线渲染由随包发布的 `BigemapElevationContourLayer` 完成，**仅在首次开启等高线时动态加载**，地图初始化不加载该脚本。
 
@@ -959,9 +959,19 @@ api.setContourVisible(false)      // 关闭
 
 首次开启时需先加载等高线库，因此返回 `Promise`；库加载失败时开关自动回退为关闭状态。
 
-#### 加载高程标签 `loadContourLabels`
-
-按需读取当前视区地形高程，在跨越的等高线上放置固定高程标签。地图移动 / 缩放不会自动重算，避免持续占用主线程；需先开启等高线。
+**开启后会自动加载并显示当前视区的高程数字**（形如 `1,500 m`，标注间隔 = 等高距 × `labelEvery`）。若此刻地形瓦片尚未加载完成，会每 500ms 自动重试，最长约 10s；关闭等高线或切换 2D 会立即终止重试。
+
+关闭等高线时会**同步清除已显示的高程数字**（不只是隐藏），重新开启后按当前视区重新采样，因此不会出现「等高线关了、数字还留在图上」的残留。切换 2D / 3D 同理：切到 2D 清除，切回 3D 自动恢复。
+
+高程数字依赖「当前视区」的地形，且不会随相机自动跟随，因此**相机停止移动后会自动重算**（防抖 400ms，两次重算最小间隔 1200ms，避免连续拖动时高频采样地形）；移动结束后地形瓦片才补齐的场景也会在地形加载完成时补算。可通过 `refreshOnMove: false` 关闭，改为自行调用 `loadContourLabels`。
+
+每次重算都是**整体替换**：先清空上一视区的数字，再按当前视区重新采样。因此从山区拖动到平原（当前视区没有等高线）时，原来的数字会一并移除，不会残留。
+
+> **高程数字的生成规则**：数字只出现在「地形高度跨越 `等高距 × labelEvery` 整数倍」的位置。默认标注间隔为 150m，若当前视区地形起伏小于该间隔，视区内不会出现任何数字，控制台会给出 `no-results` 提示。例如插件默认视角（成都市区上空 20km、近乎垂直俯视）可见地形高程仅 465~555m，起伏 90m < 150m，因此打开等高线后既没有等高线也没有数字——这与地形图在平原区不出现等高线是同一原因。将地图移动到有起伏的山区 / 丘陵即可看到数字，或调小 `contourSpacing` / `labelEvery`。
+
+#### 加载高程标签 `loadContourLabels`
+
+手动刷新当前视区的高程数字（开启等高线时已自动加载一次，相机停稳后也会自动重算；需要立即刷新时可主动调用）。
 
 ```ts
 const result = await api.loadContourLabels()
@@ -1008,14 +1018,15 @@ api.contourState.value
 | `contourSpacing` | `number` | `150` | 等高距（m） |
 | `contourWidth` | `number` | `2` | 彩色主线宽度（px） |
 | `outlineWidth` | `number` | `2` | 黑色描边宽度（px） |
-| `labelEvery` | `number` | `5` | 每隔多少条等高线显示一个高程标签 |
-| `maxLabels` | `number` | `28` | 当前视区最多显示的高程标签数量 |
+| `labelEvery` | `number` | `1` | 每隔多少条等高线显示一个高程数字（标注间隔 = 等高距 × 该值） |
+| `maxLabels` | `number` | `50` | 当前视区最多显示的高程数字数量 |
 | `labelMinDistance` | `number` | `140` | 标签之间的最小屏幕间距（px） |
 | `labelOutlineWidth` | `number` | `3` | 标签文字描边宽度（px） |
 | `sampleStep` | `number` | `80` | 高程采样步长（px） |
 | `scanStep` | `number` | `120` | 视口扫描步长（px） |
 | `viewportMargin` | `number` | `48` | 视口边缘留白（px） |
-| `legendColorStep` | `number` | `500` | 图例色阶间隔（m） |
+| `legendColorStep` | `number` | `500` | 图例色阶间隔（m） |
+| `refreshOnMove` | `boolean` | `true` | 相机停止移动后是否自动重算高程数字；关闭可省去移动后的地形采样开销 |
 | `minHeight` | `number` | 取色带首节点 | 色带最低高程（m） |
 | `maxHeight` | `number` | 取色带末节点 | 色带最高高程（m） |
 | `colorStops` | `ContourColorStop[]` | 内置 20 级色带 | 高程颜色节点 `{ height, color }`；配置后默认按首尾节点推导高程范围 |