@xingm/vmap-cesium-toolbar 0.0.7-alpha.1 → 0.0.7-alpha.2

package/dist/libs/overlay/MapPolygon.d.ts

@@ -0,0 +1,114 @@
+import { Viewer, Entity, Color, HeightReference } from '../../../node_modules/cesium';
+import { OverlayPosition, OverlayEntity } from './types';
+import * as Cesium from "cesium";
+/**
+ * Polygon 选项
+ */
+export interface PolygonOptions {
+    positions: OverlayPosition[];
+    /**
+     * 渲染模式：
+     * - auto：自动选择（默认；当前仅在“粗边框+贴地+纯色”场景下会切到 primitive）
+     * - entity：使用 Cesium Entity
+     * - primitive：使用 Cesium GroundPrimitive / GroundPolylinePrimitive（大批量静态贴地场景）
+     */
+    renderMode?: 'auto' | 'entity' | 'primitive';
+    material?: Cesium.MaterialProperty | Color | string;
+    outline?: boolean;
+    outlineColor?: Color | string;
+    outlineWidth?: number;
+    /**
+     * 是否贴地（默认：在粗边框模式下为 true）。
+     * - true：填充与边框都贴地（避免一贴地一悬空导致缝隙）。
+     * - false：填充与边框都在统一的 baseHeight 上悬空。
+     */
+    clampToGround?: boolean;
+    /** 贴地抬高量（米，clampToGround=true 时生效） */
+    groundHeightEpsilon?: number;
+    heightReference?: HeightReference;
+    extrudedHeight?: number;
+    /** 点击该覆盖物时是否高亮显示（默认 false）。支持传入自定义颜色等参数 */
+    clickHighlight?: boolean | {
+        color?: Color | string;
+        fillAlpha?: number;
+    };
+    /** 鼠标移入该覆盖物时是否高亮显示（默认 false）。支持传入自定义颜色等参数 */
+    hoverHighlight?: boolean | {
+        color?: Color | string;
+        fillAlpha?: number;
+    };
+    onClick?: (entity: Entity) => void;
+    /**
+     * Primitive 模式分层渲染 key。
+     * - 相同 layerKey 的 polygon 会被合并到同一个批次中（更高性能）
+     * - 不同 layerKey 会进入不同的“图层空间”，并按首次出现顺序确定上下层
+     * - 只对 primitive 生效；entity 模式忽略
+     */
+    layerKey?: string;
+    id?: string;
+}
+/**
+ * Polygon 工具类
+ */
+export declare class MapPolygon {
+    private viewer;
+    private entities;
+    private primitiveBatch;
+    private primitiveLayerStack;
+    private primitiveBatchesByLayer;
+    constructor(viewer: Viewer);
+    private getPrimitiveBatch;
+    private getLayeredPrimitiveBatch;
+    private getPrimitiveBatchForOverlay;
+    private resolveMaterialColor;
+    private canUsePrimitive;
+    private addPrimitivePolygon;
+    /**
+     * 转换位置为 Cartesian3
+     */
+    private convertPosition;
+    /**
+     * 转换颜色
+     */
+    private resolveColor;
+    /**
+     * 解析材质
+     */
+    private resolveMaterial;
+    /**
+     * 计算二维多边形方向（正值为 CCW）
+     */
+    private polygonArea2D;
+    /**
+     * 向内偏移二维多边形顶点（线偏移 + 邻边相交）。厚度单位：米。
+     * 对复杂凹形可能產生伪影，更适合凸多边形或温和凹形。
+     */
+    private offsetPolygon2DInward;
+    /**
+     * 计算内偏移后的 3D 顶点：使用切平面近似进行 2D 偏移再投回椭球，并统一高度。
+     */
+    private computeInnerOffsetPositions;
+    /**
+     * 为多边形顶点统一高度（含微小抬升）
+     */
+    private elevatePositions;
+    /**
+     * 添加 Polygon（多边形）
+     */
+    add(options: PolygonOptions): Entity;
+    /**
+     * 更新 Polygon 位置
+     */
+    updatePositions(entity: Entity, positions: OverlayPosition[]): void;
+    /**
+     * 更新 Polygon 样式
+     */
+    updateStyle(entity: Entity, options: Partial<Pick<PolygonOptions, 'material' | 'outline' | 'outlineColor' | 'outlineWidth'>>): void;
+    /**
+     * 移除 Polygon（通过实体或实体 id）
+     */
+    remove(entityOrId: Entity | string): boolean;
+    setPrimitiveVisible(entity: Entity, visible: boolean): void;
+    applyPrimitiveHighlight(entity: OverlayEntity, hlColor: Cesium.Color, fillAlpha: number): void;
+    restorePrimitiveHighlight(entity: OverlayEntity): void;
+}

package/dist/libs/overlay/MapPolyline.d.ts

@@ -0,0 +1,64 @@
+import { Viewer, Entity, Color } from '../../../node_modules/cesium';
+import { OverlayPosition } from './types';
+import * as Cesium from "cesium";
+/**
+ * Polyline 选项
+ */
+export interface PolylineOptions {
+    positions: OverlayPosition[];
+    width?: number;
+    material?: Cesium.MaterialProperty | Color | string;
+    clampToGround?: boolean;
+    /** 贴地抬高量（米，clampToGround=true 时生效） */
+    groundHeightEpsilon?: number;
+    /** 点击该覆盖物时是否高亮显示（默认 false）。支持传入自定义颜色等参数 */
+    clickHighlight?: boolean | {
+        color?: Color | string;
+        fillAlpha?: number;
+    };
+    /** 鼠标移入该覆盖物时是否高亮显示（默认 false）。支持传入自定义颜色等参数 */
+    hoverHighlight?: boolean | {
+        color?: Color | string;
+        fillAlpha?: number;
+    };
+    onClick?: (entity: Entity) => void;
+    id?: string;
+}
+/**
+ * Polyline 工具类
+ */
+export declare class MapPolyline {
+    private viewer;
+    private entities;
+    private readonly avoidGroundPipeline;
+    constructor(viewer: Viewer);
+    /**
+     * 转换位置为 Cartesian3
+     */
+    private convertPosition;
+    /**
+     * 转换颜色
+     */
+    private resolveColor;
+    /**
+     * 解析材质
+     */
+    private resolveMaterial;
+    private elevatePositions;
+    /**
+     * 添加 Polyline（折线）
+     */
+    add(options: PolylineOptions): Entity;
+    /**
+     * 更新 Polyline 位置
+     */
+    updatePositions(entity: Entity, positions: OverlayPosition[]): void;
+    /**
+     * 更新 Polyline 样式
+     */
+    updateStyle(entity: Entity, options: Partial<Pick<PolylineOptions, 'width' | 'material'>>): void;
+    /**
+     * 移除 Polyline（通过实体或实体 id）
+     */
+    remove(entityOrId: Entity | string): boolean;
+}

package/dist/libs/overlay/MapRectangle.d.ts

@@ -0,0 +1,101 @@
+import { Viewer, Entity, Color, HeightReference } from '../../../node_modules/cesium';
+import { OverlayEntity } from './types';
+import * as Cesium from "cesium";
+/**
+ * Rectangle 选项
+ */
+export interface RectangleOptions {
+    coordinates: Cesium.Rectangle;
+    /**
+     * 渲染模式：
+     * - auto：自动选择（默认；当前仅在“粗边框+贴地+纯色”场景下会切到 primitive）
+     * - entity：使用 Cesium Entity
+     * - primitive：使用 Cesium GroundPrimitive（大批量静态贴地场景）
+     */
+    renderMode?: 'auto' | 'entity' | 'primitive';
+    material?: Cesium.MaterialProperty | Color | string;
+    outline?: boolean;
+    outlineColor?: Color | string;
+    outlineWidth?: number;
+    /** 是否贴地（默认：在粗边框模式下为 true） */
+    clampToGround?: boolean;
+    /** 贴地抬高量（米，clampToGround=true 时生效） */
+    groundHeightEpsilon?: number;
+    /** 悬空时的基准高度（米，clampToGround=false 时有效） */
+    height?: number;
+    heightReference?: HeightReference;
+    extrudedHeight?: number;
+    /** 高度容差（米）：用于避免共面深度冲突；会同时作用于边框与填充以保证一致 */
+    heightEpsilon?: number;
+    /** 点击该覆盖物时是否高亮显示（默认 false）。支持传入自定义颜色等参数 */
+    clickHighlight?: boolean | {
+        color?: Color | string;
+        fillAlpha?: number;
+    };
+    /** 鼠标移入该覆盖物时是否高亮显示（默认 false）。支持传入自定义颜色等参数 */
+    hoverHighlight?: boolean | {
+        color?: Color | string;
+        fillAlpha?: number;
+    };
+    onClick?: (entity: Entity) => void;
+    /**
+     * Primitive 模式分层渲染 key。
+     * - 相同 layerKey 的 rectangle 会被合并到同一个批次中（更高性能）
+     * - 不同 layerKey 会进入不同的“图层空间”，并按首次出现顺序确定上下层
+     * - 只对 primitive 生效；entity 模式忽略
+     */
+    layerKey?: string;
+    id?: string;
+}
+/**
+ * Rectangle 工具类
+ */
+export declare class MapRectangle {
+    private viewer;
+    private entities;
+    private primitiveBatch;
+    private primitiveLayerStack;
+    private primitiveBatchesByLayer;
+    constructor(viewer: Viewer);
+    private getPrimitiveBatch;
+    private getLayeredPrimitiveBatch;
+    private getPrimitiveBatchForOverlay;
+    private resolveMaterialColor;
+    private canUsePrimitive;
+    private addPrimitiveRectangle;
+    /**
+     * 转换颜色
+     */
+    private resolveColor;
+    /**
+     * 解析材质
+     */
+    private resolveMaterial;
+    /**
+     * 将 Rectangle 转为四点多边形顶点（按西南→东南→东北→西北顺序）
+     */
+    private rectangleToPositions;
+    /**
+     * 按米单位向内收缩矩形边界，返回新的 Rectangle
+     */
+    private shrinkRectangle;
+    /**
+     * 添加 Rectangle（矩形）
+     */
+    add(options: RectangleOptions): Entity;
+    /**
+     * 更新 Rectangle 坐标
+     */
+    updateCoordinates(entity: Entity, coordinates: Cesium.Rectangle): void;
+    /**
+     * 更新 Rectangle 样式
+     */
+    updateStyle(entity: Entity, options: Partial<Pick<RectangleOptions, 'material' | 'outline' | 'outlineColor' | 'outlineWidth'>>): void;
+    /**
+     * 移除 Rectangle（通过实体或实体 id）
+     */
+    remove(entityOrId: Entity | string): boolean;
+    setPrimitiveVisible(entity: Entity, visible: boolean): void;
+    applyPrimitiveHighlight(entity: OverlayEntity, hlColor: Cesium.Color, fillAlpha: number): void;
+    restorePrimitiveHighlight(entity: OverlayEntity): void;
+}

package/dist/libs/overlay/MapRing.d.ts

@@ -0,0 +1,107 @@
+import { Viewer, Entity, Color } from '../../../node_modules/cesium';
+import { OverlayPosition } from './types';
+/**
+ * Ring（边缘发光圆环）选项
+ */
+export interface RingOptions {
+    /** 中心点（经纬度/高度 或 Cartesian3） */
+    position: OverlayPosition;
+    /** 半径（米） */
+    radius: number;
+    /** 边缘发光颜色 */
+    color?: Color | string;
+    /** 是否绘制内层线（默认 true）。关闭可去掉“白色芯子” */
+    showInnerLine?: boolean;
+    /** 实线颜色 */
+    lineColor?: Color | string;
+    /** 内层线型：实线/虚线（默认 solid） */
+    lineStyle?: "solid" | "dashed";
+    /** 虚线材质方案：stripe(默认) / dash */
+    lineMaterialMode?: "stripe" | "dash";
+    /** stripe 模式：条纹重复次数（默认 32） */
+    stripeRepeat?: number;
+    /** 虚线长度（像素，默认 16） */
+    dashLength?: number;
+    /** 虚线模式（16bit pattern，可选） */
+    dashPattern?: number;
+    /** 虚线间隙颜色（默认透明） */
+    gapColor?: Color | string;
+    /** 线宽（像素） */
+    width?: number;
+    /** 外层发光线宽（像素）。优先于 width */
+    glowWidth?: number;
+    /** 内层实线线宽（像素）。不传则使用自动计算 */
+    lineWidth?: number;
+    /** 发光强度（0-1），越大越“亮/粗” */
+    glowPower?: number;
+    /** 是否贴地（默认 true） */
+    clampToGround?: boolean;
+    /** 贴地抬高量（米，clampToGround=true 时生效） */
+    groundHeightEpsilon?: number;
+    /** 圆环分段数（默认 128），越大越圆滑 */
+    segments?: number;
+    /** 覆盖物点击回调 */
+    onClick?: (entity: Entity) => void;
+    /** 点击该覆盖物时是否高亮显示（默认 false）。支持传入自定义颜色等参数 */
+    clickHighlight?: boolean | {
+        color?: Color | string;
+        fillAlpha?: number;
+    };
+    /** 鼠标移入该覆盖物时是否高亮显示（默认 false）。支持传入自定义颜色等参数 */
+    hoverHighlight?: boolean | {
+        color?: Color | string;
+        fillAlpha?: number;
+    };
+    id?: string;
+}
+/**
+ * Ring 工具类：使用 polyline + PolylineGlowMaterialProperty 实现发光圆环
+ */
+export declare class MapRing {
+    private viewer;
+    private entities;
+    constructor(viewer: Viewer);
+    /**
+     * 转换位置为 Cartesian3
+     */
+    private convertPosition;
+    /**
+     * 转换颜色
+     */
+    private resolveColor;
+    private resolveLineMaterial;
+    private resolveGlowMaterial;
+    private getInnerWidth;
+    private addInnerEntity;
+    private removeInnerEntity;
+    private rebuildRingPositions;
+    /**
+     * 生成近似圆顶点（Cartesian3 数组）。segments 越大越平滑。
+     * 这里沿用 MapCircle 的大圆航线近似，保证在经纬度空间更稳定。
+     */
+    private generateCirclePositions;
+    /**
+     * 添加 Ring（边缘发光圆环）
+     */
+    add(options: RingOptions): Entity;
+    /**
+     * 更新 Ring 中心
+     */
+    updatePosition(entity: Entity, position: OverlayPosition): void;
+    /**
+     * 更新 Ring 半径
+     */
+    updateRadius(entity: Entity, radius: number): void;
+    /**
+     * 更新 Ring 样式
+     */
+    updateStyle(entity: Entity, options: Partial<Pick<RingOptions, "color" | "showInnerLine" | "lineColor" | "lineStyle" | "lineMaterialMode" | "stripeRepeat" | "dashLength" | "dashPattern" | "gapColor" | "width" | "glowWidth" | "lineWidth" | "glowPower" | "clampToGround" | "segments" | "groundHeightEpsilon">>): void;
+    /**
+     * 显示/隐藏 Ring
+     */
+    setVisible(entity: Entity, visible: boolean): void;
+    /**
+     * 移除 Ring（通过实体或实体 id）
+     */
+    remove(entityOrId: Entity | string): boolean;
+}

package/dist/libs/overlay/MapSVG.d.ts

@@ -0,0 +1,73 @@
+import { Viewer, Entity, Color, HeightReference, VerticalOrigin, HorizontalOrigin } from '../../../node_modules/cesium';
+import { OverlayPosition } from './types';
+import * as Cesium from "cesium";
+/**
+ * SVG 选项
+ */
+export interface SvgOptions {
+    position: OverlayPosition;
+    svg: string;
+    width?: number;
+    height?: number;
+    scale?: number;
+    rotation?: number;
+    pixelOffset?: Cesium.Cartesian2;
+    eyeOffset?: Cesium.Cartesian3;
+    horizontalOrigin?: HorizontalOrigin;
+    verticalOrigin?: VerticalOrigin;
+    heightReference?: HeightReference;
+    disableDepthTestDistance?: number;
+    color?: Color | string;
+    /** 点击该覆盖物时是否高亮显示（默认 false）。支持传入自定义颜色等参数 */
+    clickHighlight?: boolean | {
+        color?: Color | string;
+        fillAlpha?: number;
+    };
+    /** 鼠标移入该覆盖物时是否高亮显示（默认 false）。支持传入自定义颜色等参数 */
+    hoverHighlight?: boolean | {
+        color?: Color | string;
+        fillAlpha?: number;
+    };
+    onClick?: (entity: Entity) => void;
+    id?: string;
+}
+/**
+ * SVG 工具类
+ */
+export declare class MapSVG {
+    private viewer;
+    private entities;
+    constructor(viewer: Viewer);
+    /**
+     * 转换位置为 Cartesian3
+     */
+    private convertPosition;
+    /**
+     * 转换颜色
+     */
+    private resolveColor;
+    /**
+     * 将 SVG 字符串转换为 data URL
+     */
+    private svgToDataUrl;
+    /**
+     * 添加 SVG（使用 Billboard）
+     */
+    add(options: SvgOptions): Entity;
+    /**
+     * 更新 SVG 位置
+     */
+    updatePosition(entity: Entity, position: OverlayPosition): void;
+    /**
+     * 更新 SVG 内容
+     */
+    updateSvg(entity: Entity, svg: string): void;
+    /**
+     * 更新 SVG 样式
+     */
+    updateStyle(entity: Entity, options: Partial<Pick<SvgOptions, 'scale' | 'rotation' | 'color'>>): void;
+    /**
+     * 移除 SVG（通过实体或实体 id）
+     */
+    remove(entityOrId: Entity | string): boolean;
+}

package/dist/libs/overlay/OverlayEditController.d.ts

@@ -0,0 +1,167 @@
+import { Viewer } from '../../../node_modules/cesium';
+import { DrawEntity } from '../drawHelper';
+import { OverlayEntity } from './types';
+import { OverlayEditOptions } from './OverlayEditHandles';
+import * as Cesium from "cesium";
+export type OverlayEditChangeCallback = (entity: DrawEntity & OverlayEntity) => void;
+export interface OverlayEditControllerOptions {
+    /**
+     * 编辑模式下，拖拽结束（LEFT_UP）且覆盖物几何发生变化时触发。
+     * 回调参数为“已回写后的覆盖物 entity”。
+     */
+    onChange?: OverlayEditChangeCallback;
+    /** 编辑功能配置项，默认为全开（除 rotate） */
+    overlayEditOptions?: OverlayEditOptions;
+}
+export interface OverlayEditHost {
+    getViewer(): Viewer;
+    getEntities(): Cesium.EntityCollection;
+    getOverlayById(id: string): (DrawEntity & OverlayEntity) | undefined;
+    pickCartographic(windowPosition: Cesium.Cartesian2): Cesium.Cartographic | null;
+    /**
+     * 进入编辑前的宿主清理动作（例如清 hover/click 高亮、清 hover 状态等）。
+     * 由宿主决定“高亮系统/hover 系统”如何处理。
+     */
+    prepareEntityForEdit(entity: DrawEntity & OverlayEntity): void;
+    /** 将编辑结果回写到覆盖物 */
+    applyPolygonPositions(entity: DrawEntity & OverlayEntity, positions: Cesium.Cartesian3[]): void;
+    applyRectangleCoordinates(entity: DrawEntity & OverlayEntity, rect: Cesium.Rectangle): void;
+    applyCircle(entity: DrawEntity & OverlayEntity, center: Cesium.Cartesian3, radiusMeters: number): void;
+    applyPolylinePositions(entity: DrawEntity & OverlayEntity, positions: Cesium.Cartesian3[]): void;
+    applyPointPosition(entity: DrawEntity & OverlayEntity, position: Cesium.Cartesian3): void;
+}
+/**
+ * 覆盖物编辑控制器类，用于管理地图上覆盖物的编辑操作
+ * 支持多边形、矩形、圆形、折线和点等类型的编辑
+ */
+export declare class OverlayEditController {
+    private readonly host;
+    private enabled;
+    private handler;
+    private readonly pickGovernor;
+    private onChange;
+    private editingTarget;
+    private editingKind;
+    private editingOptions;
+    private editingPositions;
+    private editingCircleCenter;
+    private editingCircleRadiusMeters;
+    private editingPointPosition;
+    private handleEntities;
+    private dragging;
+    private dragSnapshot;
+    private dragChanged;
+    private moveStartCenter;
+    private moveStartPositions;
+    private transformStartCenter;
+    private transformStartPositions;
+    private rotateStartAngle;
+    private scaleStartDistance;
+    private cameraBackup;
+    /**
+     * 构造函数
+     * @param host 覆盖物编辑宿主对象
+     * @param options 配置选项
+     */
+    constructor(host: OverlayEditHost, options?: OverlayEditControllerOptions);
+    /**
+     * 设置编辑变化回调函数
+     * @param cb 回调函数
+     */
+    setOnChange(cb?: OverlayEditChangeCallback | null): void;
+    /**
+     * 设置编辑器启用状态
+     * @param enabled 是否启用
+     * @param options 编辑功能配置项，可选。不传时使用构造函数传入的配置或默认配置
+     */
+    setEnabled(enabled: boolean, options?: OverlayEditOptions): void;
+    /**
+     * 获取编辑器启用状态
+     * @returns 是否启用
+     */
+    getEnabled(): boolean;
+    /**
+     * 判断是否正在编辑
+     * @returns 是否正在编辑
+     */
+    isEditing(): boolean;
+    /**
+     * 销毁编辑器
+     */
+    destroy(): void;
+    /** 停止当前正在编辑的覆盖物（不会关闭全局编辑模式） */
+    stop(): void;
+    /**
+     * 主动开始编辑某个覆盖物。
+     * @returns true 表示成功进入编辑
+     */
+    start(entityOrId: (DrawEntity & OverlayEntity) | string, options?: OverlayEditOptions): boolean;
+    /**
+     * 解析编辑目标实体，根据特定条件返回合适的实体对象
+     * @param entity 输入的实体对象，需要同时满足DrawEntity和OverlayEntity类型
+     * @returns 返回解析后的实体对象，可能是原始实体或符合条件的其他实体
+     */
+    private resolveEditTarget;
+    private detectEditableKind;
+    private getPropertyValue;
+    private getNumberProperty;
+    private resolvePolygonPositions;
+    private resolvePolylinePositions;
+    private getEditablePolygonPositions;
+    private getEditablePolylinePositions;
+    private getEditablePointPosition;
+    private getEditableRectangle;
+    private getEditableCircleInfo;
+    /**
+     * 确保屏幕空间事件处理器已初始化
+     * 如果处理器不存在，则创建一个新的处理器并设置各种交互事件
+     */
+    private ensureHandler;
+    private beginDrag;
+    private beginMoveDrag;
+    private computeMovedPositions;
+    private emitChange;
+    private prepareOnChangeTarget;
+    private resolveOverlayTypeFromId;
+    private attachMarkerLngLat;
+    private attachPolylineLngLat;
+    private attachCircleLngLat;
+    private attachPolygonLngLat;
+    private attachRectangleLngLat;
+    private captureDragSnapshot;
+    private isGeometryChangedSinceSnapshot;
+    private destroyHandler;
+    private lockCameraController;
+    private restoreCameraController;
+    private clearHandles;
+    /**
+     * 重建处理句柄的方法
+     * 根据当前编辑的几何图形类型，调用相应的构建函数创建处理句柄
+     */
+    private rebuildHandles;
+    private getHandleHelpers;
+    private createHandle;
+    private applyEditedPolygon;
+    private applyEditedRectangle;
+    private applyEditedCircle;
+    private applyEditedPolyline;
+    private applyEditedPoint;
+    private getEditingClampToGround;
+    private getCartesianHeight;
+    private convertOutlineToLngLat;
+    private convertPositionToLngLat;
+    private convertCartoToLngLat;
+    private pickCartesianOnGlobe;
+    private computeSurfaceDistanceMeters;
+    private circleRadiusHandlePosition;
+    private rectangleToPositions;
+    private rectangleToLngLatPositions;
+    private positionsToRectangle;
+    private getRectangleEditHeight;
+    private computePolygonCenterCartesian;
+    private computePolygonCenterCartographic;
+    private computePolylineHandleRadius;
+    private offsetByMeters;
+    private getLocalAngleAndDistance;
+    private applyRotateScaleToPositions;
+}