@metagl/smartearth-base 0.0.0-stage → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md ADDED
@@ -0,0 +1,35 @@
1
+ # Changelog
2
+
3
+ ## 0.2.0
4
+
5
+ 第 2 期:六种业务图层。
6
+
7
+ - **包名改为 `@metagl/smartearth-base`,发 npm 公共源**(npmjs.org,public,许可证 Apache-2.0,与 sdk-render 一致)。原计划的 `@agent-earth/smartearth-base`(project 633 私服)没有发过;引用请改成新包名:`@metagl/smartearth-base`、`@metagl/smartearth-base/vite`、`@metagl/smartearth-base/vue`。
8
+
9
+ - 新增内置图层,全部经 `layers.add({ kind, ... })`,`remove` / `destroy` 时清干净:
10
+ - `geojson`:面、线、点,按字段着色,可选文字标注,数据可给对象或 URL。
11
+ - `tileset3d`:`Cesium3DTileset.fromUrl` 加载(不用 `loadCityModel`),可带 `pbr` 单独材质(经 `earth.pbr.setTilesetMaterial`,需要 sdk-render 4.x);3D Tiles 要素可拾取。
12
+ - `route`:航线回放(坐标数组 / GeoJSON LineString / KML / URL),播放、暂停、跳转、倍速、进度事件、相机跟随;不拨场景时钟。
13
+ - `popup`:点到要素时跟随位置的 HTML 浮层,可限定图层;导出 `escapeHtml()`。
14
+ - `annotation`:点选放置标注(名称/等级/说明)、增删、`exportJSON` / `importJSON`,不做持久化。
15
+ - `riverWater`:只用 sdk-render 公开接口加载水系动态水面并可挖坑。sdk-render ≥ 4.0.2 直接传河道线,河道线与湖、库都按「原地形 + 偏移」顺坡下挖;更早的版本自动退回绕过(线先转成面,只挖湖、库,避开 4.0.1 线河道停止整个场景渲染、挖坑压成平台的缺陷)。挖坑示意面默认关(`showDigViz`)。坐标没有 Z 时必须给 `height`,不让水面悄悄落在 0 米。
16
+ - `layers.get(id)` 取图层操作接口;图层上下文新增 `render`、`pbr`、`onClick`、`registerPickResolver`,自定义图层也能用。
17
+ - 新错误码 `LAYER_LOAD_FAILED`、`PBR_UNSUPPORTED`。
18
+ - 示例页:每种图层一个演示开关,样例数据在 `examples/vue/public/samples`。
19
+ - 适配 sdk-render 4.x:`earth.pbr` 透传模型材质接口(按 tileset 设材质、全局 PBR、导入导出 'material' 配置),类型 `EarthPbr` / `PbrMaterialParams` / `PbrConfig`;初始画质在 4.x 下直接传给 `createWithDefaults`。
20
+ - PBR 参数类型与 `@metagl/sdk-render` 4.0.0 对齐:含 `iblNightFactor`(全局默认 0.25)、`proceduralWindows`(默认关);编译期单测核对与 SDK 真实类型一致。
21
+ - `makeExtensible` 处理打包器产出的 getter 导出(发布包被 Vite 预构建后 createEarth 不再报 Invalid property descriptor);图层上下文新增 `sdkRenderVersion`。
22
+ - 开发依赖与示例页钉 `@metagl/sdk-render` 4.0.2(河道水面 4 项修复);peer 为 `^3.0.0 || ^4.0.1`(3.0 继续支持)。4.0.0 把 cesium 列成普通依赖、还带 webpack / webpack-cli 运行时依赖,4.0.1 已改回 cesium peer,渲染代码与 4.0.0 相同,所以跳过 4.0.0;4.0.1 下河道水面自动走绕过。cesium 仍由本包自己声明 peer(`>=1.132.0 <1.137.0`)。
23
+ - 错误信息打码只处理 8 位以上的令牌,避免误伤正常文字。
24
+
25
+ ## 0.1.0(未发布)
26
+
27
+ 首个版本,替代已废弃的 `@agent-earth/smart-earth`。
28
+
29
+ - 核心 `createEarth(container, options)`:星图影像 + 注记 + 地形,`Render.createWithDefaults` 环境基线;挂 `window.Cesium`(可写副本)、RenderState lineWidth 兼容补丁。
30
+ - 统一错误 `SmartEarthError`(`AUTH_MISSING_SDK` / `AUTH_MISSING_MAP` / `AUTH_FAILED` / `CESIUM_VERSION` / `ASSETS_MISSING` / `RENDER_INIT_FAILED` 等),失败即抛、不降级为普通 Cesium。
31
+ - 画质 `setQuality`:优先用 sdk-render 自带接口;3.0 下提供 high / low 两档,medium 抛 `QUALITY_UNSUPPORTED`。
32
+ - `Earth.supportedQualities` 与 `getSupportedQualities()`:查当前 sdk-render 能切哪些画质。
33
+ - 图层注册表 `layers.register/add/remove/setVisible/list` 与内置 `points`(按字段分色);`on('pick')`、`flyTo`。
34
+ - `./vite`:`smartEarthAssets()` 拷 Cesium 与 sdk-render 运行时资源、设置 `CESIUM_BASE_URL`。
35
+ - `./vue`:`<SmartEarthView :options @ready @error>`。
package/README.md CHANGED
@@ -1,3 +1,196 @@
1
- # Temporary Holding Version
2
-
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
1
+ 替代已废弃的 @agent-earth/smart-earth。
2
+
3
+ # @metagl/smartearth-base
4
+
5
+ 集群业务地图底层包:基于 [`@metagl/sdk-render`](https://www.npmjs.com/package/@metagl/sdk-render) 的 SmartEarth 三维地球,一次调用得到「星图影像 + 注记 + 地形 + SmartEarth 环境渲染」的地球,失败一律抛带错误码的中文错误,**不会静默退化成普通 Cesium**。
6
+
7
+ - `@metagl/smartearth-base`:核心,框架无关(`createEarth`)
8
+ - `@metagl/smartearth-base/vite`:Vite 插件 `smartEarthAssets()`,拷运行时资源、配好 Cesium
9
+ - `@metagl/smartearth-base/vue`:Vue 3 组件 `<SmartEarthView>`
10
+
11
+ ## 安装
12
+
13
+ ```bash
14
+ npm i @metagl/smartearth-base @metagl/sdk-render@4.0.2 cesium@1.136.0
15
+ # 或 pnpm add @metagl/smartearth-base @metagl/sdk-render@4.0.2 cesium@1.136.0
16
+ ```
17
+
18
+ 本包与 `@metagl/sdk-render` 都发在 npm 公共源(npmjs.org),不需要额外配 `.npmrc`。如果用户级 `.npmrc` 把 `@metagl` 作用域指到了别的源,在工程里加一行:
19
+
20
+ ```ini
21
+ @metagl:registry=https://registry.npmjs.org/
22
+ ```
23
+
24
+ pnpm 下需钉住 Cesium 子包(与 sdk-render 验证过的组合一致),写进 `pnpm-workspace.yaml` 或 `package.json` 的 `pnpm.overrides`:
25
+
26
+ ```yaml
27
+ overrides:
28
+ '@cesium/engine': 22.3.0
29
+ '@cesium/widgets': 14.1.0
30
+ ```
31
+
32
+ | peer | 版本 |
33
+ |---|---|
34
+ | `@metagl/sdk-render` | `^3.0.0 \|\| ^4.0.1`(4.0.0 多带了 webpack 等运行时依赖,跳过) |
35
+ | `cesium` | `>=1.132.0 <1.137.0` |
36
+ | `vue` | `^3.5`(只在用 `./vue` 时需要) |
37
+ | `vite` | `>=5`(只在用 `./vite` 时需要) |
38
+
39
+ ## 用法
40
+
41
+ ### Vite 配置
42
+
43
+ ```ts
44
+ // vite.config.ts
45
+ import vue from '@vitejs/plugin-vue';
46
+ import { defineConfig } from 'vite';
47
+ import { smartEarthAssets } from '@metagl/smartearth-base/vite';
48
+
49
+ export default defineConfig({ plugins: [vue(), smartEarthAssets()] });
50
+ ```
51
+
52
+ 插件会把 Cesium 的 `Assets/ThirdParty/Widgets/Workers` 拷到 `public/cesium/`,sdk-render 的 `assets/`、`resources/` 拷到 `public/`(版本没变就跳过),并设置 `CESIUM_BASE_URL`。把这些拷出来的目录加进 `.gitignore`:
53
+
54
+ ```gitignore
55
+ public/cesium/
56
+ public/assets/
57
+ public/resources/
58
+ public/.smartearth-assets.json
59
+ ```
60
+
61
+ ### 框架无关
62
+
63
+ ```ts
64
+ import 'cesium/Build/Cesium/Widgets/widgets.css';
65
+ import { createEarth, isSmartEarthError } from '@metagl/smartearth-base';
66
+
67
+ try {
68
+ const earth = await createEarth(document.getElementById('earth')!, {
69
+ auth: { sdkToken }, // 或 { licence: { lic, rsaPubKey } }
70
+ geovisToken, // 星图地图令牌
71
+ quality: 'high',
72
+ initialView: { lon: 104, lat: 30.6, height: 20000, pitch: -30 },
73
+ });
74
+ await earth.layers.add({
75
+ kind: 'points',
76
+ id: 'hazards',
77
+ data: [{ id: 'H01', lon: 103.6, lat: 31, risk: '高', name: '滑坡' }],
78
+ colorBy: 'risk',
79
+ colors: { 高: '#ef4444', 中: '#f97316', 低: '#eab308' },
80
+ labelField: 'name',
81
+ });
82
+ earth.on('pick', (e) => console.log(e.layerId, e.featureId, e.properties));
83
+ await earth.flyTo('hazards');
84
+ } catch (error) {
85
+ if (isSmartEarthError(error)) showError(error.code, error.message);
86
+ }
87
+ ```
88
+
89
+ 令牌由调用方传入:本包**不取令牌、不读环境变量、不打印令牌**。
90
+
91
+ ### Vue
92
+
93
+ ```vue
94
+ <script setup lang="ts">
95
+ import { SmartEarthView } from '@metagl/smartearth-base/vue';
96
+ const options = { auth: { sdkToken }, geovisToken };
97
+ </script>
98
+
99
+ <template>
100
+ <SmartEarthView :options="options" @ready="(earth) => {}" @error="(err) => {}" />
101
+ </template>
102
+ ```
103
+
104
+ `options` 只在挂载时读一次,换授权或底图请用 `:key` 重建组件;卸载时自动 `destroy()`。
105
+
106
+ ## API
107
+
108
+ ### `getSupportedQualities(): Quality[]`
109
+
110
+ 不建地球就能查已安装的 sdk-render 支持哪些画质,用来在 `createEarth` 前决定初始画质(比如 URL 里要 medium、而 3.0 不支持时回落到 high)。
111
+
112
+ ### `createEarth(container, options): Promise<Earth>`
113
+
114
+ | 选项 | 类型 | 默认 | 说明 |
115
+ |---|---|---|---|
116
+ | `auth` | `{ sdkToken }` \| `{ licence: { lic, rsaPubKey } }` | 必填 | SmartEarth SDK 授权;licence 需本地 sdk-licence 服务 |
117
+ | `geovisToken` | `string` | — | 星图地图令牌,星图底图或地形要用;[申请](https://datacloud.geovisearth.com/) |
118
+ | `basemap` | `'geovis'` \| `{ imageryUrl, annotationUrl?, subdomains?, maximumLevel? }` | `'geovis'` | 底图 |
119
+ | `terrain` | `boolean` | `true` | 星图地形 |
120
+ | `quality` | `'high' \| 'medium' \| 'low'` | `'high'` | 初始画质 |
121
+ | `assetsBasePath` | `string` | `'/'` | sdk-render 资源根路径 |
122
+ | `initialView` | `{ lon, lat, height, heading?, pitch? }` | 中国全景 | 初始视角(度、米) |
123
+ | `checkAssets` | `boolean` | `true` | 初始化前探测静态资源 |
124
+
125
+ ### `Earth`
126
+
127
+ | 成员 | 说明 |
128
+ |---|---|
129
+ | `viewer` | Cesium `Viewer` |
130
+ | `render` | sdk-render `Render` |
131
+ | `quality` / `setQuality(q)` | 当前画质 / 切换画质(不支持的档位抛 `QUALITY_UNSUPPORTED`) |
132
+ | `supportedQualities` | 当前 sdk-render 能切的画质:3.0 为 `['high','low']`,4.x 为三档 |
133
+ | `layers.register(kind, factory)` | 注册图层种类 |
134
+ | `layers.add({ kind, id, visible?, ... })` | 加图层,返回 `{ id, kind, visible }` |
135
+ | `layers.remove(id)` / `setVisible(id, v)` / `list()` | 删除 / 显隐 / 列表 |
136
+ | `layers.get<T>(id)` | 取图层的操作接口,如 `RouteApi`、`AnnotationApi`、`PopupApi`、`Tileset3dApi`、`RiverWaterApi` |
137
+ | `pbr` | sdk-render 4.x 的模型材质接口,3.0 下为 `undefined`:`setTilesetMaterial(tileset\|url, params)` / `getTilesetMaterial` / `clearTilesetMaterial` / `getGlobal()` / `setGlobal(params)` / `exportConfig()` / `importConfig(config)`。参数为亮度 `diffuseStrength`、金属/镜面 `specularStrength`、粗糙度偏移 `roughnessOffset`、自发光 `emissiveStrength`、`aoStrength`、IBL `iblDiffuse/iblSpecular/luminance` 等,范围以 SDK 为准 |
138
+ | `flyTo(target)` | 飞到 `{ lon, lat, height, heading?, pitch?, duration? }` 或图层 id |
139
+ | `on('pick', fn)` | 点击图层要素(含 3D Tiles 要素),回 `{ layerId, featureId, properties, position? }`;返回取消函数 |
140
+ | `destroy()` | 销毁全部图层、Render 与 Viewer |
141
+
142
+ ### 内置图层
143
+
144
+ 全部经 `earth.layers.add({ kind, id, ... })` 添加,`remove` / `destroy` 时清干净;出错一律 `SmartEarthError`。要别的种类可以自己 `layers.register(kind, factory)`。
145
+
146
+ | kind | 主要参数 | `layers.get(id)` 操作接口 |
147
+ |---|---|---|
148
+ | `points` | `data: { lon, lat, height?, ... }[]`、`colorBy`、`colors`、`defaultColor`、`pixelSize`、`labelField` | — |
149
+ | `geojson` | `data`(对象或 URL)、`colorBy: { field, colors }`、`style: { fill, fillOpacity, stroke, strokeWidth, pointColor, pointSize }`、`clampToGround`(默认 true)、`labelField` | — |
150
+ | `tileset3d` | `url`、`pbr?`(该 tileset 的单独材质,需要 sdk-render 4.x;不传不动,4.x 默认给 3D Tiles 挂共享 PBR)、`maximumScreenSpaceError?` | `Tileset3dApi`:`tileset`、`setMaterial(params)`、`clearMaterial()` |
151
+ | `route` | `path`(坐标数组 / GeoJSON LineString / KML 文本 / 二者的 URL)、`durationSeconds`(默认 60)、`loop`、`autoplay`、`follow`、`followRange`、`showPath`、颜色与粗细 | `RouteApi`:`play()`、`pause()`、`seek(0~1)`、`setSpeed(倍速)`、`setFollow(bool)`、`progress`、`playing`、`on('progress' \| 'end')` |
152
+ | `popup` | `render(feature, position) => HTMLElement \| HTML 字符串 \| null`、`layers?`(只对这些图层弹)、`className`、`offset`、`closeOnEmptyClick` | `PopupApi`:`open(position, content)`、`close()`、`isOpen` |
153
+ | `annotation` | `levels?`(等级 → 颜色,默认 高/中/低)、`items?`(初始标注) | `AnnotationApi`:`startPlacing(draft)`、`cancelPlacing()`、`add`、`remove`、`list`、`clear`、`exportJSON()`、`importJSON(json, { append? })`、`on('change')` |
154
+ | `riverWater` | `data`(水系 GeoJSON 或 URL,坐标带 Z)、`height`(坐标缺 Z 时的水面高程)、`width`(默认 60 米)、`offsetHeight`、`thickness`、`dig?: { depth }`、`showDigViz`(默认 false)、`config?`(水面外观)、`lineMode`(默认 `'auto'`) | `RiverWaterApi`:`layerIds`、`lineMode`、`update(config)` |
155
+
156
+ 几点说明:
157
+
158
+ - **航线**按路程等速播放,用自己的计时,不拨场景时钟(不影响 sdk-render 的日照)。跟随时相机在标记点后上方 `followRange` 米。
159
+ - **弹窗**内容是字符串时按 HTML 插入,由调用方保证可信;拼字段值前用导出的 `escapeHtml()`。
160
+ - **标注**不做持久化:`exportJSON()` 出 `{ version: 1, items }`,存哪里由上层决定。
161
+ - **河道水面**只用 sdk-render 公开接口(`RiverWaterSystem.loadFromGeoJson`、`WaterSystem.loadTerrainAdjustFromGeoJSON / applyTerrainAdjust`):
162
+ - 水面高度只取坐标 Z(米)。坐标没有 Z 时必须给 `height`,否则报 `INVALID_OPTIONS`,不让水面悄悄落在 0 米。
163
+ - `lineMode: 'auto'`(默认):sdk-render ≥ 4.0.2 直接传河道线;4.0.1 及更早直接传线会让整个场景停止渲染,所以先按 `width` 把线转成面再加载。也可强制 `'ribbon'` / `'native'`。
164
+ - `dig`:sdk-render ≥ 4.0.2 河道线和湖、库都挖,按「原地形 + 偏移」顺坡下挖(挖坑接口只认面,河道线会按 `width` 转成面交给它);更早的版本只挖湖、库面,因为旧版把区域压平到「平均高程 + 偏移」,沿坡河道会被压成平台。挖坑后 SDK 的青色示意面和「区域 N」标签默认关,`showDigViz: true` 打开。地形调整是全局的,一个地球只能有一个带 `dig` 的河道图层。
165
+
166
+ ### 画质
167
+
168
+ - sdk-render 提供 `setQuality` 时(4.x)直接调用它;初始画质直接传给 `createWithDefaults`,不先按 high 渲染再切。
169
+ - sdk-render 3.0:`high` = `createWithDefaults` 出厂基线;`low` = 基线叠加《渲染性能优化方案》(2026-08-18)低配档——关 SSGI/SSRT/SSR、云 56 步且关噪声、高度雾 low、关 MSAA 与 HDR(保留 FXAA)、阴影 2048/8 次模糊/硬阴影;`medium` 抛 `QUALITY_UNSUPPORTED`。切画质不改场景时间。
170
+
171
+ ### 错误码
172
+
173
+ | code | 场景 |
174
+ |---|---|
175
+ | `INVALID_OPTIONS` | 参数不合法 |
176
+ | `AUTH_MISSING_SDK` | 没给 SDK 授权 |
177
+ | `AUTH_MISSING_MAP` | 用星图底图/地形却没给地图令牌(message 附申请地址) |
178
+ | `AUTH_FAILED` | SDK 授权校验失败,或星图地形加载失败(地图令牌无效/网络不通) |
179
+ | `CESIUM_VERSION` | Cesium 版本不在 `>=1.132.0 <1.137.0` |
180
+ | `ASSETS_MISSING` | Cesium 或 sdk-render 静态资源访问不到 |
181
+ | `RENDER_INIT_FAILED` | Viewer / Render 创建失败,或切画质失败 |
182
+ | `QUALITY_UNSUPPORTED` | 当前 sdk-render 不支持所选画质 |
183
+ | `LAYER_KIND_UNKNOWN` / `LAYER_DUPLICATE` / `LAYER_NOT_FOUND` | 图层种类未注册 / id 重复 / 不存在 |
184
+ | `LAYER_LOAD_FAILED` | 图层数据读取或解析失败(URL 404、GeoJSON 坏了、3D Tiles 加载失败、挖坑失败) |
185
+ | `PBR_UNSUPPORTED` | 用到 PBR(`tileset3d` 的 `pbr`、`setMaterial`)但 sdk-render 不是 4.x |
186
+ | `DESTROYED` | 地球已销毁 |
187
+
188
+ ## 开发
189
+
190
+ ```bash
191
+ pnpm install
192
+ pnpm check # typecheck + test + build
193
+ pnpm example:dev # 构建后启动 examples/vue
194
+ ```
195
+
196
+ 示例页的令牌只从 `examples/vue/.env.local` 读(见 `.env.example`,该文件不入库)。