m-gis核心库 v0.4.4

---

@m-tech/gis-core

基于 Cesium 的三维 GIS 核心库（二次封装）。统一封装 Viewer、图层、覆盖物、量测/标绘、空间分析、特效材质与常用控件，面向业务系统提供一致的 API 与坐标模型。

项	说明
包名	@m-tech/gis-core
当前版本	0.4.5
底层引擎	Cesium 1.140（由 monorepo 根依赖提供）
模块格式	ESM (ty-gis.es.js) + UMD (ty-gis.umd.js)
类型	dist/types/index.d.ts
样式	dist/style.css

---

设计概览

Viewer (extends Cesium.Viewer)
  ├── Layer 缓存 / Effect 缓存 / Widget 缓存
  ├── MouseEvent / ViewerEvent / SceneEvent
  └── Loop (相机/层级 tick)

Overlay ──addToLayer──► Layer ──addToViewer──► Viewer
Effect  ──addToViewer──────────────────────► Viewer
Widget  ──addToViewer──────────────────────► Viewer
Analysis / Measure / Plot  ──构造时注入──► Viewer

核心约定：

1. 坐标统一用 Position：lng / lat / alt / heading / pitch / roll（角度对外为度，内部 heading/pitch/roll 以弧度存储）。
2. 代理对象 _delegate：封装类内部持有 Cesium 原生对象（Entity / Primitive / DataSource / PostProcessStage 等），对外通过本库 API 操作。
3. 链式调用：new X(...).addToLayer(layer) / layer.addToViewer(viewer) / setStyle(...) 等尽量返回 this。
4. 事件模型：封装 on / off / fire，基于 Cesium.Event；鼠标交互见 MouseEventType。

---

目录结构

packages/core/
├── index.ts              # 统一导出入口
├── viewer/               # Viewer 及默认配置
├── base/                 # Position / Color / Loop
├── overlay/              # 覆盖物（Entity / Primitive / HTML）
├── layer/                # 图层（Entity、影像、地形、MVT、WKT、CZML…）
├── event/                # 事件基类与枚举
├── material/             # 动态材质（Property + GLSL，多为 JS）
├── effects/              # 后处理特效 + shader/
├── analysis/             # 空间分析（通视、可视域、淹没、填挖方…）
├── geomatics/            # 量测 Measure / 标绘 Plot / 拾取 Pick
├── widget/               # UI 控件（搜索、鹰眼、工具箱…）
├── liteUtils/            # 相机/图层/影像/实体快捷工具（单例）
├── utils/                # 坐标转换、DOM、聚类、Suggestion…
├── roaming/              # 键盘漫游
├── plugin/               # CacheDB 等插件
├── store/                # 全局 Viewer 引用（调试）
├── assets/               # 样式、图片、heatmap 等
├── superMap/             # SuperMap3D 相关静态资源
├── dist/                 # 构建产物
└── docs/                 # TypeDoc 输出

---

快速开始

在 monorepo 内开发

# 仓库根目录
pnpm install
pnpm run core:lib          # 构建本包
pnpm run demo:serve        # 功能演示（apps/demo）
pnpm run docs:serve        # 文档站
pnpm run playground:serve  # 在线演练场

作为依赖安装（私有源）

npm install @m-tech/gis-core

import {
  Viewer,
  EntityLayer,
  Point,
  Position,
  MouseEventType,
} from "@m-tech/gis-core";
import "@m-tech/gis-core/dist/style.css";

const viewer = new Viewer(document.getElementById("cesiumContainer"), {
  defaultView: [118.78, 31.91, 2000, 0, -45, 0],
  navigationVisible: true,
  locationBar: true,
});

const layer = new EntityLayer({ id: "demo" }).addToViewer(viewer);
const point = new Point(new Position(118.786, 31.913, 10)).addToLayer(layer);
point.setStyle({ pixelSize: 16 });
point.on(MouseEventType.CLICK, (evt) => console.log(evt));

Viewer 常用选项

见 viewer/config.ts 中 OPT / DEF_OPTS：

选项	默认	说明
imageryProviderType	天地图	底图服务类型
imageryType	影像注记	底图样式
viewerMode	3D	2D / 3D
defaultView	全国视角	[lng, lat, alt, heading, pitch, roll]
locationBar	false	经纬度状态栏
navigationVisible	false	罗盘/比例尺/缩放
useMapControl	false	传统地图交互（左键平移、右键旋转）
debug	开发环境默认开	挂载 globalThis.viewer

Cesium 原生控件默认大多关闭（animation、timeline、infoBox 等），按需在 options 中打开。

---

模块能力一览

Overlay（覆盖物）

分类	类
Entity	Point Label Billboard Marker Polyline Polygon Rectangle Ellipse Wall Box Corridor Cylinder Ellipsoid Plane PolylineVolume Heatmap
Primitive	Tileset Water Video Mask ScanCirclePrimitive
HTML	DivBoard

Layer（图层）

EntityLayer PrimitiveLayer HtmlLayer ImageryLayer TerrainLayer MvtLayer WKTLayer CzmlLayer EchartsLayer

Analysis（分析）

SightLine ViewShed SkyLine Flood Buffer Elevation ElevationTrend CutFillVolume HeightLimit

Geomatics

• Measure：距离 / 面积 / 高度
• Plot：点线面圆矩形等标绘
• Pick：场景拾取

Effects / Material

• 后处理：雾、云、雨雪、扫描等（部分仅在 effects/ 内导出，根入口可能未全部 re-export）
• 动态材质：Material 命名空间（流动线、尾迹、波纹、墙体等）

Widget

LocationBar Search Toolbox HawkEye ImageryPicker HtmlOverlay Tooltip

工具

Position Color Transform Convertor Util DomUtil Clustering CameraUtil LayerUtil ImageryUtil EntityUtil Suggestion

---

构建与发布

# 类型检查 + Vite 库构建（产出 dist/）
pnpm run lib                 # 在 packages/core 下
# 或 monorepo 根：
pnpm run core:lib

# TypeDoc
pnpm run typedoc:build

# 发包（私有 registry）
pnpm run pub

构建会：

1. 打包 index.ts → dist/ty-gis.es.js / ty-gis.umd.js
2. 生成类型声明 → dist/types/
3. 拷贝 Cesium 静态资源 → dist/cesiumStatic/
4. 拷贝 SuperMap 资源 → dist/superMap/

---

相关包与应用

路径	说明
packages/biz	业务组件（地图/标绘/轨迹等 Vue 封装）
packages/vue	Vue 组件版占位
apps/demo	核心能力演示
apps/docs	VitePress 文档
apps/playground	在线代码演练
apps/example	业务最佳实践示例
apps/platform	平台工具

AI 协作说明见同目录 AGENTS.md；待办与缺口见 TODO.md。

---

许可

ISC（见 package.json）