@lijuhong1981/cesium.utils 0.0.0-stage → 0.1.0

package/src/revisions/Color.revise.js

@@ -0,0 +1,271 @@
+import { Cartesian3, Cartesian4, Check, Color, defined, DeveloperError } from "cesium";
+
+/**
+ * 扩展 Cesium 的 Color 类，补充 rgb 复制比较、与 Byte 数组的打包解包、
+ * CSS 字符串转换、与 Cartesian 互转等方法。
+ * @class Color
+ * @see {@link https://cesium.com/learn/cesiumjs/ref-doc/Color.html}
+*/
+
+/**
+ * 复制一个 Color 的 rgb 分量（不包含 alpha）。
+ *
+ * @param {Color} color 待复制的 Color 对象。
+ * @param {Color} [result] 存放结果的对象，未指定则创建新实例。
+ * @returns {Color} 修改后的 result 或新建的实例；若 color 未定义则返回 undefined。
+ * @memberof Color
+ * @static
+ */
+Color.cloneRgb = function (color, result) {
+    if (!defined(color)) {
+        return undefined;
+    }
+    if (!defined(result)) {
+        return new Color(color.red, color.green, color.blue);
+    }
+    result.red = color.red;
+    result.green = color.green;
+    result.blue = color.blue;
+    return result;
+};
+
+/**
+ * 判断两个 Color 的 rgb 分量是否相等。
+ *
+ * @param {Color} [left] 待比较的第一个 Color 对象。
+ * @param {Color} [right] 待比较的第二个 Color 对象。
+ * @returns {boolean} 两个 Color 的 rgb 相等返回 <code>true</code>，否则返回 <code>false</code>。
+ * @memberof Color
+ * @static
+ */
+Color.equalsRgb = function (left, right) {
+    return (
+        left === right || //
+        (defined(left) && //
+            defined(right) && //
+            left.red === right.red && //
+            left.green === right.green && //
+            left.blue === right.blue)
+    );
+};
+
+/**
+ * 复制当前 Color 的 rgb 分量（不包含 alpha）。
+ *
+ * @param {Color} [result] 存放结果的对象，未指定则创建新实例。
+ * @returns {Color} 修改后的 result 或新建的实例。
+ * @memberof Color
+ */
+Color.prototype.cloneRgb = function (result) {
+    return Color.cloneRgb(this, result);
+};
+
+/**
+ * 判断当前 Color 的 rgb 分量是否与 other 相等。
+ *
+ * @param {Color} [other] 待比较的 Color 对象。
+ * @returns {boolean} 两个 Color 的 rgb 相等返回 <code>true</code>，否则返回 <code>false</code>。
+ * @memberof Color
+ */
+Color.prototype.equalsRgb = function (other) {
+    return Color.equalsRgb(this, other);
+};
+
+/**
+ * 将一个Color对象属性转换为Byte，并打包入一个数组中。
+ * @param {Color} color Color对象
+ * @param {Array} [array] 存放结果的数组，如果未指定则创建一个新的数组
+ * @param {number} [startingIndex=0] 开始存放的位置，默认为0
+ * @returns {Array<number>} 返回存放结果的数组
+ * @memberof Color
+ * @static
+ */
+Color.packToBytes = function (color, array = [], startingIndex = 0) {
+    Check.typeOf.object("color", color);
+
+    array[startingIndex] = Color.floatToByte(color.red);
+    array[startingIndex + 1] = Color.floatToByte(color.green);
+    array[startingIndex + 2] = Color.floatToByte(color.blue);
+    array[startingIndex + 3] = Color.floatToByte(color.alpha);
+
+    return array;
+};
+
+/**
+ * 将一个Color对象数组属性转换为Byte，并打包入一个数组中。
+ * @param {Array<Color>} array Color对象数组
+ * @param {Array} [result] 存放结果的数组，如果未指定则创建一个新的数组
+ * @returns {Array<number>} 返回存放结果的数组
+ * @memberof Color
+ * @static
+ */
+Color.packArrayToBytes = function (array, result) {
+    //>>includeStart('debug', pragmas.debug);
+    Check.typeOf.array("array", array);
+    //>>includeEnd('debug');
+
+    const length = array.length;
+    const resultLength = length * 4;
+    if (!defined(result)) {
+        result = new Array(resultLength);
+    } else if (!Array.isArray(result) && result.length !== resultLength) {
+        throw new DeveloperError(
+            "If result is a typed array, it must have exactly array.length * 4 elements"
+        );
+    } else if (result.length !== resultLength) {
+        result.length = resultLength;
+    }
+
+    for (let i = 0; i < length; ++i) {
+        Color.packToBytes(array[i], result, i * 4);
+    }
+    return result;
+};
+
+/**
+ * 从一个Byte数组中解包出Color对象。
+ * @param {Array<number>} array 存放Color属性的Byte数组
+ * @param {number} [startingIndex=0] 开始读取的位置，默认为0
+ * @param {Color} [result] 存放结果的Color对象，如果未指定则创建一个新的Color对象
+ * @returns {Color} 返回存放结果的Color对象
+ * @memberof Color
+ * @static
+ */
+Color.unpackFromBytes = function (array, startingIndex = 0, result) {
+    Check.defined("array", array);
+
+    return Color.fromBytes(array[startingIndex], array[startingIndex + 1], array[startingIndex + 2], array[startingIndex + 3], result);;
+};
+
+/**
+ * 从一个Byte数组中解包出Color对象数组。
+ * @param {Array<number>} array 存放Color属性的Byte数组
+ * @param {Array<Color>} [result] 存放结果的Color对象数组，如果未指定则创建一个新的Color对象数组
+ * @returns {Array<Color>} 返回存放结果的Color对象数组
+ * @memberof Color
+ * @static
+ */
+Color.unpackArrayFromBytes = function (array, result) {
+    Check.defined("array", array);
+
+    if (array.length % 4 !== 0) {
+        throw new DeveloperError("array length must be a multiple of 4.");
+    }
+    //>>includeEnd('debug');
+
+    var length = array.length;
+    if (!defined(result)) {
+        result = new Array(length / 4);
+    } else {
+        result.length = length / 4;
+    }
+
+    for (var i = 0; i < length; i += 4) {
+        var index = i / 4;
+        result[index] = Color.unpackFromBytes(array, i, result[index]);
+    }
+    return result;
+};
+
+/**
+ * 从数组生成Color对象，等同于 Color.unpack。
+ * @memberof Color
+ * @static
+ * @see Color.unpack
+*/
+Color.fromArray = Color.unpack;
+
+/**
+ * 从Byte数组生成Color对象，等同于 Color.unpackFromBytes。
+ * @memberof Color
+ * @static
+ * @see Color.unpackFromBytes
+*/
+Color.fromBytesArray = Color.unpackFromBytes;
+
+/**
+ * 从CSS颜色字符串创建一个Color对象。
+ * @param {string} color CSS颜色字符串
+ * @param {number} [alpha] 透明度，如果指定则覆盖CSS颜色字符串中的透明度
+ * @param {Color} [result] 存放结果的Color对象，如果未指定则创建一个新的Color对象
+ * @returns {Color} 返回存放结果的Color对象
+ * @memberof Color
+ * @static
+ */
+Color.fromCssColorWithAlpha = function (color, alpha, result) {
+    result = Color.fromCssColorString(color, result);
+    if (defined(alpha))
+        result.alpha = alpha;
+    return result;
+};
+
+/**
+ * 将当前Color对象转换为CSS rgb颜色字符串。
+ * @return {string} CSS rgb颜色字符串，例如"rgb(255,0,0)"
+ * @memberof Color
+*/
+Color.prototype.toCssRgbString = function () {
+    const red = Color.floatToByte(this.red);
+    const green = Color.floatToByte(this.green);
+    const blue = Color.floatToByte(this.blue);
+    return `rgb(${red},${green},${blue})`;
+};
+
+/**
+ * 将当前Color对象转换为CSS rgba颜色字符串。
+ * @return {string} CSS rgba颜色字符串，例如"rgba(255,0,0,0.5)"
+ * @memberof Color
+*/
+Color.prototype.toCssRgbaString = function () {
+    const red = Color.floatToByte(this.red);
+    const green = Color.floatToByte(this.green);
+    const blue = Color.floatToByte(this.blue);
+    return `rgba(${red},${green},${blue},${this.alpha})`;
+};
+
+/**
+ * 从Cartesian3对象创建一个Color对象。
+ * @param {Cartesian3} cartesian 输入的Cartesian3对象
+ * @param {Color} [result] 存放结果的Color对象，如果未指定则创建一个新的Color对象
+ * @returns {Color} 返回存放结果的Color对象
+ * @memberof Color
+ * @static
+ */
+Color.fromCartesian3 = function (cartesian, result = new Color()) {
+    Check.typeOf.object('cartesian', cartesian);
+
+    result.red = cartesian.x;
+    result.green = cartesian.y;
+    result.blue = cartesian.z;
+    return result;
+};
+
+/**
+ * 将当前Color对象转换为Cartesian3对象。
+ * @param {Cartesian3} [result] 存放结果的Cartesian3对象，如果未指定则创建一个新的Cartesian3对象
+ * @returns {Cartesian3} 返回存放结果的Cartesian3对象
+ * @memberof Color
+*/
+Color.prototype.toCartesian3 = function (result = new Cartesian3()) {
+    result.x = this.red;
+    result.y = this.green;
+    result.z = this.blue;
+    return result;
+};
+
+/**
+ * 将当前Color对象转换为Cartesian4对象。
+ * @param {Cartesian4} [result] 存放结果的Cartesian4对象，如果未指定则创建一个新的Cartesian4对象
+ * @returns {Cartesian4} 返回存放结果的Cartesian4对象
+ * @memberof Color
+*/
+Color.prototype.toCartesian4 = function (result = new Cartesian4()) {
+    result.x = this.red;
+    result.y = this.green;
+    result.z = this.blue;
+    result.w = this.alpha;
+    return result;
+};
+
+export default Color;
+export { Color };

package/src/revisions/DistanceDisplayCondition.revise.js

@@ -0,0 +1,37 @@
+import { Math as CesiumMath, Check, DistanceDisplayCondition } from "cesium";
+
+/**
+ * 扩展 Cesium 的 DistanceDisplayCondition 类，补充基于距离判断是否显示的方法。
+ * @class DistanceDisplayCondition
+ * @see {@link https://cesium.com/learn/cesiumjs/ref-doc/DistanceDisplayCondition.html}
+*/
+
+/**
+ * 判断给定距离是否位于距离显示条件范围内。
+ * @param {DistanceDisplayCondition} distanceDisplayCondition 距离显示条件。
+ * @param {number} distance 待判断的距离，单位米。
+ * @returns {boolean} 距离位于 near 与 far 之间返回 true，否则返回 false。
+ * @memberof DistanceDisplayCondition
+ * @static
+*/
+DistanceDisplayCondition.isDisplay = function (distanceDisplayCondition, distance) {
+    Check.defined('distanceDisplayCondition', distanceDisplayCondition);
+    return CesiumMath.between(
+        distance,
+        Math.min(distanceDisplayCondition.near, distanceDisplayCondition.far),
+        Math.max(distanceDisplayCondition.near, distanceDisplayCondition.far)
+    );
+};
+
+/**
+ * 判断给定距离是否位于当前距离显示条件范围内。
+ * @param {number} distance 待判断的距离，单位米。
+ * @returns {boolean} 距离位于 near 与 far 之间返回 true，否则返回 false。
+ * @memberof DistanceDisplayCondition
+*/
+DistanceDisplayCondition.prototype.isDisplay = function (distance) {
+    return DistanceDisplayCondition.isDisplay(this, distance);
+};
+
+export default DistanceDisplayCondition;
+export { DistanceDisplayCondition };

package/src/revisions/Ellipsoid.revise.js

@@ -0,0 +1,64 @@
+import { Check, Ellipsoid, IntersectionTests, Ray } from "cesium";
+import Scratch from "../utils/Scratch.js";
+
+/**
+ * 扩展 Cesium 的 Ellipsoid 类，补充缩放椭球高、高度偏移以及射线求交等方法。
+ * @class Ellipsoid
+ * @see {@link https://cesium.com/learn/cesiumjs/ref-doc/Ellipsoid.html}
+*/
+
+/**
+ * 将给定点的高度缩放到指定的椭球高。
+ * @param {Cartesian3} cartesian 待处理的点（世界坐标）。
+ * @param {number} height 目标椭球高度，单位米。
+ * @param {Cartesian3} [result] 存放结果的对象，未指定则创建新实例。
+ * @returns {Cartesian3} 修改后的 result 或新建的实例。
+ * @memberof Ellipsoid
+*/
+Ellipsoid.prototype.scaleToGeodeticHeight = function (cartesian, height, result) {
+    Check.defined('cartesian', cartesian);
+    Check.typeOf.number('height', height);
+    const cartographic = this.cartesianToCartographic(cartesian, Scratch.scratchCartographic);
+    cartographic.height = height;
+    return this.cartographicToCartesian(cartographic, result);
+};
+
+/**
+ * 在给定点当前高度的基础上偏移指定高度，返回新的位置。
+ * @param {Cartesian3} cartesian 待处理的点（世界坐标）。
+ * @param {number} [heightOffset=0] 高度偏移量，单位米。
+ * @param {Cartesian3} [result] 存放结果的对象，未指定则创建新实例。
+ * @returns {Cartesian3} 修改后的 result 或新建的实例。
+ * @memberof Ellipsoid
+*/
+Ellipsoid.prototype.scaleGeodeticHeightOffset = function (cartesian, heightOffset = 0, result) {
+    Check.defined('cartesian', cartesian);
+    Check.typeOf.number('heightOffset', heightOffset);
+    if (heightOffset === 0)
+        return cartesian.clone(result);
+    const cartographic = this.cartesianToCartographic(cartesian, Scratch.scratchCartographic);
+    cartographic.height += heightOffset;
+    return this.cartographicToCartesian(cartographic, result);
+};
+
+/**
+ * 计算射线与椭球表面的交点。
+ * @param {Ray} ray 射线。
+ * @param {Cartesian3} [result] 存放结果的对象，未指定则创建新实例。
+ * @returns {Cartesian3} 射线与椭球的交点；无交点时返回 undefined。
+ * @memberof Ellipsoid
+*/
+Ellipsoid.prototype.rayPosition = function (ray, result) {
+    Check.instanceOf('ray', ray, Ray);
+
+    const intersection = IntersectionTests.rayEllipsoid(ray, this);
+    if (!intersection) {
+        return undefined;
+    }
+
+    const t = intersection.start > 0.0 ? intersection.start : intersection.stop;
+    return Ray.getPoint(ray, t, result);
+};
+
+export default Ellipsoid;
+export { Ellipsoid };

package/src/revisions/Geometry.revise.js

@@ -0,0 +1,79 @@
+import { BoundingSphere, Geometry, GeometryPipeline, PrimitiveType } from "cesium";
+
+/**
+ * 扩展 Cesium 的 Geometry 类，补充克隆、转线框以及获取包围球等方法。
+ * @class Geometry
+ * @see {@link https://cesium.com/learn/cesiumjs/ref-doc/Geometry.html}
+*/
+
+/**
+ * 克隆一个 Geometry 对象。
+ * @param {Geometry} geometry 待克隆的几何体。
+ * @returns {Geometry} 克隆得到的新几何体。
+ * @memberof Geometry
+ * @static
+*/
+Geometry.clone = function (geometry) {
+    return new Geometry({
+        attributes: geometry.attributes,
+        indices: geometry.indices,
+        primitiveType: geometry.primitiveType,
+        boundingSphere: geometry.boundingSphere
+    });
+};
+
+/**
+ * 克隆当前 Geometry 对象。
+ * @returns {Geometry} 克隆得到的新几何体。
+ * @memberof Geometry
+*/
+Geometry.prototype.clone = function () {
+    return Geometry.clone(this);
+};
+
+/**
+ * 将三角形类型的几何体转换为线框几何体；非三角形类型原样返回。
+ * @param {Geometry} geometry 待转换的几何体。
+ * @returns {Geometry} 转换后的线框几何体或原几何体。
+ * @memberof Geometry
+ * @static
+*/
+Geometry.toWireframe = function (geometry) {
+    if (geometry.primitiveType !== PrimitiveType.TRIANGLES &&
+        geometry.primitiveType !== PrimitiveType.TRIANGLE_FAN &&
+        geometry.primitiveType !== PrimitiveType.TRIANGLE_STRIP) {
+        return geometry;
+    }
+
+    return GeometryPipeline.toWireframe(geometry);
+};
+
+/**
+ * 将当前几何体转换为线框几何体；非三角形类型原样返回。
+ * @returns {Geometry} 转换后的线框几何体或原几何体。
+ * @memberof Geometry
+*/
+Geometry.prototype.toWireframe = function () {
+    return Geometry.toWireframe(this);
+};
+
+/**
+ * 获取当前几何体的包围球，优先使用已计算的 boundingSphere，否则由顶点计算。
+ * @param {BoundingSphere} [result] 存放结果的对象，未指定则创建新实例。
+ * @returns {BoundingSphere} 几何体的包围球。
+ * @memberof Geometry
+*/
+Geometry.prototype.getBoundingSphere = function (result) {
+    if (!result)
+        result = new BoundingSphere();
+    if (this.boundingSphere)
+        this.boundingSphere.clone(result);
+    else {
+        const positions = this.attributes.position.values;
+        BoundingSphere.fromVertices(positions, undefined, undefined, result);
+    }
+    return result;
+};
+
+export default Geometry;
+export { Geometry };

package/src/revisions/Globe.revise.js

@@ -0,0 +1,92 @@
+import { Check, Globe, GlobeSurfaceTileProvider } from "cesium";
+
+/**
+ * 扩展 Cesium 的 GlobeSurfaceTileProvider 类，补充地形分析访问属性与待渲染瓦片帧回调支持。
+ * @class GlobeSurfaceTileProvider
+ * @see {@link https://cesium.com/learn/cesiumjs/ref-doc/GlobeSurfaceTileProvider.html}
+*/
+/**
+ * 扩展 Cesium 的 Globe 类，补充地形分析（terrainAnalysis）属性。
+ * @class Globe
+ * @see {@link https://cesium.com/learn/cesiumjs/ref-doc/Globe.html}
+*/
+
+Object.defineProperties(GlobeSurfaceTileProvider.prototype, {
+    /**
+     * 获取当前的地形分析对象。
+     * @type {TerrainAnalysis}
+     * @memberof GlobeSurfaceTileProvider
+    */
+    terrainAnalysis: {
+        get: function () {
+            return this._terrainAnalysis;
+        }
+    }
+});
+
+let tilesToRender = [];
+
+/**
+ * 每帧调用，记录当前待渲染的瓦片；当瓦片集合发生变化时，
+ * 通知各影像图层提供者的 onShowTilesToRenderFrame 回调。
+ * @param {Array} tiles 本帧待渲染的瓦片数组。
+ * @memberof GlobeSurfaceTileProvider
+*/
+GlobeSurfaceTileProvider.prototype.showTilesToRenderFrame = function (tiles) {
+    let changed = false;
+    if (tiles.length !== tilesToRender.length) {
+        changed = true;
+    } else {
+        for (let i = tiles.length - 1; i >= 0; i--) {
+            let a = tiles[i];
+            let finded = false;
+            for (let j = tilesToRender.length - 1; j >= 0; j--) {
+                let b = tilesToRender[j];
+                if (a === b) {
+                    finded = true;
+                    break;
+                }
+            }
+            if (!finded) {
+                changed = true;
+                break;
+            }
+        }
+    }
+    if (changed) {
+        tilesToRender = tiles.slice();
+    }
+    const imageryLayers = this._imageryLayers;
+    for (let i = 0; i < imageryLayers.length; i++) {
+        const layer = imageryLayers.get(i);
+        const provider = layer.imageryProvider;
+        if (provider && typeof provider.onShowTilesToRenderFrame === 'function') {
+            provider.onShowTilesToRenderFrame(tiles, changed);
+        }
+    }
+};
+
+Object.defineProperties(Globe.prototype, {
+    /**
+     * 获取或设置地形分析对象；设置时会将其绑定到当前 Globe。
+     * @type {TerrainAnalysis}
+     * @memberof Globe
+    */
+    terrainAnalysis: {
+        get: function () {
+            return this._surface._tileProvider._terrainAnalysis;
+        },
+        set: function (value) {
+            if (value) {
+                Check.instanceOf('terrainAnalysis', value, TerrainAnalysis);
+                this._surface._tileProvider._terrainAnalysis = value;
+                value.globe = this;
+            } else {
+                delete this._surface._tileProvider._terrainAnalysis;
+            }
+        }
+    }
+});
+
+export default Globe;
+export { Globe, GlobeSurfaceTileProvider };