Cesium源码之flyTo(一)

 

/**
 * Flies the camera from its current position to a new position.
 *
 * @param {Object} options Object with the following properties:
 * @param {Cartesian3|Rectangle} options.destination The final position of the camera in WGS84 (world) coordinates or a rectangle that would be visible from a top-down view.
 * @param {Object} [options.orientation] An object that contains either direction and up properties or heading, pitch and roll properties. By default, the direction will point
 * towards the center of the frame in 3D and in the negative z direction in Columbus view. The up direction will point towards local north in 3D and in the positive
 * y direction in Columbus view.  Orientation is not used in 2D when in infinite scrolling mode.
 * @param {Number} [options.duration] The duration of the flight in seconds. If omitted, Cesium attempts to calculate an ideal duration based on the distance to be traveled by the flight.
 * @param {Camera.FlightCompleteCallback} [options.complete] The function to execute when the flight is complete.
 * @param {Camera.FlightCancelledCallback} [options.cancel] The function to execute if the flight is cancelled.
 * @param {Matrix4} [options.endTransform] Transform matrix representing the reference frame the camera will be in when the flight is completed.
 * @param {Number} [options.maximumHeight] The maximum height at the peak of the flight.
 * @param {Number} [options.pitchAdjustHeight] If camera flyes higher than that value, adjust pitch duiring the flight to look down, and keep Earth in viewport.
 * @param {Number} [options.flyOverLongitude] There are always two ways between 2 points on globe. This option force camera to choose fight direction to fly over that longitude.
 * @param {Number} [options.flyOverLongitudeWeight] Fly over the lon specifyed via flyOverLongitude only if that way is not longer than short way times flyOverLongitudeWeight.
 * @param {Boolean} [options.convert] Whether to convert the destination from world coordinates to scene coordinates (only relevant when not using 3D). Defaults to <code>true</code>.
 * @param {EasingFunction.Callback} [options.easingFunction] Controls how the time is interpolated over the duration of the flight.
 *
 * @exception {DeveloperError} If either direction or up is given, then both are required.
 *
 * @example
 * // 1. Fly to a position with a top-down view
 * viewer.camera.flyTo({
 *     destination : Cesium.Cartesian3.fromDegrees(-117.16, 32.71, 15000.0)
 * });
 *
 * // 2. Fly to a Rectangle with a top-down view
 * viewer.camera.flyTo({
 *     destination : Cesium.Rectangle.fromDegrees(west, south, east, north)
 * });
 *
 * // 3. Fly to a position with an orientation using unit vectors.
 * viewer.camera.flyTo({
 *     destination : Cesium.Cartesian3.fromDegrees(-122.19, 46.25, 5000.0),
 *     orientation : {
 *         direction : new Cesium.Cartesian3(-0.04231243104240401, -0.20123236049443421, -0.97862924300734),
 *         up : new Cesium.Cartesian3(-0.47934589305293746, -0.8553216253114552, 0.1966022179118339)
 *     }
 * });
 *
 * // 4. Fly to a position with an orientation using heading, pitch and roll.
 * viewer.camera.flyTo({
 *     destination : Cesium.Cartesian3.fromDegrees(-122.19, 46.25, 5000.0),
 *     orientation : {
 *         heading : Cesium.Math.toRadians(175.0),
 *         pitch : Cesium.Math.toRadians(-35.0),
 *         roll : 0.0
 *     }
 * });
 */
Camera.prototype.flyTo = function (options) {
  options = defaultValue(options, defaultValue.EMPTY_OBJECT);
  var destination = options.destination;
  //>>includeStart('debug', pragmas.debug);

  //如果没设置目的地报错
  if (!defined(destination)) {
    throw new DeveloperError("destination is required.");
  }
  //>>includeEnd('debug');

  var mode = this._mode;

  //如果当前scene正在变化中
  if (mode === SceneMode.MORPHING) {
    return;
  }

  this.cancelFlight();

  var orientation = defaultValue(
    options.orientation,
    defaultValue.EMPTY_OBJECT
  );

  //如果定义了方向，则将方向转换为HeadingPitchRoll这种格式
  if (defined(orientation.direction)) {
    orientation = directionUpToHeadingPitchRoll(
      this,
      destination,
      orientation,
      scratchSetViewOptions.orientation
    );
  }

  //如果设置的持续时间小于0，则用setView方法直接改变view，也就是0秒、没动画
  if (defined(options.duration) && options.duration <= 0.0) {
    var setViewOptions = scratchSetViewOptions;
    setViewOptions.destination = options.destination;
    setViewOptions.orientation.heading = orientation.heading;
    setViewOptions.orientation.pitch = orientation.pitch;
    setViewOptions.orientation.roll = orientation.roll;
    setViewOptions.convert = options.convert;
    setViewOptions.endTransform = options.endTransform;
    this.setView(setViewOptions);

    //如果原来的options里还说了在视角转到目的地之后要做什么，则现在setview之后做
    if (typeof options.complete === "function") {
      options.complete();
    }
    return;
  }

  //如果是通过设置需要看到的矩形区域的四个坐标
  var isRectangle = defined(destination.west);
  if (isRectangle) {
    //通过矩形的位置计算返回camera的位置
    destination = this.getRectangleCameraCoordinates(
      destination,
      scratchFlyToDestination
    );
  }

  var that = this;
  var flightTween;

  newOptions.destination = destination;
  newOptions.heading = orientation.heading;
  newOptions.pitch = orientation.pitch;
  newOptions.roll = orientation.roll;
  newOptions.duration = options.duration;
  newOptions.complete = function () {
    if (flightTween === that._currentFlight) {
      that._currentFlight = undefined;
    }
    if (defined(options.complete)) {
      options.complete();
    }
  };
  newOptions.cancel = options.cancel;
  newOptions.endTransform = options.endTransform;
  newOptions.convert = isRectangle ? false : options.convert;
  newOptions.maximumHeight = options.maximumHeight;
  newOptions.pitchAdjustHeight = options.pitchAdjustHeight;
  newOptions.flyOverLongitude = options.flyOverLongitude;
  newOptions.flyOverLongitudeWeight = options.flyOverLongitudeWeight;
  newOptions.easingFunction = options.easingFunction;

  var scene = this._scene;
  var tweenOptions = CameraFlightPath.createTween(scene, newOptions);
  // If the camera doesn't actually need to go anywhere, duration
  // will be 0 and we can just complete the current flight.
  if (tweenOptions.duration === 0) {
    if (typeof tweenOptions.complete === "function") {
      tweenOptions.complete();
    }
    return;
  }
  flightTween = scene.tweens.add(tweenOptions);
  this._currentFlight = flightTween;

  // Save the final destination view information for the PRELOAD_FLIGHT pass.
  var preloadFlightCamera = this._scene.preloadFlightCamera;
  if (this._mode !== SceneMode.SCENE2D) {
    if (!defined(preloadFlightCamera)) {
      preloadFlightCamera = Camera.clone(this);
    }
    preloadFlightCamera.setView({
      destination: destination,
      orientation: orientation,
    });

    this._scene.preloadFlightCullingVolume = preloadFlightCamera.frustum.computeCullingVolume(
      preloadFlightCamera.positionWC,
      preloadFlightCamera.directionWC,
      preloadFlightCamera.upWC
    );
  }
};