@metagl/smartearth-base 0.0.0-stage → 0.3.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 +78 -0
- package/README.md +320 -3
- package/dist/chunk-24R3PPPA.js +2116 -0
- package/dist/chunk-POH7K3F4.js +705 -0
- package/dist/chunk-UENQT22J.js +885 -0
- package/dist/createEarth-BY0dtgQQ.d.ts +647 -0
- package/dist/errors-cB7IQlHy.d.ts +15 -0
- package/dist/index.d.ts +345 -0
- package/dist/index.js +2 -0
- package/dist/presets.d.ts +312 -0
- package/dist/presets.js +2 -0
- package/dist/vite.d.ts +20 -0
- package/dist/vite.js +89 -0
- package/dist/vue.d.ts +108 -0
- package/dist/vue.js +291 -0
- package/package.json +75 -6
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
## 0.3.0
|
|
4
|
+
|
|
5
|
+
- 新增 `earth.environment`(光照时间、场景预设、环境与画面效果):
|
|
6
|
+
- 光照时间:`setTime(Date | ISO | { hour, minute })`(北京时间,日期不变)、`setClock({ animate, multiplier })`、`getTime()`、`getClockOfDay()`。
|
|
7
|
+
- 场景预设:sdk-render 4.x 自带的 7 个(晴天正午、清晨日出、黄昏落日、多云午后、阴雨天气、夜间星空、电影级),`setPreset(id, { transition })` 可渐变;`clearPreset()` 把环境恢复到进预设之前(SDK 自己的 clearPreset 会关掉全部环境系统、切画质也拉不回来,这里进预设前存快照)。
|
|
8
|
+
- 效果开关:阴影、体积云、距离雾、高度雾、风、大气散射,以及画面效果反射(SSR)、全局光照(SSGI)、环境光遮蔽(HBAO)、光束(SSRT)、泛光(后处理 bloom)。
|
|
9
|
+
- 效果参数:`getEffectOptions` / `setEffectOptions` 透传 sdk-render 各系统配置(光照、阴影、云、雾、大气、反射、全局光照、AO、光束、后处理的曝光/调色/泛光,河道水面 `riverWater` 与水体 `water` 的颜色、反射、水流、浪花、焦散、亮度,风 `wind`,Cesium 内置雾 `sceneFog`);`sceneFog` 也可用 setEffect 开关。
|
|
10
|
+
- 整份环境配置:`exportConfig()`(纯 JSON、不含令牌;返回 Promise,读 high 画质下的原值,不是叠了当前画质档的值)、`importConfig(config)`、`resetConfig()`(回到交付基线并保持当前画质)。导入 / 重置后按配置补齐各系统开关(sdk-render 的 loadConfig 不保证重新打开运行时被关掉的系统),类型直接用 sdk-render 的配置类型。
|
|
11
|
+
- 预设是底座的原生能力,分三层(设计见 `docs/预设库设计.md`):
|
|
12
|
+
- 核心:`environment.captureSnapshot({ time, camera })` / `restoreSnapshot(snapshot, …)`(环境配置 + 时间 + 视角;视角默认存下来、恢复时默认不飞过去,不改画质)、`environment.on('change', fn)`(时间、预设、效果、配置、快照、画质、SDK 面板改参数都会通知)、`earth.captureImage(maxWidth)`;`createEarth` 自动加载工程里冻结的预设文件 `{assetsBasePath}environment/preset.json`(`presetFile` 选项可改路径或 `false` 关掉;404 或开发服务器回退的 HTML 当作没有,格式不对直接报错)。核心不认识任何服务器,交付页不依赖业务集群。
|
|
13
|
+
- 预设层 `@metagl/smartearth-base/presets`:`createPresetLibrary(earth, { store, bucket, builtin, storage, sources })`,预设文档格式 `smartearth-preset/1`(带生成时的底座与 sdk-render 版本,套用前给兼容提醒);数据源可插拔:SDK 内置 7 个、业务集群预设服务(`httpPresetStore`;智作集群里经主进程本机代理,页面不碰令牌)、样板间储存桶(只读,老格式自动包装)、显式开启的本地存储、业务自定义。功能同样板间配置库:城市 + 7 大区 + 搜索、卡片、预览 / 确认 / 取消(取消真正回滚,含时间)、存到业务集群(不存浏览器,没传 `store` 时保存报错)、下载、删除、`documentFromCurrent`(冻结进工程用)、样板间上传包。
|
|
14
|
+
- 界面:Vue 组件 `SmartEarthPresetLibrary`(`./vue` 入口,`earth` + `store` 或 `library` 属性,样式内置、`se-pl-` 前缀、CSS 变量换色,事件 applied / saved / close),示例页左上角「预设库」直接用它;示例页的令牌只在 Vite 开发代理里(`PRESET_STORE_URL` / `PRESET_TOKEN`,不带 `VITE_` 前缀,不进页面)。
|
|
15
|
+
- 已核对样板间储存桶格式(`CityConfig/{adcode}/index.json` 为 `{ configs: [{ file, thumb, name, desc }] }`,`thumb` 可为空串;配置是 SDK saveConfig 的 2.0.0 格式,时间在 `settings.clockIsoTime`;文件名为 UTC 到秒)。
|
|
16
|
+
- 可移植:sdk-render 导出的配置会把内置贴图(水体法线)写成当前页面的绝对地址(样板间桶里的「晨曦北京」就是 `http://localhost:5173/@fs/...`),`exportConfig` / `importConfig` 现在把指向 SDK 资源目录的地址改回 `./assets/...`;`importConfig` 不再让 SDK 按 `settings.clockIsoTime` 拨时钟(时间只由快照的 `time` 和 `restoreSnapshot` 的选项决定)。
|
|
17
|
+
- 存储由上层传入:`createPresetLibrary(earth, { store })`、Vue 组件 `store` 属性。新增 `httpPresetStore({ baseUrl, getToken, clusterId, fetch })`,对接业务集群预设服务(stratex-cluster 已部署的 `/api/v1/presets`,`render-preset/1`,例如 `https://sites.geovisearth.com/stratex-cluster/api/v1/presets`):公开 + 本集群预设按地区名归城市、带令牌取缩略图、multipart 保存(地区取城市名与可视范围、时间按北京时间)、删除自己的本集群版本、服务端检查规则名原样报出。地址与令牌都由上层给,底座不存令牌;浏览器本地存储默认关。
|
|
18
|
+
- `createEarth` 新增选项:`baseline`(默认 `'environment'`,即 sdk-render 交付基线;可选 `'cinematic'`)、`effects`(建好后开关效果,如 `{ reflection: true, globalIllumination: true, bloom: true }`)、`showPanel`(建好后显示 sdk-render 自带的环境控制面板)。启动时效果名不对或 SDK 不支持,`createEarth` 直接失败并清理。
|
|
19
|
+
- 新增 `earth.showPanel(visible)` / `isPanelVisible`:按需创建并显示 / 隐藏 sdk-render 的 `EnvironmentControl` 面板;`destroy()` 时移除面板 DOM。
|
|
20
|
+
- 预设开着时 `setQuality` 会先退出预设、切完再进同一个预设。
|
|
21
|
+
- 与 sdk-render 环境控制面板逐项对齐(对照表见 `docs/SDK面板对照.md`,11 个页签 222 个控件):
|
|
22
|
+
- 光照:`setLightingMode('off' | 'manual' | 'sun')` / `getLightingMode()`、`setLightDirection({ azimuth, elevation })`(换算同面板)。
|
|
23
|
+
- 效果开关新增 `lighting`、`postProcessing`、`gBuffer`,后处理内的 `hdr`、`fxaa`、`msaa`、`depthOfField`、`postAmbientOcclusion`。
|
|
24
|
+
- `setEffectOptions('terrainAdjust', …)`:地形挖坑的开关 / 暂停、示意面、精度、迟滞、三角化、坡道外扩、顶点间距、塌陷方案。
|
|
25
|
+
- `enableAll()` / `disableAll()`:同面板「全部启用 / 全部关闭」(sdk-render 自己的 enableAllSystems / disableAllSystems 在 4.0.x 会抛错,面板也不用它们)。
|
|
26
|
+
- `earth.pbr.resetGlobal()`:面板「恢复默认材质」。
|
|
27
|
+
- 对齐 sdk-render 样板间(examples/vue)里面板没有的能力:
|
|
28
|
+
- 预设防护(默认开):相机高于 100 km 时延后到城市级再生效(`getPendingPreset()`,`deferAboveMeters: false` 关掉);生效后关 SSRT 镜面子层(`keepMirror: true` 保留)。
|
|
29
|
+
- 改光照强度时按 SDK `DEMO_ENVIRONMENT_BASELINE_DERIVED` 联动 SSGI / SSRT 光轴强度。
|
|
30
|
+
- 6 个调色滤镜:`applyColorFilter(id)` / `colorFilters` / 导出 `COLOR_FILTERS`。
|
|
31
|
+
- `heightGating`:云 / 雾 / 大气按相机高度淡入淡出(cameraListener)。
|
|
32
|
+
- 时区:`setTime({ hour, minute, utcOffset })`、`getClockOfDay(utcOffset)`。
|
|
33
|
+
- 读参数改为递归拷贝,函数(如 cameraListener 的回调)原样保留。
|
|
34
|
+
- 建筑材质:`setEffectOptions('buildingMaterial', …)` 与 `earth.pbr.setGlobal` 同一份全局 PBR(亮度、镜面、粗糙度、自发光、AO、IBL、夜间环境光、白模夜间窗灯);`earth.pbr.setAutoManageTilesets(on)` / `getAutoManageTilesets()` 控制是否给新加载的 3D Tiles 自动挂共享 PBR。示例页「环境」面板加建筑材质滑条与开关。
|
|
35
|
+
- `riverWater` 图层的 `config` 与 `update()` 改用 sdk-render 的 `RiverWaterConfig` 类型(原来是宽松对象)。
|
|
36
|
+
- 升级到 sdk-render 4.0.3(开发依赖与示例页;peer 仍为 `^3.0.0 || ^4.0.1`):
|
|
37
|
+
- 按坑加水:`riverWater` 的 `dig.fillWater`(`true` 或 `{ freeboard, minDepth, spacingMeters }`),挖坑后用 `loadWaterFromTerrainAdjust` 按坑生成顺着坑走的网格水面,不再另铺平水面,坐标不需要 Z;低于 4.0.3 报 `INVALID_OPTIONS`。
|
|
38
|
+
- 无高度水体贴地:坐标缺 Z 且没给 `height` 时,4.0.3 起改用 `loadFromGeoJsonOnTerrain` 贴地形放(`lift` 默认 0.5 米),不再报错;更早版本照旧报错。
|
|
39
|
+
- `RiverWaterApi.placement`:`'data'` / `'terrain'` / `'pit'`。
|
|
40
|
+
- 判断水体有没有高度时,4.0.3 起用 SDK 的 `hasHeightInfo`(properties 里的 elevation / height 也算),和 SDK 一致。
|
|
41
|
+
- 新错误码 `ENVIRONMENT_UNSUPPORTED`;导出 `ENVIRONMENT_PRESETS`、`supportsEnvironment` 与相关类型。
|
|
42
|
+
- 示例页右上角新增「挖坑 + 按坑加水」演示(和「河道水面 + 挖坑」二选一,挖坑是全局的)。
|
|
43
|
+
- 示例页新增左下角「环境」面板:时间滑条、时间流动与流速、预设、效果开关、曝光 / 反射强度 / 泛光阈值滑条、水面反射 / 水面亮度滑条、光照模式与方位角 / 高度角、挖坑开关、调色滤镜、各效果开关、导出 / 导入配置与回到交付基线按钮;左上角「调参面板」按钮(打开 SDK 自带面板)。
|
|
44
|
+
- 不提供天气粒子:sdk-render 还没有正式的天气功能(导出的 `RainSystem` 是未完成的旧件),等 SDK 做了再接。
|
|
45
|
+
|
|
46
|
+
## 0.2.0
|
|
47
|
+
|
|
48
|
+
第 2 期:六种业务图层。
|
|
49
|
+
|
|
50
|
+
- **包名改为 `@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`。
|
|
51
|
+
|
|
52
|
+
- 新增内置图层,全部经 `layers.add({ kind, ... })`,`remove` / `destroy` 时清干净:
|
|
53
|
+
- `geojson`:面、线、点,按字段着色,可选文字标注,数据可给对象或 URL。
|
|
54
|
+
- `tileset3d`:`Cesium3DTileset.fromUrl` 加载(不用 `loadCityModel`),可带 `pbr` 单独材质(经 `earth.pbr.setTilesetMaterial`,需要 sdk-render 4.x);3D Tiles 要素可拾取。
|
|
55
|
+
- `route`:航线回放(坐标数组 / GeoJSON LineString / KML / URL),播放、暂停、跳转、倍速、进度事件、相机跟随;不拨场景时钟。
|
|
56
|
+
- `popup`:点到要素时跟随位置的 HTML 浮层,可限定图层;导出 `escapeHtml()`。
|
|
57
|
+
- `annotation`:点选放置标注(名称/等级/说明)、增删、`exportJSON` / `importJSON`,不做持久化。
|
|
58
|
+
- `riverWater`:只用 sdk-render 公开接口加载水系动态水面并可挖坑。sdk-render ≥ 4.0.2 直接传河道线,河道线与湖、库都按「原地形 + 偏移」顺坡下挖;更早的版本自动退回绕过(线先转成面,只挖湖、库,避开 4.0.1 线河道停止整个场景渲染、挖坑压成平台的缺陷)。挖坑示意面默认关(`showDigViz`)。坐标没有 Z 时必须给 `height`,不让水面悄悄落在 0 米。
|
|
59
|
+
- `layers.get(id)` 取图层操作接口;图层上下文新增 `render`、`pbr`、`onClick`、`registerPickResolver`,自定义图层也能用。
|
|
60
|
+
- 新错误码 `LAYER_LOAD_FAILED`、`PBR_UNSUPPORTED`。
|
|
61
|
+
- 示例页:每种图层一个演示开关,样例数据在 `examples/vue/public/samples`。
|
|
62
|
+
- 适配 sdk-render 4.x:`earth.pbr` 透传模型材质接口(按 tileset 设材质、全局 PBR、导入导出 'material' 配置),类型 `EarthPbr` / `PbrMaterialParams` / `PbrConfig`;初始画质在 4.x 下直接传给 `createWithDefaults`。
|
|
63
|
+
- PBR 参数类型与 `@metagl/sdk-render` 4.0.0 对齐:含 `iblNightFactor`(全局默认 0.25)、`proceduralWindows`(默认关);编译期单测核对与 SDK 真实类型一致。
|
|
64
|
+
- `makeExtensible` 处理打包器产出的 getter 导出(发布包被 Vite 预构建后 createEarth 不再报 Invalid property descriptor);图层上下文新增 `sdkRenderVersion`。
|
|
65
|
+
- 开发依赖与示例页钉 `@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`)。
|
|
66
|
+
- 错误信息打码只处理 8 位以上的令牌,避免误伤正常文字。
|
|
67
|
+
|
|
68
|
+
## 0.1.0(未发布)
|
|
69
|
+
|
|
70
|
+
首个版本,替代已废弃的 `@agent-earth/smart-earth`。
|
|
71
|
+
|
|
72
|
+
- 核心 `createEarth(container, options)`:星图影像 + 注记 + 地形,`Render.createWithDefaults` 环境基线;挂 `window.Cesium`(可写副本)、RenderState lineWidth 兼容补丁。
|
|
73
|
+
- 统一错误 `SmartEarthError`(`AUTH_MISSING_SDK` / `AUTH_MISSING_MAP` / `AUTH_FAILED` / `CESIUM_VERSION` / `ASSETS_MISSING` / `RENDER_INIT_FAILED` 等),失败即抛、不降级为普通 Cesium。
|
|
74
|
+
- 画质 `setQuality`:优先用 sdk-render 自带接口;3.0 下提供 high / low 两档,medium 抛 `QUALITY_UNSUPPORTED`。
|
|
75
|
+
- `Earth.supportedQualities` 与 `getSupportedQualities()`:查当前 sdk-render 能切哪些画质。
|
|
76
|
+
- 图层注册表 `layers.register/add/remove/setVisible/list` 与内置 `points`(按字段分色);`on('pick')`、`flyTo`。
|
|
77
|
+
- `./vite`:`smartEarthAssets()` 拷 Cesium 与 sdk-render 运行时资源、设置 `CESIUM_BASE_URL`。
|
|
78
|
+
- `./vue`:`<SmartEarthView :options @ready @error>`。
|
package/README.md
CHANGED
|
@@ -1,3 +1,320 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
3
|
-
|
|
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.3 cesium@1.136.0
|
|
15
|
+
# 或 pnpm add @metagl/smartearth-base @metagl/sdk-render@4.0.3 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
|
+
**预设库组件**:预设是底座的原生能力,`@metagl/smartearth-base/presets` 之外还自带现成的面板 `SmartEarthPresetLibrary`(样式已内置,类名前缀 `se-pl-`,可用 CSS 变量 `--se-pl-bg` / `--se-pl-card-bg` / `--se-pl-fg` / `--se-pl-accent` 换色;放在哪、多宽由业务决定):
|
|
107
|
+
|
|
108
|
+
```vue
|
|
109
|
+
<script setup lang="ts">
|
|
110
|
+
import { SmartEarthPresetLibrary, SmartEarthView } from '@metagl/smartearth-base/vue';
|
|
111
|
+
const earth = shallowRef<Earth | null>(null);
|
|
112
|
+
</script>
|
|
113
|
+
|
|
114
|
+
<template>
|
|
115
|
+
<SmartEarthView :options="options" @ready="(e) => (earth = e)" />
|
|
116
|
+
<div v-if="earth" style="position: absolute; top: 16px; left: 16px; width: 420px; max-height: 80%; display: flex">
|
|
117
|
+
<!-- store:上层建好的存储,如 httpPresetStore({ baseUrl, getToken, clusterId });智作里 baseUrl 是主进程本机代理,页面不碰令牌 -->
|
|
118
|
+
<SmartEarthPresetLibrary :earth="earth" :store="store" adcode="110000" @applied="..." @saved="..." @close="..." />
|
|
119
|
+
</div>
|
|
120
|
+
</template>
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
| 属性 / 事件 | 说明 |
|
|
124
|
+
|---|---|
|
|
125
|
+
| `earth`(必填) | `createEarth` / `SmartEarthView` 给的地球 |
|
|
126
|
+
| `store` | 存预设的地方,上层建好传进来(如 `httpPresetStore({ baseUrl, getToken, clusterId })`);不传就只能浏览、不能存 |
|
|
127
|
+
| `library` | 自己用 `createPresetLibrary(earth, {...})` 建好的预设库(要自定义数据源时用),传了就不看 `store` |
|
|
128
|
+
| `adcode` | 打开时默认选中的城市 |
|
|
129
|
+
| `closable` | 显示右上角关闭按钮,默认 true |
|
|
130
|
+
| `@applied(entry)` / `@saved(entry)` / `@close` | 确认套用了某个预设 / 存了一个预设 / 点了关闭 |
|
|
131
|
+
|
|
132
|
+
## API
|
|
133
|
+
|
|
134
|
+
### `getSupportedQualities(): Quality[]`
|
|
135
|
+
|
|
136
|
+
不建地球就能查已安装的 sdk-render 支持哪些画质,用来在 `createEarth` 前决定初始画质(比如 URL 里要 medium、而 3.0 不支持时回落到 high)。
|
|
137
|
+
|
|
138
|
+
### `createEarth(container, options): Promise<Earth>`
|
|
139
|
+
|
|
140
|
+
| 选项 | 类型 | 默认 | 说明 |
|
|
141
|
+
|---|---|---|---|
|
|
142
|
+
| `auth` | `{ sdkToken }` \| `{ licence: { lic, rsaPubKey } }` | 必填 | SmartEarth SDK 授权;licence 需本地 sdk-licence 服务 |
|
|
143
|
+
| `geovisToken` | `string` | — | 星图地图令牌,星图底图或地形要用;[申请](https://datacloud.geovisearth.com/) |
|
|
144
|
+
| `basemap` | `'geovis'` \| `{ imageryUrl, annotationUrl?, subdomains?, maximumLevel? }` | `'geovis'` | 底图 |
|
|
145
|
+
| `terrain` | `boolean` | `true` | 星图地形 |
|
|
146
|
+
| `quality` | `'high' \| 'medium' \| 'low'` | `'high'` | 初始画质 |
|
|
147
|
+
| `assetsBasePath` | `string` | `'/'` | sdk-render 资源根路径 |
|
|
148
|
+
| `initialView` | `{ lon, lat, height, heading?, pitch? }` | 中国全景 | 初始视角(度、米) |
|
|
149
|
+
| `checkAssets` | `boolean` | `true` | 初始化前探测静态资源 |
|
|
150
|
+
| `baseline` | `'environment'` \| `'cinematic'` | `'environment'` | 环境基线:`'environment'` = sdk-render 交付基线(`DEMO_ENVIRONMENT_BASELINE`),`'cinematic'` = 电影级 |
|
|
151
|
+
| `effects` | `{ 效果名: boolean }` | — | 建好后开 / 关的效果,如 `{ reflection: true, globalIllumination: true, bloom: true }`(需要 4.x,效果名见「环境」) |
|
|
152
|
+
| `showPanel` | `boolean` | `false` | 建好后显示 sdk-render 自带的环境控制面板(需要 4.x) |
|
|
153
|
+
| `presetFile` | `string` \| `false` | `'{assetsBasePath}environment/preset.json'` | 工程里冻结的环境预设文件,建好后自动套用(含时间、不动视角)。文件不存在(404,或开发服务器回退成 HTML)当作没配;文件在但格式不对直接报错。`false` 关闭。交付页只读这个文件,不连预设服务器 |
|
|
154
|
+
|
|
155
|
+
### `Earth`
|
|
156
|
+
|
|
157
|
+
| 成员 | 说明 |
|
|
158
|
+
|---|---|
|
|
159
|
+
| `viewer` | Cesium `Viewer` |
|
|
160
|
+
| `render` | sdk-render `Render` |
|
|
161
|
+
| `quality` / `setQuality(q)` | 当前画质 / 切换画质(不支持的档位抛 `QUALITY_UNSUPPORTED`) |
|
|
162
|
+
| `supportedQualities` | 当前 sdk-render 能切的画质:3.0 为 `['high','low']`,4.x 为三档 |
|
|
163
|
+
| `layers.register(kind, factory)` | 注册图层种类 |
|
|
164
|
+
| `layers.add({ kind, id, visible?, ... })` | 加图层,返回 `{ id, kind, visible }` |
|
|
165
|
+
| `layers.remove(id)` / `setVisible(id, v)` / `list()` | 删除 / 显隐 / 列表 |
|
|
166
|
+
| `layers.get<T>(id)` | 取图层的操作接口,如 `RouteApi`、`AnnotationApi`、`PopupApi`、`Tileset3dApi`、`RiverWaterApi` |
|
|
167
|
+
| `pbr` | sdk-render 4.x 的模型材质接口,3.0 下为 `undefined`:`setTilesetMaterial(tileset\|url, params)` / `getTilesetMaterial` / `clearTilesetMaterial` / `getGlobal()` / `setGlobal(params)` / `exportConfig()` / `importConfig(config)` / `setAutoManageTilesets(on)` / `getAutoManageTilesets()`(是否自动给新加载的 3D Tiles 挂共享 PBR,默认开;已挂上的不会摘掉)/ `resetGlobal()`(全局 PBR 回到建地球时的值,即面板「恢复默认材质」)。参数为亮度 `diffuseStrength`、金属/镜面 `specularStrength`、粗糙度偏移 `roughnessOffset`、自发光 `emissiveStrength`、`aoStrength`、IBL `iblDiffuse/iblSpecular/luminance` 等,范围以 SDK 为准 |
|
|
168
|
+
| `environment` | 光照时间、场景预设、环境与画面效果(反射、泛光等)开关与参数,见下面「环境」 |
|
|
169
|
+
| `flyTo(target)` | 飞到 `{ lon, lat, height, heading?, pitch?, duration? }` 或图层 id |
|
|
170
|
+
| `captureImage(maxWidth = 480)` | 截当前画面,返回 JPEG dataURL(预设缩略图用) |
|
|
171
|
+
| `on('pick', fn)` | 点击图层要素(含 3D Tiles 要素),回 `{ layerId, featureId, properties, position? }`;返回取消函数 |
|
|
172
|
+
| `showPanel(visible = true)` / `isPanelVisible` | 显示 / 隐藏 sdk-render 自带的环境控制面板(画质、预设、各渲染系统调参、配置导入导出),第一次显示时才创建;需要 4.x。面板里的改动直接作用于 sdk-render,不经 `environment`(例如用面板切预设,`environment.clearPreset()` 不知道) |
|
|
173
|
+
| `destroy()` | 销毁全部图层、Render 与 Viewer(含面板) |
|
|
174
|
+
|
|
175
|
+
### 内置图层
|
|
176
|
+
|
|
177
|
+
全部经 `earth.layers.add({ kind, id, ... })` 添加,`remove` / `destroy` 时清干净;出错一律 `SmartEarthError`。要别的种类可以自己 `layers.register(kind, factory)`。
|
|
178
|
+
|
|
179
|
+
| kind | 主要参数 | `layers.get(id)` 操作接口 |
|
|
180
|
+
|---|---|---|
|
|
181
|
+
| `points` | `data: { lon, lat, height?, ... }[]`、`colorBy`、`colors`、`defaultColor`、`pixelSize`、`labelField` | — |
|
|
182
|
+
| `geojson` | `data`(对象或 URL)、`colorBy: { field, colors }`、`style: { fill, fillOpacity, stroke, strokeWidth, pointColor, pointSize }`、`clampToGround`(默认 true)、`labelField` | — |
|
|
183
|
+
| `tileset3d` | `url`、`pbr?`(该 tileset 的单独材质,需要 sdk-render 4.x;不传不动,4.x 默认给 3D Tiles 挂共享 PBR)、`maximumScreenSpaceError?` | `Tileset3dApi`:`tileset`、`setMaterial(params)`、`clearMaterial()` |
|
|
184
|
+
| `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')` |
|
|
185
|
+
| `popup` | `render(feature, position) => HTMLElement \| HTML 字符串 \| null`、`layers?`(只对这些图层弹)、`className`、`offset`、`closeOnEmptyClick` | `PopupApi`:`open(position, content)`、`close()`、`isOpen` |
|
|
186
|
+
| `annotation` | `levels?`(等级 → 颜色,默认 高/中/低)、`items?`(初始标注) | `AnnotationApi`:`startPlacing(draft)`、`cancelPlacing()`、`add`、`remove`、`list`、`clear`、`exportJSON()`、`importJSON(json, { append? })`、`on('change')` |
|
|
187
|
+
| `riverWater` | `data`(水系 GeoJSON 或 URL)、`height`(坐标缺 Z 时的水面高程)、`lift`(贴地时比地形高的米数,4.0.3)、`width`(默认 60 米)、`offsetHeight`、`thickness`、`dig?: { depth, fillWater? }`(`fillWater` = 按坑加水,4.0.3)、`showDigViz`(默认 false)、`config?`(水面外观,`RiverWaterConfig`)、`lineMode`(默认 `'auto'`) | `RiverWaterApi`:`layerIds`、`lineMode`、`placement`、`update(config)` |
|
|
188
|
+
|
|
189
|
+
几点说明:
|
|
190
|
+
|
|
191
|
+
- **航线**按路程等速播放,用自己的计时,不拨场景时钟(不影响 sdk-render 的日照)。跟随时相机在标记点后上方 `followRange` 米。
|
|
192
|
+
- **弹窗**内容是字符串时按 HTML 插入,由调用方保证可信;拼字段值前用导出的 `escapeHtml()`。
|
|
193
|
+
- **标注**不做持久化:`exportJSON()` 出 `{ version: 1, items }`,存哪里由上层决定。
|
|
194
|
+
- **河道水面**只用 sdk-render 公开接口(`RiverWaterSystem.loadFromGeoJson`、`WaterSystem.loadTerrainAdjustFromGeoJSON / applyTerrainAdjust`):
|
|
195
|
+
- 水面高度只取坐标 Z(米)。坐标没有 Z 时必须给 `height`,否则报 `INVALID_OPTIONS`,不让水面悄悄落在 0 米。
|
|
196
|
+
- `lineMode: 'auto'`(默认):sdk-render ≥ 4.0.2 直接传河道线;4.0.1 及更早直接传线会让整个场景停止渲染,所以先按 `width` 把线转成面再加载。也可强制 `'ribbon'` / `'native'`。
|
|
197
|
+
- `dig`:sdk-render ≥ 4.0.2 河道线和湖、库都挖,按「原地形 + 偏移」顺坡下挖(挖坑接口只认面,河道线会按 `width` 转成面交给它);更早的版本只挖湖、库面,因为旧版把区域压平到「平均高程 + 偏移」,沿坡河道会被压成平台。挖坑后 SDK 的青色示意面和「区域 N」标签默认关,`showDigViz: true` 打开。地形调整是全局的,一个地球只能有一个带 `dig` 的河道图层。
|
|
198
|
+
- 按坑加水(sdk-render ≥ 4.0.3):`dig: { depth, fillWater: true | { freeboard, minDepth, spacingMeters } }`,挖完按坑生成顺着坑走的水面(比坑沿低 `freeboard` 米,默认 5),不再按数据另铺平水面,坐标也不需要 Z。`RiverWaterApi.placement` 为 `'pit'`。
|
|
199
|
+
- 坐标没有 Z、也没给 `height` 时:sdk-render ≥ 4.0.3 把水面贴着地形放(比地形高 `lift` 米,默认 0.5,`placement: 'terrain'`);更早的版本仍报 `INVALID_OPTIONS`。
|
|
200
|
+
|
|
201
|
+
### 环境(`earth.environment`)
|
|
202
|
+
|
|
203
|
+
sdk-render 自带环境控制面板的每个控件对应哪个接口,见 [docs/SDK面板对照.md](docs/SDK面板对照.md)。
|
|
204
|
+
|
|
205
|
+
```ts
|
|
206
|
+
const env = earth.environment;
|
|
207
|
+
env.setTime({ hour: 18, minute: 30 }); // 北京时间,日期不变;也可传 Date 或 ISO 字符串
|
|
208
|
+
env.setClock({ animate: true, multiplier: 600 }); // 让时间走起来,一秒走十分钟
|
|
209
|
+
env.setPreset('sunset', { transition: 1.5 }); // 切预设,1.5 秒渐变
|
|
210
|
+
env.clearPreset(); // 退出预设,环境回到进预设之前的样子
|
|
211
|
+
env.setEffect('clouds', false); // 单独关体积云
|
|
212
|
+
env.setEffect('reflection', true); // 开反射(默认强度 0,要再调强度)
|
|
213
|
+
env.setEffectOptions('reflection', { intensity: 0.6 });
|
|
214
|
+
env.setEffect('bloom', true); // 开泛光
|
|
215
|
+
env.setEffectOptions('postProcessing', { exposure: 1.2, bloomBrightness: -0.5 });
|
|
216
|
+
```
|
|
217
|
+
|
|
218
|
+
| 成员 | 说明 |
|
|
219
|
+
|---|---|
|
|
220
|
+
| `setTime(time)` / `getTime()` / `getClockOfDay(utcOffset?)` | 设 / 读场景时间,太阳方向与昼夜跟着变。`time` 为 `Date`、ISO 字符串,或 `{ hour, minute?, utcOffset? }`(默认北京时间 `utcOffset: 8`,沿用当前日期,季节不变) |
|
|
221
|
+
| `setClock({ animate?, multiplier? })` / `getClock()` | 时间走或停、流速(1 = 真实速度) |
|
|
222
|
+
| `presets` | 预设列表 `{ id, name }`:`noon-clear` 晴天正午、`sunrise` 清晨日出、`sunset` 黄昏落日、`cloudy-afternoon` 多云午后、`overcast` 阴雨天气、`night` 夜间星空、`cinematic` 电影级 |
|
|
223
|
+
| `setPreset(id, { transition? })` / `getPreset()` / `clearPreset()` | 切预设(会把时间拨到预设自带的时刻,并改环境效果)/ 当前预设 / 退出预设(环境效果恢复到进预设之前,时间不回拨) |
|
|
224
|
+
| `setEffect(effect, on)` / `getEffects()` | 单独开关效果。环境:`shadow` 阴影、`clouds` 体积云、`distanceFog` 距离雾、`heightFog` 高度雾、`wind` 风、`atmosphere` 大气散射;画面:`reflection` 反射(SSR)、`globalIllumination` 全局光照(SSGI)、`ambientOcclusion` 环境光遮蔽(HBAO)、`lightShafts` 光束(SSRT)、`gBuffer`(延迟管线,上面四个都依赖它);整体:`lighting` 光照、`postProcessing` 后处理;后处理内:`bloom` 泛光、`hdr`、`fxaa`、`msaa`、`depthOfField` 景深、`postAmbientOcclusion`(Cesium 内置 AO);`sceneFog` Cesium 内置雾 |
|
|
225
|
+
| `getEffectOptions(target)` / `setEffectOptions(target, options)` | 读 / 改效果参数(只改给出的字段,不改开关)。`target` 为上面的效果名(不含 `wind`、`bloom`),另有 `lighting` 光照、`postProcessing` 后处理(曝光 `exposure`、色调映射 `tonemapper`、对比度、饱和度、色温、泛光 `bloomBrightness` / `bloomSigma` 等、抗锯齿)、`riverWater` 河道水面(深浅水颜色、`reflectionStrength` 反射、`waterSpeed` / `waterAngle` 水流、浪花 `foam*`、焦散 `caustic*`、高光、`luminance` 亮度,作用于全部河道图层)、`water` 水体(颜色、波纹、振幅、速度、高光)、`wind` 风(速度、方向、湍流)、`sceneFog` 内置雾(密度、高度衰减、颜色)、`buildingMaterial` 建筑材质(全局 PBR,与 `earth.pbr.setGlobal` 同一份)、`terrainAdjust` 地形挖坑(开关 / 暂停、示意面、精度、迟滞、三角化、坡道外扩、顶点间距、塌陷方案,`enabled` 在这里有效)、`heightGating` 云 / 雾 / 大气按相机高度淡入淡出。改 `lighting` 的 `intensity` 时,全局光照与光束强度按 SDK 公式一起联动(同样板间)。参数类型直接用 sdk-render 的 `SSRConfig`、`PostProcessingConfig` 等,范围以 SDK 为准 |
|
|
226
|
+
| `setLightingMode('off' \| 'manual' \| 'sun')` / `getLightingMode()` / `setLightDirection({ azimuth, elevation })` | 光照模式(关闭 / 方向光 / 跟随太阳)与方向光的方位角、高度角(换算同 SDK 面板) |
|
|
227
|
+
| `enableAll()` / `disableAll()` | 同 SDK 面板「全部启用」(所有系统回到 SDK 默认参数并打开)/「全部关闭」(关光照、阴影、大气、云、雾、后处理);会退出预设 |
|
|
228
|
+
| `setPreset(id, { transition, deferAboveMeters, keepMirror })` / `getPendingPreset()` | 预设的两道样板间防护(默认开):相机高于 100 km 时等飞到城市级再生效;生效后关掉 SSRT 镜面子层(低视角会画出圆弧) |
|
|
229
|
+
| `applyColorFilter(id)` / `colorFilters` | 样板间 6 个调色滤镜:`standard` 标准、`warm` 暖色调、`cool` 冷色调、`vivid` 鲜艳、`desaturate` 去色、`highcontrast` 高对比度 |
|
|
230
|
+
| `exportConfig()` / `importConfig(config)` / `resetConfig()` | 导出整份环境配置(所有渲染系统的开关与参数,纯 JSON、不含令牌;**0.3.0 起返回 Promise**,读的是 high 画质下的原值,不是叠了当前画质档的值)/ 导入(也认 sdk-render 面板导出的 JSON)/ 回到交付基线并保持当前画质。三者都会退出当前预设,时间不变 |
|
|
231
|
+
| `captureSnapshot({ time?, camera? })` / `restoreSnapshot(snapshot, { time?, camera? })` | 环境快照:整份环境配置 + 时间(默认带)+ 视角(默认存下来)+ 当时的画质与预设。恢复时默认不飞到存的视角(`camera: true` 才飞),也不改画质。预设、工程预设文件存的都是它 |
|
|
232
|
+
| `on('change', fn)` | 环境变了就通知,`fn({ source })`,`source` 为 `time` / `preset` / `effect` / `config` / `snapshot` / `quality` / `panel`(SDK 面板里调了参数,防抖 300 ms);返回取消函数。智作用它提示「环境已改动,未冻结」 |
|
|
233
|
+
|
|
234
|
+
几点说明:
|
|
235
|
+
|
|
236
|
+
- 时间对任何 sdk-render 版本都可用;预设和效果开关要 sdk-render 4.x,3.0 下抛 `ENVIRONMENT_UNSUPPORTED`。
|
|
237
|
+
- 预设开着时切画质:先退出预设、切画质、再进同一个预设。预设会盖掉部分画质设置(如电影级会打开全套延迟管线),低档机器慎用。
|
|
238
|
+
- 反射(SSR)出厂强度为 0:只开不调强度看不出来。泛光是后处理里的开关,开泛光会顺带打开后处理。
|
|
239
|
+
- 切画质、切预设会重写这些效果的开关与参数(低档会关掉全局光照、光束等),切完需要的话再设一次。
|
|
240
|
+
- 不提供雨、雪等天气粒子:sdk-render 还没有正式的天气功能。`overcast` 阴雨天气预设只是厚云、雾和暗光,没有雨滴。
|
|
241
|
+
|
|
242
|
+
### 预设库(`@metagl/smartearth-base/presets`)
|
|
243
|
+
|
|
244
|
+
预设是底座提供的原生能力,分三层:核心只管环境快照(上面的 `captureSnapshot` / `restoreSnapshot` / `on('change')` 和 `createEarth` 的 `presetFile`),不认识任何服务器;预设层 `createPresetLibrary` 管预设文档格式与数据源;界面是 Vue 组件 `SmartEarthPresetLibrary`。功能同 sdk-render 样板间的「配置库」:城市 / 大区浏览、搜索,SDK 内置、业务集群预设与样板间储存桶的卡片合在一起,点卡预览、确认或取消,存到业务集群,生成样板间上传包。
|
|
245
|
+
|
|
246
|
+
```ts
|
|
247
|
+
import { createPresetLibrary } from '@metagl/smartearth-base/presets';
|
|
248
|
+
|
|
249
|
+
import { httpPresetStore } from '@metagl/smartearth-base/presets';
|
|
250
|
+
|
|
251
|
+
// 存业务集群预设服务(stratex-cluster)。地址、令牌、集群编号都由上层给,包里没有默认地址,底座不存令牌:
|
|
252
|
+
// 智作里 baseUrl 是主进程本机代理(代理附 AEP 令牌);其他场景给 getToken(每次请求现取)或自定义 fetch。
|
|
253
|
+
const store = httpPresetStore({ baseUrl: 'https://sites.geovisearth.com/stratex-cluster/api/v1/presets', getToken, clusterId });
|
|
254
|
+
const lib = createPresetLibrary(earth, { store });
|
|
255
|
+
const cities = await lib.listCities(); // 城市列表(样板间同一接口),带 regionId
|
|
256
|
+
const hits = await lib.searchCities('四川'); // 城市名、省份、大区名、看过的预设名都能搜
|
|
257
|
+
const cards = await lib.list(110000); // SDK 内置 + 业务集群 + 样板间储存桶(card.source 区分,带 thumb)
|
|
258
|
+
await lib.preview(cards[0]); // 预览(先拍一张快照)
|
|
259
|
+
await lib.cancelPreview(); // 取消:回到第一次预览之前(含时间);lib.confirmPreview() 则保留
|
|
260
|
+
await lib.save({ name: '国贸黄昏', adcode: '110000' }); // 存到业务集群:快照(含时间和视角,套用时默认不飞过去)+ 截图
|
|
261
|
+
const doc = await lib.documentFromCurrent({ name: '交付环境', adcode: '110000' }); // 预设文档(不存),冻结进工程用
|
|
262
|
+
```
|
|
263
|
+
|
|
264
|
+
| 成员 | 说明 |
|
|
265
|
+
|---|---|
|
|
266
|
+
| `sources` | 数据源,依次为 `builtin`(SDK 内置 7 个,不分城市)、`cluster`(上层传的 `store`,如业务集群预设服务;自己写的本集群预设可删,公开预设只读)、`local`(显式开启才有)、`bucket`(样板间储存桶,只读)和 `options.sources` 里自定义的 |
|
|
267
|
+
| `regions` / `listCities()` / `searchCities(q)` | 7 个大区 + 其他(按 adcode 前两位)、城市列表、搜索 |
|
|
268
|
+
| `list(adcode)` | 某城市的卡片 `PresetSummary`(`id` 为 `{来源}:{来源内 id}`、`source`、`name`、`thumb`、`producedBy`、`writable`) |
|
|
269
|
+
| `getDocument(card)` / `compatibility(card)` | 取完整预设文档(下载用;SDK 内置没有)/ 套用前的兼容提醒:样板间老格式,或生成时 sdk-render 主版本不同 |
|
|
270
|
+
| `preview(card)` / `confirmPreview()` / `cancelPreview()` / `isPreviewing` | 预览流程;取消会真正回滚到预览前(样板间的取消不回滚) |
|
|
271
|
+
| `apply(card, { camera? })` | 直接套用(SDK 内置走 `setPreset` 的渐变与防护,其余走 `restoreSnapshot`,含时间);视角默认不动,`camera: true` 时飞到预设里存的视角 |
|
|
272
|
+
| `save({ name, desc?, adcode, tags?, camera?, thumbnail?, target? })` / `remove(card)` / `canSave` | 预设**存在上层传的 `store` 里(业务集群预设服务),不存浏览器**;没传 `store` 时 `canSave` 为 false,保存直接报错。存业务集群要城市(`adcode`,地区名取城市名、范围取当前可视范围)和缩略图。浏览器本地存储默认关,离线演示可显式传 `storage: createLocalStorageStorage()` |
|
|
273
|
+
| `documentFromCurrent({ name, desc?, adcode?, camera? })` | 把当前环境做成预设文档(`smartearth-preset/1`),不存;智作「冻结进工程」写成 `public/environment/preset.json` 用 |
|
|
274
|
+
| `bucketUploadPackage(adcode, { name, desc? })` | 样板间储存桶的上传包(老格式配置、截图、合并好的 index.json),需要往样板间那边补数据时用 |
|
|
275
|
+
|
|
276
|
+
`createPresetLibrary(earth, options)`:`store`(可写数据源,通常是 `httpPresetStore(...)`,也可以是自己实现的 `PresetSource`)、`bucket`(`{ baseUrl }` 或 `false`)、`builtin`(默认 true)、`storage`、`sources`(自己实现 `PresetSource`)、`cityListUrl`。
|
|
277
|
+
|
|
278
|
+
**与集群模板的约定**:模板 `template.json`(`cluster-template/2`)用集群已有的 `renderPresets: ["id@x.y.z", …]` 引用业务集群里的公开预设(≤10 个,第一个为默认),不另加字段。放起步工程时由智作用 `store.get(ref)` 取第一个,冻结写成工程的 `public/environment/preset.json`(预设文档,`source` 记 `{ kind: 'cluster', id: ref }`);运行时 `createEarth` 只读这个文件,不连业务集群。
|
|
279
|
+
|
|
280
|
+
`httpPresetStore({ baseUrl, getToken?, clusterId?, fetch?, label?, utcOffset? })`:业务集群预设服务(stratex-cluster `docs/api-v1.md`「地区预设 render-preset/1」)的数据源。
|
|
281
|
+
- `baseUrl` 到 `/presets` 为止,指向 stratex-cluster 已部署的接口,例如 `https://sites.geovisearth.com/stratex-cluster/api/v1/presets`。服务没开跨域,浏览器页面要经上层代理(智作主进程)访问,或传自定义 `fetch`(如走 IPC)。
|
|
282
|
+
- `getToken` 每次请求现取 AEP 访问令牌,返回空就不带(由代理附);`clusterId` 是本集群编号,非管理员写入必填,读取时带出自己写的本集群版本。写入用的是**用户自己的 AEP 登录令牌**:管理员写的直接成为公开预设(走集群后台审核上架),非管理员写的先存成「本集群可见」版本(只对本人按 `clusterId` 可见),由服务端按令牌里的角色决定,底座不区分。
|
|
283
|
+
- 列表:公开预设 + 自己写的本集群预设,按地区名(去掉省 / 市等后缀)归到城市;缩略图带令牌取回转成 `blob:` 地址。
|
|
284
|
+
- 保存:新编号 `p-<时间>-<8 位十六进制>`、版本 `1.0.0`,`render` 是 `exportConfig()` 的结果,`time` 按北京时间写日期与时分,`camera` 可选;服务端的检查不通过时报错里带规则名(如 `secret-secret-key`)。
|
|
285
|
+
- 删除:只能删自己的本集群版本;公开版本不可删。
|
|
286
|
+
|
|
287
|
+
预设文档(`smartearth-preset/1`)= `{ schema, id, name, desc?, adcode?, tags?, author?, createdAt, producedBy: { base, sdkRender } | 'legacy', source?, snapshot }`。工程里冻结的文件就是它。业务集群存的是自己的 `render-preset/1` 格式,`httpPresetStore` 读写时自动互转,接口见 stratex-cluster 的 `docs/api-v1.md`。
|
|
288
|
+
|
|
289
|
+
### 画质
|
|
290
|
+
|
|
291
|
+
- sdk-render 提供 `setQuality` 时(4.x)直接调用它;初始画质直接传给 `createWithDefaults`,不先按 high 渲染再切。
|
|
292
|
+
- sdk-render 3.0:`high` = `createWithDefaults` 出厂基线;`low` = 基线叠加《渲染性能优化方案》(2026-08-18)低配档——关 SSGI/SSRT/SSR、云 56 步且关噪声、高度雾 low、关 MSAA 与 HDR(保留 FXAA)、阴影 2048/8 次模糊/硬阴影;`medium` 抛 `QUALITY_UNSUPPORTED`。切画质不改场景时间。
|
|
293
|
+
|
|
294
|
+
### 错误码
|
|
295
|
+
|
|
296
|
+
| code | 场景 |
|
|
297
|
+
|---|---|
|
|
298
|
+
| `INVALID_OPTIONS` | 参数不合法 |
|
|
299
|
+
| `AUTH_MISSING_SDK` | 没给 SDK 授权 |
|
|
300
|
+
| `AUTH_MISSING_MAP` | 用星图底图/地形却没给地图令牌(message 附申请地址) |
|
|
301
|
+
| `AUTH_FAILED` | SDK 授权校验失败,或星图地形加载失败(地图令牌无效/网络不通) |
|
|
302
|
+
| `CESIUM_VERSION` | Cesium 版本不在 `>=1.132.0 <1.137.0` |
|
|
303
|
+
| `ASSETS_MISSING` | Cesium 或 sdk-render 静态资源访问不到 |
|
|
304
|
+
| `RENDER_INIT_FAILED` | Viewer / Render 创建失败,或切画质失败 |
|
|
305
|
+
| `QUALITY_UNSUPPORTED` | 当前 sdk-render 不支持所选画质 |
|
|
306
|
+
| `LAYER_KIND_UNKNOWN` / `LAYER_DUPLICATE` / `LAYER_NOT_FOUND` | 图层种类未注册 / id 重复 / 不存在 |
|
|
307
|
+
| `LAYER_LOAD_FAILED` | 图层数据读取或解析失败(URL 404、GeoJSON 坏了、3D Tiles 加载失败、挖坑失败) |
|
|
308
|
+
| `PBR_UNSUPPORTED` | 用到 PBR(`tileset3d` 的 `pbr`、`setMaterial`)但 sdk-render 不是 4.x |
|
|
309
|
+
| `ENVIRONMENT_UNSUPPORTED` | 用到场景预设、环境效果开关但 sdk-render 不是 4.x |
|
|
310
|
+
| `DESTROYED` | 地球已销毁 |
|
|
311
|
+
|
|
312
|
+
## 开发
|
|
313
|
+
|
|
314
|
+
```bash
|
|
315
|
+
pnpm install
|
|
316
|
+
pnpm check # typecheck + test + build
|
|
317
|
+
pnpm example:dev # 构建后启动 examples/vue
|
|
318
|
+
```
|
|
319
|
+
|
|
320
|
+
示例页的令牌只从 `examples/vue/.env.local` 读(见 `.env.example`,该文件不入库)。
|