@xingm/vmap-cesium-toolbar 0.0.1 → 0.0.2-alpha.10

package/dist/libs/drawHelper/BaseDraw.d.ts

@@ -0,0 +1,170 @@
+import { Viewer, Entity, Cartesian3 } from '../../../node_modules/cesium';
+import * as Cesium from "cesium";
+/**
+ * 绘制结果接口
+ */
+export interface DrawResult {
+    entity: Entity | null;
+    type: "line" | "polygon" | "rectangle" | "circle";
+    positions: Cartesian3[];
+    distance?: number;
+    areaKm2?: number;
+}
+/**
+ * 绘制回调接口
+ */
+export interface DrawCallbacks {
+    onDrawStart?: () => void;
+    onDrawEnd?: (entity: Entity | null, result: DrawResult) => void;
+    onEntityRemoved?: (entity: Entity) => void;
+    onMeasureComplete?: (result: DrawResult) => void;
+}
+/**
+ * 扩展后的绘制实体类型
+ * 用于在 Entity 上挂载绘图相关的元数据
+ */
+export type DrawEntity = Entity & {
+    _drawType?: "line" | "polygon" | "rectangle" | "circle";
+    _drawOptions?: DrawOptions;
+    _groundPositions?: Cartesian3[];
+    _groundPosition?: Cartesian3;
+    _groundRectangle?: Cesium.Rectangle;
+    _radius?: number;
+    _borderEntity?: Entity;
+    _onClick?: (entity: Entity, ...args: any[]) => void;
+    _isSelected?: boolean;
+    _originalStyle?: {
+        material?: any;
+        width?: any;
+        outlineColor?: any;
+        outlineWidth?: any;
+    };
+};
+/**
+ * 绘制时可选的样式和事件回调
+ */
+export interface DrawOptions {
+    strokeColor?: Cesium.Color | string;
+    strokeWidth?: number;
+    fillColor?: Cesium.Color | string;
+    outlineColor?: Cesium.Color | string;
+    outlineWidth?: number;
+    selected?: {
+        color?: Cesium.Color | string;
+        width?: number;
+        outlineColor?: Cesium.Color | string;
+        outlineWidth?: number;
+    };
+    onClick?: (entity: Entity, type?: "line" | "polygon" | "rectangle" | "circle", positions?: Cartesian3[]) => void;
+}
+/**
+ * 基础绘制类
+ * 包含所有绘制类型的通用逻辑
+ */
+export declare abstract class BaseDraw {
+    protected viewer: Viewer;
+    protected scene: Cesium.Scene;
+    protected entities: Cesium.EntityCollection;
+    protected offsetHeight: number;
+    protected originalDepthTestAgainstTerrain: boolean | null;
+    /**
+     * 当场景启用了 requestRenderMode（手动渲染）时，绘制过程中需要关闭该模式以保证动画和交互正常。
+     * 在绘制结束或取消时应恢复为原始值。
+     */
+    protected originalRequestRenderMode: boolean | null;
+    protected callbacks: DrawCallbacks;
+    protected tempPositions: Cesium.Cartesian3[];
+    protected tempEntities: Cesium.Entity[];
+    protected tempLabelEntities: Cesium.Entity[];
+    protected finishedPointEntities: Cesium.Entity[];
+    /** 当前绘制的选项（如果有） */
+    protected drawOptions?: DrawOptions;
+    /**
+     * 公开只读访问当前临时数据，供调度器使用
+     */
+    getTempPositions(): Cartesian3[];
+    getTempEntities(): Entity[];
+    getTempLabelEntities(): Entity[];
+    getFinishedPointEntities(): Entity[];
+    /**
+     * 允许调度器安全地重建临时数据
+     */
+    setTempPositions(positions: Cartesian3[]): void;
+    setTempEntities(entities: Entity[]): void;
+    setTempLabelEntities(entities: Entity[]): void;
+    /**
+     * 供调度器调用的公开包装方法
+     */
+    addPointForHelper(position: Cartesian3): void;
+    clearTempEntitiesForHelper(): void;
+    /**
+     * 清除当前绘制过程中的临时点实体
+     * 仅删除带有 point 组件的临时实体，保留其它临时线/面实体
+     */
+    clearTempPointEntitiesForHelper(): void;
+    /**
+     * 删除最后一个点并根据剩余点重建预览实体
+     * 供调度器在右键删除点时调用，具体重建逻辑仍由各子类的 updateDrawingEntity 实现
+     */
+    removeLastPointAndRedraw(): void;
+    /**
+     * 将任意颜色输入解析为 Cesium.Color
+     */
+    protected resolveColor(input?: Cesium.Color | string): Cesium.Color;
+    /**
+     * 应用/切换选中样式（统一逻辑，供调度器和子类共用）
+     */
+    protected applySelectedStyleToEntity(entity: Entity): void;
+    /**
+     * 恢复原始样式（兼容旧接口，内部仍走统一逻辑）
+     */
+    protected restoreOriginalStyleForEntity(entity: Entity): void;
+    abstract updateDrawingEntity(previewPoint?: Cesium.Cartesian3): void;
+    abstract startDrawing(options?: DrawOptions): void;
+    /**
+     * 抽象方法：完成绘制
+     */
+    abstract finishDrawing(): DrawResult | null;
+    /**
+     * 抽象方法：获取绘制类型
+     */
+    abstract getDrawType(): "line" | "polygon" | "rectangle" | "circle";
+    constructor(viewer: Viewer, callbacks?: DrawCallbacks);
+    /**
+     * 根据场景模式更新偏移高度
+     */
+    protected updateOffsetHeight(): void;
+    /**
+     * 拾取地形或椭球体上的位置
+     */
+    protected pickGlobePosition(windowPosition: Cesium.Cartesian2): Cesium.Cartesian3 | null;
+    /**
+     * 如果场景启用了 requestRenderMode（手动渲染），在开始绘制时临时关闭以保证动画/交互正常。
+     */
+    protected enableContinuousRenderingIfNeeded(): void;
+    /**
+     * 在绘制完成或取消时恢复 requestRenderMode 到原始状态（如果曾被修改过）。
+     */
+    protected restoreRequestRenderModeIfNeeded(): void;
+    /**
+     * 添加一个点到临时位置数组并创建点实体
+     */
+    protected addPoint(position: Cesium.Cartesian3): void;
+    /**
+     * 创建总长/面积标签图片
+     */
+    protected createTotalLengthBillboardImage(text: string): HTMLCanvasElement;
+    /**
+     * 创建分段长度标签图片
+     */
+    protected createSegmentLengthBillboardImage(text: string): HTMLCanvasElement;
+    /**
+     * 清理临时实体
+     */
+    protected clearTempEntities(): void;
+}
+/**
+ * 静态工具方法：切换实体的选中样式
+ * 用于避免在多个模块中重复实现相同逻辑
+ */
+export declare function toggleSelectedStyle(entity: DrawEntity): void;

package/dist/libs/drawHelper/DrawCircle.d.ts

@@ -0,0 +1,30 @@
+import { Cartesian3 } from '../../../node_modules/cesium';
+import { BaseDraw, DrawResult, DrawOptions } from './BaseDraw';
+/**
+ * 画圆绘制类
+ */
+export declare class DrawCircle extends BaseDraw {
+    private currentCircleEntity;
+    private currentBorderEntity;
+    private centerPosition;
+    /**
+     * 开始绘制
+     */
+    startDrawing(options?: DrawOptions): void;
+    /**
+     * 更新绘制实体（预览）
+     */
+    updateDrawingEntity(previewPoint?: Cartesian3): void;
+    /**
+     * 完成绘制
+     */
+    finishDrawing(): DrawResult | null;
+    /**
+     * 获取绘制类型
+     */
+    getDrawType(): "line" | "polygon" | "rectangle" | "circle";
+    /**
+     * 生成近似圆（多边形）顶点
+     */
+    private generateCirclePositions;
+}

package/dist/libs/drawHelper/DrawLine.d.ts

@@ -0,0 +1,44 @@
+import { Cartesian3 } from '../../../node_modules/cesium';
+import { BaseDraw, DrawResult, DrawOptions } from './BaseDraw';
+/**
+ * 画线绘制类
+ */
+export declare class DrawLine extends BaseDraw {
+    private currentLineEntity;
+    private currentSegmentLabels;
+    private currentTotalLabel;
+    private currentLinePositions;
+    private isTotalLabelWarmedUp;
+    /**
+     * 开始绘制
+     */
+    startDrawing(options?: DrawOptions): void;
+    /**
+     * 更新绘制实体（预览）
+     */
+    updateDrawingEntity(previewPoint?: Cartesian3): void;
+    /**
+     * 完成绘制
+     */
+    finishDrawing(): DrawResult | null;
+    /**
+     * 获取绘制类型
+     */
+    getDrawType(): "line" | "polygon" | "rectangle" | "circle";
+    /**
+     * 清理线条实体
+     */
+    private clearLineEntity;
+    /**
+     * 更新分段标签
+     */
+    private updateSegmentLabels;
+    /**
+     * 更新总距离标签
+     */
+    private updateTotalLabel;
+    /**
+     * 总长标签预热
+     */
+    private warmupTotalLengthLabel;
+}

package/dist/libs/drawHelper/DrawPolgon.d.ts

@@ -0,0 +1,29 @@
+import { Cartesian3 } from '../../../node_modules/cesium';
+import { BaseDraw, DrawResult, DrawOptions } from './BaseDraw';
+/**
+ * 画多边形绘制类
+ */
+export declare class DrawPolygon extends BaseDraw {
+    private currentPolygonEntity;
+    private currentBorderEntity;
+    /**
+     * 开始绘制
+     */
+    startDrawing(options?: DrawOptions): void;
+    /**
+     * 更新绘制实体（预览）
+     */
+    updateDrawingEntity(previewPoint?: Cartesian3): void;
+    /**
+     * 完成绘制
+     */
+    finishDrawing(): DrawResult | null;
+    /**
+     * 清理所有绘制相关的实体
+     */
+    clear(): void;
+    /**
+     * 获取绘制类型
+     */
+    getDrawType(): "line" | "polygon" | "rectangle" | "circle";
+}

package/dist/libs/drawHelper/DrawRectangle.d.ts

@@ -0,0 +1,24 @@
+import { Cartesian3 } from '../../../node_modules/cesium';
+import { BaseDraw, DrawResult, DrawOptions } from './BaseDraw';
+/**
+ * 画矩形绘制类
+ */
+export declare class DrawRectangle extends BaseDraw {
+    private currentRectangleEntity;
+    /**
+     * 开始绘制
+     */
+    startDrawing(options?: DrawOptions): void;
+    /**
+     * 更新绘制实体（预览）
+     */
+    updateDrawingEntity(previewPoint?: Cartesian3): void;
+    /**
+     * 完成绘制
+     */
+    finishDrawing(): DrawResult | null;
+    /**
+     * 获取绘制类型
+     */
+    getDrawType(): "line" | "polygon" | "rectangle" | "circle";
+}

package/dist/libs/drawHelper/index.d.ts

@@ -0,0 +1,5 @@
+export { BaseDraw, type DrawResult, type DrawCallbacks, type DrawOptions, type DrawEntity, toggleSelectedStyle } from './BaseDraw';
+export { DrawLine } from './DrawLine';
+export { DrawPolygon } from './DrawPolgon';
+export { DrawRectangle } from './DrawRectangle';
+export { DrawCircle } from './DrawCircle';

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

@@ -0,0 +1,64 @@
+import { Viewer, Entity, Color, HeightReference } from '../../../node_modules/cesium';
+import { OverlayPosition } from './types';
+import * as Cesium from "cesium";
+/**
+ * Circle 选项
+ */
+export interface CircleOptions {
+    position: OverlayPosition;
+    radius: number;
+    material?: Cesium.MaterialProperty | Color | string;
+    outline?: boolean;
+    outlineColor?: Color | string;
+    outlineWidth?: number;
+    heightReference?: HeightReference;
+    extrudedHeight?: number;
+    heightEpsilon?: number;
+    onClick?: (entity: Entity) => void;
+    id?: string;
+}
+/**
+ * Circle 工具类
+ */
+export declare class MapCircle {
+    private viewer;
+    private entities;
+    constructor(viewer: Viewer);
+    /**
+     * 转换位置为 Cartesian3
+     */
+    private convertPosition;
+    /**
+     * 转换颜色
+     */
+    private resolveColor;
+    /**
+     * 解析材质
+     */
+    private resolveMaterial;
+    /**
+     * 添加 Circle（圆形）
+     */
+    add(options: CircleOptions): Entity;
+    /**
+     * 生成近似圆（多边形）顶点，返回 Cartesian3 数组。
+     * 使用大圆航线公式，segments 越大越平滑。
+     */
+    private generateCirclePositions;
+    /**
+     * 更新 Circle 位置
+     */
+    updatePosition(entity: Entity, position: OverlayPosition): void;
+    /**
+     * 更新 Circle 半径
+     */
+    updateRadius(entity: Entity, radius: number): void;
+    /**
+     * 更新 Circle 样式
+     */
+    updateStyle(entity: Entity, options: Partial<Pick<CircleOptions, 'material' | 'outline' | 'outlineColor' | 'outlineWidth'>>): void;
+    /**
+     * 移除 Circle（通过实体或实体 id）
+     */
+    remove(entityOrId: Entity | string): boolean;
+}

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

@@ -0,0 +1,59 @@
+import { Viewer, Entity, Color, HeightReference, VerticalOrigin, HorizontalOrigin } from '../../../node_modules/cesium';
+import { OverlayPosition } from './types';
+import * as Cesium from "cesium";
+/**
+ * Icon 选项
+ */
+export interface IconOptions {
+    position: OverlayPosition;
+    image: 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;
+    onClick?: (entity: Entity) => void;
+    id?: string;
+}
+/**
+ * Icon 工具类
+ */
+export declare class MapIcon {
+    private viewer;
+    private entities;
+    constructor(viewer: Viewer);
+    /**
+     * 转换位置为 Cartesian3
+     */
+    private convertPosition;
+    /**
+     * 转换颜色
+     */
+    private resolveColor;
+    /**
+     * 添加 Icon（图标，使用 Billboard）
+     */
+    add(options: IconOptions): Entity;
+    /**
+     * 更新 Icon 位置
+     */
+    updatePosition(entity: Entity, position: OverlayPosition): void;
+    /**
+     * 更新 Icon 图片
+     */
+    updateImage(entity: Entity, image: string): void;
+    /**
+     * 更新 Icon 样式
+     */
+    updateStyle(entity: Entity, options: Partial<Pick<IconOptions, 'scale' | 'rotation' | 'color'>>): void;
+    /**
+     * 移除 Icon（通过实体或实体 id）
+     */
+    remove(entityOrId: Entity | string): boolean;
+}

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

@@ -0,0 +1,100 @@
+import { Viewer, Entity } from '../../../node_modules/cesium';
+import { OverlayPosition } from './types';
+import * as Cesium from 'cesium';
+export interface InfoWindowOptions {
+    position: OverlayPosition;
+    content: string | HTMLElement;
+    width?: number;
+    height?: number;
+    pixelOffset?: Cesium.Cartesian2;
+    show?: boolean;
+    onClick?: (entity: Entity) => void;
+    id?: string;
+    closable?: boolean;
+    onClose?: (entity: Entity) => void;
+    backgroundColor?: string;
+    color?: string;
+    font?: string;
+    className?: string;
+    style?: Partial<CSSStyleDeclaration>;
+    showArrow?: boolean;
+    arrowSize?: number;
+    positionOffset?: 'top' | 'bottom' | 'left' | 'right' | 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' | 'left-top' | 'left-bottom' | 'right-top' | 'right-bottom';
+    hideWhenOutOfView?: boolean;
+    anchorHeight?: number;
+    anchorPixel?: number;
+    tailGap?: number;
+    updateInterval?: number;
+}
+/**
+ * 面向 Cesium 的 HTML 信息窗口管理器
+ * 要求 container 为 position: relative 的 DOM 容器（通常与 viewer.canvas 同级或包裹）
+ */
+export declare class MapInfoWindow {
+    private viewer;
+    private container;
+    private entityMap;
+    private currentTopZIndex;
+    private defaultUpdateInterval;
+    private isCameraMoving;
+    private cameraMoveStartListener?;
+    private cameraMoveEndListener?;
+    /**
+     * 合并用户传入的 InfoWindowOptions 与默认值，提升入参灵活性。
+     * 注意：必填项 position / content 由调用方提供，不在默认值内。
+     */
+    private mergeOptions;
+    constructor(viewer: Viewer, container: HTMLElement);
+    /**
+     * Set default update interval (ms) for position updates when an InfoWindow doesn't specify `updateInterval`.
+     * 0 means update every frame.
+     */
+    setDefaultUpdateInterval(ms: number): void;
+    /**
+     * Force immediate update (recompute positions) of all managed info windows.
+     */
+    forceUpdateAll(): void;
+    private convertPosition;
+    /**
+     * 将世界坐标转换为相对于 container 的 CSS 像素坐标
+     */
+    private getContainerPixelPosition;
+    /**
+     * 更新单个 infoWindow 的显示状态和位置
+     */
+    private updateDomPosition;
+    /**
+     * 创建 DOM 元素
+     */
+    private createDomElement;
+    /**
+     * 将指定 InfoWindow 置于最前
+     */
+    bringToFront(entity: Entity): void;
+    /**
+     * 添加信息窗口
+     */
+    add(options: InfoWindowOptions): Entity;
+    /**
+     * 更新位置
+     */
+    updatePosition(entity: Entity, position: OverlayPosition): void;
+    /**
+     * 更新内容
+     */
+    updateContent(entity: Entity, content: string | HTMLElement): void;
+    /**
+     * 显示/隐藏
+     */
+    setVisible(entity: Entity, visible: boolean): void;
+    show(entity: Entity): void;
+    hide(entity: Entity): void;
+    /**
+     * 移除信息窗口（清理 DOM + 监听器 + 实体）
+     */
+    remove(entity: Entity): void;
+    /**
+     * 销毁整个管理器（清理所有 infoWindow）
+     */
+    destroy(): void;
+}

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

@@ -0,0 +1,63 @@
+import { Viewer, Entity, Color, HeightReference, LabelStyle, VerticalOrigin, HorizontalOrigin } from '../../../node_modules/cesium';
+import { OverlayPosition } from './types';
+import * as Cesium from "cesium";
+/**
+ * Label 选项
+ */
+export interface LabelOptions {
+    position: OverlayPosition;
+    text: string;
+    font?: string;
+    fillColor?: Color | string;
+    outlineColor?: Color | string;
+    outlineWidth?: number;
+    style?: LabelStyle;
+    pixelOffset?: Cesium.Cartesian2;
+    eyeOffset?: Cesium.Cartesian3;
+    horizontalOrigin?: HorizontalOrigin;
+    verticalOrigin?: VerticalOrigin;
+    heightReference?: HeightReference;
+    scale?: number;
+    showBackground?: boolean;
+    backgroundColor?: Color | string;
+    backgroundPadding?: Cesium.Cartesian2;
+    disableDepthTestDistance?: number;
+    onClick?: (entity: Entity) => void;
+    id?: string;
+}
+/**
+ * Label 工具类
+ */
+export declare class MapLabel {
+    private viewer;
+    private entities;
+    constructor(viewer: Viewer);
+    /**
+     * 转换位置为 Cartesian3
+     */
+    private convertPosition;
+    /**
+     * 转换颜色
+     */
+    private resolveColor;
+    /**
+     * 添加 Label（文本标签）
+     */
+    add(options: LabelOptions): Entity;
+    /**
+     * 更新 Label 位置
+     */
+    updatePosition(entity: Entity, position: OverlayPosition): void;
+    /**
+     * 更新 Label 文本
+     */
+    updateText(entity: Entity, text: string): void;
+    /**
+     * 更新 Label 样式
+     */
+    updateStyle(entity: Entity, options: Partial<Pick<LabelOptions, 'fillColor' | 'outlineColor' | 'outlineWidth' | 'font' | 'scale'>>): void;
+    /**
+     * 移除 Label（通过实体或实体 id）
+     */
+    remove(entityOrId: Entity | string): boolean;
+}

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

@@ -0,0 +1,50 @@
+import { Viewer, Entity, Color, HeightReference } from '../../../node_modules/cesium';
+import { OverlayPosition } from './types';
+import * as Cesium from "cesium";
+/**
+ * Marker 选项
+ */
+export interface MarkerOptions {
+    position: OverlayPosition;
+    pixelSize?: number;
+    color?: Color | string;
+    outlineColor?: Color | string;
+    outlineWidth?: number;
+    heightReference?: HeightReference;
+    scaleByDistance?: Cesium.NearFarScalar;
+    disableDepthTestDistance?: number;
+    onClick?: (entity: Entity) => void;
+    id?: string;
+}
+/**
+ * Marker 工具类
+ */
+export declare class MapMarker {
+    private viewer;
+    private entities;
+    constructor(viewer: Viewer);
+    /**
+     * 转换位置为 Cartesian3
+     */
+    private convertPosition;
+    /**
+     * 转换颜色
+     */
+    private resolveColor;
+    /**
+     * 添加 Marker（点标记）
+     */
+    add(options: MarkerOptions): Entity;
+    /**
+     * 更新 Marker 位置
+     */
+    updatePosition(entity: Entity, position: OverlayPosition): void;
+    /**
+     * 更新 Marker 样式
+     */
+    updateStyle(entity: Entity, options: Partial<Pick<MarkerOptions, 'color' | 'outlineColor' | 'outlineWidth' | 'pixelSize'>>): void;
+    /**
+     * 移除 Marker（通过实体或实体 id）
+     */
+    remove(entityOrId: Entity | string): boolean;
+}