卫星四棱锥视场

SatellitePyramidEffect 封装固定卫星及其四棱锥视场。业务层只传入 WGS84 经纬高、量程、视场角和姿态，卫星 Entity、填充 Primitive、轮廓 Primitive 及其释放过程均由 SDK 管理。

设计特点

• 公共 API 不暴露 Cartesian3、Color、Entity 或 Primitive。
• 水平和垂直视场角相互独立，内部按透视投影关系计算宽高比。
• 位置、姿态和量程变化只更新 modelMatrix，不重建 Frustum。
• 仅在视场角、颜色或轮廓配置变化时重建不可变几何。
• 未传 modelUrl 时显示 SDK 内置卫星标识；传入后自动切换为 glTF/GLB 模型。
• focus 根据当前视场自动计算包围球，案例层无需构造 Cesium 相机参数。
• on、off、destroy 统一管理资源，on / off 支持幂等调用。

基础用法

import {
  CesiumViewer,
  SatellitePyramidEffect,
} from '@nexa/gis-cesium'

const airViewer = new CesiumViewer('container')
const effect = new SatellitePyramidEffect({
  position: {
    longitude: 117.169969,
    latitude: 31.840886,
    height: 899999.87,
  },
  range: 1350000,
  horizontalFov: 20,
  verticalFov: 20,
  heading: 0,
  pitch: -180,
  fillColor: 'rgba(0, 255, 255, 0.4)',
  outlineColor: 'rgba(255, 255, 0, 0.7)',
  modelUrl: '/images/models/satellite.gltf',
  modelScale: 10000,
  modelMinimumPixelSize: 72,
})

effect.on(airViewer)
effect.focus({ heading: 35, pitch: -25, range: 5000000 })
effect.updateOptions({ heading: 15, pitch: -170 })
effect.setVisible(false)
effect.setVisible(true)
effect.destroy()

示例工程提供 /images/models/satellite.gltf 轻量模型，可直接展示 3D 卫星；未传入 modelUrl 时，效果会降级为 SDK 内置卫星图标。

配置项

参数	类型	默认值	说明
position	GeographicCoordinate	必填	卫星 WGS84 经纬高坐标
range	number	卫星高度 × 1.5	四棱锥量程，单位米
horizontalFov	number	20	水平视场角，单位度，有效范围 (0, 179)
verticalFov	number	20	垂直视场角，单位度，有效范围 (0, 179)
heading	number	0	航向角，单位度
pitch	number	-180	俯仰角，单位度，默认朝向地表
roll	number	0	翻滚角，单位度
fillColor	string	rgba(0, 255, 255, 0.4)	填充 CSS 颜色
outlineColor	string	rgba(255, 255, 0, 0.55)	轮廓 CSS 颜色
showOutline	boolean	true	是否显示轮廓
modelUrl	string	无	可选卫星 glTF/GLB 地址
modelScale	number	60	卫星模型缩放
modelMinimumPixelSize	number	72	模型最小屏幕像素
markerSize	number	72	未使用模型时的内置卫星标识大小

更新与生命周期

effect.updateOptions({
  position: { longitude: 118, latitude: 32, height: 920000 },
  range: 1500000,
  horizontalFov: 24,
  heading: 10,
})

const state = effect.getOptions()
effect.off()     // 移除资源，之后可再次 on
effect.on(airViewer)
effect.destroy() // 最终销毁，之后不可再次启用