# PointUtil
查阅Cesium API

#### PointUtil()
util/PointUtil.js 1

单个坐标或位置矩阵相关的处理 静态方法

### 方法

#### static mars3d.PointUtil.addPositionsHeight(positions, addHeight) → Cesium.Cartesian3|Array.<Cesium.Cartesian3>
util/PointUtil.js 141

对坐标（或坐标数组）增加 指定的海拔高度值

参数名称 | 类型 | 默认值 | 描述信息
--- | --- | --- | ---
`positions` | Cesium.Cartesian3 | Array.<Cesium.Cartesian3> |  | 笛卡尔坐标数组
`addHeight` | number | `0` | 可选 增加的海拔高度值

##### 返回值:

增加高度后的坐标（或坐标数组）

#### static mars3d.PointUtil.getCameraHeadingPitchRollForLine(scene, localStart, localEnd, reverse) → Cesium.HeadingPitchRoll
util/PointUtil.js 853

求 localStart点 到 localEnd点的 Heading Pitch Roll方向 【用于Camera相机的方向】

参数名称 | 类型 | 描述信息
--- | --- | ---
`scene` | Cesium.Scene | 三维地图场景对象，一般用map.scene或viewer.scene
`localStart` | Cesium.Cartesian3 | LngLatPoint | 起点坐标
`localEnd` | Cesium.Cartesian3 | LngLatPoint | 终点坐标
`reverse` | boolean | 可选 是否翻转

##### 返回值:

Heading Pitch Roll方向

#### static mars3d.PointUtil.getCurrentMouseTerrainPosition(scene, position) → Cesium.Cartesian3
util/PointUtil.js 315

获取 屏幕XY坐标 对应的 地形上的笛卡尔三维坐标（不拾取模型、矢量数据等）

参数名称 | 类型 | 描述信息
--- | --- | ---
`scene` | Cesium.Scene | 三维地图场景对象，一般用map.scene或viewer.scene
`position` | Cesium.Cartesian2 | 屏幕XY坐标（如鼠标所在位置)

##### 返回值:

笛卡尔三维坐标

#### static mars3d.PointUtil.getHeadingPitchRollByMatrix(matrix, ellipsoid, fixedFrameTransform, result) → Cesium.HeadingPitchRoll
util/PointUtil.js 646

根据matrix转换矩阵 求 Heading Pitch Roll角度

参数名称 | 类型 | 默认值 | 描述信息
--- | --- | --- | ---
`matrix` | Cesium.Matrix4 |  | 转换矩阵
`ellipsoid` | Cesium.Ellipsoid | `Cesium.Ellipsoid.WGS84` | 可选 变换中使用固定坐标系的椭球。
`fixedFrameTransform` | Cesium.Transforms.LocalFrameToFixedFrame | `Cesium.Transforms.eastNorthUpToFixedFrame` | 可选 参考系
`result` | Cesium.HeadingPitchRoll |  | 可选 可以先实例化返回的 Heading Pitch Roll角度对象

##### 返回值:

Heading Pitch Roll角度

#### static mars3d.PointUtil.getHeadingPitchRollByOrientation(position, orientation, ellipsoid, fixedFrameTransform) → Cesium.HeadingPitchRoll
util/PointUtil.js 623

根据 position位置 和 orientation四元数实例 求 Heading Pitch Roll方向

参数名称 | 类型 | 默认值 | 描述信息
--- | --- | --- | ---
`position` | Cesium.Cartesian3 |  | 位置坐标
`orientation` | Cesium.Quaternion |  | 四元数实例
`ellipsoid` | Cesium.Ellipsoid | `Cesium.Ellipsoid.WGS84` | 可选 变换中使用固定坐标系的椭球。
`fixedFrameTransform` | Cesium.Transforms.LocalFrameToFixedFrame | `Cesium.Transforms.eastNorthUpToFixedFrame` | 可选 参考系

##### 返回值:

Heading Pitch Roll方向

#### static mars3d.PointUtil.getHeadingPitchRollForLine(localStart, localEnd, reverse) → Cesium.HeadingPitchRoll
util/PointUtil.js 659

求 localStart点 到 localEnd点的 Heading Pitch Roll方向

参数名称 | 类型 | 描述信息
--- | --- | ---
`localStart` | Cesium.Cartesian3 | LngLatPoint | 起点坐标
`localEnd` | Cesium.Cartesian3 | LngLatPoint | 终点坐标
`reverse` | boolean | 可选 是否翻转

##### 返回值:

Heading Pitch Roll方向

#### static mars3d.PointUtil.getHeight(scene, position, options) → number
util/PointUtil.js 204

获取 坐标 的 贴地高度 （非精确计算，根据当前加载的地形和模型数据情况有关,准确计算请用getSurfaceHeight方法） 如需计算贴模型，请模型构造时加 enableCollision: true 参数

参数名称 | 类型 | 默认值 | 描述信息
--- | --- | --- | ---
`scene` | Cesium.Scene |  | 三维地图场景对象，一般用map.scene或viewer.scene
`position` | Cesium.Cartesian3 | LngLatPoint |  | 坐标
`options` | object | `{}` | 可选 参数对象:
参数名称 | 类型 | 默认值 | 描述信息
--- | --- | --- | ---
`heightReference` | Cesium.HeightReference | `Cesium.HeightReference.CLAMP_TO_GROUND` | 可选 高度参考，决定是否仅贴模型、仅贴地形、全部都考虑
`original` | boolean | `false` | 可选 计算失败时是否返回原始高度值
`min` | number |  | 可选 限定最小数,屏蔽异常数
`max` | number |  | 可选 限定最大数,屏蔽异常数

##### 返回值:

贴地高度

#### static mars3d.PointUtil.getMaxHeight(positions, defaultVal) → number
util/PointUtil.js 84

获取 坐标数组 中 最高高程值

参数名称 | 类型 | 默认值 | 描述信息
--- | --- | --- | ---
`positions` | Array.<Cesium.Cartesian3> | Array.<LngLatPoint> | Array |  | 笛卡尔坐标数组
`defaultVal` | number | `0` | 可选 默认高程值

##### 返回值:

最高高程值

#### static mars3d.PointUtil.getMidpoint(mpt1, mpt2, fraction) → Cesium.Cartesian3
util/PointUtil.js 343

求2点的中间点（贴地表）

参数名称 | 类型 | 默认值 | 描述信息
--- | --- | --- | ---
`mpt1` | Cesium.Cartesian3 | LngLatPoint |  | 点1坐标
`mpt2` | Cesium.Cartesian3 | LngLatPoint |  | 点2坐标
`fraction` | number | `0.5` | 可选 起始点和终点之间距离的比例

##### 返回值:

中间点

#### static mars3d.PointUtil.getMinHeight(positions, defaultVal) → number
util/PointUtil.js 115

获取 坐标数组 中 最低高程值

参数名称 | 类型 | 默认值 | 描述信息
--- | --- | --- | ---
`positions` | Array.<Cesium.Cartesian3> |  | 笛卡尔坐标数组
`defaultVal` | number | `0` | 可选 默认高程值

##### 返回值:

最低高程值

#### static mars3d.PointUtil.getOnLinePointByLen(p1, p2, len, addBS) → Cesium.Cartesian3
util/PointUtil.js 424

求 p1指向p2方向线上，距离p1或p2指定长度的 新的点

参数名称 | 类型 | 默认值 | 描述信息
--- | --- | --- | ---
`p1` | Cesium.Cartesian3 |  | 起点坐标
`p2` | Cesium.Cartesian3 |  | 终点坐标
`len` | number |  | 指定的距离，addBS为false时：len为距离起点p1的距离，addBS为true时：len为距离终点p2的距离
`addBS` | boolean | `false` | 可选 标识len的参考目标

##### 返回值:

计算得到的新坐标

#### static mars3d.PointUtil.getOnLinePointByRatio(p1, p2, ratio) → Cesium.Cartesian3
util/PointUtil.js 449

求 p1指向p2方向线上，距离p1指定比例的 新的点

参数名称 | 类型 | 描述信息
--- | --- | ---
`p1` | Cesium.Cartesian3 | 起点坐标
`p2` | Cesium.Cartesian3 | 终点坐标
`ratio` | number | 指定的比例，0-1的时候在P1-P2之间，大于1在P2后面

##### 返回值:

计算得到的新坐标

#### static mars3d.PointUtil.getPositionByDirectionAndLen(position, angle, radius) → Cesium.Cartesian3
util/PointUtil.js 496

根据观察点的方向角度和距离，计算目标点坐标

参数名称 | 类型 | 描述信息
--- | --- | ---
`position` | Cesium.Cartesian3 | LngLatPoint | 观察点坐标
`angle` | number | 方向角度 (正东方向为0,顺时针到360度)
`radius` | number | 半径距离

##### 返回值:

目标点坐标

#### static mars3d.PointUtil.getPositionByHprAndLen(position, hpr, radiusZ) → Cesium.Cartesian3
util/PointUtil.js 522

根据观察点的hpr方向和距离，计算目标点坐标

参数名称 | 类型 | 描述信息
--- | --- | ---
`position` | Cesium.Cartesian3 | LngLatPoint | 观察点坐标
`hpr` | Cesium.HeadingPitchRoll | 方向值
`radiusZ` | number | 半径距离

##### 返回值:

目标点坐标

#### static mars3d.PointUtil.getPositionByHprAndOffset(position, offest, hpr, ellipsoid, fixedFrameTransform) → Cesium.Cartesian3
util/PointUtil.js 471

根据 坐标位置、hpr方向、偏移距离，计算目标点坐标

参数名称 | 类型 | 默认值 | 描述信息
--- | --- | --- | ---
`position` | Cesium.Cartesian3 | LngLatPoint |  | 坐标位置
`offest` | Cesium.Cartesian3 |  | 偏移距离值, xyz值的单位：米
`hpr` | Cesium.HeadingPitchRoll |  | 方向值
`ellipsoid` | Cesium.Ellipsoid | `Cesium.Ellipsoid.WGS84` | 可选 变换中使用固定坐标系的椭球。
`fixedFrameTransform` | Cesium.Transforms.LocalFrameToFixedFrame | `Cesium.Transforms.eastNorthUpToFixedFrame` | 可选 参考系

##### 返回值:

目标点坐标

#### static mars3d.PointUtil.getPositionValue(position, time) → Cesium.Cartesian3
util/PointUtil.js 60

获取position的最终value值， 因为cesium经常属性或绑定一层，通过该方法可以内部去判断是否有getValue或_value进行取最终value值。

参数名称 | 类型 | 默认值 | 描述信息
--- | --- | --- | ---
`position` | Cesium.Cartesian3 | Cesium.SampledPositionProperty | * |  | 各种位置属性对象
`time` | Cesium.JulianDate | `Cesium.JulianDate.now()` | 可选 指定的时间值 ,如 map.clock.currentTime

##### 返回值:

具体的Cartesian3对象坐标值

#### static mars3d.PointUtil.getPropertyIndex(property, time, result) → object
util/PointUtil.js 705

获取属性坐标对应时间的index和坐标值

参数名称 | 类型 | 描述信息
--- | --- | ---
`property` | Cesium.SampledPositionProperty | 属性坐标
`time` | Cesium.JulianDate | 指定时间
`result` | Cesium.Cartesian3 | 可选 坐标对象

##### 返回值:

返回index和坐标值 , 示例：{ position: xx, index:xx }

#### static mars3d.PointUtil.getRayEarthPosition(position, orientation, reverse, ellipsoid, fixedFrameTransform) → Cesium.Cartesian3
util/PointUtil.js 546

按观察点坐标和orientation方向，求观察点射向地球与地球的交点

参数名称 | 类型 | 默认值 | 描述信息
--- | --- | --- | ---
`position` | Cesium.Cartesian3 |  | 观察点坐标
`orientation` | Cesium.HeadingPitchRoll | Cesium.Quaternion |  | HeadingPitchRoll方向 或 四元数实例
`reverse` | boolean |  | 是否翻转射线方向
`ellipsoid` | Cesium.Ellipsoid | `Cesium.Ellipsoid.WGS84` | 可选 变换中使用固定坐标系的椭球。
`fixedFrameTransform` | Cesium.Transforms.LocalFrameToFixedFrame | `Cesium.Transforms.eastNorthUpToFixedFrame` | 可选 参考系

##### 返回值:

射线与地球的交点

#### static mars3d.PointUtil.getRayEarthPositionByMatrix(matrix, reverse, ellipsoid) → Cesium.Cartesian3
util/PointUtil.js 572

按转换矩阵，求观察点射向地球与地球的交点

参数名称 | 类型 | 默认值 | 描述信息
--- | --- | --- | ---
`matrix` | Cesium.Matrix4 |  | 转换矩阵
`reverse` | boolean |  | 是否翻转射线方向
`ellipsoid` | Cesium.Ellipsoid | `Cesium.Ellipsoid.WGS84` | 可选 变换中使用固定坐标系的椭球。

##### 返回值:

射线与地球的交点

#### static mars3d.PointUtil.getReflectVector(view, normal) → Cesium.Cartesian3
util/PointUtil.js 687

获取反射向量

参数名称 | 类型 | 描述信息
--- | --- | ---
`view` | Cesium.Cartesian3 | 视角方向
`normal` | Cesium.Cartesian3 | 法线方向

##### 返回值:

反射向量

#### static mars3d.PointUtil.getRotateCenterPoint(center, point1, angle) → Cesium.Cartesian3
util/PointUtil.js 390

获取 点point1 绕 点center 的地面法向量 旋转顺时针angle角度 后的 新坐标

参数名称 | 类型 | 描述信息
--- | --- | ---
`center` | Cesium.Cartesian3 | 中心点坐标
`point1` | Cesium.Cartesian3 | 点坐标
`angle` | number | 旋转角度,顺时针方向 0至360度

##### 返回值:

计算得到的新坐标

#### static mars3d.PointUtil.getSurfaceHeight(scene, position, options) → Promise.<object>
util/PointUtil.js 246

异步精确计算坐标的 贴地(或贴模型)高度

参数名称 | 类型 | 默认值 | 描述信息
--- | --- | --- | ---
`scene` | Cesium.Scene |  | 三维地图场景对象，一般用map.scene或viewer.scene
`position` | Cesium.Cartesian3 | LngLatPoint |  | 坐标
`options` | object | `{}` | 可选 参数对象:
参数名称 | 类型 | 默认值 | 描述信息
--- | --- | --- | ---
`has3dtiles` | boolean | `auto` | 可选 是否在3dtiles模型上分析（模型分析较慢，按需开启）, 默认内部根据点的位置自动判断（但可能不准）
`objectsToExclude` | Array.<object> |  | 可选 贴模型分析时，排除的不进行贴模型计算的模型对象，可以是： primitives, entities, 或 3D Tiles features

##### 返回值:

异步计算完成的Promise

##### 使用示例:

    const position = graphic.position
      mars3d.PointUtil.getSurfaceHeight(map.scene, graphic.position, { has3dtiles: true }).then((result) => {
        console.log("原始高度为：" + result.height_original.toFixed(2) + ",贴地高度：" + result.height.toFixed(2))

        graphic.position = result.position
      })

#### static mars3d.PointUtil.getSurfacePosition(scene, position, options) → Cesium.Cartesian3
util/PointUtil.js 281

计算 贴地(或贴模型)高度 坐标 （非精确计算，根据当前加载的地形和模型数据情况有关）

参数名称 | 类型 | 默认值 | 描述信息
--- | --- | --- | ---
`scene` | Cesium.Scene |  | 三维地图场景对象，一般用map.scene或viewer.scene
`position` | Cesium.Cartesian3 |  | 坐标
`options` | object | `{}` | 可选 参数对象，具有以下属性:
参数名称 | 类型 | 默认值 | 描述信息
--- | --- | --- | ---
`heightReference` | Cesium.HeightReference | `Cesium.HeightReference.CLAMP_TO_GROUND` | 可选 高度参考，决定是否仅贴模型、仅贴地形、全部都考虑
`minHeight` | number |  | 可选 可以限定最低高度，当计算的结果小于minHeight时，原样返回position
`maxHeight` | number |  | 可选 可以限定最高高度，当计算的结果大于maxHeight时，原样返回position

##### 返回值:

贴地坐标

#### static mars3d.PointUtil.getSurfaceTerrainHeight(scene, position) → Promise.<object>
util/PointUtil.js 259

异步精确计算坐标的 贴地形高度

参数名称 | 类型 | 描述信息
--- | --- | ---
`scene` | Cesium.Scene | 三维地图场景对象，一般用map.scene或viewer.scene
`position` | Cesium.Cartesian3 | LngLatPoint | 坐标

##### 返回值:

异步计算完成的Promise

#### static mars3d.PointUtil.getTransFun(srcCoordType, dstCoordType) → function
util/PointUtil.js 20

获取PointTrans中对应的坐标转换方法 srcCoordType 转 dstCoordType 对应的方法名称

参数名称 | 类型 | 描述信息
--- | --- | ---
`srcCoordType` | ChinaCRS | 原始的坐标系
`dstCoordType` | ChinaCRS | 转换后的坐标系

##### 返回值:

PointTrans中对应的坐标转换方法

#### static mars3d.PointUtil.isRepeatPoint(mpt1, mpt2) → boolean
util/PointUtil.js 370

判断2个点是否为重复的点，比如标绘中的双击会偶尔产生2个重复点

参数名称 | 类型 | 描述信息
--- | --- | ---
`mpt1` | Cesium.Cartesian3 | 点1坐标
`mpt2` | Cesium.Cartesian3 | 点2坐标

##### 返回值:

2个点是否为重复的点

#### static mars3d.PointUtil.locHpr2CameraHpr(scene, position, hpr) → Cesium.HeadingPitchRoll
util/PointUtil.js 876

Camera相机的hpr方向 转为 普通hpr方向

参数名称 | 类型 | 描述信息
--- | --- | ---
`scene` | Cesium.Scene | 三维地图场景对象，一般用map.scene或viewer.scene
`position` | Cesium.Cartesian3 | LngLatPoint | 坐标
`hpr` | Cesium.HeadingPitchRoll | 相机朝向的Heading Pitch Roll方向

##### 返回值:

普通hpr方向

#### static mars3d.PointUtil.setPositionsHeight(positions, height) → Cesium.Cartesian3|Array.<Cesium.Cartesian3>
util/PointUtil.js 170

对坐标（或坐标数组）赋值修改为 指定的海拔高度值

参数名称 | 类型 | 默认值 | 描述信息
--- | --- | --- | ---
`positions` | Cesium.Cartesian3 | Array.<Cesium.Cartesian3> |  | 笛卡尔坐标数组
`height` | number | `0` | 可选 增加的海拔高度值

##### 返回值:

增加高度后的坐标（或坐标数组）