Transforms - Cesium Documentation

# Transforms

Contains functions for transforming positions to various reference frames.

Source: Core/Transforms.js, line 48

### Methods

#### staticTransforms.computeFixedToIcrfMatrix(date, result) → Matrix3

  Computes a rotation matrix to transform a point or vector from the Earth-Fixed frame axes (ITRF) to the International Celestial Reference Frame (GCRF/ICRF) inertial frame axes at a given time. This function may return undefined if the data necessary to do the transformation is not yet loaded.

  Name | Type | Description
  --- | --- | ---
  `date` | JulianDate | The time at which to compute the rotation matrix.
  `result` | Matrix3 | optional The object onto which to store the result. If this parameter is not specified, a new instance is created and returned.

  ##### Returns:

  The rotation matrix, or undefined if the data necessary to do the transformation is not yet loaded.

  ##### Example:

      // Transform a point from the ICRF axes to the Fixed axes.
      var now = new Cesium.JulianDate();
      var pointInFixed = Cesium.Cartesian3.fromDegrees(0.0, 0.0);
      var fixedToIcrf = Cesium.Transforms.computeIcrfToFixedMatrix(now);
      var pointInInertial = new Cesium.Cartesian3();
      if (Cesium.defined(fixedToIcrf)) {
          pointInInertial = Cesium.Matrix3.multiplyByVector(fixedToIcrf, pointInFixed, pointInInertial);
      }

  ##### See:

  - Transforms.preloadIcrfFixed
  Source: Core/Transforms.js, line 625

#### staticTransforms.computeIcrfToFixedMatrix(date, result) → Matrix3

  Computes a rotation matrix to transform a point or vector from the International Celestial Reference Frame (GCRF/ICRF) inertial frame axes to the Earth-Fixed frame axes (ITRF) at a given time. This function may return undefined if the data necessary to do the transformation is not yet loaded.

  Name | Type | Description
  --- | --- | ---
  `date` | JulianDate | The time at which to compute the rotation matrix.
  `result` | Matrix3 | optional The object onto which to store the result. If this parameter is not specified, a new instance is created and returned.

  ##### Returns:

  The rotation matrix, or undefined if the data necessary to do the transformation is not yet loaded.

  ##### Example:

      scene.preRender.addEventListener(function(scene, time) {
        var icrfToFixed = Cesium.Transforms.computeIcrfToFixedMatrix(time);
        if (Cesium.defined(icrfToFixed)) {
          var offset = Cesium.Matrix4.multiplyByPoint(camera.transform, camera.position, new Cesium.Cartesian3());
          var transform = Cesium.Matrix4.fromRotationTranslation(icrfToFixed)
          var inverseTransform = Cesium.Matrix4.inverseTransformation(transform, new Cesium.Matrix4());
          Cesium.Matrix4.multiplyByPoint(inverseTransform, offset, offset);
          camera.lookAtTransform(transform, offset);
        }
      });

  ##### See:

  - Transforms.preloadIcrfFixed
  Source: Core/Transforms.js, line 578

#### staticTransforms.computeTemeToPseudoFixedMatrix(date, result) → Matrix3

  Computes a rotation matrix to transform a point or vector from True Equator Mean Equinox (TEME) axes to the pseudo-fixed axes at a given time. This method treats the UT1 time standard as equivalent to UTC.

  Name | Type | Description
  --- | --- | ---
  `date` | JulianDate | The time at which to compute the rotation matrix.
  `result` | Matrix3 | optional The object onto which to store the result.

  ##### Returns:

  The modified result parameter or a new Matrix3 instance if none was provided.

  ##### Example:

      //Set the view to in the inertial frame.
      scene.preRender.addEventListener(function(scene, time) {
         var now = new Cesium.JulianDate();
         var offset = Cesium.Matrix4.multiplyByPoint(camera.transform, camera.position, new Cesium.Cartesian3());
         var transform = Cesium.Matrix4.fromRotationTranslation(Cesium.Transforms.computeTemeToPseudoFixedMatrix(now));
         var inverseTransform = Cesium.Matrix4.inverseTransformation(transform, new Cesium.Matrix4());
         Cesium.Matrix4.multiplyByPoint(inverseTransform, offset, offset);
         camera.lookAtTransform(transform, offset);
      });

  Source: Core/Transforms.js, line 444

#### staticTransforms.eastNorthUpToFixedFrame(origin, ellipsoid, result) → Matrix4

  Computes a 4x4 transformation matrix from a reference frame with an east-north-up axes centered at the provided origin to the provided ellipsoid's fixed reference frame. The local axes are defined as:
  - The `x` axis points in the local east direction.
  - The `y` axis points in the local north direction.
  - The `z` axis points in the direction of the ellipsoid surface normal which passes through the position.

  Name | Type | Default | Description
  --- | --- | --- | ---
  `origin` | Cartesian3 |  | The center point of the local reference frame.
  `ellipsoid` | Ellipsoid | `Ellipsoid.WGS84` | optional The ellipsoid whose fixed frame is used in the transformation.
  `result` | Matrix4 |  | optional The object onto which to store the result.

  ##### Returns:

  The modified result parameter or a new Matrix4 instance if none was provided.

  ##### Example:

      // Get the transform from local east-north-up at cartographic (0.0, 0.0) to Earth's fixed frame.
      var center = Cesium.Cartesian3.fromDegrees(0.0, 0.0);
      var transform = Cesium.Transforms.eastNorthUpToFixedFrame(center);

  Source: Core/Transforms.js, line 74

#### staticTransforms.headingPitchRollQuaternion(origin, heading, pitch, roll, ellipsoid, result) → Quaternion

  Computes a quaternion from a reference frame with axes computed from the heading-pitch-roll angles centered at the provided origin. Heading is the rotation from the local north direction where a positive angle is increasing eastward. Pitch is the rotation from the local east-north plane. Positive pitch angles are above the plane. Negative pitch angles are below the plane. Roll is the first rotation applied about the local east axis.

  Name | Type | Default | Description
  --- | --- | --- | ---
  `origin` | Cartesian3 |  | The center point of the local reference frame.
  `heading` | Number |  | The heading angle in radians.
  `pitch` | Number |  | The pitch angle in radians.
  `roll` | Number |  | The roll angle in radians.
  `ellipsoid` | Ellipsoid | `Ellipsoid.WGS84` | optional The ellipsoid whose fixed frame is used in the transformation.
  `result` | Quaternion |  | optional The object onto which to store the result.

  ##### Returns:

  The modified result parameter or a new Quaternion instance if none was provided.

  ##### Example:

      // Get the quaternion from local heading-pitch-roll at cartographic (0.0, 0.0) to Earth's fixed frame.
      var center = Cesium.Cartesian3.fromDegrees(0.0, 0.0);
      var heading = -Cesium.Math.PI_OVER_TWO;
      var pitch = Cesium.Math.PI_OVER_FOUR;
      var roll = 0.0;
      var quaternion = Cesium.Transforms.headingPitchRollQuaternion(center, heading, pitch, roll);

  Source: Core/Transforms.js, line 408

#### staticTransforms.headingPitchRollToFixedFrame(origin, heading, pitch, roll, ellipsoid, result) → Matrix4

  Computes a 4x4 transformation matrix from a reference frame with axes computed from the heading-pitch-roll angles centered at the provided origin to the provided ellipsoid's fixed reference frame. Heading is the rotation from the local north direction where a positive angle is increasing eastward. Pitch is the rotation from the local east-north plane. Positive pitch angles are above the plane. Negative pitch angles are below the plane. Roll is the first rotation applied about the local east axis.

  Name | Type | Default | Description
  --- | --- | --- | ---
  `origin` | Cartesian3 |  | The center point of the local reference frame.
  `heading` | Number |  | The heading angle in radians.
  `pitch` | Number |  | The pitch angle in radians.
  `roll` | Number |  | The roll angle in radians.
  `ellipsoid` | Ellipsoid | `Ellipsoid.WGS84` | optional The ellipsoid whose fixed frame is used in the transformation.
  `result` | Matrix4 |  | optional The object onto which to store the result.

  ##### Returns:

  The modified result parameter or a new Matrix4 instance if none was provided.

  ##### Example:

      // Get the transform from local heading-pitch-roll at cartographic (0.0, 0.0) to Earth's fixed frame.
      var center = Cesium.Cartesian3.fromDegrees(0.0, 0.0);
      var heading = -Cesium.Math.PI_OVER_TWO;
      var pitch = Cesium.Math.PI_OVER_FOUR;
      var roll = 0.0;
      var transform = Cesium.Transforms.headingPitchRollToFixedFrame(center, heading, pitch, roll);

  Source: Core/Transforms.js, line 375

#### staticTransforms.northEastDownToFixedFrame(origin, ellipsoid, result) → Matrix4

  Computes a 4x4 transformation matrix from a reference frame with an north-east-down axes centered at the provided origin to the provided ellipsoid's fixed reference frame. The local axes are defined as:
  - The `x` axis points in the local north direction.
  - The `y` axis points in the local east direction.
  - The `z` axis points in the opposite direction of the ellipsoid surface normal which passes through the position.

  Name | Type | Default | Description
  --- | --- | --- | ---
  `origin` | Cartesian3 |  | The center point of the local reference frame.
  `ellipsoid` | Ellipsoid | `Ellipsoid.WGS84` | optional The ellipsoid whose fixed frame is used in the transformation.
  `result` | Matrix4 |  | optional The object onto which to store the result.

  ##### Returns:

  The modified result parameter or a new Matrix4 instance if none was provided.

  ##### Example:

      // Get the transform from local north-east-down at cartographic (0.0, 0.0) to Earth's fixed frame.
      var center = Cesium.Cartesian3.fromDegrees(0.0, 0.0);
      var transform = Cesium.Transforms.northEastDownToFixedFrame(center);

  Source: Core/Transforms.js, line 175

#### staticTransforms.northUpEastToFixedFrame(origin, ellipsoid, result) → Matrix4

  Computes a 4x4 transformation matrix from a reference frame with an north-up-east axes centered at the provided origin to the provided ellipsoid's fixed reference frame. The local axes are defined as:
  - The `x` axis points in the local north direction.
  - The `y` axis points in the direction of the ellipsoid surface normal which passes through the position.
  - The `z` axis points in the local east direction.

  Name | Type | Default | Description
  --- | --- | --- | ---
  `origin` | Cartesian3 |  | The center point of the local reference frame.
  `ellipsoid` | Ellipsoid | `Ellipsoid.WGS84` | optional The ellipsoid whose fixed frame is used in the transformation.
  `result` | Matrix4 |  | optional The object onto which to store the result.

  ##### Returns:

  The modified result parameter or a new Matrix4 instance if none was provided.

  ##### Example:

      // Get the transform from local north-up-east at cartographic (0.0, 0.0) to Earth's fixed frame.
      var center = Cesium.Cartesian3.fromDegrees(0.0, 0.0);
      var transform = Cesium.Transforms.northUpEastToFixedFrame(center);

  Source: Core/Transforms.js, line 272

#### staticTransforms.pointToWindowCoordinates(modelViewProjectionMatrix, viewportTransformation, point, result) → Cartesian2

  Transform a point from model coordinates to window coordinates.

  Name | Type | Description
  --- | --- | ---
  `modelViewProjectionMatrix` | Matrix4 | The 4x4 model-view-projection matrix.
  `viewportTransformation` | Matrix4 | The 4x4 viewport transformation.
  `point` | Cartesian3 | The point to transform.
  `result` | Cartesian2 | optional The object onto which to store the result.

  ##### Returns:

  The modified result parameter or a new Cartesian2 instance if none was provided.
  Source: Core/Transforms.js, line 740

#### staticTransforms.preloadIcrfFixed(timeInterval) → Promise.<undefined>

  Preloads the data necessary to transform between the ICRF and Fixed axes, in either direction, over a given interval. This function returns a promise that, when resolved, indicates that the preload has completed.

  Name | Type | Description
  --- | --- | ---
  `timeInterval` | TimeInterval | The interval to preload.

  ##### Returns:

  A promise that, when resolved, indicates that the preload has completed and evaluation of the transformation between the fixed and ICRF axes will no longer return undefined for a time inside the interval.

  ##### Example:

      var interval = new Cesium.TimeInterval(...);
      when(preloadIcrfFixed(interval), function() {
          // the data is now loaded
      });

  ##### See:

  - Transforms.computeIcrfToFixedMatrix
  - Transforms.computeFixedToIcrfMatrix
  - when
  Source: Core/Transforms.js, line 540