@mesh3d/cesium-vectortile-gl 0.4.6 → 0.5.2

package/README.md

@@ -13,6 +13,7 @@
 - ✅ **GPU 精准剔除**：利用 FBO + RTT 技术生成瓦片 ID 纹理，在 GPU 中高效剔除不可见矢量片段
 - ✅ **高度可扩展**：提供清晰接口，轻松接入新数据源（如 TopoJSON）或自定义图层类型（如热力图、流线）
 - ✅ **文字符号自动避让**：使用 `maplibre-gl` `GridIndex`类，结合 Cesium.Label 屏幕空间位置和包围盒计算API，实现符号碰撞检测（自动避让）
+- ✅ **样式动态修改**：提供`setLayoutProperty`、`setPaintProperty`、`setFilter`等`样式修改API`，可动态控制图层`显隐`、`颜色`、`透明度`
 
 #### 🧠 技术栈亮点
 
@@ -83,6 +84,34 @@ const tileset = new VectorTileset({
 viewer.scene.primitives.add(tileset)
 ```
 
+### 样式修改示例
+
+```js
+tileset.readyEvent.addEventListener(() => {
+  // 1、修改绘制属性（颜色、透明度），不会触发强制刷新，实时变化
+  tileset.setPaintProperty('background', 'background-color', 'skyblue')
+  tileset.setPaintProperty('geolines', 'line-color', 'green')
+  tileset.setPaintProperty('us_states:fill', 'fill-color', 'red')
+  tileset.setPaintProperty('countries-label', 'text-color', 'blue')
+
+  // 2、修改布局属性，除 visibility 外，都会触发强制刷新
+  // 2.1、布局属性修改：图层显隐，不会触发强制刷新
+  tileset.setLayoutProperty('coastline', 'visibility', 'none')
+  // 2.2、布局属性修改（非visibility）：字体大小修改，会触发强制刷新
+  tileset.setLayoutProperty('countries-label', 'text-size', {
+    stops: [
+      [2, 12],
+      [4, 16],
+      [6, 20]
+    ]
+  })
+
+  // 3、修改过滤器。
+  //和setLayoutProperty一样（visibility例外）会触发强制刷新
+  tileset.setFilter('geolines', null)
+})
+```
+
 ### 可选：Web Worker 多线程瓦片处理
 
 将瓦片解析、坐标转换、几何构建放到子线程，减轻主线程卡顿。不传 `workerUrl` 时仍走主线程。

package/Source/VectorTileset.js

@@ -33,6 +33,7 @@ export class VectorTileset {
     this._tilesToRender = []
     /**@type {StyleLayer[]} */
     this._styleLayers = []
+    this._styleLayerIndexMap = new Map()
     /**@type {VectorTileRenderList} */
     this._renderList = new VectorTileRenderList(this._styleLayers)
     this.numLoading = 0
@@ -95,6 +96,7 @@ export class VectorTileset {
     //初始化样式图层
     for (let i = 0; i < style.layers.length; i++) {
       this._styleLayers[i] = new StyleLayer(style.layers[i])
+      this._styleLayerIndexMap.set(style.layers[i].id, i)
     }
 
     //创建顶级瓦片LOD
@@ -257,6 +259,65 @@ export class VectorTileset {
     }
   }
 
+  //样式编辑API
+
+  setLayoutProperty(layerId, name, value) {
+    const styleLayerIndexMap = this._styleLayerIndexMap
+    if (!styleLayerIndexMap.has(layerId)) {
+      warnOnce(`不存在图层：${layerId}`)
+      return false
+    }
+    const layerIndex = styleLayerIndexMap.get(layerId)
+    const styleLayer = this._styleLayers[layerIndex]
+    const changed = styleLayer.setLayoutProperty(name, value)
+    //强制更新
+    if (changed && name !== 'visibility') {
+      this._forceUpdate()
+    }
+    return changed
+  }
+
+  setPaintProperty(layerId, name, value) {
+    const styleLayerIndexMap = this._styleLayerIndexMap
+    if (!styleLayerIndexMap.has(layerId)) {
+      warnOnce(`不存在图层：${layerId}`)
+      return false
+    }
+    const layerIndex = styleLayerIndexMap.get(layerId)
+    const styleLayer = this._styleLayers[layerIndex]
+    return styleLayer.setPaintProperty(name, value)
+  }
+
+  setFilter(layerId, filter) {
+    const styleLayerIndexMap = this._styleLayerIndexMap
+    if (!styleLayerIndexMap.has(layerId)) {
+      warnOnce(`不存在图层：${layerId}`)
+      return false
+    }
+    const layerIndex = styleLayerIndexMap.get(layerId)
+    const styleLayer = this._styleLayers[layerIndex]
+    const changed = styleLayer.setFilter(filter)
+    if (changed) {
+      this._forceUpdate()
+    }
+    return changed
+  }
+
+  //强制更新
+  _forceUpdate() {
+    for (const cacheTile of this._cacheTiles) {
+      cacheTile.unload()
+    }
+    for (const cacheTile of this._tilesToRender) {
+      cacheTile.unload()
+    }
+    for (const cacheTile of this._tilesToUpdate) {
+      cacheTile.unload()
+    }
+    this._tilesToRender.length = 0
+    this._tilesToUpdate.length = 0
+  }
+
   destroy() {
     const scene = this.scene
     const rootTiles = this._rootTiles

package/Source/layers/BackgroundRenderLayer.js

@@ -80,6 +80,21 @@ export class BackgroundRenderLayer extends IRenderLayer {
 
       frameState.commandList = preCommandList
     }
+    if (this.primitive && this.paintNeedsUpdate) {
+      const style = this.style,
+        tile = this.tile
+      const color = style.convertColor(
+        style.paint.getDataConstValue('background-color', tile.z)
+      )
+      const opacity = style.paint.getDataConstValue(
+        'background-opacity',
+        tile.z
+      )
+      color.alpha *= opacity
+      this.primitive.appearance.material.uniforms.color = color
+
+      this.paintNeedsUpdate = false
+    }
   }
 
   destroy() {

package/Source/layers/FillRenderLayer.js

@@ -4,13 +4,47 @@ import { registerRenderLayer } from './registerRenderLayer'
 import { FillLayerVisualizer } from './visualizers/FillLayerVisualizer'
 
 export class FillRenderLayer extends IRenderLayer {
+  constructor(sourceFeatures, styleLayer, tile) {
+    super(sourceFeatures, styleLayer, tile)
+    this.outlineOffsets = []
+    this.outlineCounts = []
+  }
   /**
    * @param {Cesium.FrameState} frameState
    * @param {VectorTileset} tileset
    */
   update(frameState, tileset) {
     //可以在这里实现同步样式，动态更新图层颜色等样式
+    if (this.paintNeedsUpdate) {
+      const style = this.style,
+        tile = this.tile,
+        batchTable = this._batchTable
+
+      for (const feature of this.features) {
+        const fillColor = style.convertColor(
+          style.paint.getDataValue('fill-color', tile.z, feature)
+        )
+        const fillOpacity = style.paint.getDataValue(
+          'fill-opacity',
+          tile.z,
+          feature
+        )
+        feature.fillColor = fillColor
+        feature.fillOpacity = fillOpacity
+
+        const batchId = feature.batchId
+        const colorBytes = fillColor.toBytes()
+        colorBytes[3] = Math.floor(colorBytes[3] * fillOpacity)
+        batchTable.setBatchedAttribute(batchId, 0, {
+          x: colorBytes[0],
+          y: colorBytes[1],
+          z: colorBytes[2],
+          w: colorBytes[3]
+        })
+      }
 
+      this.paintNeedsUpdate = false
+    }
     super.update(frameState, tileset)
   }
 }

package/Source/layers/IRenderLayer.js

@@ -82,6 +82,10 @@ export class IRenderLayer {
      * @type {'none'|'done'|'error'}
      */
     this.state = 'none'
+    /**
+     * 绘制（paint）属性版本号，用于监听绘制属性变化
+     */
+    this.paintVersion = styleLayer.paintVersion
   }
 
   get id() {
@@ -92,6 +96,15 @@ export class IRenderLayer {
     return this.style.type
   }
 
+  get paintNeedsUpdate() {
+    return this.paintVersion !== this.style.paintVersion
+  }
+  set paintNeedsUpdate(val) {
+    if (!val) {
+      this.paintVersion = this.style.paintVersion
+    }
+  }
+
   /**
    * 更渲染图层，可在该方法内实现绘图命令构建、动态样式更新等图层渲染准备相关功能。该方法可以被子类重写或复用
    * @param {Cesium.FrameState} frameState

package/Source/layers/LineRenderLayer.js

@@ -5,6 +5,7 @@ import { IRenderLayer } from './IRenderLayer'
 import { registerRenderLayer } from './registerRenderLayer'
 import { VectorTileLOD } from '../VectorTileLOD'
 import { LineLayerVisualizer } from './visualizers/LineLayerVisualizer'
+import { warnOnce } from 'maplibre-gl/src/util/util'
 
 export class LineRenderLayer extends IRenderLayer {
   /**
@@ -91,7 +92,49 @@ export class LineRenderLayer extends IRenderLayer {
     // }
     // if (this.primitive && this.primitive.length) {
     //     this.primitive.update(frameState)
+    //     this._batchTable = primitive._batchTable
     // }
+    if (this.paintNeedsUpdate) {
+      const style = this.style,
+        tile = this.tile,
+        batchTable = this._batchTable
+
+      for (const feature of this.features) {
+        const lineWidth = style.paint.getDataValue(
+          'line-width',
+          tile.z,
+          feature
+        )
+        const lineColor = style.convertColor(
+          style.paint.getDataValue('line-color', tile.z, feature)
+        )
+        const lineOpacity = style.paint.getDataValue(
+          'line-opacity',
+          tile.z,
+          feature
+        )
+
+        if (lineWidth !== feature.lineWidth) {
+          warnOnce('不支持动态修改 line 图层样式属性：line-width')
+        }
+
+        feature.lineColor = lineColor
+        feature.lineOpacity = lineOpacity
+        feature.lineWidth = lineWidth
+
+        const batchId = feature.batchId
+        const colorBytes = lineColor.toBytes()
+        colorBytes[3] = Math.floor(colorBytes[3] * lineOpacity)
+        batchTable.setBatchedAttribute(batchId, 0, {
+          x: colorBytes[0],
+          y: colorBytes[1],
+          z: colorBytes[2],
+          w: colorBytes[3]
+        })
+      }
+
+      this.paintNeedsUpdate = false
+    }
     super.update(frameState, tileset)
   }
 

package/Source/layers/SymbolRenderLayer.js

@@ -22,6 +22,41 @@ export class SymbolRenderLayer extends IRenderLayer {
    */
   update(frameState, tileset) {
     //TODO：动态更新符号样式
+    if (this.paintNeedsUpdate) {
+      const style = this.style,
+        tile = this.tile
+
+      for (let i = 0; i < this.features.length; i++) {
+        const feature = this.features[i]
+        const label = this.labels[i]
+
+        const textColor = style.convertColor(
+          style.paint.getDataValue('text-color', tile.z, feature)
+        )
+        const outlineColor = style.convertColor(
+          style.paint.getDataValue('text-halo-color', tile.z, feature)
+        )
+        const outlineWidth = style.paint.getDataValue(
+          'text-halo-width',
+          tile.z,
+          feature
+        )
+
+        feature.textColor = textColor
+        feature.outlineColor = outlineColor
+        feature.outlineWidth = outlineWidth
+
+        label.fillColor = textColor
+        label.style = outlineWidth && Cesium.LabelStyle.FILL_AND_OUTLINE
+        label.outlineWidth = outlineWidth * feature.textSize
+        label.outlineColor = outlineColor
+
+        label._baseFillColor = label.fillColor.clone()
+        label._baseOutlineColor = label.outlineColor.clone()
+      }
+
+      this.paintNeedsUpdate = false
+    }
 
     super.update(frameState, tileset)
   }

package/Source/layers/visualizers/FillLayerVisualizer.js

@@ -22,6 +22,7 @@ export class FillLayerVisualizer extends ILayerVisualizer {
     super(layers, tile)
 
     this.geometryInstances = []
+    this.outlineGeometryInstances = []
     this.primitive = null
     this.commandsReady = false
   }
@@ -67,6 +68,11 @@ export class FillLayerVisualizer extends ILayerVisualizer {
         sourceFeature
       )
 
+      const fillOutlineColor =
+        style.convertColor(
+          style.paint.getDataValue('fill-outline-color', tile.z, sourceFeature)
+        ) || fillColor
+
       //关键：对投影坐标细分，而不是使用cesium内置的细分
       const vtCoords = loadGeometry(sourceFeature)
       const polygons = classifyRings(vtCoords)
@@ -84,6 +90,7 @@ export class FillLayerVisualizer extends ILayerVisualizer {
           featureId,
           fillColor,
           fillOpacity,
+          fillOutlineColor,
           properties,
           //保存原始数据的要素id，后续可以用来支持 featureState 表达式，这个表达式可以实现选定要素高亮显示
           id: sourceFeatureId,
@@ -92,6 +99,7 @@ export class FillLayerVisualizer extends ILayerVisualizer {
         }
 
         scope.addFeature(fillFeature, granularity)
+        layer.features.push(fillFeature)
 
         featureId++
       }
@@ -186,9 +194,12 @@ export class FillLayerVisualizer extends ILayerVisualizer {
    */
   addFeature(feature, granularity) {
     const geometryInstances = this.geometryInstances
-    const { coordinates, fillColor, fillOpacity } = feature
+    const outlineGeometryInstances = this.outlineGeometryInstances
+    const { coordinates, fillColor, fillOpacity, fillOutlineColor } = feature
     const colorBytes = fillColor.toBytes()
     colorBytes[3] = Math.floor(colorBytes[3] * fillOpacity)
+    const outlineColorBytes = fillOutlineColor.toBytes()
+    outlineColorBytes[3] = Math.floor(outlineColorBytes[3] * fillOpacity)
 
     // 使用 maplibre-gl 的 subdividePolygon 基于投影坐标进行细分，
     // 而不是在转成世界坐标后再使用 Cesium.PolygonGeometry 构建，这样才能避免出现自相交、破面等现象。
@@ -198,7 +209,7 @@ export class FillLayerVisualizer extends ILayerVisualizer {
       coordinates,
       this.tile,
       granularity,
-      false
+      true
     )
     const verticesFlattened = subdivisionRes.verticesFlattened
     const coordDeg = [0, 0],
@@ -240,6 +251,14 @@ export class FillLayerVisualizer extends ILayerVisualizer {
           : Uint8Array
     )(subdivisionRes.indicesTriangles)
 
+    const outlineIndices = new (
+      vertCount > 65535
+        ? Uint32Array
+        : vertCount > 255
+          ? Uint16Array
+          : Uint8Array
+    )(subdivisionRes.indicesLineList.flat(3))
+
     const geometry = new Cesium.Geometry({
       attributes: {
         position: {
@@ -265,6 +284,19 @@ export class FillLayerVisualizer extends ILayerVisualizer {
       indices: indices,
       boundingSphere: Cesium.BoundingSphere.fromVertices(positions)
     })
+    const outlineGeometry = new Cesium.Geometry({
+      attributes: {
+        position: {
+          componentDatatype: Cesium.ComponentDatatype.DOUBLE,
+          componentsPerAttribute: 3,
+          normalize: false,
+          values: positions
+        }
+      },
+      primitiveType: Cesium.PrimitiveType.LINES,
+      indices: outlineIndices,
+      boundingSphere: Cesium.BoundingSphere.fromVertices(positions)
+    })
 
     const cartographic = Cesium.Cartographic.fromCartesian(
       geometry.boundingSphere.center
@@ -294,6 +326,25 @@ export class FillLayerVisualizer extends ILayerVisualizer {
       })
     })
     geometryInstances.push(instance)
+
+    const outlineInstance = new Cesium.GeometryInstance({
+      geometry: outlineGeometry,
+      attributes: {
+        color: new Cesium.GeometryInstanceAttribute({
+          componentDatatype: Cesium.ComponentDatatype.UNSIGNED_BYTE,
+          componentsPerAttribute: 4,
+          normalize: true,
+          value: outlineColorBytes
+        })
+      },
+      //通过entity的形式暴露给Cesium pickEntity，这样点击时系统自带的inforbox可以弹出
+      id: new Cesium.Entity({
+        position: center,
+        id: feature.id,
+        properties: feature.properties
+      })
+    })
+    outlineGeometryInstances.push(outlineInstance)
   }
 
   createPrimitive() {
@@ -427,6 +478,143 @@ void main()
    */
   onBatchTableCreated(batchTable) {
     this._batchTable = batchTable
+    for (const layer of this.layers) {
+      layer._batchTable = batchTable
+    }
+  }
+
+  createOutlinePrimitive() {
+    const primitive = new Cesium.Primitive({
+      geometryInstances: this.outlineGeometryInstances,
+      asynchronous: !(
+        this.outlineGeometryInstances[0].geometry instanceof Cesium.Geometry
+      ),
+      appearance: new Cesium.PerInstanceColorAppearance({
+        flat: true,
+        translucent: false,
+        renderState: {
+          //这里设置是没有用的，只要 translucent 为 false，
+          //Cesium 内部都会覆盖成 true，所以我们需要在 DrawCommand 创建完成后再设置
+          depthMask: false
+        },
+        fragmentShaderSource: /*glsl*/ ` 
+in vec4 v_color;
+
+uniform vec4 tileId;
+uniform sampler2D tileIdTexture;
+
+void main()
+{
+    vec2 id_st = gl_FragCoord.xy / czm_viewport.zw; 
+    vec4 bgId = texture(tileIdTexture, id_st);
+    if (!all(equal(bgId, tileId)))
+    {
+       discard;
+    }
+    out_FragColor = v_color;
+}
+                `
+      })
+    })
+
+    //通过定义 Primitive 私有变量 _geometries、_batchTable 的 setter 和 getter，
+    //监听合批几何体和批次表的创建：
+    //1、几何体创建完成后，根据 batchId 和 featureId，计算每个图层几何体的起始索引（offset）和索引数量（count）
+    //2、批次表创建完成后，保存备用
+    let scope = this
+    Object.defineProperties(primitive, {
+      _geometries: {
+        get() {
+          return this._geometries_
+        },
+        set(geometries) {
+          this._geometries_ = geometries
+          if (geometries) {
+            scope.onOutlineGeometriesLoaded(geometries)
+          } else {
+            scope = null
+          }
+        }
+      },
+      _batchTable: {
+        get() {
+          return this._batchTable_
+        },
+        set(batchTable) {
+          this._batchTable_ = batchTable
+          if (batchTable) {
+            scope.onOutlineBatchTableCreated(batchTable)
+          }
+        }
+      }
+    })
+
+    this.outlinePrimitive = primitive
+  }
+  /**
+   * 根据 batchId 和 featureId，计算每个图层几何体的起始索引（offset）和索引数量（count）
+   * @param {Cesium.Geometry[]} geometries
+   */
+  onOutlineGeometriesLoaded(geometries) {
+    //Cesium 几何体合批结果可能是多个几何体，对应多个 DrawCommand
+    for (let pass = 0; pass < geometries.length; pass++) {
+      const batches = {}
+      const geometry = geometries[pass]
+      const batchIds = geometry.attributes.batchId.values
+      const indices = geometry.indices
+
+      //提取每个批次的起始和结束索引
+      let currBatchId = -1
+      let currBatch = null
+      for (let i = 0; i < indices.length; i++) {
+        const vertIndex = indices[i]
+        const batchId = batchIds[vertIndex]
+        if (currBatchId !== batchId) {
+          currBatchId = batchId
+          currBatch = batches[currBatchId] = {
+            begin: i,
+            end: i
+          }
+        }
+        currBatch.end = i
+      }
+
+      //根据图层批次范围，提取图层几何体索引范围，即起始索引（offset）和索引数量（count）
+      for (const layer of this.layers) {
+        const { firstBatchId, lastBatchId } = layer
+        if (firstBatchId === -1 || lastBatchId === -1) {
+          continue
+        }
+
+        let begin = -1,
+          end = -1
+        for (let batchId = firstBatchId; batchId <= lastBatchId; batchId++) {
+          const batch = batches[batchId]
+          if (batch) {
+            if (begin === -1) begin = batch.begin
+            end = batch.end
+          }
+        }
+
+        if (begin === -1 || end === -1) {
+          continue
+        }
+
+        //起始和结束索引，索引数量需要加1
+        layer.outlineOffsets[pass] = begin
+        layer.outlineCounts[pass] = end - begin + 1
+      }
+    }
+  }
+  /**
+   * 保存 Cesium Primitive 创建的批次表。图层样式变化时，通过更新批次表传递到GPU，同步更新渲染效果
+   * @param {Cesium.BatchTable} batchTable
+   */
+  onOutlineBatchTableCreated(batchTable) {
+    this._outlineBatchTable = batchTable
+    for (const layer of this.layers) {
+      layer._outlineBatchTable = batchTable
+    }
   }
 
   /**
@@ -452,14 +640,29 @@ void main()
     for (let i = 0; i < this.layers.length; i++) {
       const layer = this.layers[i]
       const layerCommandList = (layer.commandList = [])
+      const passes = {
+        fill: 0,
+        outline: 0
+      }
 
-      for (let pass = 0; pass < batchedCommandList.length; pass++) {
-        const offset = layer.offsets[pass],
-          count = layer.counts[pass]
+      for (let i = 0; i < batchedCommandList.length; i++) {
+        const command = batchedCommandList[i]
+        let pass, offsets, counts
+        if (command.primitiveType == Cesium.PrimitiveType.LINES) {
+          pass = passes.outline++
+          offsets = layer.outlineOffsets
+          counts = layer.outlineCounts
+        } else {
+          pass = passes.fill++
+          offsets = layer.offsets
+          counts = layer.counts
+        }
+
+        const offset = offsets[pass],
+          count = counts[pass]
         if (typeof offset !== 'number' || typeof count !== 'number') {
           continue
         }
-        const command = batchedCommandList[pass]
         command.uniformMap.tileIdTexture = function () {
           return tileset.tileIdTexture
         }
@@ -493,6 +696,7 @@ void main()
 
     if (!this.primitive && this.geometryInstances.length) {
       this.createPrimitive()
+      this.createOutlinePrimitive()
     }
 
     if (this.primitive && this.state !== 'done' && this.state !== 'error') {
@@ -504,13 +708,18 @@ void main()
       //执行 primitive 的 update ，直到生成了合批后的drawCommand
       try {
         this.primitive.update(frameState)
+        this.outlinePrimitive.update(frameState)
       } catch (err) {
         //如果报错，下一帧就不要再执行 update 了，以免重复打印错误信息
         this.geometryInstances = []
+        this.outlineGeometryInstances = []
         this.setState('error')
         if (err.stack) console.trace(err.stack)
         else console.error(err)
         return
+      } finally {
+        //恢复系统的 commandList
+        frameState.commandList = preCommandList
       }
 
       //使用合批后的 drawCommand 创建副本，为渲染图层分配 drawCommand
@@ -518,14 +727,22 @@ void main()
         this.createLayerCommands(batchedCommandList, tileset)
       }
 
-      if (this.primitive._state === Cesium.PrimitiveState.FAILED) {
+      if (
+        this.primitive._state === Cesium.PrimitiveState.FAILED ||
+        this.outlinePrimitive._state === Cesium.PrimitiveState.FAILED
+      ) {
         this.setState('error')
       }
 
-      //恢复系统的 commandList
-      frameState.commandList = preCommandList
       this.geometryInstances = []
     }
+
+    if (this._batchTable && this._batchTable._batchValuesDirty) {
+      this._batchTable.update(frameState)
+    }
+    if (this._outlineBatchTable && this._outlineBatchTable._batchValuesDirty) {
+      this._outlineBatchTable.update(frameState)
+    }
   }
 
   destroy() {