Cesium PolylineGeometry 添加折现完整知识点 & TS 代码

PolylineGeometry 用于 Primitive + PolylineMaterialAppearance，做三维空间折线，支持 Z 高程（MultiLineString‑Z），不是贴地线。 贴地线请用 GroundPolylineGeometry / GroundPolylinePrimitive。

一、核心概念

1. PolylineGeometry：几何体，只存顶点坐标、线宽；不能直接渲染，必须包装进 GeometryInstance，交给 Primitive 渲染。
2. PolylineMaterialAppearance：配套外观材质，支持纯色、虚线、纹理；独有 depthFailAppearance（被地形遮挡时切换材质）。
3. 不支持每个线段不同颜色；同一份 Primitive 内所有线段共用一套 Appearance。

如果要多条线不同颜色：按颜色分组，每个颜色新建一套 Primitive（就是现在业务的做法）。

关键参数 PolylineGeometry

const lineGeo = new Cesium.PolylineGeometry({
  positions: Cartesian3[],   // 笛卡尔3坐标数组，必须≥2个点，支持独立高程Z
  width: number,             // 线宽【⚠️WebGL限制，大部分浏览器最大有效2px】
  vertexFormat: Cesium.VertexFormat.POSITION_ONLY
});

⚠️坑：width >2 在很多浏览器会强制变成 1 像素。粗线不要用这个，改用 GroundPolylinePrimitive。

Primitive 重要属性

表格

二、基础完整示例

1、单条三维空间线

// 经纬度高程转Cartesian3
function lngLatHeightToCart3(lng:number,lat:number,h=0){
  return Cesium.Cartesian3.fromDegrees(lng,lat,h);
}

//1.顶点数组
const positions = [
  lngLatHeightToCart3(102.49,24.70,1800),
  lngLatHeightToCart3(102.50,24.71,1900),
  lngLatHeightToCart3(102.51,24.72,1750),
];

//2.构建几何体
const lineGeometry = new Cesium.PolylineGeometry({
  positions: positions,
  width:2
});

//3.包装实例
const instance = new Cesium.GeometryInstance({
  geometry: lineGeometry,
  id:"line_001" //拾取id
});

//4.创建Primitive，带地下遮挡材质
const prim = new Cesium.Primitive({
  geometryInstances: instance,
  appearance: new Cesium.PolylineMaterialAppearance({
    material: Cesium.Material.fromType("Color",{
      color:Cesium.Color.ORANGE
    })
  }),
  // 被地形埋住，地下显示半透明
  depthFailAppearance: new Cesium.PolylineMaterialAppearance({
    material: Cesium.Material.fromType("Color",{
      color:Cesium.Color.ORANGE.withAlpha(0.3)
    })
  }),
  asynchronous:true
});

//添加到场景
this.viewer.scene.primitives.add(prim);

2、多条线批量（按颜色分组，项目现有模式）

// 按颜色分组，每个颜色一组instances
const tempLineGroup = new Map<string, {positions:Cesium.Cartesian3[],_featureId:string}[]>();

// 模拟多条线数据
tempLineGroup.forEach((lineList,cssColor)=>{
  const instances:Cesium.GeometryInstance[] = [];

  lineList.forEach(opt=>{
    if(opt.positions.length <2) return;
    const geo = new Cesium.PolylineGeometry({
      positions:opt.positions,
      width:3
    });
    instances.push(new Cesium.GeometryInstance({
      geometry:geo,
      id:opt._featureId
    }))
  })

  if(!instances.length) return;

  const mainColor = Cesium.Color.fromCssColorString(cssColor);
  const prim = new Cesium.Primitive({
    geometryInstances:instances,
    appearance: new Cesium.PolylineMaterialAppearance({
      material:Cesium.Material.fromType("Color",{color:mainColor})
    }),
    depthFailAppearance: new Cesium.PolylineMaterialAppearance({
      material:Cesium.Material.fromType("Color",{color:mainColor.withAlpha(0.35)})
    }),
    asynchronous:true
  })
  this.viewer.scene.primitives.add(prim);
  //保存引用，用于后续删除
  this.lineCollectionMap.set(cssColor, prim);
})

三、depthFailAppearance 两种常用材质

①地下半透明实线（上面示例）

②地下虚线（管线 / 高压线业务最常用）

depthFailAppearance: new Cesium.PolylineMaterialAppearance({
  material: new Cesium.Material({
    fabric:{
      type:"Dash",
      uniforms:{
        dashPattern:255,
        color: mainColor.withAlpha(0.35)
      }
    }
  })
})

四、拾取点击

Primitive 开启拾取，点击拿到 GeometryInstance 的 id

const handler = new Cesium.ScreenSpaceEventHandler(this.viewer.canvas);
handler.setInputAction((click)=>{
  const pick = this.viewer.scene.pick(click.position);
  if(Cesium.defined(pick)){
    console.log('线要素id', pick.id);
  }
},Cesium.ScreenSpaceEventType.LEFT_CLICK)

五、销毁、清除（内存泄漏重点）

// Map保存所有线Primitive引用
private lineCollectionMap = new Map<string,Cesium.Primitive>();

//清除所有线
public clearLinePrimitive(){
  this.lineCollectionMap.forEach(prim=>{
    this.viewer.scene.primitives.remove(prim);
  })
  this.lineCollectionMap.clear();
}

六、PolylineGeometry 重要坑清单

1. width 受 WebGL 限制，有效宽度一般最大 2px；设置 width=5，浏览器渲染依旧很细。

✅粗线解决方案：改用GroundPolylinePrimitive（贴地）或者 Entity polyline。

1. 三维空间线（带 Z 高程）不能用 GroundPolylineGeometry；Ground 系列强制贴地形，会丢弃顶点 Z。

2. depthFailAppearance 只有 PolylineMaterialAppearance 支持；PerInstanceColorAppearance（面）不支持。

3. Primitive 一旦创建，不能修改单条线的顶点、颜色。更新数据：销毁旧 Primitive，全部重新构建。

4. 输入坐标必须是 Cartesian3，不能直接传经纬度；Cartesian3.fromDegrees(lng,lat,height)。

5. 线段至少 2 个点；少于 2 个点会直接报错渲染崩溃。解析 WKT 时要做过滤、去重重合点。

6. 同一份 Primitive 内所有线段共用一套材质；想要不同颜色，必须拆分成多个 Primitive（你的 Map 分组就是标准做法）。

七、对比表

业务选型建议

1. 三维管线、高压线、MultiLineString‑Z：选PolylineGeometry + Primitive + depthFailAppearance。
2. 不需要高程、只贴地表、需要粗线：GroundPolylinePrimitive。
3. 数量少，频繁修改：Entity。