@soonspacejs/plugin-tiles 2.14.34 → 2.14.35

package/dist/plot/GroundDecalManager.d.ts

@@ -0,0 +1,115 @@
+import { PlotOverlay } from 'um-3d-tiles-renderer/three/plugins';
+import { ImageOverlayPlugin } from 'um-3d-tiles-renderer/plugins';
+import { GisPlotBase } from './plugins/base';
+import { GisPlotArrowSnapshot, GisPlotSnapshot, LonLatPoint, PlotAddOptions } from './plugins/types';
+import { default as SoonSpace } from 'soonspacejs';
+/** 构造 {@link GroundDecalManager} 时的选项 */
+export type GroundDecalManagerOptions = {
+    /** SoonSpace 实例（必传） */
+    ssp: SoonSpace;
+    /** 传入后会在首次有图形时自动将 PlotOverlay 注册到该插件 */
+    imageOverlayPlugin?: ImageOverlayPlugin;
+};
+/** {@link GroundDecalManager.getItem} / {@link GroundDecalManager.getItemDeep} 的联合返回类型 */
+export type GisPlotItemSnapshot = GisPlotSnapshot | GisPlotArrowSnapshot;
+/**
+ * 标绘样式补丁：与 {@link GisPlotBase.update} 一致，允许在基类字段之外带扩展键。
+ */
+export type GisPlotStylePatch = Partial<Parameters<GisPlotBase['update']>[0]> & Record<string, unknown>;
+/**
+ * {@link GroundDecalManager.setCenter} 的中心点（度）。
+ */
+export type CenterLonLat = {
+    lon?: number;
+    lat?: number;
+};
+export declare class GroundDecalManager {
+    /** 标绘 id → 实例；与 `PlotOverlay.imageSource.shapes` 共用同一引用 */
+    private readonly _items;
+    /** 标绘 id */
+    readonly id: string;
+    /** 标绘 overlay */
+    private readonly _overlay;
+    /** SoonSpace 实例 */
+    readonly ssp: SoonSpace;
+    /** 传入的 ImageOverlayPlugin，用于在有图形时自动注册 overlay */
+    private _imageOverlayPlugin?;
+    /** overlay 是否已注册到 ImageOverlayPlugin */
+    private _overlayAttached;
+    /** 合并同一帧内多次 `_markDirty`，值为 `requestAnimationFrame` 句柄 */
+    private _redrawTimer;
+    constructor(options: GroundDecalManagerOptions);
+    /**
+     * 内部使用的 `PlotOverlay` 实例。
+     * 注册到 `ImageOverlayPlugin` 的 `overlays` 数组中，顺序靠后者通常绘制在上层。
+     */
+    get overlay(): PlotOverlay;
+    /**
+     * 绑定 / 更换 ImageOverlayPlugin（切换地形重建插件后调用）。
+     * 如果当前已有图形，会在下一帧自动重新注册 overlay。
+     */
+    setImageOverlayPlugin(plugin: ImageOverlayPlugin): void;
+    /**
+     * 添加标绘：由 `options.type` 决定实例化哪一类 `GisPlot*`（与各类 `*Options` 对应）。
+     */
+    addPlot(options: PlotAddOptions): string;
+    /** 按 id 移除标绘；存在并删除成功时触发重绘 */
+    remove(id: string): void;
+    /** 清空全部标绘 */
+    clear(): void;
+    /**
+     * 读取标绘快照（**浅拷贝**：`options` 为新对象，但 `points` 与内部仍为同一数组引用）。
+     * 若需完全独立副本，请用 {@link getItemDeep}。
+     */
+    getItem(id: string): GisPlotItemSnapshot | null;
+    /**
+     * 深拷贝快照：`points` 等嵌套数组被复制，修改返回值不会影响内部状态。
+     * 箭头类型额外深拷贝 `generatedCoords`。
+     */
+    getItemDeep(id: string): GisPlotItemSnapshot | null;
+    /**
+     * 合并更新样式与几何字段（调用对应 `GisPlot*.update`）。
+     * `patch` 形状需与该 id 下图元类型兼容。
+     */
+    setStyle(id: string, patch: GisPlotStylePatch): void;
+    /**
+     * 将 **第一个顶点** 设为新的经纬度中心（适用于点、矩形中心、扇心、文字锚点等单中心语义）。
+     */
+    setCenter(id: string, center: CenterLonLat): void;
+    /** 整体替换顶点列表（每项为 `[lon, lat]`） */
+    setCoords(id: string, coords: LonLatPoint[]): void;
+    /** 修改指定下标顶点；`coord` 分量可为 `undefined` 表示不改该分量 */
+    setCoord(id: string, index: number, coord: Partial<LonLatPoint> | [number?, number?]): void;
+    /** 在 `index` 处插入一个顶点（可插在末尾，`index` 越界时钳位） */
+    insertCoord(id: string, index: number, coord: LonLatPoint): void;
+    /**
+     * 删除指定下标顶点。
+     * 多边形至少保留 3 点，其余类型至少 2 点（与 `shape.category` 联动）。
+     */
+    removeCoord(id: string, index: number): void;
+    /** 对所有顶点做经纬度平移（度） */
+    translateCoords(id: string, dLon: number, dLat: number): void;
+    /** 仅对 `category === 'text'` 的项更新 `options.content` */
+    setText(id: string, text: string): void;
+    /** 设置整个 overlay 不透明度（0–1，具体语义以 `PlotOverlay` 为准） */
+    setGlobalOpacity(opacity: number): void;
+    getCoordCount(id: string): number;
+    /**
+     * 在经纬度平面上找离 `(lon, lat)` 最近的顶点下标（平方距离最小）；
+     * 无顶点时返回 `-1`。
+     */
+    findNearestCoord(id: string, lon: number, lat: number): number;
+    render: () => void;
+    /**
+     * 释放 overlay 内部 RTT / 纹理等资源。
+     * `PlotImageSource` 的运行时实现含 `dispose`，类型声明可能未列出，故做断言。
+     */
+    dispose(): void;
+    /**
+     * 标记需要在下一帧重绘瓦片标绘层；同一帧内多次调用只会调度一次。
+     * 首次有图形且尚未挂载时，先将 PlotOverlay 注册到 ImageOverlayPlugin（此时 shapes 已有数据，
+     * `init()` → `hasContent` 能正确返回 true）。
+     */
+    private _markDirty;
+}
+export type { PlotAddOptions, } from './plugins/types';

package/dist/plot/plugins/arrow.d.ts

@@ -0,0 +1,25 @@
+import { LonLat } from './utils/ArrowUtils';
+import { GisPlotBase } from './base';
+import { GisPlotArrowSnapshot, PlotArrowOptions } from './types';
+/**
+ * 箭头标绘（面类）→ {@link PlotArrowOptions}
+ *
+ * CPU 端由 `./utils/ArrowUtils` 生成闭合多边形 → `generatedCoords`，复用 polygon type 2 渲染。
+ * 与折线端点箭头样式（`PlotArrowStyle`）不同。
+ */
+export declare class GisPlotArrow extends GisPlotBase {
+    readonly category: "arrow";
+    options: PlotArrowOptions;
+    /** `generateCoords()` 填充的闭合多边形顶点 */
+    generatedCoords: LonLat[];
+    constructor(options: PlotArrowOptions);
+    update(patch: Partial<PlotArrowOptions>): void;
+    /**
+     * 按 `arrowType` 与控制点生成闭合多边形顶点（供 GroundDecalManager / PlotOverlay 重建几何）。
+     */
+    generateCoords(): LonLat[];
+    /** 浅拷贝：`options`、`generatedCoords` 与内部共享引用（顶点数组仍与 `options.points` 规则一致）。 */
+    getSnapshot(): GisPlotArrowSnapshot;
+    /** 深拷贝：`options.points` 与 `generatedCoords` 均为新数组。 */
+    getSnapshotDeep(): GisPlotArrowSnapshot;
+}

package/dist/plot/plugins/base.d.ts

@@ -0,0 +1,32 @@
+import { GisPlotBaseOptions, GisPlotCategory, GisPlotSnapshot, LonLatPoint } from './types';
+/**
+ * GIS 标绘对象基类。
+ *
+ * 数据结构对齐 {@link GisPlotBaseOptions}：`points` 为 `[[lon, lat], ...]`。
+ * 子类在 `options` 中扩展各自字段（如 `size`、`radius`、`arrowType` 等）。
+ */
+export declare class GisPlotBase {
+    readonly id: string;
+    category: GisPlotCategory;
+    options: GisPlotBaseOptions;
+    constructor(options: GisPlotBaseOptions);
+    /**
+     * 合并更新 `options`（不可变风格：整表替换为新对象）。
+     * 子类应覆盖为 `Partial<具体Options>`，以便类型提示包含各类型专有字段。
+     */
+    update(patch: Partial<GisPlotBaseOptions> & Record<string, unknown>): void;
+    /**
+     * 浅拷贝快照：`options` 为一层展开新对象，`points` 与内部仍为同一数组引用。
+     * {@link GroundDecalManager.getItem} 默认使用此方法。
+     */
+    getSnapshot(): GisPlotSnapshot;
+    /**
+     * 深拷贝快照：`points` 中每个顶点为新数组，修改返回值不会影响标绘内部状态。
+     * 需独立副本时请用 {@link GroundDecalManager.getItemDeep} 或本方法。
+     */
+    getSnapshotDeep(): GisPlotSnapshot;
+    /** 用于计算 ENU 参考中心的坐标点 */
+    getCenterPoints(): LonLatPoint[];
+    /** 用于计算最大空间范围的坐标点（子类可覆盖以扩展半径等） */
+    getExtentPoints(): LonLatPoint[];
+}

package/dist/plot/plugins/circle.d.ts

@@ -0,0 +1,13 @@
+import { GisPlotBase } from './base';
+import { LonLatPoint, PlotCircleOptions } from './types';
+/**
+ * 圆标绘 → {@link PlotCircleOptions}
+ * `points[0]` 为圆心；shader type 1。
+ */
+export declare class GisPlotCircle extends GisPlotBase {
+    readonly category: "circle";
+    options: PlotCircleOptions;
+    constructor(options: PlotCircleOptions);
+    update(patch: Partial<PlotCircleOptions>): void;
+    getExtentPoints(): LonLatPoint[];
+}

package/dist/plot/plugins/index.d.ts

@@ -0,0 +1,10 @@
+export * from './types';
+export * from './base';
+export * from './point';
+export * from './line';
+export * from './polygon';
+export * from './rectangle';
+export * from './sector';
+export * from './arrow';
+export * from './text';
+export * from './circle';

package/dist/plot/plugins/line.d.ts

@@ -0,0 +1,12 @@
+import { GisPlotBase } from './base';
+import { PlotLineOptions } from './types';
+/**
+ * 折线标绘 → {@link PlotLineOptions}
+ * `options.points` 为折线顶点；shader type 3。
+ */
+export declare class GisPlotLine extends GisPlotBase {
+    readonly category: "line";
+    options: PlotLineOptions;
+    constructor(options: PlotLineOptions);
+    update(patch: Partial<PlotLineOptions>): void;
+}

package/dist/plot/plugins/point.d.ts

@@ -0,0 +1,14 @@
+import { GisPlotBase } from './base';
+import { LonLatPoint, PlotPointOptions } from './types';
+/**
+ * 点标绘 → {@link PlotPointOptions}
+ * `options.points[0]` 为点的中心；shader type 6。
+ */
+export declare class GisPlotPoint extends GisPlotBase {
+    readonly category: "point";
+    options: PlotPointOptions;
+    constructor(options: PlotPointOptions);
+    update(patch: Partial<PlotPointOptions>): void;
+    getCenterPoints(): LonLatPoint[];
+    getExtentPoints(): LonLatPoint[];
+}

package/dist/plot/plugins/polygon.d.ts

@@ -0,0 +1,12 @@
+import { GisPlotBase } from './base';
+import { PlotPolygonOptions } from './types';
+/**
+ * 多边形标绘 → {@link PlotPolygonOptions}
+ * 至少 3 个顶点；shader type 2。
+ */
+export declare class GisPlotPolygon extends GisPlotBase {
+    readonly category: "polygon";
+    options: PlotPolygonOptions;
+    constructor(options: PlotPolygonOptions);
+    update(patch: Partial<PlotPolygonOptions>): void;
+}

package/dist/plot/plugins/rectangle.d.ts

@@ -0,0 +1,13 @@
+import { GisPlotBase } from './base';
+import { LonLatPoint, PlotRectangleOptions } from './types';
+/**
+ * 矩形标绘 → {@link PlotRectangleOptions}
+ * `points[0]` 为矩形中心；`width`/`height` 为米；shader type 0（sdBox）。
+ */
+export declare class GisPlotRectangle extends GisPlotBase {
+    readonly category: "rectangle";
+    options: PlotRectangleOptions;
+    constructor(options: PlotRectangleOptions);
+    update(patch: Partial<PlotRectangleOptions>): void;
+    getExtentPoints(): LonLatPoint[];
+}

package/dist/plot/plugins/sector.d.ts

@@ -0,0 +1,13 @@
+import { GisPlotBase } from './base';
+import { LonLatPoint, PlotSectorOptions } from './types';
+/**
+ * 扇形标绘 → {@link PlotSectorOptions}
+ * `points[0]` 为扇心；shader type 5。
+ */
+export declare class GisPlotSector extends GisPlotBase {
+    readonly category: "sector";
+    options: PlotSectorOptions;
+    constructor(options: PlotSectorOptions);
+    update(patch: Partial<PlotSectorOptions>): void;
+    getExtentPoints(): LonLatPoint[];
+}

package/dist/plot/plugins/text.d.ts

@@ -0,0 +1,14 @@
+import { GisPlotBase } from './base';
+import { LonLatPoint, PlotTextOptions } from './types';
+/**
+ * 文本标绘 → {@link PlotTextOptions}
+ * `points[0]` 为标签锚点；shader type 4（label atlas）。
+ */
+export declare class GisPlotText extends GisPlotBase {
+    readonly category: "text";
+    options: PlotTextOptions;
+    constructor(options: PlotTextOptions);
+    update(patch: Partial<PlotTextOptions>): void;
+    getCenterPoints(): LonLatPoint[];
+    getExtentPoints(): LonLatPoint[];
+}

package/dist/plot/plugins/types.d.ts

@@ -0,0 +1,108 @@
+/** 经纬度顶点：[经度°, 纬度°]（与 RTT / shader 中 lon/lat 一致） */
+export type LonLatPoint = [number, number];
+/** 标绘类别 */
+export type GisPlotCategory = 'point' | 'line' | 'polygon' | 'rectangle' | 'sector' | 'arrow' | 'text' | 'circle';
+/**
+ * 标绘公共基类型。
+ * stroke* / fill* 不透明度为 **0–100** 整数百分比（与 GroundDecalManager / shader 一致）。
+ */
+export type GisPlotBaseOptions = {
+    /** 图形的顶点坐标 [[lon, lat], ...] */
+    points: LonLatPoint[];
+    strokeColor: string;
+    strokeWidth: number;
+    strokeOpacity: number;
+    fillColor: string;
+    fillOpacity: number;
+    visible: boolean;
+};
+/** {@link GisPlotBase.getSnapshot} / {@link GisPlotBase.getSnapshotDeep} 返回值 */
+export type GisPlotSnapshot<T extends GisPlotBaseOptions = GisPlotBaseOptions> = {
+    type: GisPlotCategory;
+    options: T;
+};
+/** 点标绘：样式（圆/方）、大小（米） */
+export type PlotPointOptions = GisPlotBaseOptions & {
+    pointStyle: 'circle' | 'square';
+    size: number;
+};
+/** 线标绘：折线顶点 + 可选端点箭头（SDF） */
+export type PlotLineStrokeStyle = 'solid' | 'dashed' | 'dotted';
+export type PlotEndpointStyle = 'round' | 'square';
+export type PlotArrowStyle = 'simple' | 'filled' | 'open' | 'double' | 'diamond' | 'bar';
+export type PlotLineOptions = GisPlotBaseOptions & {
+    strokeStyle?: PlotLineStrokeStyle;
+    endpointStyle?: PlotEndpointStyle;
+    showArrow?: boolean;
+    startArrowStyle?: PlotArrowStyle | null;
+    endArrowStyle?: PlotArrowStyle | null;
+    /** 线端箭头尺度（与示例 GroundDecalManager / shader 一致） */
+    arrowSize?: number;
+};
+export type PlotStrokeStyle = 'solid' | 'dashed';
+export type PlotFillStyle = 'solid' | 'diagonal' | 'grid';
+/** 多边形标绘 */
+export type PlotPolygonOptions = GisPlotBaseOptions & {
+    strokeStyle?: PlotStrokeStyle;
+    fillStyle?: PlotFillStyle;
+};
+/** 矩形：中心点 + 宽/高（米） */
+export type PlotRectangleOptions = GisPlotBaseOptions & {
+    strokeStyle?: PlotStrokeStyle;
+    width: number;
+    height: number;
+};
+/** 扇形：中心 + 半径与角度（度） */
+export type PlotSectorOptions = GisPlotBaseOptions & {
+    strokeStyle?: PlotStrokeStyle;
+    radius: number;
+    startAngle: number;
+    sectorAngle: number;
+};
+/** 圆：圆心 + 半径（米） */
+export type PlotCircleOptions = GisPlotBaseOptions & {
+    strokeStyle?: PlotStrokeStyle;
+    radius: number;
+};
+/** 箭头：控制点生成多边形；`straight` 在 CPU 端退化为首尾两点的 fine 箭头 */
+export type PlotArrowType = 'straight' | 'curved' | 'fine' | 'attack';
+export type PlotArrowOptions = GisPlotBaseOptions & {
+    strokeStyle?: PlotStrokeStyle;
+    arrowType: PlotArrowType;
+    headSize: number;
+};
+/** 文本标绘 */
+export type PlotTextAlign = 'left' | 'center' | 'right';
+export type PlotTextOptions = GisPlotBaseOptions & {
+    content: string;
+    fontColor: string;
+    fontSize: number;
+    textAlign?: PlotTextAlign;
+    showBorder?: boolean;
+    offsetX?: number;
+    offsetY?: number;
+};
+/** 箭头快照：在 options 外附加 `generatedCoords` */
+export type GisPlotArrowSnapshot = GisPlotSnapshot<PlotArrowOptions> & {
+    generatedCoords: LonLatPoint[];
+};
+/**
+ * `GroundDecalManager.addPlot` 入参：字段 `type` 与对应 `*Options` 组合，内部据此实例化 `GisPlot*`。
+ */
+export type PlotAddOptions = ({
+    type: 'point';
+} & PlotPointOptions) | ({
+    type: 'line';
+} & PlotLineOptions) | ({
+    type: 'polygon';
+} & PlotPolygonOptions) | ({
+    type: 'rectangle';
+} & PlotRectangleOptions) | ({
+    type: 'circle';
+} & PlotCircleOptions) | ({
+    type: 'sector';
+} & PlotSectorOptions) | ({
+    type: 'text';
+} & PlotTextOptions) | ({
+    type: 'arrow';
+} & PlotArrowOptions);

package/dist/plot/plugins/utils/ArrowUtils.d.ts

@@ -0,0 +1,129 @@
+/**
+ * @module ArrowUtils
+ *
+ * 箭头标绘图形生成工具库。
+ *
+ * 移植自 cesium-plot-js，将原始 Cesium `Cartesian3` 逻辑改为纯 2D **[经度, 纬度]**（度）计算。
+ * 各 `create*` 函数接收控制点，返回闭合多边形顶点序列，供 `GroundDecalManager.addArrowPlot()` 等以
+ * **面多边形**（如 type 2 / polygon SDF）渲染。
+ *
+ * **约定**
+ *
+ * - 坐标：`[longitude, latitude]`，单位 **度**。
+ * - 距离：在经纬度平面内按欧氏距离计算（**非**椭球大地线长或真实米制距离）。
+ */
+/** 经纬度对：索引 0 为经度（°），索引 1 为纬度（°）。 */
+export type LonLat = [number, number];
+/**
+ * 两点在经纬度平面上的欧氏距离。
+ *
+ * @param p1 - 起点
+ * @param p2 - 终点
+ */
+export declare function MathDistance(p1: LonLat, p2: LonLat): number;
+/**
+ * 折线顶点依次相连的总长度。
+ *
+ * @param points - 至少两个点；单点或空数组时循环不执行，返回 `0`。
+ */
+export declare function wholeDistance(points: LonLat[]): number;
+/**
+ * 作为箭头宽度尺度的基准长度：总折线长的 `0.99` 次幂。
+ *
+ * 幂次小于 1 使较长箭头的宽度增长略慢于线性，避免过长箭头翼展过大。
+ *
+ * @param points - 定义箭杆路径的控制点
+ */
+export declare function getBaseLength(points: LonLat[]): number;
+/**
+ * 两点的中点。
+ */
+export declare function Mid(p1: LonLat, p2: LonLat): LonLat;
+/**
+ * 从 `startPnt` 指向 `endPnt` 的方位角（类似地平经度），弧度，范围 **[0, 2π)**。
+ *
+ * @param startPnt - 起点
+ * @param endPnt - 终点（与起点重合时除零由调用方避免）
+ */
+export declare function getAzimuth(startPnt: LonLat, endPnt: LonLat): number;
+/**
+ * 在点 `b` 处，由 `b→a` 与 `b→c` 两方向方位角之差，归一化到 **[0, 2π)**。
+ */
+export declare function getAngleOfThreePoints(a: LonLat, b: LonLat, c: LonLat): number;
+/**
+ * 判断折线段 `p1 → p2 → p3` 在 `p2` 处是否为顺时针转向（2D 叉积符号）。
+ */
+export declare function isClockWise(p1: LonLat, p2: LonLat, p3: LonLat): boolean;
+/**
+ * 从 `endPnt` 出发，沿 `startPnt → endPnt` 方向旋转 `angle`（弧度），再前进 `distance`（度制平面距离），得到第三点。
+ *
+ * `clockWise` 为 `true` 时向一侧偏转，为 `false` 时向另一侧偏转，用于箭头两翼、颈部等对称结构。
+ */
+export declare function getThirdPoint(startPnt: LonLat, endPnt: LonLat, angle: number, distance: number, clockWise: boolean): LonLat;
+/**
+ * 在顶点 `p2` 处，`p1→p2` 与 `p3→p2` 两方向单位向量之和，用作角平分线法向（未单位化）。
+ */
+export declare function getNormal(p1: LonLat, p2: LonLat, p3: LonLat): LonLat;
+/**
+ * 在 `p2` 处沿角平分线方向生成左右两条 Bézier 控制点；`t` 控制偏移与邻边长的比例。
+ *
+ * @param t - 弯曲强度系数，典型值与 `getCurvePoints` 中一致（如 `0.3`）
+ * @returns `[ rightControl, leftControl ]`（命名与原始 cesium-plot 一致）
+ */
+export declare function getBisectorNormals(t: number, p1: LonLat, p2: LonLat, p3: LonLat): [LonLat, LonLat];
+/**
+ * 由折线控制点生成 **三次 Bézier 链** 上的密化点列。
+ *
+ * 1. 内部顶点：角平分线法向 → 左右控制点（{@link getBisectorNormals}）。
+ * 2. 首尾：镜像控制点（{@link getLeftMostControlPoint} / {@link getRightMostControlPoint}）。
+ * 3. 相邻控制点间用标准三次 Bézier 公式采样 {@link FITTING_COUNT} 段。
+ *
+ * @param t - 控制点偏移强度（如 `0.3`）
+ * @param controlPoints - 至少 **3** 个点
+ */
+export declare function getCurvePoints(t: number, controlPoints: LonLat[]): LonLat[];
+/**
+ * 均匀二次 B 样条对折线点列做平滑，步长 `0.05`。
+ *
+ * 用于攻击箭头左右侧边，使折线变为平滑曲线；适合「贴近控制点但不强制插值」的造型。
+ *
+ * @param points - 至少 2 个点；≤2 时原样返回
+ */
+export declare function getQBSplinePoints(points: LonLat[]): LonLat[];
+/**
+ * **直线箭头（线型）**：`p1 → p2` 的箭杆 + 末端约 **30°**（`π/6`）张角的翼。
+ *
+ * 返回 **5 个顶点** 的折线（非闭合）：`p1, p2, leftWing, p2, rightWing`，用于 `createCurvedArrow` 两点退化等场景。
+ *
+ * @param headSize - 头部尺度；`>0` 时翼长取 `min(距离/5, headSize*0.01)` 等组合逻辑
+ */
+export declare function createStraightArrow(p1: LonLat, p2: LonLat, headSize: number): LonLat[];
+/**
+ * **细箭头（填充多边形）**：两点定义箭杆方向，生成带尾翼、颈部、头部的 **8 顶点** 逆时针闭合多边形。
+ *
+ * 宽度相对 `getBaseLength([p1,p2])` 的比例：尾 **10%**、颈 **20%**、翼 **25%**；翼角约 **π/8.5**，颈角约 **π/13**。
+ *
+ * @param p1 - 尾部中心
+ * @param p2 - 箭头尖端
+ */
+export declare function createFineArrow(p1: LonLat, p2: LonLat): LonLat[];
+/**
+ * **曲线箭头（填充多边形）**：3 个及以上控制点定义箭杆曲率，末端为三角箭头。
+ *
+ * 流程概要：`getCurvePoints` → 降采样 → 沿曲线法向左右偏移形成带宽度体部 → 末端 `getThirdPoint` 生成翼与颈 →
+ * 闭合顺序：左轮廓 → 头 → 右轮廓逆序。
+ *
+ * **2 点** 时退化为 {@link createFineArrow}。
+ *
+ * @param lnglatPoints - 控制点序列，至少 2 个
+ */
+export declare function createCurvedArrow(lnglatPoints: LonLat[]): LonLat[];
+/**
+ * **攻击箭头（填充多边形）**：首两点定义尾部宽度，后续点为脊线控制点（至少 3 点）。
+ *
+ * - 尾宽：`distance(points[0], points[1])`；顺逆时针决定 `tailLeft` / `tailRight`。
+ * - 脊线：尾边中点接 `points[2..]`；体宽沿脊线由尾宽渐变到颈宽；侧边经 B 样条平滑并降采样。
+ *
+ * @param lnglatPoints - 至少 3 个点
+ */
+export declare function createAttackArrow(lnglatPoints: LonLat[]): LonLat[];

package/dist/plot/plugins/utils/colorUtils.d.ts

@@ -0,0 +1,51 @@
+/**
+ * @module colorUtils
+ *
+ * 颜色与不透明度工具函数。
+ *
+ * 为 {@link GroundDecalManager} 及标绘渲染管线提供颜色字符串解析与不透明度兼容层。
+ * SDF shader 中颜色以归一化 RGBA `[0,1]` 传入，alpha 通道通常已合并 `fillOpacity` / `strokeOpacity`。
+ */
+/** 归一化 RGBA 四元组，各分量 ∈ [0, 1]。 */
+export type NormalizedRGBA = readonly [number, number, number, number];
+/**
+ * 可携带填充/描边不透明度或统一透明度的样式片段。
+ *
+ * - **store 格式（推荐）**：`fillOpacity` / `strokeOpacity` 为 **0–100** 的整数百分比。
+ * - **旧版**：`opacity` 为 **0–1** 浮点数，同时作用于 fill 与 stroke。
+ */
+export interface StyleOpacityInput {
+    fillOpacity?: number;
+    strokeOpacity?: number;
+    opacity?: number;
+}
+/**
+ * 将颜色字符串解析为归一化 RGBA 数组 `[r, g, b, a]`，各分量 ∈ [0, 1]。
+ *
+ * **支持的输入格式**
+ *
+ * | 形式 | 说明 |
+ * |------|------|
+ * | `'#hex'` | 3 位或 6 位十六进制（如 `'#f00'`, `'#ff0000'`） |
+ * | `'rgb(r,g,b)'` | RGB 分量 0–255 |
+ * | `'rgba(r,g,b,a)'` | `a` ∈ [0, 1] |
+ * | `'transparent'` | 全透明 `[0,0,0,0]` |
+ * | `null` / `undefined` / 空字符串 | 全透明 `[0,0,0,0]` |
+ *
+ * 无法识别的字符串回退为 **不透明白** `[1,1,1,1]`。
+ *
+ * @param color - CSS 风格颜色字符串；空或透明则返回全透明。
+ * @returns 长度为 4 的归一化 RGBA 数组（新数组，可安全修改副本若需）。
+ */
+export declare function parseColorToRGBA(color: string | null | undefined): number[];
+/**
+ * 解析不透明度参数，兼容两种样式约定，并写入长度为 2 的输出数组。
+ *
+ * 1. **store 格式**：`fillOpacity` / `strokeOpacity` 为 0–100 整数 → 除以 100 得到 0–1。
+ * 2. **旧版**：仅提供 `opacity`（0–1）时，填充与描边共用该值。
+ * 3. 若某通道未指定，默认 **1**（完全不透明）。
+ *
+ * @param style - 图形样式对象（仅需不透明度相关字段）。
+ * @param base - 长度为 2 的数组；执行后 `base[0]` = 填充不透明度，`base[1]` = 描边不透明度，均为 0–1。
+ */
+export declare function resolveOpacity(style: StyleOpacityInput, base: [number, number]): void;

package/dist/plot/plugins/utils/coordUtils.d.ts

@@ -0,0 +1,48 @@
+import { Vector3 } from 'three';
+/** 角度（度）→ 弧度，与 `THREE.MathUtils.DEG2RAD` 一致。 */
+export declare const DEG2RAD: number;
+/**
+ * 标签 atlas 画布边长（像素）。
+ *
+ * 文字标签预渲染到 `LABEL_ATLAS × LABEL_ATLAS` 的 2D canvas，再上传为 `CanvasTexture` 供 shader 采样。
+ */
+export declare const LABEL_ATLAS = 2048;
+/**
+ * 椭球体接口：至少实现由大地坐标（弧度）到 ECEF 的转换。
+ *
+ * 与 Three.js / 瓦片渲染器中椭球实现兼容：`getCartographicToPosition( latRad, lonRad, height, target )`。
+ */
+export interface EllipsoidLike {
+    /**
+     * @param latitude - 纬度（弧度）
+     * @param longitude - 经度（弧度）
+     * @param height - 椭球面以上高度（米），地表一般为 0
+     * @param result - 输出 ECEF 坐标（米）
+     */
+    getCartographicToPosition(latitude: number, longitude: number, height: number, result: Vector3): Vector3;
+}
+/** ENU 平面上的东向、北向分量（米）。 */
+export interface ENUMeters {
+    /** East（东向）分量，米。 */
+    e: number;
+    /** North（北向）分量，米。 */
+    n: number;
+}
+/**
+ * 将经纬度（度）转换为以给定 ENU 原点为参考的局部东-北坐标（米）。
+ *
+ * **步骤概要**
+ *
+ * 1. `(lonDeg, latDeg)` → ECEF（通过椭球 `getCartographicToPosition`）。
+ * 2. ECEF 减去参考点 ECEF，得位移向量。
+ * 3. 位移分别与 `east`、`north` 单位向量点积，得到 `e`、`n`（米）。
+ *
+ * @param lonDeg - 经度（度）
+ * @param latDeg - 纬度（度）
+ * @param ellipsoid - 椭球体（WGS84 等）
+ * @param east - ECEF 空间中东向单位向量（与 `north`、径向构成右手系）
+ * @param north - ECEF 空间中北向单位向量
+ * @param centerECEF - ENU 原点在 ECEF 下的位置（米）
+ * @returns 局部平面坐标 `{ e, n }`（米）
+ */
+export declare function lonLatToMeters(lonDeg: number, latDeg: number, ellipsoid: EllipsoidLike, east: Vector3, north: Vector3, centerECEF: Vector3): ENUMeters;

package/dist/terrain-tiles-renderer/TerrainTilesRenderer.d.ts

@@ -6,6 +6,7 @@ import { OverlayManager } from './OverlayManager';
 import { ResourceManager } from './ResourceManager';
 import { TerrainManager } from './TerrainManager';
 import { ITerrainTilesRendererOptions, IGeoJSONOverlayOptions, ICesiumIonOverlayOptions, ITMSTilesOverlayOptions, IXYZTilesOverlayOptions, IWMSTilesOverlayOptions, IWMTSTilesOverlayOptions, IUrlTemplateOverlayOptions, AlphaClipMode, ITerrainConfig } from './types';
+import { GroundDecalManager } from '../plot/GroundDecalManager';
 /**
  * TerrainTilesRenderer 地形渲染器
  * 支持多种地形源和多个叠加层
@@ -28,6 +29,8 @@ export declare class TerrainTilesRenderer {
     terrainManager: TerrainManager;
     /** Overlay 管理器（管理实例） */
     overlayManager: OverlayManager;
+    /** 标绘管理器（管理标绘实例） */
+    groundDecalManager?: GroundDecalManager;
     /** 当前地形配置 */
     private _currentTerrainConfig;
     /** Alpha 裁剪模式 */

package/dist/terrain-tiles-renderer/types.d.ts

@@ -222,7 +222,8 @@ export declare enum OverlayType {
     XYZ = "xyz",
     WMS = "wms",
     WMTS = "wmts",
-    URL_TEMPLATE = "urlTemplate"
+    URL_TEMPLATE = "urlTemplate",
+    PLOT = "plot"
 }
 /**
  * Overlay 存储项