BufferAnalysis 缓冲区分析

基于 turf 对点 / 线 / 面要素计算缓冲区多边形，并写入 Cesium 实体。对齐源案例 Analysis/BufferAnalysis：源要素（黄色）+ 缓冲面（红色半透明）一并展示。

---

能力定位

BufferAnalysis 适合：

• 空间缓冲分析：对 POI、管线、地块等点 / 线 / 面要素计算固定半径缓冲范围（GIS 标准分析能力）；
• 影响范围可视化：缓冲面以红色半透明多边形叠加在源要素上，直观呈现可达半径 / 影响区域；
• 多要素批量缓冲：addPoint / addPolyline / addPolygon 可连续调用，clear 一次性回收。

通过公开 Cesium API + turf 纯计算组合（对齐源案例 initPointBuffer / initPolylineBuffer / initPolygonBuffer）：

要素	计算	展示
点	turf.point + turf.buffer → 圆环	黄色点 + 红色半透明圆缓冲面
线	turf.lineString + turf.buffer → 端帽缓冲带	黄色线 + 红色半透明缓冲带
面	turf.polygon + turf.buffer → 外扩缓冲	黄色面（带描边）+ 红色半透明外扩面

与其他工具的区分：

工具	作用面	行为
BufferAnalysis（本工具）	turf 计算 + 实体	要素缓冲范围分析，可整体回收
DrawManager	交互绘制	手动画点 / 线 / 面，不计算缓冲
Measure	测距 / 测面	测量量算，不生成缓冲多边形

纯计算函数

createBufferRing(
  type: BufferFeatureType,               // 'point' | 'line' | 'polygon'
  coordinates: LngLat | LngLat[],        // 点：[lng, lat]；线 / 面：[lng, lat][]
  radius: number,                        // 缓冲半径（单位由 units 指定）
  options?: { units?: BufferUnits; steps?: number }
): LngLat[]                              // 缓冲多边形外环 [lng, lat][]

无 Viewer 依赖，可在 Node 环境直接验证；radius 为 0 或负数时抛错。

构造函数

constructor(viewer: Viewer, options?: BufferOptions)

interface BufferOptions {
  sourceColor?: Color    // 源要素颜色，默认黄色
  bufferColor?: Color    // 缓冲面颜色，默认红色半透明（0.6）
  sourceVisible?: boolean // 是否同时添加源要素实体，默认 true
  radiusUnits?: BufferUnits // 缓冲半径单位，默认 'meters'
  height?: number        // 缓冲面高程（米）；不设置时为贴地分类多边形
  steps?: number         // turf 缓冲圆滑步数，默认 64
}

参数	类型	默认值	描述
sourceColor	Color	Color.YELLOW	源要素（点 / 线 / 面）颜色
bufferColor	Color	Color.RED.withAlpha(0.6)	缓冲面颜色（半透明）
sourceVisible	boolean	true	false 时仅创建缓冲面，不添加源要素
radiusUnits	BufferUnits	'meters'	半径单位（meters / kilometers / miles / yards / feet / degrees / radians / nauticalmiles）
height	number	缺省	缓冲面高程；缺省为贴地分类多边形（classificationType: BOTH）
steps	number	64	turf 缓冲圆滑步数，越大外环越平滑

无必填项（viewer 除外）。

实例方法

方法	说明
addPoint(coordinates, radius, options?)	点缓冲，返回缓冲面实体
addPolyline(coordinates, radius, options?)	线缓冲，返回缓冲面实体
addPolygon(coordinates, radius, options?)	面缓冲，返回缓冲面实体
clear()	移除本实例创建的全部实体（含源要素），幂等
destroy()	clear + 释放 viewer 引用，幂等；销毁后 add* 抛错

add* 的 options 覆盖构造选项（如 { radiusUnits: 'kilometers' }）。

基础示例

import { BufferAnalysis } from '@nexa/gis-cesium'

const analysis = new BufferAnalysis(viewer)
analysis.addPoint([106.42, 29.57], 60)                       // 点 + 60 米圆缓冲
analysis.addPolyline([[106.42, 29.57], [106.43, 29.57]], 30) // 线 + 30 米缓冲带
analysis.addPolygon([[106.44, 29.57], [106.44, 29.58], [106.43, 29.575], [106.44, 29.57]], 60) // 面外扩

进阶示例

单位与样式透传、整体回收：

const analysis = new BufferAnalysis(viewer, {
  sourceColor: Cesium.Color.CYAN,
  bufferColor: Cesium.Color.BLUE,
  radiusUnits: 'kilometers',
})

analysis.addPoint([0, 0], 1)      // 1 千米缓冲
analysis.addPolyline([[0, 0], [0.01, 0]], 0.5, { sourceVisible: false }) // 半千米缓冲，不带源线

analysis.clear()                  // 移除本次分析的全部实体
analysis.destroy()                // 释放引用，幂等

实现说明

• 纯计算层 createBufferRing：turf.buffer 对 point / lineString / polygon 要素计算缓冲，取外环坐标，无 Viewer 依赖、可 headless 验证；MultiPolygon 结果取第一个面外环，radius ≤ 0 抛错；
• 实体层 BufferAnalysis：源要素 + 缓冲面一并入 viewer.entities，颜色对齐源案例（黄源红缓冲）；所有实体被实例追踪，clear 整体回收；
• 样式细节：源点（pixelSize: 10 + 描边）、源线（width: 2）、源面（polygon + polyline 描边）；缓冲面为贴地分类多边形（classificationType: BOTH，与源案例一致），设置 height 后转为指定高程多边形；
• 资源所有权：实例只创建自己追踪的实体，clear / destroy 不触碰调用方其他实体；destroy 后重复调用安全。

清理责任

analysis.clear()   // 清理本次分析的源 + 缓冲实体（可继续 add*）
analysis.destroy() // 释放实例（clear + 置空引用，之后 add* 抛错）

重复调用 clear / destroy 安全。

依赖与体积说明

• turf：使用已声明的直接依赖 @turf/turf（^7.3.5），从其中具名导入 buffer / point / lineString / polygon，依赖 rollup 摇树；
• 体积代价：@turf/buffer 传递依赖引入 @turf/jsts 等，UMD 产物增量约 +284KB（已通过 <300KB 门禁）。若对产物体积敏感，可改为按需加载（动态 import('@turf/turf')）或仅对线 / 面要素启用 turf。

Cesium 版本限制

• 依赖 Cesium 公开 API：EntityCollection.add/remove、PolygonHierarchy、Cartesian3.fromDegreesArray、Color、ClassificationType；
• 无私有字段 / GLSL 依赖；缓冲面几何渲染需真实浏览器 / WebGL 验证；已验证目标版本：Cesium 1.133.1。