SedcEarth-SDK

Build a Cesium enhanced SDK tailored for front-end developers from scratch, which is constructed based on Cesium 1.135, TypeScript, Rollup, Vite, and Trae, and is mainly used for the daily front-end development of SEDC.

🚀 项目启动 (Project Startup)

1. 安装依赖

   npm install
   # 或者
   pnpm install

2. 配置环境变量

   copy .env.example .env.local

   按需填写以下配置：

   • VITE_CESIUM_TOKEN
   • VITE_TDT_KEY
   • VITE_BING_KEY

3. 启动演示项目 (Playground)

   npm run dev

   访问: http://localhost:5173 (具体端口视终端输出而定)

   也可以在 Playground 右上角通过"服务配置"按钮直接录入并缓存密钥。

4. 构建 SDK

   npm run build

🧱 框架治理基线

• SDK 统一入口：src/se3dx-sdk/index.ts
• 模块总台账：src/se3dx-sdk/moduleRegistry.ts
• 协作规范：src/se3dx-sdk/开发协作手册.md
• 架构设计：ARCHITECTURE.md

新增或修改模块时，至少同步检查以下事项：

npm run check:se3dx-api-tiers
npm run check:se3dx-public-exports
npm run check:se3dx-architecture-guards
npm run check:se3dx-module-registry
npm run check:se3dx-manager-lifecycle

说明：

• moduleRegistry.ts 用于统一登记运行时 manager、独立核心类、UI 组件、Legacy 兼容入口
• check:se3dx-module-registry 会校验 Viewer 注册关系、公共导出、源码路径和组件挂载关系
• check:se3dx-manager-lifecycle 会校验运行时模块的最小生命周期契约，并提示缺少 metadata / summary / state 的模块
• viewer.getRuntimeLifecycleAudit() 可在运行时查看哪些 manager 已完全标准化、哪些仍在使用兜底能力
• 当前已优先收口第一批核心模块：layer / tileset / graphic / control
• 当前已继续收口第二批核心模块：effect / analysis / editor / overview
• 当前已继续收口第三批扩展模块：field / advanced / geology / building
• 当前已补齐收尾模块：event / measure / draw
• 当前 17 个运行时模块已全部通过显式生命周期契约检查
• 后续新增功能建议按 "types → core → moduleRegistry → ui → docs" 的顺序推进

📌 能力现状说明

• README 下方表格以产品路线图为主，不等同于全部已交付能力。
• 当前已落地与部分落地能力、主要缺口和整改项，见 SDK_能力现状与整改清单.md。
• 若用于对外评审或国产化认证材料，建议优先引用整改清单中的"已实现 / 部分实现 / 待规划"口径。

🗺️ se3dx-sdk 功能封装清单

| 主模块 | 子模块 | 核心功能点（封装建议） | | :--- | :--- | :--- | | 1. 快速开始 | 场景创建 | 提供简洁的API创建三维场景（支持配置文件/json/原生Cesium方式） | | | UI控件样板 | 封装常用UI控件（如缩放、底图切换）的快速引入与布局示例 | | 2. 三维场景 | 场景配置 | 支持通过参数配置scene、terrain、basemaps、layers、control、effect、thing等 | | | 场景控制 | 封装图层叠加/管理、地图事件、坐标系（chinaCRS）、多语言、场景销毁等基础控制 | | | 背景控制 | 封装场景出图、自定义天空盒/背景图、DIV遮罩、反选遮罩等 (✅ 已实现) | | | 相机视角 | 封装视角书签、视点飞行、环绕旋转、第一人称漫游、键盘漫游、视角限制、时序任务等 (✅ 已实现) | | | 鼠标交互 | 封装坐标拾取、鼠标习惯切换、街景操作习惯等 (✅ 已实现) | | | 视图对比 | 封装二三维切换、双屏对比、与Leaflet/OpenLayers联动等 (✅ 已实现) | | 3. 三维地形 | 地形图层 | 封装标准地形服务加载（如天地图地形） | | | 地形分析 | 封装地形开挖/压平/抬升、等高线、坡度坡向、淹没分析、地下模式等 (✅ 已实现) | | 4. 瓦片底图 | 在线地图 | 统一封装国内外主流图商（天地图、高德、谷歌、Mapbox等）的加载接口 (✅ 已实现)坐标系支持：明确支持EPSG:3857, 4326, 4490，并在底层处理坐标转换 (✅ 已实现) | | | 标准服务 | 封装TMS、WMS、WMTS、ArcGIS服务、谷歌地球企业版等标准瓦片服务 (✅ 已实现) | | | 本地数据 | 封装单张/局部图片、TIF文件、极坐标图等本地影像加载 (✅ 已实现) | | | 图层控制 | 封装瓦片透明度/滤镜/事件、动态时序图、瓦片贴模型等高级控制 (✅ 已实现) | | 5. 矢量图层 | 基础图层 | 封装Graphic、业务数据、DIV、glTF小模型、3DTiles、I3S、S3M等数据图层 | | | GeoJson图层 | 封装GeoJson加载及光晕线、建筑物立体面、渐变行政区、立体户型图等扩展样式 | | | 本地文件 | 封装Excel/CSV、SHP、KML/KMZ、WKT等常见矢量文件格式的加载器 | | | WFS服务 | 封装与GeoServer、ArcGIS Server等标准WFS服务的交互 | | | 服务查询 | 封装针对ArcGIS/GeoServer/iServer的矢量要素查询、POI查询、路径规划等 | | 6. 3DTiles模型 | 模型类型 | 支持倾斜摄影、BIM、人工建模、点云、城市白模、3DGS等主流3DTiles类型 | | | 单体化 | 封装模型内单体化、矢量叠加单体化、分层分户单体化及其编辑功能 | | | 样式效果 | 封装建筑物样式切换、BIM分层/进度展示、自定义着色器(customShader)等 | | | 模型分析 | 封装模型剖切、裁剪、压平、淹没模拟、限高分析、热力图等分析功能 | | 7. 矢量对象 | 统一机制 | 建立统一的数据格式（坐标/样式/属性）、绘制编辑、对象聚合机制 | | | 核心对象 | 封装点（含Primitive批量）、线、面、体（盒/球/圆锥）、模型（glTF）、文本、图标等 | | | 高级对象 | 封装漫游路线、军标、动态水域、粒子特效、视频投射、雷达扫描、卫星推演等 (✅ 已实现) | | | 专题应用 | 提供台风、智慧社区、数字城市、红蓝对抗等典型场景的组合示例 | | | 空间计算 (新增) | 封装点/线/面的生成、最近点分析、求交、切割、等值面、网格生成等计算工具 | | 8. 控件 | 信息窗 | 封装Popup、Tooltip、右键菜单等 | | | 按钮/面板 | 封装视角复位、底图切换、全屏、比例尺、鹰眼图、导航球、时钟轴、时间线等 | | | 控件管理 | 提供统一API来控制所有UI控件的显示/隐藏 | | 9. 环境特效 | 天气特效 | 封装雨、雪、雾、云、闪电等天气效果 | | | 后期特效 | 封装泛光、颜色校正、景深、夜视、黑白等屏幕后期处理效果 | | 10. 分析工具 | 基础量算 | 封装距离、面积、高度、角度的实时测量工具 | | | 高级分析 | 封装剖面、方量、通视、可视域、缓冲区、最短路径（基于地形）等分析 | | 11. 其他图层 | 热力图 | 封装贴地/高度/动态/立体曲面热力图及色斑图（kriging插值） | | | 气象数据 | 封装风向图、经纬向剖面、雷达图、等值体、格点动画等气象专用图层 | | | 矢量瓦片 | 封装PBF、ArcGIS矢量瓦片，及用矢量瓦片方式加载GeoJson/SHP | | | 态势图 | 封装动态点/线/面、蜂巢图、迁徙图等态势可视化图层 | | | 特殊星球 | 封装月球、火星等离线或在线数据的快速加载 |

💡 封装实现的注意事项与建议

1. 命名规范与一致性：

   • 核心类：建议遵循 Se3d[模块][功能] 的命名方式，如 Se3dMap、Se3dTerrainAnalysis。
   • API设计：保持与Cesium原生的相似性以降低学习成本，但通过封装简化复杂性。例如，viewer.scene.open('url') 可封装为 se3dMap.openBasemap('tdt')。
   • 配置项：所有模块应支持统一的"参数对象"方式进行初始化，并与Mars3D的 options 风格看齐。

2. 接口分层设计：

   • 底层（Core）：直接封装Cesium原生API，提供基础的类和管理器（如LayerManager, ControlManager）。
   • 上层（Widgets / Plugins）：基于底层构建面向业务的组件。例如，DrawPlugin 调用 GraphicLayer 实现绘制功能。

3. 性能优化内置：

   • 批量渲染：对于大量点、线、面（如截图中的"大量盒子(合并渲染Primitive)"），SDK内部应自动判断并使用Primitive API进行合并渲染，对用户透明。
   • 数据懒加载：对于矢量瓦片、3DTiles等，遵循其原有的LOD机制，并提供简洁的配置接口。
   • 内存管理：封装destroy方法，确保图层、对象销毁时彻底释放Cesium资源，避免内存泄漏。

4. 扩展性设计：

   • 插件机制：允许用户通过SDK注册自定义的图层类型、分析算法或UI控件。例如，Se3dPlotting.registerSymbol('myArrow', myArrowFunction)。
   • 事件机制：建立统一的事件总线（如se3dMap.on('layer-added', callback)），方便用户监听SDK内部状态变化。

5. 文档与示例：

   • 代码即文档：使用JSDoc等工具，为每个公开的API生成详细注释，并能在IDE中智能提示。
   • 示例驱动：为清单中的每一个核心功能点，提供一个最小可运行的HTML示例，并直接放在SDK的 examples 目录下，方便验证和测试。

📄 License

Apache License 2.0