@lijuhong1981/cesium.utils 0.0.0-stage → 0.1.1

package/src/parses/parseToRange.js

@@ -0,0 +1,26 @@
+import getValidValue from '@lijuhong1981/jscheck/src/getValidValue.js';
+import Interval from '@lijuhong1981/jsmath/src/Interval.js';
+import { Check } from "cesium";
+
+/**
+ * 把数组或对象解析为区间（Interval）。
+ * @param {Interval|Array|object} value 待解析的值，支持 [minimum,maximum] 数组或含 start/end/min/max 等字段的对象
+ * @param {Interval} [result=new Interval()] 用于存储结果的可选对象
+ * @returns {Interval} 解析后的区间对象
+ */
+function parseToRange(value, result = new Interval()) {
+    Check.defined('value', value);
+    if (value instanceof Interval) {
+        if (result && value !== result)
+            return value.clone(result);
+        else
+            return value;
+    }
+    const minimum = getValidValue(value[0], value.start, value.minimum, value.min, value.x);
+    const maximum = getValidValue(value[1], value.end, value.maximum, value.max, value.y);
+    result.setValues(minimum, maximum);
+    return result;
+};
+
+export default parseToRange;
+export { parseToRange };

package/src/parses/parseToRectangle.js

@@ -0,0 +1,32 @@
+import getValidValue from "@lijuhong1981/jscheck/src/getValidValue.js";
+import { Check, defined, DeveloperError, Rectangle } from "cesium";
+
+/**
+ * 把数组或对象解析为矩形（{@link Rectangle}）。
+ * @param {Rectangle|Array|object} value 待解析的值，支持 [west,south,east,north] 数组或含 west/south/east/north 字段的对象
+ * @param {Rectangle} [result] 用于存储结果的可选对象
+ * @param {boolean} [isDegrees=true] 输入是否为角度制，为 true 时按角度解析
+ * @returns {Rectangle} 解析后的矩形
+ */
+function parseToRectangle(value, result, isDegrees = true) {
+    Check.defined('value', value);
+    if (value instanceof Rectangle) {
+        if (result && value !== result)
+            return value.clone(result);
+        else
+            return value;
+    }
+    const west = getValidValue(value[0], value.west);
+    const south = getValidValue(value[1], value.south);
+    const east = getValidValue(value[2], value.east);
+    const north = getValidValue(value[3], value.north);
+    if (!defined(west) || !defined(south) || !defined(east) || !defined(north))
+        throw new DeveloperError('the west or south or east or north is undefined.');
+    if (isDegrees)
+        return Rectangle.fromDegrees(west, south, east, north, result);
+    else
+        return Rectangle.fromRadians(west, south, east, north, result);
+}
+
+export default parseToRectangle;
+export { parseToRectangle };

package/src/parses/parseToTimeInterval.js

@@ -0,0 +1,45 @@
+import { TimeInterval } from "cesium";
+import parseToJulianDate from "./parseToJulianDate.js";
+
+/**
+ * 把字符串、数组或对象解析为时间区间（{@link TimeInterval}）。
+ * @param {TimeInterval|string|Array|object} value 待解析的值，字符串按 ISO8601 解析，数组为 [start,stop]
+ * @param {TimeInterval} [result] 用于存储结果的可选对象
+ * @returns {TimeInterval} 解析后的时间区间
+ */
+function parseToTimeInterval(value, result) {
+    if (value instanceof TimeInterval) {
+        if (result && value !== result)
+            return TimeInterval.clone(value, result);
+        else
+            return value;
+    } else if (typeof value === 'string')
+        return TimeInterval.fromIso8601(value, result);
+
+    if (result === undefined)
+        result = new TimeInterval();
+
+    if (Array.isArray(value)) {
+        let start = parseToJulianDate(value[0]);
+        let stop = parseToJulianDate(value[1]);
+        result.start = start;
+        result.stop = stop;
+    } else if (typeof value === 'object') {
+        let start = value.start || value.startTime;
+        start = parseToJulianDate(start);
+        let stop = value.stop || value.stopTime;
+        stop = parseToJulianDate(stop);
+        result.start = start;
+        result.stop = stop;
+        if (value.data !== undefined)
+            result.data = value.data;
+        if (value.isStartIncluded)
+            result.isStartIncluded = value.isStartIncluded;
+        if (value.isStopIncluded)
+            result.isStopIncluded = value.isStopIncluded;
+    }
+    return result;
+};
+
+export default parseToTimeInterval;
+export { parseToTimeInterval };

package/src/parses/parseVerticalOrigin.js

@@ -0,0 +1,28 @@
+import { DeveloperError, VerticalOrigin } from "cesium";
+
+/**
+ * 把字符串或数字解析为 Cesium 的 {@link VerticalOrigin} 枚举值。
+ * @param {string|number} value 待解析的值，字符串支持 'top'、'bottom'、'baseline'、'center'
+ * @returns {VerticalOrigin} 解析后的 VerticalOrigin
+ */
+function parseVerticalOrigin(value) {
+    if (typeof value === 'string') {
+        switch (value.toLowerCase()) {
+            case 'top':
+                return VerticalOrigin.TOP;
+            case 'bottom':
+                return VerticalOrigin.BOTTOM;
+            case 'baseline':
+                return VerticalOrigin.BASELINE;
+            case 'center':
+            default:
+                return VerticalOrigin.CENTER;
+        }
+    } else if (typeof value === 'number')
+        return value;
+    else
+        throw new DeveloperError('unable parse the ' + value + ' to VerticalOrigin.');
+};
+
+export default parseVerticalOrigin;
+export { parseVerticalOrigin };

package/src/revisions/BoundingSphere.revise.js

@@ -0,0 +1,107 @@
+import { BoundingSphere, Cartesian3, Check, defined, Matrix4 } from "cesium";
+import parseGeographicsToPositions from "../parses/parseGeographicsToPositions.js";
+import Scratch from "../utils/Scratch.js";
+
+/**
+ * 扩展 Cesium 的 BoundingSphere 类，补充从中心点/半径、地理坐标、模型矩阵创建包围球，
+ * 以及计算到世界坐标点、相机的距离等方法。
+ * @class BoundingSphere
+ * @see {@link https://cesium.com/learn/cesiumjs/ref-doc/BoundingSphere.html}
+*/
+
+/**
+ * 从中心点与半径创建包围球。
+ * @param {Cartesian3} center 包围球中心点（世界坐标）。
+ * @param {number} [radius=0] 包围球半径，单位米。
+ * @param {BoundingSphere} [result=new BoundingSphere()] 用于存储结果的可选对象。
+ * @returns {BoundingSphere} 生成或填充后的包围球。
+ * @memberof BoundingSphere
+ * @static
+*/
+BoundingSphere.fromElements = function (center, radius = 0, result = new BoundingSphere()) {
+    result.center = center;
+    result.radius = radius;
+    return result;
+};
+
+/**
+ * 从一组地理坐标创建包围球，通过计算这些点在世界坐标系下的包围范围得到。
+ * @param {Array|object} geographics 地理坐标点集合。
+ * @param {Ellipsoid} [ellipsoid] 参考椭球体。
+ * @param {BoundingSphere} [result] 用于存储结果的可选对象。
+ * @returns {BoundingSphere} 包含所有点的包围球。
+ * @memberof BoundingSphere
+ * @static
+*/
+BoundingSphere.fromGeographics = function (geographics, ellipsoid, result) {
+    const positions = parseGeographicsToPositions(geographics, undefined, ellipsoid);
+    return BoundingSphere.fromPoints(positions, result);
+};
+
+/**
+ * 从模型矩阵与半径创建包围球，中心点取矩阵的平移分量。
+ * @param {Matrix4} modelMatrix 模型矩阵。
+ * @param {number} [radius] 包围球半径；未提供时保留结果对象原有的半径。
+ * @param {BoundingSphere} [result=new BoundingSphere()] 用于存储结果的可选对象。
+ * @returns {BoundingSphere} 生成或填充后的包围球。
+ * @memberof BoundingSphere
+ * @static
+*/
+BoundingSphere.fromModelMatrix = function (modelMatrix, radius, result = new BoundingSphere()) {
+    Check.defined("modelMatrix", modelMatrix);
+    const center = Matrix4.getTranslation(modelMatrix, Scratch.scratchCenter);
+    result.center = Cartesian3.clone(center, result.center);
+    if (defined(radius))
+        result.radius = radius;
+    return result;
+};
+
+/**
+ * 计算某个世界坐标位置到包围球表面的距离，若点在球内则返回 0。
+ * @param {BoundingSphere} boundingSphere 目标包围球。
+ * @param {Cartesian3} positionWC 世界坐标位置。
+ * @returns {number} 位置到球表面的距离，单位米。
+ * @memberof BoundingSphere
+ * @static
+*/
+BoundingSphere.distanceToCartesian = function (boundingSphere, positionWC) {
+    Check.defined("boundingSphere", boundingSphere);
+    Check.defined("positionWC", positionWC);
+    return Math.max(0.0, Cartesian3.distance(boundingSphere.center, positionWC) - boundingSphere.radius);
+};
+
+/**
+ * 计算某个世界坐标位置到包围球表面的距离，若点在球内则返回 0。
+ * @param {Cartesian3} positionWC 世界坐标位置。
+ * @returns {number} 位置到球表面的距离，单位米。
+ * @memberof BoundingSphere
+*/
+BoundingSphere.prototype.distanceToCartesian = function (positionWC) {
+    return BoundingSphere.distanceToCartesian(this, positionWC);
+};
+
+/**
+ * 计算相机到包围球表面的距离，若相机在球内则返回 0。
+ * @param {BoundingSphere} boundingSphere 目标包围球。
+ * @param {Camera} camera 相机。
+ * @returns {number} 相机到球表面的距离，单位米。
+ * @memberof BoundingSphere
+ * @static
+*/
+BoundingSphere.distanceToCamera = function (boundingSphere, camera) {
+    Check.defined("camera", camera);
+    return BoundingSphere.distanceToCartesian(boundingSphere, camera.positionWC);
+};
+
+/**
+ * 计算相机到包围球表面的距离，若相机在球内则返回 0。
+ * @param {Camera} camera 相机。
+ * @returns {number} 相机到球表面的距离，单位米。
+ * @memberof BoundingSphere
+*/
+BoundingSphere.prototype.distanceToCamera = function (camera) {
+    return BoundingSphere.distanceToCamera(this, camera);
+};
+
+export default BoundingSphere;
+export { BoundingSphere };

package/src/revisions/Camera.revise.js

@@ -0,0 +1,366 @@
+import { BoundingSphere, Camera, Cartesian3, Math as CesiumMath, Check, HeadingPitchRoll, Matrix4, Ray, defined } from "cesium";
+import parseAttitudeToHeadingPitchRoll from "../parses/parseAttitudeToHeadingPitchRoll.js";
+import parseGeographicToCartesian from "../parses/parseGeographicToCartesian.js";
+import parseToCartesian3 from "../parses/parseToCartesian3.js";
+import parseToHeadingPitchRange from "../parses/parseToHeadingPitchRange.js";
+import parseToRectangle from "../parses/parseToRectangle.js";
+import computeModelMatrix from "../utils/computeModelMatrix.js";
+import Scratch from "../utils/Scratch.js";
+
+/**
+ * 扩展 Cesium 的 Camera 类，补充地理坐标、姿态、视线方向等访问属性，
+ * 并扩展 setView、flyTo、flyHome 等方法以支持更丰富的参数形式。
+ * @class Camera
+ * @see {@link https://cesium.com/learn/cesiumjs/ref-doc/Camera.html}
+*/
+
+Object.defineProperties(Camera.prototype, {
+    /**
+     * 获取相机所属的场景对象。
+     * @type {Scene}
+     * @memberof Camera
+    */
+    scene: {
+        get: function () {
+            return this._scene;
+        }
+    },
+    /**
+     * 获取相机当前位置对应的地理坐标。
+     * @type {Geographic}
+     * @memberof Camera
+    */
+    geographic: {
+        get: function () {
+            return this.positionCartographic.toGeographic();
+        }
+    },
+    /**
+     * 获取相机航向角（角度制，单位度）。
+     * @type {number}
+     * @memberof Camera
+    */
+    headingDegrees: {
+        get: function () {
+            return CesiumMath.toDegrees(this.heading);
+        }
+    },
+    /**
+     * 获取相机俯仰角（角度制，单位度）。
+     * @type {number}
+     * @memberof Camera
+    */
+    pitchDegrees: {
+        get: function () {
+            return CesiumMath.toDegrees(this.pitch);
+        }
+    },
+    /**
+     * 获取相机横滚角（角度制，单位度）。
+     * @type {number}
+     * @memberof Camera
+    */
+    rollDegrees: {
+        get: function () {
+            return CesiumMath.toDegrees(this.roll);
+        }
+    },
+    /**
+     * 获取相机当前姿态对应的 HeadingPitchRoll（弧度制）。
+     * @type {HeadingPitchRoll}
+     * @memberof Camera
+    */
+    orientation: {
+        get: function () {
+            if (!defined(this._orientation))
+                this._orientation = new HeadingPitchRoll();
+            this._orientation.heading = this.heading;
+            this._orientation.pitch = this.pitch;
+            this._orientation.roll = this.roll;
+            return this._orientation;
+        }
+    },
+    /**
+     * 获取相机当前姿态的角度制表示（度）。
+     * @type {object}
+     * @memberof Camera
+    */
+    orientationDegrees: {
+        get: function () {
+            return this.orientation.toDegrees();
+        }
+    },
+    /**
+     * 获取相机当前姿态的角度制表示（度），等同于 orientationDegrees。
+     * @type {object}
+     * @memberof Camera
+    */
+    attitude: {
+        get: function () {
+            return this.orientationDegrees;
+        }
+    },
+    /**
+     * 获取相机视锥体的投影矩阵。
+     * @type {Matrix4}
+     * @memberof Camera
+    */
+    projectionMatrix: {
+        get: function () {
+            return this.frustum.projectionMatrix;
+        }
+    },
+    /**
+     * 判断相机当前是否正在执行飞行（视角切换）动画。
+     * @type {boolean}
+     * @memberof Camera
+    */
+    isFlighting: {
+        get: function () {
+            return defined(this._currentFlight);
+        }
+    },
+    /**
+     * 获取相机所属场景的参考椭球体。
+     * @type {Ellipsoid}
+     * @memberof Camera
+    */
+    ellipsoid: {
+        get: function () {
+            return this._scene.ellipsoid;
+        }
+    }
+});
+
+/**
+ * 计算给定距离处每个像素对应的地面米数。
+ * @param {number} distance 距离相机的位置距离，单位米。
+ * @returns {number} 每个像素对应的米数。
+ * @memberof Camera
+*/
+Camera.prototype.getMetersPerPixel = function (distance) {
+    Check.typeOf.number('distance', distance);
+    const pixelSize = this.frustum.getPixelDimensions(
+        this._scene.drawingBufferWidth,
+        this._scene.drawingBufferHeight,
+        distance,
+        this._scene.pixelRatio,
+        Scratch.scratchPixelSize
+    );
+    return Math.max(pixelSize.x, pixelSize.y);
+};
+
+/**
+ * 原始 setView 方法的引用，扩展后的 setView 在完成参数处理后调用它。
+ * @type {function}
+ * @memberof Camera
+*/
+Camera.prototype.originalSetView = Camera.prototype.setView;
+
+/**
+ * 重写 setView，支持通过 geographic、position、rectangle、attitude 等参数形式设置视角。
+ * @param {object} options 视角设置项，支持 geographic/position/rectangle/attitude/destination/orientation 等字段。
+ * @memberof Camera
+*/
+Camera.prototype.setView = function (options) {
+    if (defined(options.geographic) || defined(options.position)) {
+        const modelMatrix = computeModelMatrix({
+            geographic: options.geographic,
+            position: options.position,
+            translation: options.translation,
+            ellipsoid: this.ellipsoid,
+        });
+        options.destination = Matrix4.getTranslation(modelMatrix, new Cartesian3());
+    } else if (defined(options.rectangle)) {
+        options.destination = parseToRectangle(options.rectangle);
+    }
+    if (defined(options.attitude))
+        options.orientation = parseAttitudeToHeadingPitchRoll(options.attitude);
+    else if (options.orientation && Array.isArray(options.orientation))
+        options.orientation = HeadingPitchRoll.unpack(options.orientation);
+    this.originalSetView(options);
+};
+
+/**
+ * 原始 flyTo 方法的引用，扩展后的 flyTo 在完成参数处理后调用它。
+ * @type {function}
+ * @memberof Camera
+*/
+Camera.prototype.originalFlyTo = Camera.prototype.flyTo;
+
+/**
+ * 重写 flyTo，支持通过 geographic、position、rectangle、attitude 等参数形式进行视角飞行。
+ * @param {object} options 飞行设置项，支持 geographic/position/rectangle/attitude/destination/orientation 等字段。
+ * @memberof Camera
+*/
+Camera.prototype.flyTo = function (options) {
+    if (defined(options.geographic) || defined(options.position)) {
+        const modelMatrix = computeModelMatrix({
+            geographic: options.geographic,
+            position: options.position,
+            translation: options.translation,
+            ellipsoid: this.ellipsoid,
+        });
+        options.destination = Matrix4.getTranslation(modelMatrix, new Cartesian3());
+    } else if (defined(options.rectangle)) {
+        options.destination = parseToRectangle(options.rectangle);
+    }
+    if (defined(options.attitude))
+        options.orientation = parseAttitudeToHeadingPitchRoll(options.attitude);
+    else if (options.orientation && Array.isArray(options.orientation))
+        options.orientation = HeadingPitchRoll.unpack(options.orientation);
+    this.originalFlyTo(options);
+};
+
+/**
+ * 设置 HomeView（视角），flyHome 时将优先飞至该设置。
+ * @param {object} options 视角设置项，参数参见 flyTo。
+ * @memberof Camera
+*/
+Camera.prototype.setHomeView = function (options) {
+    if (!options)
+        return;
+    this.homeViewOptions = options;
+}
+
+/**
+ * 设置默认视角，flyHome 时将使用该设置。
+ * @param {object} options 视角设置项，参数参见 flyTo。
+ * @memberof Camera
+ * @deprecated 已废弃，请改用 setHomeView。
+*/
+Camera.prototype.setDefaultView = function (options) {
+    console.warn('setDefaultView function is deprecated, use setHomeView instead.');
+    this.setHomeView(options);
+};
+
+//记录Camera原始的flyHome方法
+/**
+ * 原始 flyHome 方法的引用，扩展后的 flyHome 在未设置 homeView 时调用它。
+ * @type {function}
+ * @memberof Camera
+*/
+Camera.prototype.originalFlyHome = Camera.prototype.flyHome;
+
+/**
+ * 重写 flyHome，优先飞至 homeView 设置，未设置时执行原始的 flyHome。
+ * @param {number} [duration] 飞行持续时间，单位秒；未指定时使用默认值。
+ * @memberof Camera
+*/
+Camera.prototype.flyHome = function (duration) {
+    if (this.homeViewOptions) {
+        const options = Object.assign({}, this.homeViewOptions);
+        if (defined(duration))
+            options.duration = duration;
+        this.flyTo(options);
+    } else {
+        this.originalFlyHome(duration);
+    }
+};
+
+/**
+ * 相机飞至指定的视点。
+ * @param {Cartesian3} viewPoint 目标视点（世界坐标）。
+ * @param {HeadingPitchRange|Array} offset 视角偏移，可为 HeadingPitchRange 或数组。
+ * @param {object} [options={}] 飞行选项，透传给 flyToBoundingSphere。
+ * @memberof Camera
+*/
+Camera.prototype.flyToViewPoint = function (viewPoint, offset, options = {}) {
+    Check.defined('viewPoint', viewPoint);
+    Check.defined('offset', offset);
+
+    const boundingSphere = BoundingSphere.fromElements(viewPoint, 0, Scratch.scratchBoundingSphere);
+
+    options.offset = parseToHeadingPitchRange(offset, Scratch.scratchHeadingPitchRange, offset.degrees);
+
+    this.flyToBoundingSphere(boundingSphere, options);
+
+};
+
+/**
+ * 相机飞至指定的矩形范围。
+ * @param {Rectangle} rectangle 目标矩形范围。
+ * @param {object} [options={}] 飞行选项，透传给 flyToBoundingSphere。
+ * @memberof Camera
+*/
+Camera.prototype.flyToRectangle = function (rectangle, options = {}) {
+    Check.defined('rectangle', rectangle);
+
+    const boundingSphere = BoundingSphere.fromRectangle3D(rectangle, this.ellipsoid, options.surfaceHeight, Scratch.scratchBoundingSphere);
+    this.flyToBoundingSphere(boundingSphere, options);
+};
+
+/**
+ * 相机看向指定的方向。
+ * @param {Cartesian3} direction 目标方向。
+ * @param {Cartesian3} [up] 上方向；未提供时使用当前位置的椭球法线。
+ * @memberof Camera
+*/
+Camera.prototype.lookAtDirection = function (direction, up) {
+
+    Check.typeOf.object('direction', direction);
+    direction = parseToCartesian3(direction, Scratch.scratchDirection, false);
+    Cartesian3.normalize(direction, direction);
+    if (up) {
+        up = parseToCartesian3(up, Scratch.scratchUp, false);
+        Cartesian3.normalize(up, up);
+    } else {
+        up = this.ellipsoid.geodeticSurfaceNormal(this.positionWC, Scratch.scratchUp);
+    }
+
+    this.setView({
+        orientation: {
+            direction: direction,
+            up: up,
+        }
+    });
+
+};
+
+/**
+ * 相机看向指定的世界坐标位置。
+ * @param {Cartesian3} position 目标位置（世界坐标）。
+ * @memberof Camera
+*/
+Camera.prototype.lookAtPosition = function (position) {
+
+    Check.typeOf.object('position', position);
+    position = parseToCartesian3(position, Scratch.scratchPositionWC, false);
+
+    const direction = Cartesian3.subtract(position, this.positionWC, Scratch.scratchDirection);
+
+    this.lookAtDirection(direction);
+
+};
+
+/**
+ * 相机看向指定的地理坐标位置。
+ * @param {Geographic} geographic 目标地理坐标。
+ * @memberof Camera
+*/
+Camera.prototype.lookAtGeographic = function (geographic) {
+
+    Check.typeOf.object('geographic', geographic);
+    const position = parseGeographicToCartesian(geographic, Scratch.scratchPositionWC, this.ellipsoid);
+
+    const direction = Cartesian3.subtract(position, this.positionWC, Scratch.scratchDirection);
+
+    this.lookAtDirection(direction);
+
+};
+
+/**
+ * 获取相机当前位置沿当前朝向的射线。
+ * @param {Ray} [result] 存放结果的 Ray 对象。
+ * @returns {Ray} 相机朝向射线。
+ * @memberof Camera
+*/
+Camera.prototype.getDirectionRay = function (result = new Ray()) {
+    result.origin = this.positionWC;
+    result.direction = this.directionWC;
+    return result;
+};
+
+export default Camera;
+export { Camera };
+