UT3D

基于 Cesium 的低空（无人机/UAV）应用场景地图 JavaScript 库。

✨ 特性

• 🌍 基于 Cesium 的 3D 地球渲染引擎
• 🗺️ 内置天地图、高德、ArcGIS 等主流底图服务（HTTPS）
• 🧩 三层架构（engine → ui → base），按需引用
• 🎛️ 开箱即用的地图控件：工具栏、指北针、缩放、底图切换
• ✈️ 低空/无人机专用模块：航线编辑、轨迹回放
• 📐 纯 JavaScript + JSDoc 类型注解（自动生成 .d.ts 类型声明）
• 🎨 CSS 自定义属性（Design Tokens）驱动的可定制主题
• 📖 TypeDoc 自动生成 API 文档并集成到 VitePress

📁 项目结构

ut3d/
├── apps/
│   ├── docs/              # VitePress 文档网站
│   ├── sandcastle/        # 功能示例沙盒（模仿 Cesium Sandcastle）
│   └── vanilla-template/  # 纯 JS 最小示例模板
├── packages/
│   ├── engine/            # @ut3d/engine — 核心引擎
│   ├── ui/                # @ut3d/ui    — UI 组件库
│   └── base/              # @ut3d/base  — 集成库
└── docs/                  # 项目规划文档

🚀 快速开始

安装依赖

pnpm install

开发

# 启动所有包的开发模式（watch-build）
pnpm dev

# 启动文档网站（含 API 文档生成）
pnpm docs:dev

# 启动沙盒网站
pnpm dev:sandcastle

构建

# 构建所有包（按依赖顺序：engine → ui → base）
pnpm build:packages

# 构建所有应用
pnpm build:apps

# 生成 API 文档并构建文档网站
pnpm docs:build

生成 API 文档

# 仅生成 API 文档（TypeDoc → Markdown → apps/docs/api/）
pnpm docs:api

📦 包说明

@ut3d/engine

核心引擎包。重新导出 Cesium，并封装与 UI 无关的基础 API：

导出	说明
UT3DViewer	轻量 Cesium Viewer 封装，关闭默认 UI
CameraManager	相机飞行、缩放、默认位置管理
LayerManager	影像图层增删改查 + 底图切换 + 变化监听
lonLatToCartesian3	经纬度 → Cartesian3
cartesian3ToLonLat	Cartesian3 → 经纬度
calculateDistance	两点直线距离
calculateSurfaceDistance	两点大地线距离
calculatePolygonArea	多边形面积
calculateBearing	方位角

@ut3d/ui

框架无关的 DOM UI 组件库：

组件	说明
Popup	气泡弹窗（支持标题、关闭按钮、定位）
Tooltip	悬浮提示框
Panel	可折叠面板
ExpandPanel	可展开面板（hover/click 触发模式）

@ut3d/base

集成库，整合 engine + ui，提供完整的地图应用 API：

导出	说明
UT3DMap	地图主类，一行代码创建完整地图
Toolbar	工具栏容器（工具按钮 + 自定义控件）
CompassControl	指北针控件
ZoomControl	缩放 + 复位控件
BaseLayerSwitcher	底图切换面板（分组 + 缩略图）
RouteEditor	航线编辑器（航点增删、距离/方位自动计算）
TrajectoryPlayer	轨迹回放器（基于 Cesium Clock 系统）

📝 使用示例

import { UT3DMap } from '@ut3d/base';

// 创建地图（自动初始化工具栏、底图切换器等）
const map = new UT3DMap('cesiumContainer', {
  tiandituKey: 'your-tianditu-key',
  toolbar: { position: 'bottom-right' },
  baseLayerSwitcher: true,
});

// 通过 cameraManager 飞行到北京
map.cameraManager.flyTo(
  Cesium.Cartesian3.fromDegrees(116.39, 39.90, 15000),
  { duration: 3, pitch: Cesium.Math.toRadians(-30) }
);

// 切换底图
map.switchBaseLayer('gaode-imagery');

// 销毁
map.destroy();

🎨 CSS 自定义属性

所有 UI 组件通过 CSS 自定义属性（Design Tokens）控制外观，支持主题定制：

/* 覆盖主题变量 */
:root {
  --ut3d-color-bg: #1a1a2e;
  --ut3d-color-text: #eee;
  --ut3d-color-primary: #4fc3f7;
  --ut3d-shadow-md: 0 2px 8px rgba(0, 0, 0, 0.3);
}

完整变量列表见 packages/ui/src/styles/variables.css。

🛠️ 技术栈

技术	说明
Cesium ^1.137.0	3D 地球渲染引擎
JavaScript + JSDoc	纯 JS 源码 + JSDoc 类型注解（tsc 生成 .d.ts）
Vite (rolldown-vite)	构建工具（ES + CJS 双格式输出）
VitePress	文档框架
TypeDoc	JSDoc → Markdown API 文档生成
Vue 3	Sandcastle 应用 UI
pnpm	Monorepo 包管理器
oxlint + oxfmt	代码规范检查与格式化

📄 License

Private (UNLICENSED, internal use only)