m-gis核心库 v0.4.4

@m-tech/gis-core

基于 Cesium 封装的 3D GIS 核心 API 库，提供面向业务的图层、覆盖物、量算、分析、特效、控件等开箱即用的能力，屏蔽 Cesium 原生 API 的底层细节。

本包是 m-gis monorepo 的核心包，位于 packages/core，由 monorepo 的 apps/* 与 packages/biz 共同消费。

✨ 特性

Viewer 封装：继承自 Cesium.Viewer，内置鼠标/场景/视图事件、相机控制、默认底图、定位、罗盘等能力。
图层体系：统一的 Layer 抽象，覆盖 Entity、Primitive、Imagery、Terrain、MVT、Echarts、Html、CZML、WKT 等常用场景。
覆盖物（Overlay）：点、线、面、广告牌、文字、墙、走廊、体、热力图、3DTiles、视频投影、水面等。
量算与标绘（Geomatics）：距离/面积/角度/高度量算、点选拾取、标绘工具。
空间分析（Analysis）：缓冲区、可视域、通视、天际线、洪水淹没、高程、高程趋势、限高、填挖方。
特效（Effects）：根入口当前导出大气雾、云、雾；effects/ 下还包含雨、雪、辉光、雷达扫描、圆形扫描等模块。
材质（Material）：流动线、虚线、尾迹、水面、墙体扫光、城市描边等自定义 MaterialProperty。
控件（Widget）：鹰眼、定位栏、底图选择器、搜索、工具箱、HTML 覆盖物。
漫游（Roaming）：键盘漫游控制。
工具集：坐标转换、聚合、DOM 工具、地址建议、ECEF 转换等。
TypeScript 优先，类型友好；按需导出，便于摇树。

📦 安装

该包目前作为 monorepo 的 workspace 包使用，在仓库根目录执行：

bash

pnpm install

构建产物：

bash

pnpm run core:lib            # 生产构建
pnpm run core:lib:visualizer # 带 bundle 可视化分析

发布到 npm registry：

bash

pnpm run core:publish

依赖	版本	说明
`cesium`	`1.140`	仓库根依赖；核心库源码直接依赖 Cesium
`vue`	`3.x`	文档、示例和构建工具链使用；core 不导出 Vue 组件

🚀 快速开始

import {
  Color,
  EntityLayer,
  ImageryType,
  ImageryProviderType,
  Point,
  Position,
  Viewer,
  ViewerMode,
} from "@m-tech/gis-core";

const viewer = new Viewer("cesiumContainer", {
  imageryProviderType: ImageryProviderType.TMap,
  imageryType: ImageryType.IMG_C,
  viewerMode: ViewerMode["3D"],
  navigationVisible: true,
  locationBar: true,
});

// 添加一个点
const layer = new EntityLayer({ id: "demo-layer" }).addToViewer(viewer);
new Point(new Position(120.5, 28.88, 0))
  .setStyle({ pixelSize: 10, color: Color.fromCssColor("#ff0000") })
  .addToLayer(layer);

🗂️ 目录结构

packages/core/
├── analysis/      # 空间分析：Buffer / ViewShed / SightLine / SkyLine / Flood / Elevation / HeightLimit / CutFillVolume ...
├── assets/        # 内置样式与静态资源（CSS / SCSS / 图标）
├── base/          # 基础类型：Color / Position / Loop
├── effects/       # 特效：Fog / Cloud / Rain / Snow / Bloom / Stormy / RadarScan / CircleScan ...
│   └── shader/    # 自定义 GLSL 着色器
├── event/         # 事件体系：Mouse / Scene / Viewer / Layer / Overlay / Effect / Measure 事件 + EventEnums
├── geomatics/     # 量算与标绘：Measure / Plot / Pick
├── layer/         # 图层：Entity / Primitive / Imagery / Terrain / MVT / Echarts / Html / Czml / WKT
├── liteUtils/     # 轻量工具：CameraUtil / EntityUtil / ImageryUtil / LayerUtil
├── material/      # 自定义 MaterialProperty（流光、尾迹、扫光、水面等）
├── overlay/       # 覆盖物
│   ├── entity/    # Entity 覆盖物：Point / Polyline / Polygon / Label / Marker / Billboard / Wall ...
│   ├── primitive/ # Primitive 覆盖物：Tileset / Mask / Water / Video / ScanCirclePrimitive
│   └── html/      # HTML 覆盖物
├── plugin/        # 插件：CacheDB 等
├── roaming/       # 漫游：KeyboardRoaming
├── store/         # 全局 Store
├── superMap/      # SuperMap 适配
├── utils/         # 通用工具：Util / DomUtil / Clustering / Convertor / Suggestion / Transform / ECEF
├── viewer/        # Viewer（继承 Cesium.Viewer）+ ViewerMode + 默认配置
├── widget/        # 控件：HawkEye / LocationBar / ImageryPicker / Search / Toolbox / HtmlOverlay
├── global.d.ts
├── index.ts       # 唯一对外入口（所有 public API 在此聚合 export）
└── package.json

🧩 核心概念

Viewer

Viewer 继承自 Cesium.Viewer，在构造时注入 MouseEvent、SceneEvent、ViewerEvent、CameraUtil、ImageryUtil、LayerUtil，并通过 on/off 监听 ViewerEventType、SceneEventType、MouseEventType。

关键配置（ViewerOptions，详见 viewer/config.ts）：

imageryProviderType / imageryType：默认底图提供商与类型
viewerMode：ViewerMode["2D"] / ViewerMode["3D"]
navigationVisible：罗盘/比例尺/缩放控件
locationBar：经纬度/海拔状态栏
useMapControl：左键平移、右键旋转的传统 GIS 交互
depthTestAgainstTerrain：开启地形深度测试
defaultView：[lng, lat, height, heading, pitch, roll]

Layer ↔ Overlay

所有可视元素遵循 Overlay → Layer → Viewer 的三层装配关系：

overlay.addToLayer(layer);
layer.addToViewer(viewer);

Layer 提供 show、zIndex、minZoom/maxZoom、addOverlay/removeOverlay 等通用能力。
Overlay 提供 setStyle、show、on/off、remove 等统一接口；通过 OverlayEventType 监听 ADD / REMOVE / CLICK / MOUSE_OVER / MOUSE_OUT 等事件。

事件

统一通过事件枚举管理：ViewerEventType、SceneEventType、MouseEventType、OverlayEventType、PrimitiveOverlayEventType、LayerEventType、EffectEventType、MeasureEventType、DivBoardEventType。

import { MouseEventType } from "@m-tech/gis-core";

viewer.on(MouseEventType.CLICK, (e) => {
  // e.position / e.target
}, viewer);

分析与量算

import { Measure, MeasureType, Position, ViewShed } from "@m-tech/gis-core";

const measure = new Measure(viewer);
measure.start(MeasureType.DISTANCE, false, (result) => {
  // result.distance
});

const viewShed = new ViewShed(viewer, {
  viewPosition: new Position(120.5, 28.88, 100),
  viewPositionEnd: new Position(120.51, 28.89, 100),
});

viewShed.clear();

🛠️ 开发

在 monorepo 根目录使用以下脚本（详见根 README.md）：

命令	说明
`pnpm run core:lib`	构建 `@m-tech/gis-core` 库
`pnpm run core:lib:visualizer`	构建并生成体积分析报告
`pnpm run core:typedoc`	生成 TypeDoc API 文档
`pnpm run core:publish`	发布到 npm
`pnpm run docs:serve`	启动文档站点（含 TypeDoc）
`pnpm run playground:serve`	启动 Playground 示例

约束：

Node >= 18；包管理器固定为 pnpm（仓库 preinstall 中通过 only-allow pnpm 强制约束）。
提交信息走 commitlint + cz-customizable，使用 pnpm cz 生成。
代码风格走 @antfu/eslint-config。

📚 文档与示例

文档站点（VitePress + TypeDoc）：apps/docs
在线演练场：apps/playground
Demo：apps/demo

启动文档：pnpm run docs:serve。

📄 License

packages/core/package.json 当前声明为 ISC。

classes

@m-tech/gis-core ​

✨ 特性 ​

📦 安装 ​

🚀 快速开始 ​

🗂️ 目录结构 ​

🧩 核心概念 ​

Viewer ​

Layer ↔ Overlay ​

事件 ​

分析与量算 ​

🛠️ 开发 ​

📚 文档与示例 ​

📄 License ​

@m-tech/gis-core

✨ 特性

📦 安装

🚀 快速开始

🗂️ 目录结构

🧩 核心概念

Viewer

Layer ↔ Overlay

事件

分析与量算

🛠️ 开发

📚 文档与示例

📄 License