地理信息工具（GIS Utils）

提供坐标转换、卫星轨道传播、相对轨道计算和时间处理等核心地理信息工具。

---

CoordinateUtils — 坐标系统转换

静态工具类，支持多种坐标系间的相互转换，以及距离、方位角、面积等几何计算。

坐标转换方法：

方法	说明
CoordinateUtils.degreesToCartesian3(lon, lat, height?)	经纬度(度) → 笛卡尔坐标
CoordinateUtils.cartesian3ToDegrees(cartesian)	笛卡尔坐标 → 地理坐标 {longitude, latitude, height}
CoordinateUtils.cartesian3ToCartographic(cartesian)	笛卡尔坐标 → Cartographic(弧度)
CoordinateUtils.degreesArrayToCartesian3Array(coords)	经纬度数组 [lon1, lat1, ...] → Cartesian3[]
CoordinateUtils.degreesArrayHeightToCartesian3Array(coords)	含高度经纬度数组 → Cartesian3[]
CoordinateUtils.degreesToWebMercator(lon, lat)	经纬度 → Web 墨卡托 {x, y}
CoordinateUtils.webMercatorToDegrees(x, y)	Web 墨卡托 → 经纬度 {longitude, latitude}
CoordinateUtils.cartesian3ToScreen(viewer, cartesian)	笛卡尔坐标 → 屏幕坐标（可为 null）
CoordinateUtils.screenToCartesian3(viewer, screenX, screenY)	屏幕坐标 → 笛卡尔坐标（可为 null）

几何计算方法：

方法	说明
CoordinateUtils.distanceBetweenCartesian3(from, to)	两点直线距离(米)
CoordinateUtils.geodesicDistance(lon1, lat1, lon2, lat2)	椭球面距离 + 方位角
CoordinateUtils.destinationFromDistance(lon, lat, bearing, distance)	根据方位角和距离推算终点
CoordinateUtils.calculateBearing(from, to)	计算两点方位角(度, 北向0°)
CoordinateUtils.calculatePolygonArea(positions)	计算多边形面积(平方米)
CoordinateUtils.calculateLineLength(positions)	计算折线总长度(米)

坐标系转换方法：

方法	说明
CoordinateUtils.eciToEcef(positionECI, time)	ECI(惯性系) → ECEF(地固系)
CoordinateUtils.ecefToEci(positionECEF, time)	ECEF → ECI
CoordinateUtils.batchConvert(coords, targetFormat)	批量坐标转换
CoordinateUtils.isValidGeographic(lon, lat)	验证经纬度是否有效
CoordinateUtils.getBoundCenter(sw, ne)	计算地理边界中心点

示例：

import { CoordinateUtils } from './utils-gis/CoordinateUtils'

// 经纬度转笛卡尔坐标
const cartesian = CoordinateUtils.degreesToCartesian3(120.13, 30.27, 1000)

// 计算两点距离
const distance = CoordinateUtils.distanceBetweenCartesian3(
  CoordinateUtils.degreesToCartesian3(116.4, 39.9),
  CoordinateUtils.degreesToCartesian3(116.5, 40.0)
)

// 用方位角推算终点
const dest = CoordinateUtils.destinationFromDistance(
  116.404, 39.915, Math.PI / 2, 1000
)

---

SatelliteOrbitTool — 卫星轨道工具

基于 TLE + SGP4（satellite.js）的卫星轨道传播工具，支持实时轨道计算和轨迹生成。

构造方法：

const tle: TLE = {
  name: 'ISS (ZARYA)',
  line1: '1 25544U 98067A   24123.51782528  .00016717  00000-0  10270-4 0  9001',
  line2: '2 25544  51.6414  80.5114 0006702  89.1582 271.0270 15.50367711452180'
}
const orbitTool = new SatelliteOrbitTool(tle)

核心方法：

方法	返回类型	说明
orbitTool.getState(time?)	SatelliteState	获取指定时刻的卫星状态（位置、速度）
orbitTool.getTrack(options)	OrbitTrack	生成轨迹点集合
orbitTool.getOneDayTrack(startTime, step?)	OrbitTrack	生成一天轨迹
orbitTool.getMinutesTrack(startDate, minutes, step?)	OrbitTrack	生成指定分钟的轨迹
orbitTool.createCesiumTrack(track)	{position, availability}	创建 Cesium 轨迹时间属性

示例：

// 生成 90 分钟轨迹（每 10 秒采样）
const track = orbitTool.getMinutesTrack(new Date(), 90, 10)

// 转换为 Cesium 属性
const { position, availability } = orbitTool.createCesiumTrack(track)

// 应用到 Entity
entity.position = position
entity.availability = availability

返回的 ICesiumTrack 类型：

interface ICesiumTrack {
  position: Cesium.SampledPositionProperty
  availability: Cesium.TimeIntervalCollection
}

---

RelativeOrbitUtils — 相对轨道计算

在 LVLH（Local Vertical Local Horizontal）和 VVLH（Velocity Velocity Local Horizontal）参考系中计算相对轨迹。

核心方法：

方法	说明
RelativeOrbitUtils.createRelativeTrajectory(viewer, options)	创建动态相对轨迹 Entity
RelativeOrbitUtils.computeRelativePositions(time, source, target, frame, step)	动态计算相对位置点集
RelativeOrbitUtils.computeLVLHMatrix(position, velocity)	计算 LVLH 坐标系旋转矩阵
RelativeOrbitUtils.computeVVLHMatrix(position, velocity)	计算 VVLH 坐标系旋转矩阵
RelativeOrbitUtils.computeEntityVelocity(entity, time)	计算 Entity 瞬时速度
RelativeOrbitUtils.getGroundTrack(points)	获取星下点轨迹

类型定义：

type RelativeFrame = 'LVLH' | 'VVLH'

interface RelativeTrajectoryOptions {
  sourceEntity: Cesium.Entity   // 主目标实体
  targetEntity: Cesium.Entity   // 参考目标实体
  frame?: RelativeFrame         // 参考系，默认 'LVLH'
  step?: number                 // 采样点数，默认 100
  color?: Cesium.Color          // 线颜色
  width?: number                // 线宽，默认 2
  id?: string                   // entity id
}

interface OrbitPoint {
  t: number   // Unix 毫秒时间戳
  x: number   // X 坐标
  y: number   // Y 坐标
  z: number   // Z 坐标
}

interface GroundTrackPoint {
  t: number    // Unix 毫秒时间戳
  lon: number  // 经度
  lat: number  // 纬度
  alt: number  // 高度
}

示例：

import { RelativeOrbitUtils } from './utils-gis/RelativeOrbitUtils'

// 创建 LVLH 相对轨迹
RelativeOrbitUtils.createRelativeTrajectory(viewer, {
  sourceEntity: satelliteA,
  targetEntity: satelliteB,
  frame: 'LVLH',
  step: 200,
  color: Cesium.Color.YELLOW
})

---

TimeUtils（DateTimeUtils）— 时间工具

基于 Cesium JulianDate 和 dayjs 的时间处理工具类，支持时区转换和格式化。

JulianDate 转换：

方法	说明
TimeUtils.dateToJulian(date)	Date → JulianDate
TimeUtils.julianToDate(julian)	JulianDate → Date
TimeUtils.timestampToJulian(ts)	时间戳 → JulianDate
TimeUtils.julianToTimestamp(julian)	JulianDate → 时间戳
TimeUtils.isoToJulian(iso)	ISO8601 → JulianDate
TimeUtils.julianToISO(julian)	JulianDate → ISO8601

时间格式转换：

方法	说明
TimeUtils.dateToISO(date)	Date → ISO8601
TimeUtils.isoToDate(iso)	ISO8601 → Date
TimeUtils.timestampToISO(ts)	时间戳 → ISO8601
TimeUtils.isoToTimestamp(iso)	ISO8601 → 时间戳

时区转换：

方法	说明
TimeUtils.toUTCString(input, format?)	转 UTC 字符串
TimeUtils.toBeijingTimeString(input, format?)	转北京时间(UTC+8)字符串
TimeUtils.beijingToUTC(beijingTime)	北京时间 → UTC ISO
TimeUtils.toTimezoneString(input, timezone, format?)	任意时区转换

时间计算：

方法	说明
TimeUtils.addSeconds(julian, seconds)	JulianDate 增加秒数
TimeUtils.secondsDifference(start, end)	计算时间差（秒）

示例：

const now = TimeUtils.nowJulian()
const beijingTime = TimeUtils.toBeijingTimeString(new Date())
const isoStr = TimeUtils.julianToISO(now)

---

完整类型索引

// 坐标类型
interface GeographicCoordinate { longitude: number; latitude: number; height?: number }
interface WebMercatorCoordinate { x: number; y: number }
interface ScreenCoordinate { x: number; y: number }
interface LngLatAlt { longitude: number; latitude: number; height: number }
interface ECIPosition { x: number; y: number; z: number }
interface ECEFPosition { x: number; y: number; z: number }

// 距离类型
interface DistanceAndBearing { distance: number; bearing: number }
interface SurfaceDistanceInfo { surfaceDistance: number; bearing: number; backBearing: number }

// 卫星类型
interface TLE { name?: string; line1: string; line2: string }
interface SatelliteState { time: Date; position: LngLatAlt; eci: ECIPosition; ecef: ECEFPosition; velocity: Velocity }
interface Velocity { x: number; y: number; z: number; speed: number }
interface OrbitTrackPoint extends SatelliteState { index: number }
interface OrbitTrack { startTime: Date; endTime: Date; step: number; points: OrbitTrackPoint[] }
interface OrbitTrackOptions { startTime: Date; endTime?: Date; duration?: number; step?: number }
interface SatelliteOrbit { tle: TLE; satrec: SatRec }
interface ICesiumTrack { position: SampledPositionProperty; availability: TimeIntervalCollection }