@yituengine/keymap 1.0.0

package/dist/types/primitive/basePrimitive.d.ts

@@ -0,0 +1,42 @@
+import { LayerType } from '../layer';
+import * as Cesium from 'cesium';
+/** 基础图元配置项。 */
+export interface BasePrimitiveOptions {
+    /** 图元唯一标识；未传入时自动生成。 */
+    id?: string;
+    /** 图元名称；未传入时使用图元类型和唯一标识生成。 */
+    name?: string;
+    /** 图元的参考位置或锚点坐标。 */
+    position?: Cesium.Cartesian3;
+}
+/**
+ * Primitive 图元基类。
+ *
+ * 保存 SDK 图元对象的通用标识、归属图层和 Cesium Primitive 引用，并提供显示、隐藏和销毁的基础生命周期方法。
+ */
+export default class BasePrimitive {
+    /** 图元唯一标识。 */
+    id: string;
+    /** 图元名称。 */
+    name: string;
+    /** 图元类型，默认取具体子类名称。 */
+    readonly type: string;
+    /** 图元参考位置；未配置时为 `null`。 */
+    position: Cesium.Cartesian3 | null;
+    /** 图元所属图层。 */
+    layer: LayerType | null;
+    /** 当前 SDK 图元对应的 Cesium Primitive 实例。 */
+    primitive: Cesium.Primitive | null;
+    /**
+     * 创建基础图元实例。
+     *
+     * @param opt - 基础图元配置项。
+     */
+    constructor(opt: BasePrimitiveOptions);
+    /** 将图元重新注册到地图资源管理器中。 */
+    show(): void;
+    /** 从地图资源管理器中解绑图元。 */
+    hide(): void;
+    /** 从场景中移除 Cesium Primitive，并从地图资源管理器中解绑图元。 */
+    destroy(): void;
+}

package/dist/types/primitive/index.d.ts

@@ -0,0 +1,16 @@
+import TubePrimitive from './Tube';
+import WallPrimitive from './Wall';
+import ClassificationPrimitive from './ClassificationPrimitive';
+export { default as TubePrimitive } from './Tube';
+export { default as WallPrimitive } from './Wall';
+export { default as ClassificationPrimitive } from './ClassificationPrimitive';
+export type { BasePrimitiveOptions } from './basePrimitive';
+export type { TubePrimitiveOptions } from './Tube';
+export type { WallPrimitiveOptions } from './Wall';
+/** SDK 内置 Primitive 图元实例类型。 */
+export type PrimitiveType = TubePrimitive | WallPrimitive | ClassificationPrimitive;
+declare const _default: {
+    TubePrimitive: typeof TubePrimitive;
+    WallPrimitive: typeof WallPrimitive;
+};
+export default _default;

package/dist/types/types/general.d.ts

@@ -0,0 +1,94 @@
+import * as Cesium from 'cesium';
+import { LayerType } from '../layer';
+import { PopupGraphicOptions } from '../graphic/popupGraphic';
+import { CustomPopupGraphicOptions } from '../graphic/customPopupGraphic';
+export type GeojsonCoordinate = [number, number, number?];
+export interface GeojsonLine {
+    type: 'Feature';
+    properties: {
+        color: string;
+        directConnected?: boolean;
+    };
+    geometry: {
+        type: 'LineString';
+        coordinates: GeojsonCoordinate[];
+    };
+}
+export interface GeojsonPolygon {
+    type: 'Feature';
+    properties: {
+        color: string;
+    };
+    geometry: {
+        type: 'Polygon';
+        coordinates: GeojsonCoordinate[][];
+    };
+}
+export interface GeojsonPoint {
+    type: 'Feature';
+    properties: {
+        color: string;
+        clampToGround?: boolean;
+    };
+    geometry: {
+        type: 'Point';
+        coordinates: GeojsonCoordinate;
+    };
+}
+export interface GeojsonCircle {
+    type: 'Feature';
+    properties: {
+        color: string;
+        clampToGround?: boolean;
+    };
+    geometry: {
+        type: 'Circle';
+        coordinates: GeojsonCoordinate;
+        radius: number;
+    };
+}
+export type GeojsonFeature = GeojsonLine | GeojsonPolygon | GeojsonPoint | GeojsonCircle;
+export interface Asset {
+    id: string;
+    name: string | null;
+    type: string;
+    layer?: LayerType | null;
+    show?: () => void;
+    hide?: () => void;
+    destroy?: () => void;
+    popup?: PopupGraphicOptions | CustomPopupGraphicOptions | null;
+    showHandler?: () => void;
+    clearHandler?: () => void;
+}
+export declare enum EMaterialName {
+    LightingFlow = "LightingFlowMaterial",
+    PolylineDashed = "PolylineDashedMaterial",
+    TextureFlow = "TextureFlowMaterial",
+    Wave = "WaveMaterial"
+}
+export interface WGS84Pos {
+    lng: number;
+    lat: number;
+    alt: number;
+}
+export type MaterialConstructorWithCache<T = Record<string, unknown>> = typeof Cesium.Material & {
+    _materialCache: {
+        addMaterial: (type: string, material: {
+            fabric: {
+                type: string;
+                uniforms: T;
+                source: string;
+            };
+            translucent?: boolean | ((material: T) => boolean);
+        }) => void;
+    };
+};
+export interface Rotation {
+    heading: number;
+    pitch: number;
+    roll: number;
+}
+export interface DistanceDisplayCondition {
+    min: number;
+    max: number;
+}

package/dist/types/types/index.d.ts

@@ -0,0 +1,2 @@
+export * from './general';
+export * from './public';

package/dist/types/types/public.d.ts

@@ -0,0 +1,11 @@
+import * as Cesium from 'cesium';
+import { Asset, WGS84Pos } from './general';
+export type { Asset, DistanceDisplayCondition, GeojsonCoordinate, Rotation, WGS84Pos } from './general';
+export type MousePickHandlerArgs = {
+    event: Cesium.ScreenSpaceEventHandler.PositionedEvent;
+    coordinate: WGS84Pos | null;
+    pickedObj: any;
+    pickedAsset: Asset | null;
+    lastPickedAsset: Asset | null;
+};
+export type MousePickHandler = (args: MousePickHandlerArgs) => any;

package/dist/types/utils/CoordTransform.d.ts

@@ -0,0 +1,26 @@
+import * as Cesium from 'cesium';
+type CoordinateValue = number | string;
+type WGS84Input = {
+    lng?: number;
+    lon?: number;
+    lat: number;
+    alt?: number;
+};
+type WGS84Output = {
+    lng: number;
+    lat: number;
+    alt: number;
+};
+declare class CoordTransform {
+    static BD09ToGCJ02(lng: CoordinateValue, lat: CoordinateValue): number[];
+    static GCJ02ToBD09(lng: CoordinateValue, lat: CoordinateValue): number[];
+    static WGS84ToGCJ02(lng: CoordinateValue, lat: CoordinateValue): number[];
+    static GCJ02ToWGS84(lng: CoordinateValue, lat: CoordinateValue): number[];
+    static delta(lng: number, lat: number): number[];
+    static transformLng(lng: CoordinateValue, lat: CoordinateValue): number;
+    static transformLat(lng: CoordinateValue, lat: CoordinateValue): number;
+    static out_of_china(lng: CoordinateValue, lat: CoordinateValue): boolean;
+    static transformWGS84ToCartesian(_viewer: Cesium.Viewer, position?: WGS84Input | null, alt?: number): Cesium.Cartesian3;
+    static transformCartesianToWGS84(_viewer: Cesium.Viewer, cartesian: Cesium.Cartesian3): WGS84Output;
+}
+export default CoordTransform;

package/dist/types/utils/controlPoint.d.ts

@@ -0,0 +1,10 @@
+import * as Cesium from 'cesium';
+import { GraphicType } from '../graphic';
+export declare class ControlPoint extends Cesium.Entity {
+    pointIndex: number;
+    parentAsset: GraphicType;
+    position: Cesium.PositionProperty;
+    constructor(pointIndex: number, parentAsset: GraphicType, opt: Partial<Cesium.Entity.ConstructorOptions> & {
+        position: Cesium.PositionProperty | Cesium.Cartesian3;
+    });
+}

package/dist/types/utils/cutFillAnalysis.d.ts

@@ -0,0 +1,38 @@
+import * as Cesium from 'cesium';
+export interface CutFillAnalysisOptions {
+    viewer: Cesium.Viewer;
+    positions: Cesium.Cartesian3[];
+    height: number;
+    precision?: number;
+    dataSource: Cesium.CustomDataSource;
+}
+export interface CutFillResult {
+    allArea: number;
+    cutArea: number;
+    cutVolume: number;
+    fillArea: number;
+    fillVolume: number;
+    noArea: number;
+}
+type HeightPosition = {
+    heightPos: Cesium.Cartesian3;
+    noHeightPos: Cesium.Cartesian3;
+    height: number;
+};
+export default class CutFillAnalysis {
+    viewer: Cesium.Viewer;
+    positions: Cesium.Cartesian3[];
+    height: number;
+    precision: number;
+    dataSource: Cesium.CustomDataSource;
+    maxHeigh: number;
+    geom: Cesium.Geometry | undefined;
+    result: CutFillResult | null;
+    constructor(opt: CutFillAnalysisOptions);
+    createPolygonGeo(points: Cesium.Cartesian3[]): void;
+    VolumeAnalysis(): CutFillResult;
+    computeCentroid4Polygon(positions: Cesium.Cartesian3[]): Cesium.Cartesian3;
+    computeArea4Triangle(pos1: Cesium.Cartesian3, pos2: Cesium.Cartesian3, pos3: Cesium.Cartesian3): number;
+    returnPosition(positions: ArrayLike<number>, index: number): HeightPosition;
+}
+export {};

package/dist/types/utils/graphic.d.ts

@@ -0,0 +1,45 @@
+import * as Cesium from 'cesium';
+/**
+ * 创建模型实体
+ * @param {String} opt.url 模型地址
+ * @param {Number} opt.scale 缩放
+ * @param {Boolean} opt.fixedScale 是否固定大小
+ * @param {Number} opt.clampToGround 贴地选项
+ */
+export declare const createModelGraphic: (opt: Cesium.ModelGraphics.ConstructorOptions) => Cesium.ModelGraphics;
+export declare const createPolylineGraphic: (opt: Cesium.PolylineGraphics.ConstructorOptions) => Cesium.PolylineGraphics;
+export declare const createPolygonGraphic: (opt: Cesium.PolygonGraphics.ConstructorOptions) => Cesium.PolygonGraphics;
+export declare const createPolylineVolumeGraphic: (opt: Cesium.PolylineVolumeGraphics.ConstructorOptions) => Cesium.PolylineVolumeGraphics;
+export declare const createWallGraphic: (opt: Cesium.WallGraphics.ConstructorOptions) => Cesium.WallGraphics;
+export declare const createBillboardGraphic: (opt: Cesium.BillboardGraphics.ConstructorOptions) => Cesium.BillboardGraphics;
+/**
+ * label标签图形
+ * @param {*} opt
+ */
+export declare const createLabelGraphic: (opt: Cesium.LabelGraphics.ConstructorOptions) => Cesium.LabelGraphics;
+/**
+ * box盒子图形
+ * @param {*} opt
+ */
+export declare const createBoxGraphic: (opt: Cesium.BoxGraphics.ConstructorOptions) => Cesium.BoxGraphics;
+/**
+ * point点图形
+ * @param {*} opt
+ * @returns
+ */
+export declare const createPointGraphic: (opt: Cesium.PointGraphics.ConstructorOptions) => Cesium.PointGraphics;
+/**
+ * plane平面图形
+ * @param {*} opt
+ */
+export declare const createPlaneGraphic: (opt: Cesium.PlaneGraphics.ConstructorOptions) => Cesium.PlaneGraphics;
+/**
+ * CylinderGraphic平面图形
+ * @param {*} opt
+ */
+export declare const createCylinderGraphic: (opt: Cesium.CylinderGraphics.ConstructorOptions) => Cesium.CylinderGraphics;
+/**
+ * EllipseGraphic平面图形
+ * @param {*} opt
+ */
+export declare const createEllipseGraphic: (opt: Cesium.EllipseGraphics.ConstructorOptions) => Cesium.EllipseGraphics;

package/dist/types/utils/midPoint.d.ts

@@ -0,0 +1,11 @@
+import { GraphicType } from '../graphic';
+import * as Cesium from 'cesium';
+export declare class MidPoint extends Cesium.Entity {
+    pointIndex: number;
+    parentAsset: GraphicType;
+    position: Cesium.PositionProperty;
+    constructor(pointIndex: number, parentAsset: GraphicType, opt: Partial<Cesium.Entity.ConstructorOptions> & {
+        position: Cesium.PositionProperty | Cesium.Cartesian3;
+    });
+    destroy(): void;
+}

package/dist/types/utils/rightMenu.d.ts

@@ -0,0 +1 @@
+export default function createMenuDiv(): HTMLElement;

package/dist/types/utils/tools.d.ts

@@ -0,0 +1,38 @@
+import { WGS84Pos } from '../types';
+import * as Cesium from 'cesium';
+export declare function generateUniqueId(): string;
+/**
+ * 经纬高转笛卡尔三坐标系
+ * @param {WGS84Pos} pos
+ */
+export declare function wgs84Tocar3(pos: WGS84Pos): Cesium.Cartesian3;
+/**
+ * 笛卡尔三坐标系转经纬高
+ * @param {Cesium.Cartesian3} car3
+ */
+export declare function car3Towgs84(car3: Cesium.Cartesian3): {
+    lng: number;
+    lat: number;
+    alt: number;
+};
+export declare function wgs84ArrToCar3Arr(posArr: WGS84Pos[]): Cesium.Cartesian3[];
+export declare function car3ArrTowgs84Arr(posArr: Cesium.Cartesian3[]): WGS84Pos[];
+export declare function calcDistance(posArr: Cesium.Cartesian3[]): 0 | {
+    distance: string;
+    allDistance: string;
+};
+/**
+ * 传入屏幕坐标，输出对应的Cartesian3坐标
+ * @param {Cesium.Cartesian2} car2
+ * @returns {Cesium.Cartesian3 | undefined} 对应的Cartesian3坐标
+ */
+export declare function pickPosition(car2: Cesium.Cartesian2, viewer: Cesium.Viewer): Cesium.Cartesian3 | undefined;
+/**
+ * 用圆心经纬度和半径生成近似圆的点列表
+ * @param center  圆心经纬度坐标
+ * @param radius  半径（单位：米）
+ * @param angle   角度间隔（默认：5°）
+ * @returns       圆的点列表（包含闭合点）
+ */
+export declare function generateCirclePoints(center: Cesium.Cartesian3, radius: number, angle?: number): Cesium.Cartesian3[];
+export declare function calcPolygonCenter(posArr: Cesium.Cartesian3[]): Cesium.Cartesian3 | undefined;

package/docs/guide/draw-measure.md

@@ -0,0 +1,97 @@
+# 绘制与测量
+
+绘制和测量工具都接收当前 `KeyMap` 实例，并通过 `activate()` 开始交互。当前只允许一个绘制或测量实例处于激活状态，启动新的实例会自动移除旧实例。按 `Escape` 可以取消当前实例。
+
+## 绘制点线面圆
+
+```ts
+import { draw } from '@yituengine/keymap';
+
+const drawPolyline = new draw.DrawPolyline(map);
+
+drawPolyline.setFinishCallback(() => {
+  console.log('线绘制完成');
+});
+
+drawPolyline.activate();
+```
+
+可用绘制类：
+
+| 类             | 说明         |
+| -------------- | ------------ |
+| `DrawPoint`    | 绘制点。     |
+| `DrawPolyline` | 绘制折线。   |
+| `DrawPolygon`  | 绘制多边形。 |
+| `DrawCircle`   | 绘制圆。     |
+
+常用控制：
+
+```ts
+drawPolyline.deactivate();
+drawPolyline.clear();
+drawPolyline.destroy();
+```
+
+## 绘制交互约定
+
+- 左键通常用于添加节点或确认关键点。
+- 鼠标移动用于预览当前图形。
+- 右键通常用于撤销上一步或重置当前状态。
+- 中键或点击完成图标用于结束绘制，具体行为以各绘制类为准。
+- `Escape` 会取消当前激活的绘制或测量实例。
+
+## 测量
+
+```ts
+import { measure } from '@yituengine/keymap';
+
+const distance = new measure.MeasureDistance(map);
+
+distance.setFinishCallback((result) => {
+  console.log('距离测量结果', result);
+});
+
+distance.activate();
+```
+
+可用测量类：
+
+| 类                | 说明         |
+| ----------------- | ------------ |
+| `MeasureDistance` | 距离测量。   |
+| `MeasureArea`     | 面积测量。   |
+| `MeasureHeight`   | 高度测量。   |
+| `MeasureCutFill`  | 挖填方测量。 |
+
+常用控制：
+
+```ts
+distance.measureEnd();
+distance.clear();
+distance.destroy();
+```
+
+## 和业务 UI 配合
+
+建议业务按钮只负责创建和激活工具，工具完成或取消后再更新按钮状态：
+
+```ts
+let activeTool: { destroy: () => void } | null = null;
+
+function startDistanceMeasure() {
+  activeTool?.destroy();
+
+  const tool = new measure.MeasureDistance(map);
+  activeTool = tool;
+
+  tool.setFinishCallback((result) => {
+    console.log(result);
+    activeTool = null;
+  });
+
+  tool.activate();
+}
+```
+
+如果同时使用弹窗，可以把 `disablePopup` 与业务的绘制/测量状态绑定，避免绘制过程中误弹出业务弹窗。

package/docs/guide/graphic.md

@@ -0,0 +1,136 @@
+# 图层与图形
+
+## 图层
+
+`GraphicLayer` 是业务图形的常用容器。图形加入图层后，会同时登记到 `KeyMap.Assets`，便于后续通过 id 查找或删除。
+
+```ts
+import { layer } from '@yituengine/keymap';
+
+const graphicLayer = new layer.GraphicLayer({ name: '标绘图层' });
+map.addLayer(graphicLayer);
+```
+
+常用操作：
+
+```ts
+graphicLayer.show();
+graphicLayer.hide();
+graphicLayer.removeChild('asset-id');
+graphicLayer.removeAll();
+map.removeLayer(graphicLayer);
+```
+
+## HeatmapLayer
+
+`HeatmapLayer` 用于展示二维热力图。它会把经纬度权重点绘制到 canvas，再作为 Cesium rectangle 图片材质贴到固定地理范围上，适合校园人流密度、区域热度等平面覆盖场景。
+
+```ts
+import * as Cesium from 'cesium';
+import { layer } from '@yituengine/keymap';
+
+const heatmapLayer = new layer.HeatmapLayer({
+  name: '校园人流密度',
+  rectangle: Cesium.Rectangle.fromDegrees(113.26, 23.12, 113.29, 23.15),
+  min: 0,
+  max: 100,
+  radius: 36,
+  points: [
+    { lng: 113.2644, lat: 23.1291, value: 80 },
+    { lng: 113.276, lat: 23.136, value: 45 },
+  ],
+});
+
+map.addLayer(heatmapLayer);
+```
+
+实时更新数据时优先保持 `rectangle`、`min`、`max` 固定，避免热力颜色语义随数据批次漂移。
+
+```ts
+heatmapLayer.setData([
+  { lng: 113.2644, lat: 23.1291, value: 60 },
+  { lng: 113.271, lat: 23.134, value: 95 },
+]);
+
+heatmapLayer.hide();
+heatmapLayer.show();
+map.removeLayer(heatmapLayer);
+```
+
+## BillboardGraphic
+
+```ts
+import * as Cesium from 'cesium';
+import { graphic } from '@yituengine/keymap';
+
+const billboard = new graphic.BillboardGraphic({
+  id: 'project-point',
+  name: '项目点位',
+  position: Cesium.Cartesian3.fromDegrees(113.2644, 23.1291, 20),
+  image: '/icons/location.svg',
+  width: 32,
+  height: 32,
+  onChanged(position) {
+    console.log('点位移动后的位置', position);
+  },
+});
+
+graphicLayer.addGraphic(billboard);
+```
+
+进入编辑模式后，点位会显示一个控制点，拖拽结束时触发 `onChanged`。
+
+```ts
+billboard.showHandler();
+billboard.clearHandler();
+```
+
+## PolylineGraphic
+
+```ts
+const polyline = new graphic.PolylineGraphic({
+  name: '线路',
+  positions: [Cesium.Cartesian3.fromDegrees(113.26, 23.12, 0), Cesium.Cartesian3.fromDegrees(113.27, 23.13, 0), Cesium.Cartesian3.fromDegrees(113.28, 23.14, 0)],
+  width: 4,
+  material: Cesium.Color.CYAN,
+  clampToGround: true,
+  onChanged(positions) {
+    console.log('线更新后的节点', positions);
+  },
+});
+
+graphicLayer.addGraphic(polyline);
+polyline.showHandler();
+```
+
+折线编辑模式下会显示控制点和中点。拖拽控制点会移动节点，拖拽中点会转换为新的控制点。右键控制点可以通过默认菜单删除节点，删除后至少保留 2 个节点。
+
+## PolygonGraphic
+
+```ts
+const polygon = new graphic.PolygonGraphic({
+  name: '范围面',
+  positions: [Cesium.Cartesian3.fromDegrees(113.26, 23.12, 0), Cesium.Cartesian3.fromDegrees(113.29, 23.12, 0), Cesium.Cartesian3.fromDegrees(113.29, 23.15, 0), Cesium.Cartesian3.fromDegrees(113.26, 23.15, 0)],
+  material: Cesium.Color.BLUE.withAlpha(0.35),
+  outlineMaterial: Cesium.Color.WHITE,
+  outlineWidth: 3,
+  onChanged(positions) {
+    console.log('面更新后的节点', positions);
+  },
+});
+
+graphicLayer.addGraphic(polygon);
+polygon.showHandler();
+```
+
+多边形支持拖拽控制点、中点补点、右键删除控制点和悬停白色描边。`outlineMaterial` 优先级高于 `outlineColor`，适合使用自定义线材质。
+
+## 清理图形
+
+```ts
+polyline.clearHandler();
+polyline.destroy();
+graphicLayer.removeAll();
+```
+
+业务侧只需要销毁图形或图层，不需要直接操作 Cesium `EntityCollection`。

package/docs/guide/index.md

@@ -0,0 +1,29 @@
+# 指南首页
+
+这组文档面向业务项目接入易图引擎，重点说明常见组合用法。完整 API 以 `npm run doc` 生成的 TypeDoc 文档为准。
+
+## 推荐阅读顺序
+
+1. [快速开始](quick-start.md)
+2. [图层与图形](graphic.md)
+3. [右键菜单](menu.md)
+4. [绘制与测量](draw-measure.md)
+
+## 基础约定
+
+- 地图容器必须是页面中已存在的 `HTMLDivElement`，并且建议由业务页面控制宽高。
+- SDK 基于 `cesium@1.106`，业务项目需要处理 Cesium 静态资源、token、地形和影像资源部署。
+- 经纬度示例使用 `[lng, lat, alt?]`，与 Cesium 的 `Cartesian3.fromDegrees` 参数顺序一致。
+- 图形资产通常先添加到 `GraphicLayer`，再由 `KeyMap.Assets` 统一索引。
+- 进入编辑模式使用 `showHandler()`，退出编辑模式使用 `clearHandler()`。
+
+## 默认交互
+
+`KeyMap` 初始化时会自动注册一组默认交互，包括：
+
+- 鼠标悬停图形高亮。
+- 图形点击弹窗和自定义弹窗。
+- 控制点和中点拖拽编辑。
+- 控制点右键删除。
+- 全局右键菜单。
+- 当前绘制或测量实例的互斥和 `Escape` 取消。