【004--001】-CesiumJS-API-Transforms类中各个函数的作用

1. Cesium.Transforms.computeFixedToIcrfMatrix(date, result) → Matrix3

其作用是计算将一个固定的地球坐标系（固定系）转换为一个惯性坐标系（ICRF系）的变换矩阵。其中，ICRF是Inertial Celestial Reference Frame的缩写，指的是一种与地球固定的坐标系相对静止的坐标系，用于描述天体在太阳系中的运动。

这个函数接受一个时间参数，用于计算地球在该时刻的位置和姿态。函数返回一个Matrix3类型的变换矩阵，可以用于将固定系坐标下的向量或点转换为ICRF系坐标下的向量或点。

具体的计算过程包括以下步骤：

1. 计算儒略日（Julian Date）。

2. 计算地球在儒略日对应时刻的位置和姿态。

3. 根据地球的位置和姿态，计算从固定系到ICRF系的旋转矩阵。

4. 将旋转矩阵转换为Matrix3类型的变换矩阵。

使用这个函数需要注意以下几点：

5. 时间参数必须是一个合法的儒略日。

6. 这个函数计算的是地球的位置和姿态，因此只适用于地球上的应用。

7. 由于计算过程比较复杂，因此调用这个函数的时间可能比较长，需要注意性能问题。

下面是一个使用computeFixedToIcrfMatrix函数将固定系坐标下的向量转换为ICRF系坐标下的向量的示例代码：

// 计算当前时刻的固定系到ICRF系的变换矩阵
var fixedToIcrf = Cesium.Transforms.computeFixedToIcrfMatrix(Cesium.JulianDate.now());
// 定义一个固定系坐标下的向量
var fixedVector = new Cesium.Cartesian3(0.0, 0.0, 6378137.0);
// 将固定系坐标下的向量转换为ICRF系坐标下的向量
var icrfVector = Cesium.Matrix3.multiplyByVector(fixedToIcrf, fixedVector, new Cesium.Cartesian3());
// 输出转换后的向量
console.log(icrfVector);

2. Cesium.Transforms.computeIcrfToFixedMatrix(date, result) → Matrix3

用于计算一个时间的惯性参考系（ICRF）转换为固定参考系（fixed）的4x4变换矩阵。ICRF是一个与地球相对静止的参考系，用于描述宇宙中物体的位置和运动。

这个函数需要传入一个JulianDate类型的时间参数，并返回一个Matrix4类型的矩阵。

使用示例：

// 通过JulianDate获取当前时间
var time = Cesium.JulianDate.now();
// 获取地球上的一个位置
var position = Cesium.Cartesian3.fromDegrees(-75.59777, 40.03883);
// 获取ICRF到固定参考系的变换矩阵
var icrfToFixed = Cesium.Transforms.computeIcrfToFixedMatrix(time);
// 将位置从ICRF坐标系转换到固定参考系
var fixedPosition = Cesium.Matrix4.multiplyByPoint(icrfToFixed, position, new Cesium.Cartesian3());
console.log(fixedPosition);

首先通过JulianDate.now()函数获取当前时间。然后，使用Cesium.Cartesian3.fromDegrees函数获取地球上一个位置的Cartesian3坐标。接下来，通过调用Cesium.Transforms.computeIcrfToFixedMatrix函数获取ICRF到固定参考系的变换矩阵。最后，使用Cesium.Matrix4.multiplyByPoint函数将位置从ICRF坐标系转换到固定参考系。

3. Cesium.Transforms.computeTemeToPseudoFixedMatrix(date, result) → Matrix3

用于计算瞬时地心惯性系 (True Equator Mean Equinox) 到假定固定的旋转地球坐标系的转换矩阵。它的作用是将给定瞬时地心惯性系 (True Equator Mean Equinox) 的位置、速度和加速度数据转换为假定固定的旋转地球坐标系的数据。这个函数的输入参数为一个 JulianDate 类型的时间和一个指向一个 Cartesian3 类型的地球位置向量的引用。它返回一个 Matrix3 类型的旋转矩阵，可以将瞬时地心惯性系的位置、速度和加速度数据转换到假定固定的旋转地球坐标系。

以下是使用示例代码：
// Calculate JulianDate object from current date and time
var now = Cesium.JulianDate.now();
// Define the position of the earth at the current time
var position = new Cesium.Cartesian3(6378137.0, 0.0, 0.0);
// Calculate the rotation matrix from TEME to pseudo-fixed frame
var temeToPseudoFixedMatrix = Cesium.Transforms.computeTemeToPseudoFixedMatrix(now, position);
// Convert a position from TEME to pseudo-fixed frame
var positionInTeme = new Cesium.Cartesian3(0.0, 7000000.0, 0.0);
var positionInPseudoFixed = Cesium.Matrix3.multiplyByVector(temeToPseudoFixedMatrix, positionInTeme, new Cesium.Cartesian3());

使用 Cesium.JulianDate.now() 方法计算当前日期和时间的 JulianDate 对象。然后，它定义了地球在当前时间的位置，该位置为 x 轴上的单位向量。接下来，它使用 Cesium.Transforms.computeTemeToPseudoFixedMatrix() 函数计算从 TEME 到假定固定的旋转地球坐标系的转换矩阵。最后，它将一个在 TEME 坐标系中的位置向量转换为假定固定的旋转地球坐标系中的位置向量。

4. Cesium.Transforms.eastNorthUpToFixedFrame(origin, ellipsoid, result) → Matrix4

其作用是计算一个东北向上坐标系（ENU）到固定坐标系的转换矩阵。

具体而言，该函数接受一个Cartesian3类型的位置参数作为中心点，然后根据该点在WGS84椭球体上的位置计算该点的东北向上坐标系，并将其转换为固定坐标系。函数返回一个Matrix4类型的矩阵，该矩阵将任何坐标从东北向上坐标系转换为固定坐标系。

在使用此函数时，应注意输入的位置参数必须使用WGS84椭球体上的坐标。如果使用其他椭球体或大地水准面上的坐标，则需要使用其他转换函数将其转换为WGS84坐标。

使用示例：

// 获取某个位置的东北向上坐标系到固定坐标系的转换矩阵var position = Cesium.Cartesian3.fromDegrees(-75.59777, 40.03883);var enuToFixed = Cesium.Transforms.eastNorthUpToFixedFrame(position);
// 将某个点从ENU坐标系转换为固定坐标系var pointInEnu = new Cesium.Cartesian3(1000, 2000, 3000);var pointInFixed = Cesium.Matrix4.multiplyByPoint(enuToFixed, pointInEnu, new Cesium.Cartesian3());
// 在Cesium场景中创建一个以某个位置为中心的地图视图var viewer = new Cesium.Viewer('cesiumContainer');var center = Cesium.Cartesian3.fromDegrees(-75.59777, 40.03883);var enuToFixed = Cesium.Transforms.eastNorthUpToFixedFrame(center);viewer.scene.camera.setView({destination: Cesium.Cartesian3.fromDegrees(-75.59777, 40.03883, 1000),orientation: {direction: Cesium.Cartesian3.negate(Cesium.Cartesian3.UNIT_Z, new Cesium.Cartesian3()),up: Cesium.Cartesian3.clone(Cesium.Cartesian3.UNIT_Y),right: Cesium.Cartesian3.clone(Cesium.Cartesian3.UNIT_X)}});

5. Cesium.Transforms.fixedFrameToHeadingPitchRoll(transform, ellipsoid, fixedFrameTransform, result) → HeadingPitchRoll

函数是用于计算一个确定的本地坐标系与一个参考椭球体上的正东、正北和正上方之间的旋转，即方位、俯仰和翻转角度。此函数返回一个包含方位、俯仰和翻转角度的对象，以弧度为单位。

var position = Cesium.Cartesian3.fromDegrees(-74.0707383, 40.7117244);
var headingPitchRoll = new Cesium.HeadingPitchRoll();
// 获取本地坐标系到参考椭球体的固定框架的转换函数
var transform = Cesium.Transforms.eastNorthUpToFixedFrame(position);
// 计算旋转角度
Cesium.Transforms.fixedFrameToHeadingPitchRoll(transform, Cesium.Ellipsoid.WGS84, headingPitchRoll);
console.log(headingPitchRoll.heading); // 方位角，弧度值
console.log(headingPitchRoll.pitch); // 俯仰角，弧度值
console.log(headingPitchRoll.roll); // 翻滚角，弧度值

6. Cesium.Transforms.headingPitchRollQuaternion(origin, headingPitchRoll, ellipsoid, fixedFrameTransform, result) → Quaternion

用于计算从本地参考系（东北天）到惯性参考系（ICRF）的旋转四元数。它的作用是将给定的“heading”（方位角）、“pitch”（俯仰角）和“roll”（翻滚角）转换为一个旋转四元数，该四元数可以被用于将来自本地参考系的坐标旋转到惯性参考系下的坐标。

这个方法接受两个参数：

• headingPitchRoll：一个对象，包含三个属性 heading、pitch 和 roll，它们都是以弧度为单位的角度值。

• result：一个可选的 Quaternion 对象，用于存储计算结果。如果未提供，则会创建一个新的 Quaternion 对象。

下面是一个示例代码，它演示了如何使用 headingPitchRollQuaternion 方法将本地参考系下的坐标（即相机位置）旋转到惯性参考系下的坐标：

// 定义本地参考系下的坐标（相机位置）
var localPosition = new Cesium.Cartesian3(x, y, z);
// 定义本地参考系下的方位角、俯仰角和翻滚角
var heading = Cesium.Math.toRadians(90);
var pitch = Cesium.Math.toRadians(-45);
var roll = Cesium.Math.toRadians(0);
// 计算旋转四元数
var rotation = Cesium.Transforms.headingPitchRollQuaternion(
    { heading: heading, pitch: pitch, roll: roll }
);
// 将本地参考系下的坐标旋转到惯性参考系下的坐标
var inertialPosition = Cesium.Matrix3.multiplyByVector(
    Cesium.Matrix3.fromQuaternion(rotation),
    localPosition,
    new Cesium.Cartesian3()
);

我们首先定义了一个本地参考系下的坐标 localPosition，然后定义了方位角、俯仰角和翻滚角，接着调用 headingPitchRollQuaternion 方法计算了旋转四元数 rotation，最后使用 Matrix3.multiplyByVector 方法将本地参考系下的坐标旋转到惯性参考系下的坐标 inertialPosition。

7. Cesium.Transforms.headingPitchRollToFixedFrame(origin, headingPitchRoll, ellipsoid, fixedFrameTransform, result) → Matrix4

其作用是根据提供的方位角、俯仰角和翻滚角计算一个旋转矩阵，将地球上的东北天坐标系转换为固定参考系。

函数定义如下：

static headingPitchRollToFixedFrame(headingPitchRoll, ellipsoid, fixedFrameTransform)

参数说明：

• headingPitchRoll：一个包含三个角度值的数组，表示方位角、俯仰角和翻滚角，单位为弧度。

• ellipsoid：一个Ellipsoid对象，表示地球的椭球体。

• fixedFrameTransform：一个Matrix4对象，表示一个从惯性系到固定参考系的转换矩阵。

函数返回值为一个Matrix4对象，表示一个从地球上的东北天坐标系到固定参考系的转换矩阵。

示例代码：

// 定义一个地球对象
var ellipsoid = Cesium.Ellipsoid.WGS84;
// 定义方位角、俯仰角和翻滚角
var headingPitchRoll = new Cesium.HeadingPitchRoll(Cesium.Math.toRadians(45), Cesium.Math.toRadians(-30), Cesium.Math.toRadians(60));
// 计算转换矩阵
var fixedFrameTransform = Cesium.Transforms.eastNorthUpToFixedFrame(Cesium.Cartesian3.fromDegrees(120.0, 30.0, 0.0));
var transformMatrix = Cesium.Transforms.headingPitchRollToFixedFrame(headingPitchRoll, ellipsoid, fixedFrameTransform);

上述代码中，首先定义了一个地球对象，然后定义了一个包含方位角、俯仰角和翻滚角的数组。接着，通过调用eastNorthUpToFixedFrame方法计算了一个固定参考系的转换矩阵，最后调用headingPitchRollToFixedFrame方法计算了一个从地球上的东北天坐标系到固定参考系的转换矩阵。

8. Cesium.Transforms.localFrameToFixedFrameGenerator(firstAxis, secondAxis) → Transforms.LocalFrameToFixedFrame

它返回一个函数，用于计算本地坐标系到固定坐标系的变换矩阵。该函数的原型如下：

staticlocalFrameToFixedFrameGenerator(axes: Transforms.LocalFrameAxes): Transforms.LocalFrameToFixedFrame;

其中，axes是一个对象，描述本地坐标系的三个轴向，包括以下属性：

• east：表示本地坐标系的东向量，类型为Cartesian3。

• north：表示本地坐标系的北向量，类型为Cartesian3。

• up：表示本地坐标系的上向量，类型为Cartesian3。

返回值是一个函数，原型为：

typescriptCopy codetypeLocalFrameToFixedFrame = (origin: Cartesian3) =>Matrix4

该函数用于计算从本地坐标系到固定坐标系的变换矩阵。参数origin是本地坐标系的原点，类型为Cartesian3。返回值是一个Matrix4对象，表示从本地坐标系到固定坐标系的变换矩阵。

使用该函数时，首先需要定义本地坐标系的三个轴向，例如：

const axes = {
  east: newCesium.Cartesian3(1, 0, 0),
  north: newCesium.Cartesian3(0, 1, 0),
  up: newCesium.Cartesian3(0, 0, 1),
};

然后，可以调用localFrameToFixedFrameGenerator函数，生成一个从本地坐标系到固定坐标系的变换函数：

const localFrameToFixedFrame = Cesium.Transforms.localFrameToFixedFrameGenerator(axes);

最后，可以使用该函数将本地坐标系的点变换到固定坐标系：

const origin = newCesium.Cartesian3(0, 0, 0);
const localPosition = newCesium.Cartesian3(1, 2, 3);
const fixedPosition = localFrameToFixedFrame(origin)(localPosition);

以上代码将本地坐标系的点(1, 2, 3)变换到固定坐标系，并将结果存储在fixedPosition中。

9. Cesium.Transforms.northEastDownToFixedFrame(origin, ellipsoid, result) → Matrix4

用于生成将局部坐标系转换为惯性坐标系的变换矩阵，其中局部坐标系以北、东、下方向为坐标轴。其函数定义如下：

Cesium.Transforms.northEastDownToFixedFrame(origin, ellipsoid, result)

其中，origin为局部坐标系的原点，类型为Cartesian3；ellipsoid为参考椭球体，类型为Ellipsoid；result为输出的变换矩阵，类型为Matrix4。如果未提供result，则函数会创建一个新的变换矩阵并返回。

这个函数的返回值是一个Matrix4类型的变换矩阵，表示将局部坐标系转换为惯性坐标系的变换。

10. Cesium.Transforms.northUpEastToFixedFrame(origin, ellipsoid, result) → Matrix4

函数的作用是计算给定原点处的从北向上、东向右的局部坐标系（通常称为ENU）与固定坐标系之间的转换矩阵。

具体来说，该函数使用提供的原点计算固定坐标系下该点的位置，并将ENU坐标系转换为该固定坐标系下的坐标系。它返回一个四元数，用于将ENU坐标系的向量旋转到固定坐标系。

使用该函数时需要提供以下参数：

• center：一个Cartesian3类型的点，表示局部坐标系的原点。

• ellipsoid：一个Ellipsoid类型的椭球体，用于确定原点所在的椭球体表面。

• fixedFrameTransform：一个Transform类型的函数，将ENU坐标系的向量转换为固定坐标系下的向量。该函数可以通过调用localFrameToFixedFrameGenerator来创建。

下面是一个使用northUpEastToFixedFrame函数的示例代码：

// 定义局部坐标系的原点
var center = Cesium.Cartesian3.fromDegrees(-75.59777, 40.03883, 0);
// 创建一个椭球体对象
var ellipsoid = Cesium.Ellipsoid.WGS84;
// 创建一个将ENU坐标系转换为固定坐标系的函数
var transform = Cesium.Transforms.northUpEastToFixedFrame(center, ellipsoid);
// 将一个在ENU坐标系下的向量转换为固定坐标系下的向量
var enuVector = new Cesium.Cartesian3(1.0, 0.0, 0.0);
var fixedVector = transform(enuVector);
// 创建一个四元数，用于将ENU坐标系的向量旋转到固定坐标系
var enuQuaternion = Cesium.Quaternion.fromAxisAngle(enuVector, Cesium.Math.PI_OVER_TWO);
var fixedQuaternion = Cesium.Quaternion.multiplyTransformation(transform, enuQuaternion);
// 将一个在ENU坐标系下的位置转换为固定坐标系下的位置
var enuPosition = new Cesium.Cartesian3(10.0, 0.0, 0.0);
var fixedPosition = Cesium.Matrix3.multiplyByVector(transform, enuPosition, new Cesium.Cartesian3());
fixedPosition = Cesium.Cartesian3.add(center, fixedPosition, new Cesium.Cartesian3());

11. Cesium.Transforms.northWestUpToFixedFrame(origin, ellipsoid, result) → Matrix4

用于根据给定的地球上的位置，创建一个固定于一个以该位置为中心的以北西向上（NWU）为坐标轴的参考系的4x4变换矩阵。

函数定义如下：

northWestUpToFixedFrame(origin, ellipsoid, result);

其中，origin是以弧度表示的一个包含经度、纬度和高度信息的Cartographic对象，ellipsoid是地球椭球体模型，result是一个可选的Matrix4对象，表示函数的输出结果。

函数返回一个Matrix4对象，表示固定在NWU参考系的变换矩阵。

使用示例：

var origin = Cesium.Cartographic.fromDegrees(-75.59777, 40.03883, 300);
var transform = Cesium.Transforms.northWestUpToFixedFrame(origin, Cesium.Ellipsoid.WGS84);

上面的代码将创建一个以(-75.59777, 40.03883)为中心的NWU坐标系，其中原点高度为300米，使用WGS84椭球体模型。

12. esium.Transforms.pointToWindowCoordinates(modelViewProjectionMatrix, viewportTransformation, point, result) → Cartesian2

用于将场景中的三维点转换为屏幕上的二维坐标。它需要一个PointPrimitive对象和一个Scene对象作为参数，并返回一个Cartesian2对象，表示屏幕上的坐标。在转换过程中，函数使用了Canvas坐标系，其中屏幕左上角是(0,0)，屏幕右下角是(width, height)。

注意，如果点在屏幕外，返回的坐标将是负数，表示该点不可见。

用法示例：

var scene = viewer.scene;
var ellipsoid = viewer.scene.globe.ellipsoid;
// Create a point primitive
var point = new Cesium.PointPrimitive({
    position : ellipsoid.cartographicToCartesian(Cesium.Cartographic.fromDegrees(-75.59777, 40.03883)),
    color : Cesium.Color.RED
});
// Add the point to the scene
scene.primitives.add(point);
// Get the screen coordinates of the point
var windowPosition = Cesium.SceneTransforms.pointToWindowCoordinates(scene, point.position);
console.log(windowPosition);

13. Cesium.Transforms.preloadIcrfFixed(timeInterval) → Promise.<void>

是一个静态函数，用于预加载固定坐标系（fixed frame）和惯性坐标系（ICRF）之间的转换矩阵。预加载矩阵可以在场景中需要进行大量相机和实体位置计算的情况下提高性能。在调用任何需要该矩阵的函数之前，预加载该矩阵可以避免需要时再进行计算，从而提高性能。

是一个异步函数，用于预加载将惯性系固定到地球固定系的转换矩阵，以减少第一次调用时的延迟。该函数返回一个Promise，当转换矩阵已经准备好时，Promise将被解析。

使用示例：

Cesium.Transforms.preloadIcrfFixed(timeInterval, maximumMemoryUsage)

注意点：

• 该函数只有在需要频繁地使用转换矩阵时才有必要使用，否则不建议使用。

• 该函数只需调用一次即可，多次调用不会产生任何影响。

• 可以在任何时候调用该函数，但最好在需要使用转换矩阵之前调用。

14. Cesium.Transforms.rotationMatrixFromPositionVelocity(position, velocity, ellipsoid, result) → Matrix3

是Transforms类中的一个函数，用于计算一个由地心惯性系到固定参考系的旋转矩阵，该矩阵可以用于将地心惯性系中的位置和速度转换为固定参考系中的位置和速度。

函数原型如下：

Transforms.rotationMatrixFromPositionVelocity(position, velocity, ellipsoid, fixedFrameTransform)

参数说明：

• position：描述对象在惯性系中的位置的笛卡尔坐标（Cartesian3）。

• velocity：描述对象在惯性系中的速度的笛卡尔坐标（Cartesian3）。

• ellipsoid：用于确定当前坐标系的椭球体（Ellipsoid）。

• fixedFrameTransform：描述坐标系之间的变换的矩阵（Matrix4），表示从惯性系到目标坐标系的变换。

该函数返回一个描述惯性系到固定参考系的旋转矩阵（Matrix3）。

注意事项：

• 该函数中的参数单位应该是米和秒，如果需要使用其他单位，需要自行进行单位转换。

• 该函数中的旋转矩阵是一个3x3的矩阵，而不是4x4的矩阵，因此不能直接使用Transforms类中的相关函数进行坐标变换，需要使用Matrix3类中的相关函数进行处理。

示例代码：

var position = Cesium.Cartesian3.fromDegrees(-75.62898254394531, 40.02804946899414, 1000.0);
var velocity = new Cesium.Cartesian3(0.0, 0.0, -5000.0);
var ellipsoid = Cesium.Ellipsoid.WGS84;
var fixedFrameTransform = Cesium.Transforms.computeTemeToPseudoFixedMatrix(new Date());
var rotationMatrix = Cesium.Transforms.rotationMatrixFromPositionVelocity(position, velocity, ellipsoid, fixedFrameTransform);
console.log(rotationMatrix);

15. Cesium.Transforms.LocalFrameToFixedFrame(origin, ellipsoid, result) → Matrix4

用于将局部坐标系的点转换为固定坐标系中的点。其定义如下：

static LocalFrameToFixedFrameGenerator LocalFrameToFixedFrame(Cartesian3 origin, Ellipsoid ellipsoid, LocalFrameEastNorthUp localFrame)

该函数的参数包括：

• origin: 局部坐标系的原点，类型为 Cartesian3。

• ellipsoid: 用于进行坐标转换的参考椭球体，类型为 Ellipsoid。

• localFrame: 局部坐标系，类型为 LocalFrameEastNorthUp。

返回值是一个 LocalFrameToFixedFrameGenerator 对象，可以用来将局部坐标系中的点转换为固定坐标系中的点。使用示例如下：

// 定义一个原点为 (0, 0, 0) 的局部坐标系
var localFrame = new Cesium.LocalFrameEastNorthUp(Cesium.Ellipsoid.WGS84, Cesium.Cartesian3.ZERO);
// 获取一个将局部坐标系中点 (10000, 0, 0) 转换到固定坐标系中的函数
var localToFixedFrame = Cesium.Transforms.LocalFrameToFixedFrame(Cesium.Cartesian3.ZERO, Cesium.Ellipsoid.WGS84, localFrame);
var pointInFixedFrame = localToFixedFrame(Cesium.Cartesian3.fromArray([10000, 0, 0]));
console.log(pointInFixedFrame); // 输出：Cartesian3 {x: 6378137.000000145, y: 0, z: 0}

本函数主要用于在三维场景中创建自定义坐标系，将局部坐标系中的点转换为固定坐标系中的点，以便正确地渲染和交互。