cesium-pocket 0.7.0-alpha → 0.7.2-alpha

package/src/czml/path/pathHeightEditor.d.ts

@@ -0,0 +1,204 @@
+import { Cartesian3, Color, Viewer } from 'cesium';
+import { PathPoint } from './pathHeightMath';
+export type { PathPoint };
+/** 编辑器可配置项，所有字段都有默认值 */
+export interface PathHeightEditorOptions {
+    /** 高度下限（米），默认 0 */
+    minHeight?: number;
+    /** 高度上限（米），默认不限 */
+    maxHeight?: number;
+    /** 空中折线颜色，默认青色 */
+    lineColor?: Color;
+    /** 地面投影虚线颜色 */
+    groundLineColor?: Color;
+    /** 节点圆点颜色 */
+    pointColor?: Color;
+    /** 拖拽中的节点颜色 */
+    activeColor?: Color;
+    /** 垂线颜色 */
+    stickColor?: Color;
+    /** 是否显示地面投影虚线与垂线，默认显示 */
+    showProjection?: boolean;
+    /** 是否允许拖拽，默认允许 */
+    editable?: boolean;
+    /** 每个节点下方的地面参考高度（米），不传则取初始节点的高度 */
+    groundHeights?: number[];
+    /** 高度变化回调，拖拽过程中会持续触发，index 为 -1 表示批量修改 */
+    onChange?: (points: PathPoint[], index: number) => void;
+    /** 开始拖拽某个节点 */
+    onDragStart?: (index: number) => void;
+    /** 结束拖拽 */
+    onDragEnd?: (index: number) => void;
+}
+/**
+ * 折线节点高程编辑器。
+ *
+ * - 每个节点是一个可拖拽的圆点，拖拽时只改变高程，经纬度保持不变；
+ * - 也可以通过 {@link setHeight} / {@link setHeights} 直接改指定节点的高度；
+ * - 节点高度变化会实时反映到折线、垂线和标签上。
+ *
+ * 纯几何计算（坐标转换、钳制、射线求高度）见 `pathHeightMath.ts`。
+ *
+ * ```ts
+ * // 直接传绘制得到的 Cartesian3[]
+ * const editor = new PathHeightEditor(viewer, positions);
+ * editor.setHeight(0, 1500);
+ * ```
+ */
+export declare class PathHeightEditor {
+    /** 所属三维场景 */
+    private readonly viewer;
+    /** 创建时传入的配置，构造后不再变化 */
+    private readonly options;
+    /** 拖拽所需的鼠标事件句柄 */
+    private readonly handler;
+    /** 编辑器所有实体都放这个数据源里，销毁时统一移除 */
+    private readonly dataSource;
+    /** 节点实体 → 序号，拖拽拾取时用，避免解析字符串 */
+    private readonly nodeEntities;
+    /** 节点数据，索引与 nodeEntities 中的序号一致 */
+    private points;
+    /** 每个节点下方的地面参考高度，用于绘制垂线 */
+    private groundHeights;
+    /** 是否允许拖拽，可在运行时切换 */
+    private editable;
+    /** 正在拖拽的节点序号，未拖拽为 -1 */
+    private activeIndex;
+    /** 上一帧鼠标位置，射线求解退化时按像素差换算高度 */
+    private lastScreen;
+    /** 是否已销毁，销毁后所有公共方法变为空操作 */
+    private destroyed;
+    /**
+     * 创建编辑器：转换节点数据、注册数据源、生成实体并绑定鼠标事件。
+     *
+     * @param viewer 三维场景
+     * @param positions 折线节点，通常来自绘制工具，直接传 Cartesian3[]
+     * @param options 可选配置
+     */
+    constructor(viewer: Viewer, positions: Cartesian3[], options?: PathHeightEditorOptions);
+    /**
+     * 读取当前所有节点。返回的是副本，修改不会影响编辑器内部数据。
+     * @returns 节点数组，经纬度为度、高度为米
+     */
+    getPoints(): PathPoint[];
+    /**
+     * 读取当前所有节点的世界坐标，可直接用于绘制折线或生成 CZML。
+     * @returns 每个节点当前空中位置
+     */
+    getPositions(): Cartesian3[];
+    /**
+     * 读取当前所有节点的高度。
+     * @returns 与节点顺序一致的高度数组（米）
+     */
+    getHeights(): number[];
+    /**
+     * 查询当前正在拖拽的节点。
+     * @returns 节点序号，未在拖拽时返回 -1
+     */
+    getActiveIndex(): number;
+    /**
+     * 运行时开关拖拽。关闭时会立即结束正在进行的拖拽，并恢复相机操作。
+     * @param editable 是否允许拖拽
+     */
+    setEditable(editable: boolean): void;
+    /**
+     * 修改单个节点的高度，用于输入框等外部入口。
+     * 高度会按 `minHeight` / `maxHeight` 钳制，值未变化时不触发回调。
+     * @param index 节点序号
+     * @param height 目标高度（米）
+     */
+    setHeight(index: number, height: number): void;
+    /**
+     * 批量修改高度，按数组顺序对应节点；多出的高度或非有限值会被忽略。
+     * 有实际变化时以 index = -1 触发一次 `onChange`。
+     * @param heights 高度数组（米）
+     */
+    setHeights(heights: number[]): void;
+    /**
+     * 用新的折线整体替换当前节点，重建全部实体。
+     * 会先结束正在进行的拖拽。
+     * @param positions 新的折线节点（世界坐标）
+     */
+    setPoints(positions: Cartesian3[]): void;
+    /**
+     * 销毁编辑器：结束拖拽、移除事件句柄、移除数据源及全部实体。
+     * 重复调用安全。
+     */
+    destroy(): void;
+    /**
+     * 按当前节点数据重建全部实体：地面投影、空中折线、节点与垂线。
+     * 节点位置/高度都通过 CallbackProperty 实时读取，改动数据后无需重建即可刷新。
+     */
+    private build;
+    /**
+     * 创建单个节点的圆点、标签，以及（可选）垂直投影线。
+     * @param index 节点序号
+     * @param showProjection 是否同时创建垂线
+     */
+    private addNode;
+    /** 绑定鼠标按下、移动、抬起三个事件 */
+    private bindEvents;
+    /**
+     * 左键按下：命中节点则进入拖拽状态。
+     * 拖拽期间关闭相机操作，否则视角会和节点一起被拖动。
+     * @param screenPosition 鼠标位置（画布坐标）
+     */
+    private onLeftDown;
+    /**
+     * 鼠标移动：拖拽中则更新高度；未拖拽时只切换悬停光标。
+     * @param screenPosition 鼠标位置（画布坐标）
+     */
+    private onMouseMove;
+    /** 结束拖拽：复位状态、恢复相机操作与光标，并触发 `onDragEnd` */
+    private endDrag;
+    /**
+     * 在鼠标位置拾取节点。
+     * 先用 Map 命中，失败再退化为解析实体 id，兼容拾取结果的包装差异。
+     * @param screenPosition 鼠标位置（画布坐标）
+     * @returns 节点序号，未命中返回 -1
+     */
+    private pickNode;
+    /** 各节点当前高度位置，用于空中折线 */
+    private airPositions;
+    /** 各节点在地面参考高度上的投影，用于地面虚线 */
+    private groundPositions;
+    /**
+     * 单个节点垂线的两个端点。
+     * @param index 节点序号
+     */
+    private stickPositions;
+    /**
+     * 节点当前位置。
+     * @param index 节点序号
+     */
+    private nodePosition;
+    /**
+     * 节点对应的地面参考高度，越界或非法值按 0 处理。
+     * @param index 节点序号
+     */
+    private groundHeightAt;
+    /**
+     * 节点颜色：拖拽中高亮，否则用配置色（默认橙色）。
+     * @param index 节点序号
+     */
+    private nodeColor;
+    /**
+     * 批量计算地面参考高度，结果与节点顺序一一对应。
+     * @param points 节点数组
+     */
+    private buildGroundHeights;
+    /**
+     * 按配置的上下限钳制高度。
+     * @param height 原始高度（米）
+     */
+    private clampHeight;
+    /**
+     * 单节点变化：请求重绘并通知调用方。
+     * @param index 变化节点的序号
+     */
+    private notify;
+    /** 整体变化：请求重绘并以 index = -1 通知调用方 */
+    private refresh;
+    /** 请求一次重绘，兼容 requestRenderMode 与已销毁的场景 */
+    private requestRender;
+}

package/src/czml/path/pathHeightMath.d.ts

@@ -0,0 +1,89 @@
+import { Cartesian2, Cartesian3, Viewer } from 'cesium';
+/** 折线节点：经度、纬度（度）与高度（米） */
+export type PathPoint = {
+    /** 经度（度，WGS84） */
+    lon: number;
+    /** 纬度（度，WGS84） */
+    lat: number;
+    /** 高度（米），绝对高程 */
+    height: number;
+};
+/** 节点实体 id 前缀，拾取时用于反查节点序号 */
+export declare const NODE_ID_PREFIX = "pathHeightNode";
+/**
+ * 拼接节点实体 id。
+ * @param index 节点序号
+ */
+export declare const nodeId: (index: number) => string;
+/**
+ * 复制一个节点，避免把内部对象直接暴露给调用者。
+ * @param point 源节点
+ * @returns 新的节点对象
+ */
+export declare const clonePoint: (point: PathPoint) => PathPoint;
+/**
+ * 世界坐标转经纬度 + 高度。
+ * 绘制工具给出的坐标是笛卡尔坐标，编辑器内部统一用经纬度 + 高度存储，
+ * 这样拖拽计算时不必反复做反投影。
+ * @param cartesian 世界坐标
+ * @returns 节点（经度、纬度单位为度）
+ */
+export declare const toPathPoint: (cartesian: Cartesian3) => PathPoint;
+/**
+ * 节点转世界坐标，高度取节点自身高度（空中位置）。
+ * @param point 节点
+ */
+export declare const toCartesian3: (point: PathPoint) => Cartesian3;
+/**
+ * 节点投影到指定地面高度上的世界坐标，用于垂线起点和地面投影虚线。
+ * @param point 节点
+ * @param groundHeight 地面参考高度（米）
+ */
+export declare const toGroundCartesian3: (point: PathPoint, groundHeight: number) => Cartesian3;
+/**
+ * 把高度限制在 [min, max] 区间内。
+ * 拖拽和输入数字两条路径都经过这里，保证行为一致。
+ * @param height 原始高度
+ * @param min 下限，默认 0
+ * @param max 上限，默认不限
+ */
+export declare const clampHeight: (height: number, min?: number, max?: number) => number;
+/**
+ * 确定垂线的地面起点高度。
+ * 优先使用调用方显式给的 `groundHeights`；没给时退回节点初始高度，
+ * 这样从绘制结果创建时，垂线起点就是绘制点落在地形上的位置。
+ * @param point 节点
+ * @param index 节点序号
+ * @param groundHeights 调用方指定的地面高度数组（可选）
+ */
+export declare const resolveGroundHeight: (point: PathPoint, index: number, groundHeights?: number[]) => number;
+/**
+ * 生成节点标签文本，形如 `P1 · 3800 m`。
+ * @param index 节点序号（从 0 开始，展示时 +1）
+ * @param height 当前高度（米）
+ */
+export declare const formatNodeLabel: (index: number, height: number) => string;
+/**
+ * 从实体 id 反解节点序号。
+ * 拾取到的实体可能是任意类型，这里对非 `pathHeightNode{n}` 形式的 id 返回 -1。
+ * @param id 实体 id（未知类型）
+ * @returns 节点序号，非本编辑器的实体返回 -1
+ */
+export declare const parseNodeIndex: (id: unknown) => number;
+/**
+ * 计算拖拽后节点的新高度，经纬度保持不变。
+ *
+ * 做法：取屏幕点对应的相机射线，求该射线与“过节点、沿地表法线方向”的
+ * 竖直线的最近点，最近点在竖直线上的位置即为新高度。这样鼠标上下移动
+ * 时节点只会沿竖直线升降，不会平移。
+ *
+ * 相机近乎垂直俯视时射线与竖直线接近平行，公式分母趋近 0，此时退化为
+ * 按“上一帧鼠标位置”的纵向像素差换算成米数。
+ *
+ * @param viewer 三维场景
+ * @param point 当前被拖拽的节点（用于取其经纬度和当前高度）
+ * @param screenPosition 当前鼠标位置（画布坐标）
+ * @param lastScreen 上一帧鼠标位置，仅像素换算兜底时使用
+ * @returns 新的绝对高度（米），未做上下限钳制
+ */
+export declare const screenHeightOnVerticalLine: (viewer: Viewer, point: PathPoint, screenPosition: Cartesian2, lastScreen: Cartesian2) => number;

package/src/gauger/circleSolid.d.ts

@@ -0,0 +1,6 @@
+import { Cartesian3, Entity } from 'cesium';
+import { PullColumn } from './pullColumn';
+/** 正圆底面拉成圆柱，体积 = πr²h。 */
+export declare class CircleSolid extends PullColumn {
+    add(entity: Entity, center: Cartesian3, radius: number): void;
+}

package/src/gauger/heightPole.d.ts

@@ -0,0 +1,43 @@
+import { Cartesian3, Viewer } from 'cesium';
+export type HeightPoleOptions = {
+    /** 放好一个圆面后通知页面，用来更新提示。 */
+    onPlace?: () => void;
+};
+/**
+ * 地面上的水平小圆面，拉高时圆面跟着上升，圆面始终与当地水平面平行。
+ * 圆面用 Primitive 只建一次，拉高时改 modelMatrix，避免 Entity 椭圆每帧重建导致闪烁。
+ * 放置与拖拽都在类内用 ScreenSpaceEventHandler 处理。
+ */
+export declare class HeightPole {
+    private readonly viewer;
+    private readonly onPlace;
+    private readonly records;
+    private readonly handler;
+    private drag;
+    private placing;
+    /** 拖完圆面后会冒泡出 LEFT_CLICK，用来挡住误放置。 */
+    private suppressClick;
+    private cameraHeld;
+    private destroyed;
+    private lastPosition;
+    constructor(viewer: Viewer, options?: HeightPoleOptions);
+    /** 开始在地图上放置圆面。放置会保持开启，以便连续测量。 */
+    start(): void;
+    add(position: Cartesian3): void;
+    hits(windowPosition: {
+        x: number;
+        y: number;
+    }): boolean;
+    destroy(): void;
+    private readonly applyExtrude;
+    private readonly metersPerPixel;
+    private readonly find;
+    private readonly hover;
+    private readonly onClick;
+    private readonly onDown;
+    private readonly onMove;
+    private readonly onUp;
+    private readonly canvasPosition;
+    private readonly stopCamera;
+    private readonly restoreCamera;
+}

package/src/gauger/polygonSolid.d.ts

@@ -0,0 +1,6 @@
+import { Cartesian3, Entity } from 'cesium';
+import { PullColumn } from './pullColumn';
+/** 多边形底面拉成棱柱，体积 = 底面积 × 高度。 */
+export declare class PolygonSolid extends PullColumn {
+    add(entity: Entity, positions: Cartesian3[]): void;
+}

package/src/gauger/pullColumn.d.ts

@@ -0,0 +1,37 @@
+import { Cartesian3, EllipseGraphics, Entity, PolygonGraphics, Viewer } from 'cesium';
+type HeightGraphic = EllipseGraphics | PolygonGraphics;
+export declare const centroid: (positions: Cartesian3[]) => Cartesian3;
+export declare const averageHeight: (positions: Cartesian3[]) => number;
+export declare const planarArea: (positions: Cartesian3[]) => number;
+/**
+ * 把已经画好的贴地底面向上拉成柱体，并在柱顶标注体积。
+ * 鼠标移到底面上时显示上下拖动光标。
+ */
+export declare class PullColumn {
+    private readonly viewer;
+    private readonly records;
+    private readonly handler;
+    private drag;
+    private cameraHeld;
+    private paused;
+    private destroyed;
+    private lastPosition;
+    constructor(viewer: Viewer);
+    /** 贴地绘制过程中暂停上拉，避免和绘制抢鼠标。 */
+    setPause(paused: boolean): void;
+    destroy(): void;
+    protected mount(entity: Entity, graphic: HeightGraphic, center: Cartesian3, baseHeight: number, area: number): void;
+    private readonly currentExtrude;
+    private readonly applyExtrude;
+    private readonly metersPerPixel;
+    private readonly createLabel;
+    private readonly canvasPosition;
+    private readonly findVolume;
+    private readonly hover;
+    private readonly onExtrudeDown;
+    private readonly onExtrudeMove;
+    private readonly onExtrudeUp;
+    private readonly stopCameraOnVolume;
+    private readonly restoreCamera;
+}
+export {};

package/src/gauger/rectSolid.d.ts

@@ -0,0 +1,6 @@
+import { Cartesian3, Entity } from 'cesium';
+import { PullColumn } from './pullColumn';
+/** 矩形底面拉成四棱柱。corners 为贴地四个顶点，第 1、3 个点是鼠标点下的对角点。 */
+export declare class RectSolid extends PullColumn {
+    add(entity: Entity, corners: Cartesian3[]): void;
+}

package/src/gauger/util.d.ts

@@ -8,10 +8,17 @@ export declare const getDistanceLabel: (distance: number) => string;
  * @returns
  */
 export declare const getCentroid: (positions: Cartesian3[]) => Cartesian3 | null;
+/** 顶点高程的平均值，单位米。 */
+export declare const averageHeight: (positions: Cartesian3[]) => number;
+/**
+ * 计算平面多边形面积，单位平方米。
+ * 以点集包围球中心建立东北天局部坐标系，再用鞋带公式求面积。
+ */
+export declare const getPlanarArea: (positions: Cartesian3[]) => number;
+export declare const getAreaText: (area: number) => string;
 /**
  * 计算面积
  * @param positions
  * @returns
  */
 export declare const calculatePlanarArea: (positions: Cartesian3[]) => string;
-export declare const getAreaText: (area: number) => string;