@3clear/basegis 0.1.1 → 0.1.2

package/README.md

@@ -13,17 +13,19 @@
 ## 安装
 
 ```bash
-npm install @3clear/basegis leaflet axios pixi.js leaflet-pixi-overlay
+npm install @3clear/basegis leaflet axios
 ```
 
+`d3-contour`、`pixi.js` 和 `leaflet-pixi-overlay` 已随 BaseGIS 构建产物发布，业务项目不需要单独安装。其中 Pixi 相关代码只在首次使用 Leaflet 海量点能力时按需加载。
+
 使用样式：
 
 ```js
 import '@3clear/basegis/style.css'
 ```
 
-Cesium 当前不随 npm 包发布，宿主项目需要按原项目方式把 Cesium 静态资源放到 `public/lib/Cesium`，并保证初始化前能访问 `window.Cesium`。
-如果需要加载 GeoTIFF 网格，需要宿主项目提前提供 `window.GeoTIFF`。
+Cesium 当前不随 npm 包发布，项目需要按原项目方式把 Cesium 静态资源放到 `public/lib/Cesium`，并保证初始化前能访问 `window.Cesium`。
+如果需要加载 GeoTIFF 网格，需要项目提前提供 `window.GeoTIFF`。
 
 ## 出口
 
@@ -39,6 +41,7 @@ import {
   PointLargeLayerController,
   PointDensityController,
   ContourLayerController,
+  RasterContourController,
   PressureContourLayer,
   createPressureDataResolver,
   buildPressureRenderData,
@@ -281,15 +284,8 @@ const mapCore = new BaseGIS({
 // 创建地图实例。
 mapCore.init()
 
-// 只修改当前运行时引擎配置，不会自动重建地图实例。
-mapCore.setEngine('leaflet')
-
-// 真正切换地图引擎，需要再次 init。
-// init 内部会先销毁旧 adapter，再按新 engineType 创建新地图实例。
-mapCore.init({
-  engineType: 'leaflet',
-  containerId: 'map',
-})
+// 只传目标引擎即可完成切换、视野保留和托管图层恢复。
+await mapCore.setEngine('leaflet')
 
 // 覆盖运行时配置，不会自动重建地图。
 mapCore.setConfig({ view: { defaultSceneMode: '2d' } })
@@ -304,13 +300,33 @@ mapCore.getMapInstance()
 mapCore.destroy()
 ```
 
+Cesium 默认使用最高 2 倍设备像素比、FXAA 和 4 倍 MSAA，避免高分屏上的细线出现明显像素阶梯。可按设备性能覆盖：
+
+```js
+const mapCore = new BaseGIS({
+  config: {
+    engine: {
+      cesium: {
+        renderQuality: {
+          maximumDevicePixelRatio: 1.5,
+          fxaa: true,
+          msaaSamples: 4,
+        },
+      },
+    },
+  },
+})
+```
+
 方法说明：
 
 | 方法 | 参数 | 说明 |
 | --- | --- | --- |
-| `init(options)` | `{ container, containerId, engineType }` | 初始化地图。`container` 可传 DOM，`containerId` 可传 DOM id。 |
-| `destroy()` | 无 | 销毁当前地图实例和 adapter。 |
-| `setEngine(engineType)` | `'cesium'/'leaflet'` | 修改当前引擎类型；不自动重建地图。 |
+| `init(options)` | `{ container, containerId, engineType }` | 初始化地图。重复调用时会自动恢复 BaseGIS 托管图层。 |
+| `setEngine(engineType, options)` | 引擎类型、初始化参数 | 未初始化时记录默认引擎；已初始化时自动切换、保留视野并恢复托管图层。 |
+| `switchEngine(engineType, options)` | 引擎类型、初始化参数 | `setEngine()` 的兼容别名。 |
+| `whenReady()` | 无 | 等待最近一次 `init()` 触发的托管图层恢复完成。 |
+| `destroy()` | 无 | 销毁当前地图实例和 adapter，并清空托管图层快照。 |
 | `setConfig(config)` | `Object` | 合并运行时配置；不自动重建地图。 |
 | `getEngineType()` | 无 | 返回当前引擎类型。 |
 | `getConfig()` | 无 | 返回当前运行时配置。 |
@@ -318,62 +334,55 @@ mapCore.destroy()
 
 #### 推荐的引擎切换写法
 
-页面上做 Cesium / Leaflet 切换时，建议把切换动作收敛成一个函数。`setEngine()` 用来更新 `BaseGIS` 内部引擎类型，`init()` 才是真正重建地图。
+页面上做 Cesium / Leaflet 切换时，直接调用 `setEngine()`。它会保留当前视野、重建目标引擎，并等待托管图层自动恢复。
 
 ```js
-async function switchEngine(engineType) {
+async function changeEngine(engineType) {
   if (!mapCore || mapCore.getEngineType() === engineType) {
     return
   }
 
-  const result = mapCore.init({
-    engineType,
-    containerId: 'map',
-  })
+  const result = await mapCore.setEngine(engineType)
 
   if (!result.success) {
     console.warn(result.message)
     return
   }
-
-  // 地图实例已经重建，业务图层需要用自己的数据源重新加载。
-  await reloadBusinessLayers()
 }
 ```
 
-也可以显式先调用 `setEngine()`：
+直接重复调用 `init({ engineType })` 也会自动开始恢复；如果后续逻辑依赖恢复完成，需要再等待 `whenReady()`：
 
 ```js
-mapCore.setEngine('leaflet')
 const result = mapCore.init({
+  engineType: 'leaflet',
   containerId: 'map',
 })
+
+if (result.success) {
+  await mapCore.whenReady()
+}
 ```
 
-两种写法效果一致；如果 `init({ engineType })` 已经传了目标引擎，可以不单独调用 `setEngine()`。
+`switchEngine()` 作为兼容别名保留，行为与 `setEngine()` 一致。
 
 #### 切换后的图层处理
 
-引擎切换不是把 Cesium 图层“搬到” Leaflet，也不是把 Leaflet 图层“搬到” Cesium。`init()` 重建地图时会销毁旧引擎实例，因此：
+引擎切换不是把 Cesium 图层对象“搬到” Leaflet，也不是把 Leaflet 图层对象“搬到” Cesium。BaseGIS 会保存托管图层的业务参数，并在新 adapter 中重新创建图层。
 
-- `BaseGIS` 的配置会保留，例如 `config / initialView / basemap`。
-- 业务数据应由页面或 store 保存，例如站点数组、图片地址、等值线数据、风场数据。
-- 切换成功后，用这些业务数据重新调用对应 Controller 的 `load/update`，或重新调用 `BaseGIS` 图层方法。
+- 自动恢复范围包括图片、网格、海量点、点位抽稀、等值线和三维体图层，对应 `upsert*Layer` 方法及 Controller。
+- 图层最新的数据参数、显隐、清空、删除、海量点删除和高亮状态会同步到 BaseGIS 快照。
+- 快照只保存业务参数引用，不复制大数组，不保存任何底层引擎对象。
+- 三维体图层切到 Leaflet 时会返回不支持结果，但快照仍保留，切回 Cesium 后会继续恢复。
 - Cesium 专有能力在 Leaflet 下不可用，例如 DEM、三维体渲染、三维切片/剖面渲染。
-- 页面层不应直接依赖 Cesium / Leaflet 分支；如果确实要访问底层实例，只在边界很清楚的地方使用 `getMapInstance()`。
+- 一次性绘制对象、点击监听、风场、剖面图层和页面直接操作底层引擎创建的对象不在托管范围内，需要业务自行恢复。
 
-常见重载示例：
+切换结果中可以查看恢复明细：
 
 ```js
-async function reloadBusinessLayers() {
-  await imageLayer.update(currentImagePayload)
-  await pointLayer.load({ points: currentPoints })
-  await contour.load(currentContourPayload)
-
-  if (mapCore.getEngineType() === 'cesium') {
-    mapCore.upsertVolumeLayer(currentVolumePayload)
-  }
-}
+const result = await mapCore.setEngine('leaflet')
+console.log(result.data.restore.restored)
+console.log(result.data.restore.failed)
 ```
 
 
@@ -1444,6 +1453,8 @@ if (result.success) {
 
 用于海量点位渲染。它会尽量把传入的有效点位全部渲染出来，适合站点、设备、告警、监测点等需要保留全部点位并支持点击、高亮、删除、显隐的场景。
 
+Leaflet 模式使用 BaseGIS 内置的 `pixi.js` 和 `leaflet-pixi-overlay` 异步渲染，业务项目无需安装这两个依赖；Cesium 模式不加载 Pixi 相关代码。
+
 如果业务目标是“地图缩小时按屏幕网格抽稀，只显示代表点”，应使用后文的 `PointDensityController`。
 
 ### Demo 位置
@@ -2189,6 +2200,8 @@ await contour.load({
     color: '#ff4d4f',
     width: 2,
   },
+  showLabel: true,
+  labelFormatter: (item) => String(item.value),
 })
 
 await contour.update({
@@ -2203,7 +2216,182 @@ contour.clear()
 contour.destroy()
 ```
 
-数据别名支持 `contours / isolines / isoline / lines / data / items`。
+数据别名支持 `contours / isolines / isoline / lines / data / items`。开启 `showLabel` 后，Cesium 和 Leaflet 都会根据当前屏幕范围重新选择可见线段上的位置；地图平移、缩放、容器尺寸变化或切换引擎时只重排标签，不重新生成等值线。
+
+Cesium 在默认椭球地表上使用 `PolylineCollection` 批量落图；真正启用 DEM 地形后才使用 `GroundPolylinePrimitive`。新批次就绪后再替换旧批次，不为每条线创建独立 Entity。标签定位可通过 `labelLineThinStep` 抽样投影点，不会改变实际绘制的等值线。
+
+Leaflet 默认复用高精度 SVG renderer，并使用 `smoothFactor: 0.5` 做屏幕空间简化：缩小时清理挤在同一像素内的折点，放大后自动保留曲线细节，避免全局 `preferCanvas` 放大细线锯齿。线位于 `dt-contour-pane`（层级 `450`），稳定显示在图片图层上方，并保持在 `markerPane` 数值标签下方；显式传入 `pane` 时仍以业务配置为准。
+
+屏幕标注参数：
+
+| 参数 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `showLabel/showLabels` | `boolean` | `false` | 是否显示等值线数值。 |
+| `labelFormatter(item, record)` | `Function` | 等值级别 | 格式化标签文本。 |
+| `labelColor` | `string` | `#34464f` | 文字颜色。 |
+| `labelBackgroundColor` | `string` | `rgba(255,255,255,0.78)` | 背景色。 |
+| `labelBorderColor/labelBorderWidth` | `string/number` | `rgba(93,112,116,0.35)` / `0.5` | 边框颜色和宽度。 |
+| `labelBorderRadius` | `number` | `8` | 圆角，单位 px。 |
+| `labelFontSize/labelFontWeight` | `number/string` | `10/600` | 字号和字重。 |
+| `labelPaddingX/labelPaddingY` | `number` | `4/0` | 标签内部留白。 |
+| `labelMinWidth` | `number` | `32` | 标签最小宽度，短数值保持横向胶囊形状。 |
+| `labelViewportPadding` | `number/object/Function` | `24` | 屏幕安全边距；对象为 `top/right/bottom/left`，函数接收 `{width,height}`。 |
+| `labelMinScreenLength` | `number` | `72` | 可见线段达到该像素长度后才允许放标签。 |
+| `labelLineThinStep` | `number` | Cesium `3`，Leaflet `1` | 标签定位时的投影抽样步长，不影响实际线几何。 |
+| `labelCollisionPadding` | `number` | `7` | 标签碰撞间距。 |
+| `labelMaxPerLevel` | `number` | `Infinity` | 每个等值级别在当前视野中的标签上限；默认按可见线数量自动决定。 |
+| `labelDisableDepthTestDistance` | `number` | `Infinity` | Cesium 标签关闭深度检测的距离。 |
+
+`getState()` 的 `labelCount` 是当前视野实际显示的标签数量。Cesium 状态额外包含 `lineRenderer/lineBuildElapsed/labelLayoutElapsed/primitiveReadyElapsed`，用于区分线构建、标签排版和异步就绪耗时。`onStateChange(state)` 会在视野重排后回传新状态。页面存在侧栏等遮挡时，可通过 `labelViewportPadding` 排除对应区域。
+
+## RasterContourController
+
+用于从 GeoTIFF、灰度图或数值网格直接计算并绘制等值线。内部统一使用 `d3-contour` 追踪等值线，输出仍交给 `ContourLayerController`，所以页面不需要区分 Cesium 和 Leaflet；调用 `BaseGIS.setEngine()` 时，已经生成的等值线会随托管图层自动恢复。
+
+### 1. GeoTIFF 生成等值线
+
+```js
+import { RasterContourController } from '@3clear/basegis/methods'
+
+const rasterContour = new RasterContourController({
+  mapCore,
+  layerId: 'temperature-raster-contour',
+  // thresholds / interval / thresholdCount 三选一。
+  interval: 5,
+  smooth: true,
+  visible: true,
+})
+
+const result = await rasterContour.loadGeoTiff({
+  tifUrl: '/data/temperature.tif',
+  // TIF 范围不准确时可用 WGS84 四至覆盖文件元数据。
+  area: {
+    startLon: -180,
+    startLat: -90,
+    endLon: 180,
+    endLat: 90,
+  },
+  band: 0,
+  interval: 5,
+  clampToGround: true,
+  showLabel: true,
+  labelFormatter: (item) => String(Math.round(item.value)),
+  labelViewportPadding: { top: 32, right: 32, bottom: 32, left: 360 },
+  styleCallback: (item) => ({
+    color: item.value >= 30 ? '#ff6b6b' : '#d5f4ff',
+    width: item.value % 10 === 0 ? 2 : 1,
+    weight: item.value % 10 === 0 ? 2 : 1,
+  }),
+})
+
+if (!result.success) {
+  console.warn(result.message)
+}
+
+// 仅调整等值距时复用已解析网格，不再请求和解码 TIF。
+await rasterContour.update({ interval: 2 })
+```
+
+GeoTIFF 依赖宿主页面提供 `window.GeoTIFF`。控制器会读取波段、尺寸、坐标系和范围；当前原生支持 EPSG:4326、EPSG:3857。其他投影可先转换为 WGS84，或传入 WGS84 `area` 覆盖原始范围。
+
+### 2. 灰度图生成等值线
+
+```js
+await rasterContour.loadGrayImage({
+  grayImageUrl: '/data/pressure-gray.png',
+  area: [-180, -90, 180, 90],
+  grayMinValue: 0,
+  grayMaxValue: 255,
+  minValue: 960,
+  maxValue: 1040,
+  noDataValue: 255,
+  interval: 4,
+})
+```
+
+灰度换算规则：
+
+```text
+业务值 = (灰度值 - grayMinValue) / (grayMaxValue - grayMinValue)
+       * (maxValue - minValue) + minValue
+```
+
+灰度图片本身没有地理范围和业务值含义，因此 `area` 必填；要表达真实数据，还应传正确的灰度范围与业务值范围。已经着色的彩色 PNG 不能反推出原始业务值，应使用对应 TIF 或直接传数值网格。
+
+### 3. 数值网格生成等值线
+
+```js
+await rasterContour.loadGrid({
+  values: [12, 14, 16, 18, 20, 22],
+  width: 3,
+  height: 2,
+  area: [100, 20, 103, 22],
+  thresholds: [15, 20],
+})
+
+// values 也可以直接传二维数组，此时不需要 width / height。
+await rasterContour.loadGrid({
+  values: [
+    [12, 14, 16],
+    [18, 20, 22],
+  ],
+  area: [100, 20, 103, 22],
+  thresholdCount: 6,
+})
+```
+
+### 4. 参数
+
+数据源参数：
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- | --- |
+| `mapCore/baseGIS` | `BaseGIS` | 构造时必填 | `null` | 当前 BaseGIS 实例。 |
+| `layerId/contourLayerId` | `string` | 否 | `raster-contour-default` | 等值线图层 id。 |
+| `sourceType` | `geotiff/grayscale/grid` | 否 | 自动判断 | `loadGeoTiff/loadGrayImage/loadGrid` 会自动补齐。 |
+| `tifUrl/tiffUrl` | `string` | GeoTIFF 必填 | `''` | GeoTIFF 地址。 |
+| `arrayBuffer` | `ArrayBuffer` | 否 | `null` | 可代替 `tifUrl` 直接传 TIF 内容。 |
+| `band` | `number` | 否 | `0` | GeoTIFF 波段下标，从 0 开始。 |
+| `imageIndex` | `number` | 否 | `0` | 多图像 GeoTIFF 的图像下标。 |
+| `grayImageUrl/imageUrl` | `string` | 灰度图必填 | `''` | 灰度图地址，服务端必须允许 Canvas 跨域读取。 |
+| `values/data/grid` | `Array/TypedArray` | 数值网格必填 | - | 一维或二维数值。 |
+| `width/height` | `number` | 一维网格必填 | `0` | 一维数组的网格尺寸。 |
+| `area` | `object/number[]` | 图片和普通网格必填 | `null` | WGS84 范围；数组顺序为 `[west,south,east,north]`。 |
+| `sourceProjection` | `string` | 否 | 自动读取 | 支持 `EPSG:4326`、`EPSG:3857`。 |
+| `noDataValue` | `number` | 否 | TIF 自动读取 | 指定无效值；灰度图不传时仅透明像素无效。 |
+| `validMin/validMax` | `number` | 否 | - | 过滤值域外数据。 |
+| `scale/offset` | `number` | 否 | `1/0` | 数值换算为 `value * scale + offset`。 |
+| `isSplit` | `boolean` | 否 | `false` | 把左右半幅交换，处理以 0° 经线为边界的全球数据。 |
+
+等值线参数：
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- | --- |
+| `thresholds/levels` | `number[]` | 三选一 | - | 显式等值线级别，仅保留实际值域内的值。 |
+| `interval/contourInterval` | `number` | 三选一 | - | 固定等值距。 |
+| `thresholdCount/levelCount` | `number` | 三选一 | `12` | 自动均分级别数量，范围 1~100。 |
+| `smooth` | `boolean` | 否 | `true` | 是否平滑等值线。 |
+| `smoothingIterations` | `number` | 否 | `0` | Chaikin 补点平滑次数，范围 0~3；气象格点通常取 1~2，次数越高，点数越多。 |
+| `excludeBoundary` | `boolean` | 否 | `true` | 去掉 d3 面边界中贴着栅格四边的伪矩形线。 |
+| `maxCells` | `number` | 否 | `1000000` | 超过该像元数时先等比例抽样，避免大图阻塞页面。 |
+| `minimumLinePoints` | `number` | 否 | `3` | 最短线点数，用于过滤栅格四角的两点补边。 |
+| `coordinatePrecision` | `number` | 否 | `6` | 输出经纬度小数位数。 |
+| `visible` | `boolean` | 否 | `true` | 初始显隐。 |
+| 其他渲染参数 | - | 否 | - | 与 `ContourLayerController` 相同，如 `color/width/weight/styleCallback/showLabel/labelViewportPadding`。 |
+
+### 5. 方法和状态
+
+| 方法 | 说明 |
+| --- | --- |
+| `load(payload, options)` | 自动判断数据源并生成等值线。 |
+| `loadGeoTiff(payload, options)` | 从 GeoTIFF 生成。 |
+| `loadGrayImage(payload, options)` | 从灰度图生成。 |
+| `loadGrid(payload, options)` | 从数值网格生成。 |
+| `update(payload)` | 合并配置后重新计算；仅修改等值线或渲染参数时复用已解析网格，修改数据源参数时自动重新加载。 |
+| `show/hide/toggle` | 控制等值线显隐。 |
+| `clear/destroy` | 清空或销毁控制器。 |
+| `getState()` | 返回尺寸、值域、级别、线数、当前标注数、投影、耗时和底层 contour 状态。 |
+| `getRasterData()` | 返回当前标准栅格，包含 `values/width/height/area`。 |
 
 [//]: # ()
 [//]: # (## PressureContourLayer)
@@ -2460,20 +2648,19 @@ export function useBaseGIS(options = {}) {
     mapCore.value = null
   })
 
-  function switchEngine(engineType) {
+  async function setEngine(engineType) {
     if (!mapCore.value || mapCore.value.getEngineType() === engineType) {
       return { success: true }
     }
 
-    return mapCore.value.init({
+    return mapCore.value.setEngine(engineType, {
       ...options,
-      engineType,
     })
   }
 
   return {
     mapCore,
-    switchEngine,
+    setEngine,
   }
 }
 ```
@@ -2488,22 +2675,22 @@ export function useBaseGIS(options = {}) {
 <script setup>
 import { useBaseGIS } from './useBaseGIS'
 
-const { mapCore, switchEngine } = useBaseGIS({
+const { mapCore, setEngine } = useBaseGIS({
   engineType: 'cesium',
   containerId: 'map',
 })
 </script>
 ```
 
-如果页面有业务图层，`switchEngine()` 成功后要重新加载图层数据：
+BaseGIS 托管图层会自动恢复，页面不需要重新请求数据：
 
 ```js
-const result = switchEngine('leaflet')
-if (result.success) {
-  await reloadBusinessLayers()
-}
+const result = await setEngine('leaflet')
+console.log(result.data?.restore)
 ```
 
+只有风场、剖面、一次性绘制对象或页面直接创建的底层引擎对象需要在切换成功后自行恢复。
+
 ## 能力支持说明
 
 | 能力 | Cesium | Leaflet |
@@ -2634,18 +2821,13 @@ mapCore.init()
 
 ### 切换引擎后图层没了
 
-这是预期行为。Cesium 和 Leaflet 的图层对象不能互相复用，`init({ engineType })` 会销毁旧地图实例并创建新地图实例。
-
-处理方式是：页面或 store 保存业务数据，切换成功后重新调用对应的加载方法。
+直接使用 `setEngine()`。BaseGIS 会保留视野，并自动恢复图片、网格、海量点、点位抽稀、等值线和三维体等托管图层：
 
 ```js
-const result = mapCore.init({
-  engineType: 'leaflet',
-  containerId: 'map',
-})
+const result = await mapCore.setEngine('leaflet')
 
-if (result.success) {
-  await imageLayer.update(currentImagePayload)
-  await pointLayer.load({ points: currentPoints })
-}
+console.log(result.data?.restore?.restored)
+console.log(result.data?.restore?.failed)
 ```
+
+如果丢失的是 `drawPoint/drawLine/drawPolygon/drawText/addMarker`、点击监听、风场、剖面图层或页面直接创建的 Cesium / Leaflet 对象，它们不属于托管图层，需要业务在切换成功后自行恢复。