Utils

一些Cesium相关的工具函数

canvasCoordToCartesian

import type { Cartesian2, Cartesian3, Scene } from 'cesium';
/**
 * Convert canvas coordinates to Cartesian coordinates
 *
 * @param canvasCoord Canvas coordinates
 * @param scene Cesium.Scene instance
 * @param mode optional values are 'pickPosition' | 'globePick' | 'auto' | 'noHeight'  @default 'auto'
 *
 * `pickPosition`: Use scene.pickPosition for conversion, which can be used for picking models, oblique photography, etc.
 * However, if depth detection is not enabled (globe.depthTestAgainstTerrain=false), picking terrain or inaccurate issues may occur
 *
 * `globePick`: Use camera.getPickRay for conversion, which cannot be used for picking models or oblique photography,
 * but can be used for picking terrain. If terrain does not exist, the picked elevation is 0
 *
 * `auto`: Automatically determine which picking content to return
 *
 * Calculation speed comparison: globePick > auto >= pickPosition
 */
export declare function canvasCoordToCartesian(canvasCoord: Cartesian2, scene: Scene, mode?: 'pickPosition' | 'globePick' | 'auto'): Cartesian3 | undefined;

cartesianToCanvasCoord

import type { Cartesian2, Cartesian3, Scene } from 'cesium';
/**
 * Convert Cartesian coordinates to canvas coordinates
 *
 * @param position Cartesian coordinates
 * @param scene Cesium.Scene instance
 */
export declare function cartesianToCanvasCoord(position: Cartesian3, scene: Scene): Cartesian2;

cesiumEquals

/**
 * Determines if two Cesium objects are equal.
 *
 * This function not only judges whether the instances are equal,
 * but also judges the equals method in the example.
 *
 * @param left The first Cesium object
 * @param right The second Cesium object
 * @returns Returns true if the two Cesium objects are equal, otherwise false
 */
export declare function cesiumEquals(left: any, right: any): boolean;

convertDMS

import type { CommonCoord, CoordArray_ALT } from './types';
export type DMSCoord = [longitude: string, latitude: string, height?: number];
/**
 * Convert degrees to DMS (Degrees Minutes Seconds) format string
 *
 * @param degrees The angle value
 * @param precision The number of decimal places to retain for the seconds, defaults to 3
 * @returns A DMS formatted string in the format: degrees° minutes′ seconds″
 */
export declare function dmsEncode(degrees: number, precision?: number): string;
/**
 * Decode a DMS (Degrees Minutes Seconds) formatted string to a decimal angle value
 *
 * @param dmsCode DMS formatted string, e.g. "120°30′45″N"
 * @returns The decoded decimal angle value, or 0 if decoding fails
 */
export declare function dmsDecode(dmsCode: string): number;
/**
 * Convert latitude and longitude coordinates to degrees-minutes-seconds format
 *
 * @param position The latitude and longitude coordinates
 * @param precision The number of decimal places to retain for 'seconds', default is 3
 * @returns Returns the coordinates in degrees-minutes-seconds format, or undefined if the conversion fails
 */
export declare function degreesToDms(position: CommonCoord, precision?: number): DMSCoord | undefined;
/**
 * Convert DMS (Degrees Minutes Seconds) format to decimal degrees for latitude and longitude coordinates
 *
 * @param dms The latitude or longitude coordinate in DMS format
 * @returns Returns the coordinate in decimal degrees format, or undefined if the conversion fails
 */
export declare function dmsToDegrees(dms: DMSCoord): CoordArray_ALT | undefined;

is

import type { AnyFn } from './types';
export declare function isDef<T = any>(val?: T): val is T;
export declare function isBoolean(val: any): val is boolean;
export declare function isFunction<T extends AnyFn>(val: any): val is T;
export declare function isNumber(val: any): val is number;
export declare function isString(val: unknown): val is string;
export declare function isObject(val: any): val is object;
export declare function isWindow(val: any): val is Window;
export declare function isPromise<T extends Promise<any>>(val: any): val is T;
export declare function isElement<T extends Element>(val: any): val is T;
export declare const isArray: (arg: any) => arg is any[];
export declare function isBase64(val: string): boolean;
export declare function assertError(condition: boolean, error: any): void;

isCesiumConstant

import type { MaybeProperty } from './property';
/**
 * Determines if the Cesium property is a constant.
 *
 * @param value Cesium property
 */
export declare function isCesiumConstant(value: MaybeProperty): boolean;

material

import type { Event, JulianDate, MaterialProperty, TextureMagnificationFilter, TextureMinificationFilter } from 'cesium';
import { Material } from 'cesium';
/**
 * Cesium.Material.fabric parameters
 */
export interface CesiumMaterialFabricOptions<U> {
    /**
     * Used to declare what material the fabric object will ultimately generate. If it's an official built-in one, use the official built-in one directly; otherwise, create a custom material and cache it.
     */
    type: string;
    /**
     * Can nest another level of child fabric to form a composite material
     */
    materials?: Material;
    /**
     * glsl code
     */
    source?: string;
    components?: {
        diffuse?: string;
        alpha?: string;
    };
    /**
     * Pass variables to glsl code
     */
    uniforms?: U & Record<string, any>;
}
/**
 * Cesium.Material parameters
 */
export interface CesiumMaterialConstructorOptions<U> {
    /**
     * Strict mode
     */
    strict?: boolean;
    /**
     * translucent
     */
    translucent?: boolean | ((...params: any[]) => any);
    /**
     * Minification filter
     */
    minificationFilter?: TextureMinificationFilter;
    /**
     * Magnification filter
     */
    magnificationFilter?: TextureMagnificationFilter;
    /**
     * Matrix configuration
     */
    fabric: CesiumMaterialFabricOptions<U>;
}
/**
 * Only as a type fix for `Cesium.Material`
 */
export declare class CesiumMaterial<U> extends Material {
    constructor(options: CesiumMaterialConstructorOptions<U>);
    /**
     * Matrix configuration
     */
    fabric: CesiumMaterialFabricOptions<U>;
}
/**
 * Only as a type fix for `Cesium.MaterialProperty`
 */
export interface CesiumMaterialProperty<V> extends MaterialProperty {
    get isConstant(): boolean;
    get definitionChanged(): Event<(scope: this, field: string, value: any, previous: any) => void>;
    getType: (time: JulianDate) => string;
    getValue: (time: JulianDate, result?: V) => V;
    equals: (other?: any) => boolean;
}
/**
 * Get material from cache, alias of `Material._materialCache.getMaterial`
 */
export declare function getMaterialCache<T extends Material = CesiumMaterial<any>>(type: string): T | undefined;
/**
 * Add material to Cesium's material cache, alias of `Material._materialCache.addMaterial`
 */
export declare function addMaterialCache(type: string, material: CesiumMaterialConstructorOptions<any>): void;

pick

/**
 * Analyze the result of Cesium's `scene.pick` and convert it to an array format
 */
export declare function resolvePick(pick?: any): any[];
/**
 * Determine if the given array of graphics is hit by Cesium's `scene.pick`
 *
 * @param pick The `scene.pick` object used for matching
 * @param graphic An array of graphics to check for hits
 */
export declare function pickHitGraphic(pick: any, graphic: any | any[]): boolean;

property

import type { JulianDate, Property } from 'cesium';
export type MaybeProperty<T = any> = T | {
    getValue: (time?: JulianDate) => T;
};
export type MaybePropertyOrGetter<T = any> = MaybeProperty<T> | (() => T);
/**
 * Is Cesium.Property
 * @param value - The target object
 */
export declare function isProperty(value: any): value is Property;
/**
 * Converts a value that may be a Property into its target value, @see {toProperty} for the reverse operation
 * ```typescript
 * toPropertyValue('val') //=> 'val'
 * toPropertyValue(new ConstantProperty('val')) //=> 'val'
 * toPropertyValue(new CallbackProperty(()=>'val')) //=> 'val'
 * ```
 *
 * @param value - The value to convert
 */
export declare function toPropertyValue<T = unknown>(value: MaybeProperty<T>, time?: JulianDate): T;
export type PropertyCallback<T = any> = (time: JulianDate, result?: T) => T;
/**
 * Converts a value that may be a Property into a Property object, @see {toPropertyValue} for the reverse operation
 *
 * @param value - The property value or getter to convert, can be undefined or null
 * @param isConstant - The second parameter for converting to CallbackProperty
 * @returns Returns the converted Property object, if value is undefined or null, returns undefined
 */
export declare function toProperty<T>(value?: MaybePropertyOrGetter<T>, isConstant?: boolean): Property;
/**
 * Create a Cesium property key
 *
 * @param scope The host object
 * @param field The property name
 * @param maybeProperty Optional property or getter
 * @param readonly Whether the property is read-only
 */
export declare function createPropertyField<T>(scope: any, field: string, maybeProperty?: MaybePropertyOrGetter<T>, readonly?: boolean): void;
export interface CreateCesiumAttributeOptions {
    readonly?: boolean;
    toProperty?: boolean;
    /**
     * The event name that triggers the change
     * @default 'definitionChanged'
     */
    changedEventKey?: string;
    shallowClone?: boolean;
}
export declare function createCesiumAttribute<Scope extends object>(scope: Scope, key: keyof Scope, value: any, options?: CreateCesiumAttributeOptions): void;
export interface CreateCesiumPropertyOptions {
    readonly?: boolean;
    /**
     * The event name that triggers the change
     * @default 'definitionChanged'
     */
    changedEventKey?: string;
}
export declare function createCesiumProperty<Scope extends object>(scope: Scope, key: keyof Scope, value: any, options?: CreateCesiumPropertyOptions): void;

throttle

export type ThrottleCallback<T extends any[]> = (...rest: T) => void;
/**
 * Throttle function, which limits the frequency of execution of the function
 *
 * @param callback raw function
 * @param delay Throttled delay duration (ms)
 * @param trailing Trigger callback function after last call @default true
 * @param leading Trigger the callback function immediately on the first call @default false
 * @returns Throttle function
 */
export declare function throttle<T extends any[]>(callback: ThrottleCallback<T>, delay?: number, trailing?: boolean, leading?: boolean): ThrottleCallback<T>;

toCartesian3

import type { CommonCoord } from './types';
import { Cartesian3 } from 'cesium';
/**
 * Converts position to a coordinate point in the Cartesian coordinate system
 *
 * @param position Position information, which can be a Cartesian coordinate point (Cartesian3), a geographic coordinate point (Cartographic), an array, or an object containing WGS84 latitude, longitude, and height information
 * @returns The converted Cartesian coordinate point. If the input parameter is invalid, undefined is returned
 */
export declare function toCartesian3(position?: CommonCoord): Cartesian3 | undefined;

toCartographic

import type { CommonCoord } from './types';
import { Cartographic } from 'cesium';
/**
 * Converts a position to a Cartographic coordinate point
 *
 * @param position Position information, which can be a Cartesian3 coordinate point, a Cartographic coordinate point, an array, or an object containing WGS84 longitude, latitude, and height information
 * @returns The converted Cartographic coordinate point, or undefined if the input parameter is invalid
 */
export declare function toCartographic(position?: CommonCoord): Cartographic | undefined;

toCoord

import type { CommonCoord, CoordArray, CoordArray_ALT, CoordObject, CoordObject_ALT } from './types';
interface ToCoordOptions<T extends 'Array' | 'Object', Alt extends boolean> {
    /**
     * Return type
     * @default 'Array'
     */
    type?: T;
    /**
     * Whether to return altitude information
     */
    alt?: Alt;
}
export type ToCoordReturn<T extends 'Array' | 'Object', Alt extends boolean> = T extends 'Array' ? Alt extends true ? CoordArray_ALT : CoordArray : Alt extends true ? CoordObject_ALT : CoordObject;
/**
 * Converts coordinates to an array or object in the specified format.
 *
 * @param position The coordinate to be converted, which can be a Cartesian3, Cartographic, array, or object.
 * @param options Conversion options, including conversion type and whether to include altitude information.
 * @returns The converted coordinate, which may be an array or object. If the input position is empty, undefined is returned.
 *
 * @template T Conversion type, optional values are 'Array' or 'Object', @default 'Array'.
 * @template Alt Whether to include altitude information, default is false
 */
export declare function toCoord<T extends 'Array' | 'Object' = 'Array', Alt extends boolean = false>(position?: CommonCoord, options?: ToCoordOptions<T, Alt>): ToCoordReturn<T, Alt> | undefined;
export {};

arrayDiff

export interface ArrayDiffRetrun<T> {
    added: T[];
    removed: T[];
}
/**
 * 计算两个数组的差异，返回新增和删除的元素
 */
export declare function arrayDiff<T>(list: T[], oldList: T[] | undefined): ArrayDiffRetrun<T>;