cesium_dev_kit 1.1.24 → 1.2.1

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/dist/index.d.mts CHANGED
@@ -53,6 +53,13 @@ interface TerrainLngLat {
53
53
  interface TerrainLngLatHeight extends TerrainLngLat {
54
54
  height: number;
55
55
  }
56
+ /** 经纬度包围盒 */
57
+ interface TerrainBounds {
58
+ minLng: number;
59
+ minLat: number;
60
+ maxLng: number;
61
+ maxLat: number;
62
+ }
56
63
  /** 地形编辑模式的字面量类型 */
57
64
  type TerrainEditMode = 'sink' | 'raise' | 'flatten' | 'smooth';
58
65
  /** 形变参数 */
@@ -88,6 +95,28 @@ interface TerrainStats {
88
95
  /** 笔刷模式:抬升 / 下沉 / 整平到目标高度 / 平滑 */
89
96
  type TerrainBrushMode = 'raise' | 'lower' | 'level' | 'smooth';
90
97
 
98
+ /**
99
+ * 一份地形高度场载荷(可直接 `JSON.stringify`)。
100
+ *
101
+ * `base` / `current` 是 base64 编码的 Float32 小端字节流,长度必须是
102
+ * `(segments + 1)² × 4` 字节;解码时会校验,损坏或被截断会直接报错,
103
+ * 而不是悄悄渲染出一块乱七八糟的地形。
104
+ */
105
+ interface TerrainHeightsPayload {
106
+ /** 每边划分数(顶点数 = segments + 1) */
107
+ segments: number;
108
+ /** 边缘过渡宽度(米) */
109
+ slopeWidth: number;
110
+ /** 是否填平多边形内部空洞(与导出时一致,决定 inside 掩膜) */
111
+ fillHoles: boolean;
112
+ /** 格网经纬度范围,载入时用来核对多边形是否配错 */
113
+ bounds: TerrainBounds;
114
+ /** 原始地形高度,base64(Float32 小端) */
115
+ base: string;
116
+ /** 编辑后地形高度,base64(Float32 小端) */
117
+ current: string;
118
+ }
119
+
91
120
  /** 多边形顶点输入:`[lng, lat]`、`[lng, lat, height]`、`{lng, lat}` 或 Cesium.Cartesian3 */
92
121
  type TerrainEditPosition = [number, number] | [number, number, number] | TerrainLngLat | TerrainLngLatHeight | any;
93
122
  /** 绘制参数 */
@@ -175,15 +204,86 @@ interface TerrainEditAreaOptions {
175
204
  /** 是否把区域内部被包住的空洞填平,默认 true(见 setPolygon) */
176
205
  fillHoles?: boolean;
177
206
  /**
178
- * 是否启用程序化岩土材质,默认 false。
207
+ * 是否启用程序化岩土材质,默认 true。
179
208
  *
180
- * 这是给「在近乎垂直的陡壁上强行贴影像」准备的高级选项,正常开挖不需要:
181
- * 笔刷现在刷出的是平底平台 + 窄立面,立面只有几米宽,影像几乎不被拉伸;
182
- * 台阶的层次靠几何坡折和方向性明暗表现,比换一张贴图清楚得多。
183
- * 打开后按「坡度 + 挖填深度」把影像渐变成岩土。
209
+ * 陡壁上的卫星影像是平面俯视图,竖向铺到立面上必然发虚;打开后按「坡度 + 挖填深度」
210
+ * 在影像之上叠一层 3D 噪声岩土,近垂直立面会逐渐换成土石断面。缓坡仍以影像为主。
211
+ * 需要完全保留影像时显式关掉。
184
212
  */
185
213
  cutSurface?: boolean;
186
214
  }
215
+ /** 笔刷参数快照(不含只在一次笔画内有效的 `targetHeight`) */
216
+ type TerrainEditBrushState = Required<Omit<TerrainEditBrushOptions, 'targetHeight'>>;
217
+ /** 笔刷区域参数快照,便于按同样的范围重建 */
218
+ interface TerrainEditAreaInfo {
219
+ /** 区域中心 */
220
+ center: TerrainLngLat;
221
+ /** 边长(米) */
222
+ size: number;
223
+ /** 每边划分数 */
224
+ segments: number;
225
+ /** 边缘过渡宽度(米) */
226
+ feather: number;
227
+ }
228
+ /** 导出时一并带走的表现状态 */
229
+ interface TerrainEditViewState {
230
+ /** 水面高程(米),null 表示没有水面 */
231
+ waterLevel: number | null;
232
+ /** 是否显示等高线 */
233
+ contour: boolean;
234
+ /** 等高距(米),0 表示按高差自动取 */
235
+ contourInterval: number;
236
+ /** 是否使用影像贴图 */
237
+ texture: boolean;
238
+ /** 是否启用程序化岩土材质 */
239
+ cutSurface: boolean;
240
+ }
241
+ /**
242
+ * 地形编辑数据包(`exportData()` 的返回值)。
243
+ *
244
+ * 整体是可 `JSON.stringify` 的纯数据:没有类实例、没有 TypedArray、没有 DOM 引用,
245
+ * 所以能直接 `POST` 给后端、塞进 `localStorage`、写进 IndexedDB 或做成文件下载。
246
+ *
247
+ * 高度场是 **base + current** 两份:只存 current 的话,载入后就没法再算挖填方、
248
+ * 也没法把坡面明暗重新烘对,二次编辑会「看起来一样、但所有统计都变 0」。
249
+ */
250
+ interface TerrainEditSnapshot {
251
+ /** 固定标识:`cesium-dev-kit:terrain-edit`,用来识别数据来源 */
252
+ kind: 'cesium-dev-kit:terrain-edit';
253
+ /** 数据格式版本,当前为 1;结构不兼容变更时递增 */
254
+ version: number;
255
+ /** 导出时间(ISO 8601) */
256
+ createdAt: string;
257
+ /** `area`:`setArea()` 铺的矩形;`polygon`:手绘 / `setPolygon()` 的范围 */
258
+ mode: 'area' | 'polygon';
259
+ /** `setArea()` 的原始参数,`polygon` 模式下为 null */
260
+ area: TerrainEditAreaInfo | null;
261
+ /** 编辑范围顶点(含高度) */
262
+ polygon: TerrainLngLatHeight[];
263
+ /** 高度场与重建格网所需的参数 */
264
+ grid: TerrainHeightsPayload;
265
+ /** 表现状态 */
266
+ view: TerrainEditViewState;
267
+ /** 笔刷参数,载入后可接着刷 */
268
+ brush: TerrainEditBrushState;
269
+ /** 导出时的土方统计,便于「不载入模型也能读数据」的展示场景 */
270
+ stats: TerrainEditStatsResult | null;
271
+ }
272
+ /**
273
+ * 内存形态的高度场(`getHeightField()` 的返回值)。
274
+ *
275
+ * 不需要序列化、只想马上算点东西时用它:数组是副本,改它不会影响场景。
276
+ */
277
+ interface TerrainHeightField {
278
+ /** 每边划分数(顶点数 = segments + 1) */
279
+ segments: number;
280
+ /** 格网覆盖的经纬度范围 */
281
+ bounds: TerrainBounds;
282
+ /** 原始地形高度(米) */
283
+ base: Float32Array;
284
+ /** 编辑后地形高度(米);与 `base` 之差即每点挖填量(负数挖、正数填) */
285
+ current: Float32Array;
286
+ }
187
287
  /** 创建地形编辑模块的参数 */
188
288
  interface TerrainEditModuleOptions {
189
289
  /** 复用 kit 的 ThreeJs 实例(必填,且需先调用 initThree) */
@@ -286,6 +386,72 @@ interface TerrainEditInstance {
286
386
  * 获取当前多边形(度)。
287
387
  */
288
388
  getPolygon(): TerrainLngLatHeight[];
389
+ /**
390
+ * 导出当前编辑结果,得到一份可直接 `JSON.stringify` 的数据包。
391
+ *
392
+ * **为什么是「返回数据」而不是「保存文件」**:这个模块跑在调用方的页面里,
393
+ * 数据落到哪儿(后端接口、localStorage、对象存储、GIS 文件、剪贴板)属于业务决定,
394
+ * 库不该替用户选。所以这里只产出**完整、自包含、可序列化**的快照,
395
+ * 存哪儿、存多久、要不要加密压缩,交给调用方;示例页里的「保存数据」
396
+ * 就是拿这个返回值自己做了个下载,而不是库内置了一套存储。
397
+ *
398
+ * 快照不只包含高度:二次编辑需要「原始地形 + 几何参数」才能正确重算挖填方、
399
+ * 重烘坡面明暗、继续用笔刷,所以 `grid.base` 与 `grid.current` 两份高度场都会带上
400
+ * (Float32 原样 base64,往返逐位无损),并附带多边形、区域参数、水面 / 等高线 /
401
+ * 贴图状态以及笔刷设置。
402
+ *
403
+ * 体量:`segments = 160` 时约 277KB(两份 161×161 的 Float32,base64 后),gzip 约 180KB。
404
+ * 这份开销是「无损」换来的:需要更小的载荷就降低 `setArea({ segments })`,
405
+ * 或者只用 `getHeightField()` 自己量化 / 转成 GeoTIFF 等格式。
406
+ *
407
+ * @returns 数据包;尚未圈定编辑范围时返回 null
408
+ * @example
409
+ * // 存到自己的后端
410
+ * const data = terrainEdit.exportData()
411
+ * await fetch('/api/terrain/1', { method: 'POST', body: JSON.stringify(data) })
412
+ *
413
+ * // 或者做成文件让用户下载(下载这一步属于业务侧,不在库里)
414
+ * const blob = new Blob([JSON.stringify(data)], { type: 'application/json' })
415
+ * const a = document.createElement('a')
416
+ * a.href = URL.createObjectURL(blob)
417
+ * a.download = 'terrain.json'
418
+ * a.click()
419
+ */
420
+ exportData(): TerrainEditSnapshot | null;
421
+ /**
422
+ * 载入 `exportData()` 导出的数据,恢复到可继续编辑的状态。
423
+ *
424
+ * 与 `setPolygon()` 的关键区别:**不会再采样地形**。高度直接从数据包里恢复,
425
+ * 所以即使此刻没有配置地形服务、或者原地形数据已经变了,也能一模一样地复原;
426
+ * 载入后笔刷、撤销、统计、水面、等高线照常工作,地表贴图按新范围在后台重新取。
427
+ *
428
+ * 数据包结构不对(不是本模块导出的、版本不匹配、base64 损坏、长度对不上、
429
+ * 范围与 polygon 不匹配)都会抛 `INVALID_ARGUMENT`,不会渲染出一块错位的地形。
430
+ *
431
+ * @param snapshot - `exportData()` 的返回值,或它 `JSON.parse` 之后的对象;
432
+ * 也可以直接给 JSON 字符串(例如 `localStorage.getItem()` 的返回值),内部会自己解析
433
+ * @example
434
+ * const data = await (await fetch('/api/terrain/1')).json()
435
+ * terrainEdit.importData(data).enableBrush(true)
436
+ *
437
+ * // 从 localStorage 读也一样
438
+ * terrainEdit.importData(localStorage.getItem('terrain-1') || '')
439
+ */
440
+ importData(snapshot: TerrainEditSnapshot | string): TerrainEditInstance;
441
+ /**
442
+ * 取当前高度场(Float32Array 副本),用于在内存里做二次计算。
443
+ *
444
+ * 不需要序列化、只要数值时用这个:不经过 base64,直接拿到 `base` / `current`,
445
+ * 两者之差就是每个顶点的挖填量(负数挖、正数填),可以直接喂给等高线、
446
+ * 坡度分析、导出成 GeoTIFF 或自己的格网格式。数组是副本,改它不影响场景。
447
+ *
448
+ * @returns 高度场;尚未圈定编辑范围时返回 null
449
+ * @example
450
+ * const field = terrainEdit.getHeightField()
451
+ * const delta = field.current.map((h, i) => h - field.base[i])
452
+ * console.log('最大挖深', Math.min(...delta))
453
+ */
454
+ getHeightField(): TerrainHeightField | null;
289
455
  /**
290
456
  * 就地开辟一块可连续涂抹的地形编辑区域(不需要先画多边形)。
291
457
  *
@@ -340,11 +506,10 @@ interface TerrainEditInstance {
340
506
  */
341
507
  setTextureEnabled(enabled: boolean): TerrainEditInstance;
342
508
  /**
343
- * 挖/填出来的坡面是否换成岩土材质(默认 true)。
509
+ * 挖/填出来的坡面是否叠加程序化岩土材质(默认 true)。
344
510
  *
345
- * 影像按经纬度平面取样,坡面越陡被拉得越长(拉伸比 = sqrt(1 + 坡度²)),
346
- * 挖到几百米深时坑壁会糊成一片色带。打开后按「坡度 + 挖填深度」把影像渐变成
347
- * 程序化岩土,消除这种拉伸;关掉则完全保留原始影像。
511
+ * 陡壁上的卫星影像是平面俯视图,近垂直面会发虚;打开后按「坡度 + 挖填深度」
512
+ * 在影像之上叠一层 3D 噪声岩土,更像真实的开挖断面。缓坡仍保留影像。
348
513
  * @example
349
514
  * terrainEdit.setCutSurfaceEnabled(false)
350
515
  */
@@ -671,4 +836,4 @@ interface InitCesiumConstructor {
671
836
  }
672
837
  declare const initCesium: InitCesiumConstructor;
673
838
 
674
- export { type CesiumContext, type CesiumContextOptions, CesiumDevKitError, type CesiumDevKitErrorCode, type CesiumDevKitErrorHandler, CesiumGlobal, type CreateKitOptions, type ResModulesType, TerrainEdit, type TerrainEditApplyOptions, type TerrainEditConstructor, type TerrainEditDrawOptions, type TerrainEditInstance, type TerrainEditMode, type TerrainEditModuleOptions, type TerrainEditPosition, type TerrainEditStatsResult, assertBrowser, createContext, createKit, disposeContext, getErrorHandler, initCesium, isBrowser, isCesiumDevKitError, reportError, setErrorHandler };
839
+ export { type CesiumContext, type CesiumContextOptions, CesiumDevKitError, type CesiumDevKitErrorCode, type CesiumDevKitErrorHandler, CesiumGlobal, type CreateKitOptions, type ResModulesType, TerrainEdit, type TerrainEditApplyOptions, type TerrainEditAreaInfo, type TerrainEditBrushState, type TerrainEditConstructor, type TerrainEditDrawOptions, type TerrainEditInstance, type TerrainEditMode, type TerrainEditModuleOptions, type TerrainEditPosition, type TerrainEditSnapshot, type TerrainEditStatsResult, type TerrainEditViewState, type TerrainHeightField, type TerrainHeightsPayload, assertBrowser, createContext, createKit, disposeContext, getErrorHandler, initCesium, isBrowser, isCesiumDevKitError, reportError, setErrorHandler };
package/dist/index.d.ts CHANGED
@@ -53,6 +53,13 @@ interface TerrainLngLat {
53
53
  interface TerrainLngLatHeight extends TerrainLngLat {
54
54
  height: number;
55
55
  }
56
+ /** 经纬度包围盒 */
57
+ interface TerrainBounds {
58
+ minLng: number;
59
+ minLat: number;
60
+ maxLng: number;
61
+ maxLat: number;
62
+ }
56
63
  /** 地形编辑模式的字面量类型 */
57
64
  type TerrainEditMode = 'sink' | 'raise' | 'flatten' | 'smooth';
58
65
  /** 形变参数 */
@@ -88,6 +95,28 @@ interface TerrainStats {
88
95
  /** 笔刷模式:抬升 / 下沉 / 整平到目标高度 / 平滑 */
89
96
  type TerrainBrushMode = 'raise' | 'lower' | 'level' | 'smooth';
90
97
 
98
+ /**
99
+ * 一份地形高度场载荷(可直接 `JSON.stringify`)。
100
+ *
101
+ * `base` / `current` 是 base64 编码的 Float32 小端字节流,长度必须是
102
+ * `(segments + 1)² × 4` 字节;解码时会校验,损坏或被截断会直接报错,
103
+ * 而不是悄悄渲染出一块乱七八糟的地形。
104
+ */
105
+ interface TerrainHeightsPayload {
106
+ /** 每边划分数(顶点数 = segments + 1) */
107
+ segments: number;
108
+ /** 边缘过渡宽度(米) */
109
+ slopeWidth: number;
110
+ /** 是否填平多边形内部空洞(与导出时一致,决定 inside 掩膜) */
111
+ fillHoles: boolean;
112
+ /** 格网经纬度范围,载入时用来核对多边形是否配错 */
113
+ bounds: TerrainBounds;
114
+ /** 原始地形高度,base64(Float32 小端) */
115
+ base: string;
116
+ /** 编辑后地形高度,base64(Float32 小端) */
117
+ current: string;
118
+ }
119
+
91
120
  /** 多边形顶点输入:`[lng, lat]`、`[lng, lat, height]`、`{lng, lat}` 或 Cesium.Cartesian3 */
92
121
  type TerrainEditPosition = [number, number] | [number, number, number] | TerrainLngLat | TerrainLngLatHeight | any;
93
122
  /** 绘制参数 */
@@ -175,15 +204,86 @@ interface TerrainEditAreaOptions {
175
204
  /** 是否把区域内部被包住的空洞填平,默认 true(见 setPolygon) */
176
205
  fillHoles?: boolean;
177
206
  /**
178
- * 是否启用程序化岩土材质,默认 false。
207
+ * 是否启用程序化岩土材质,默认 true。
179
208
  *
180
- * 这是给「在近乎垂直的陡壁上强行贴影像」准备的高级选项,正常开挖不需要:
181
- * 笔刷现在刷出的是平底平台 + 窄立面,立面只有几米宽,影像几乎不被拉伸;
182
- * 台阶的层次靠几何坡折和方向性明暗表现,比换一张贴图清楚得多。
183
- * 打开后按「坡度 + 挖填深度」把影像渐变成岩土。
209
+ * 陡壁上的卫星影像是平面俯视图,竖向铺到立面上必然发虚;打开后按「坡度 + 挖填深度」
210
+ * 在影像之上叠一层 3D 噪声岩土,近垂直立面会逐渐换成土石断面。缓坡仍以影像为主。
211
+ * 需要完全保留影像时显式关掉。
184
212
  */
185
213
  cutSurface?: boolean;
186
214
  }
215
+ /** 笔刷参数快照(不含只在一次笔画内有效的 `targetHeight`) */
216
+ type TerrainEditBrushState = Required<Omit<TerrainEditBrushOptions, 'targetHeight'>>;
217
+ /** 笔刷区域参数快照,便于按同样的范围重建 */
218
+ interface TerrainEditAreaInfo {
219
+ /** 区域中心 */
220
+ center: TerrainLngLat;
221
+ /** 边长(米) */
222
+ size: number;
223
+ /** 每边划分数 */
224
+ segments: number;
225
+ /** 边缘过渡宽度(米) */
226
+ feather: number;
227
+ }
228
+ /** 导出时一并带走的表现状态 */
229
+ interface TerrainEditViewState {
230
+ /** 水面高程(米),null 表示没有水面 */
231
+ waterLevel: number | null;
232
+ /** 是否显示等高线 */
233
+ contour: boolean;
234
+ /** 等高距(米),0 表示按高差自动取 */
235
+ contourInterval: number;
236
+ /** 是否使用影像贴图 */
237
+ texture: boolean;
238
+ /** 是否启用程序化岩土材质 */
239
+ cutSurface: boolean;
240
+ }
241
+ /**
242
+ * 地形编辑数据包(`exportData()` 的返回值)。
243
+ *
244
+ * 整体是可 `JSON.stringify` 的纯数据:没有类实例、没有 TypedArray、没有 DOM 引用,
245
+ * 所以能直接 `POST` 给后端、塞进 `localStorage`、写进 IndexedDB 或做成文件下载。
246
+ *
247
+ * 高度场是 **base + current** 两份:只存 current 的话,载入后就没法再算挖填方、
248
+ * 也没法把坡面明暗重新烘对,二次编辑会「看起来一样、但所有统计都变 0」。
249
+ */
250
+ interface TerrainEditSnapshot {
251
+ /** 固定标识:`cesium-dev-kit:terrain-edit`,用来识别数据来源 */
252
+ kind: 'cesium-dev-kit:terrain-edit';
253
+ /** 数据格式版本,当前为 1;结构不兼容变更时递增 */
254
+ version: number;
255
+ /** 导出时间(ISO 8601) */
256
+ createdAt: string;
257
+ /** `area`:`setArea()` 铺的矩形;`polygon`:手绘 / `setPolygon()` 的范围 */
258
+ mode: 'area' | 'polygon';
259
+ /** `setArea()` 的原始参数,`polygon` 模式下为 null */
260
+ area: TerrainEditAreaInfo | null;
261
+ /** 编辑范围顶点(含高度) */
262
+ polygon: TerrainLngLatHeight[];
263
+ /** 高度场与重建格网所需的参数 */
264
+ grid: TerrainHeightsPayload;
265
+ /** 表现状态 */
266
+ view: TerrainEditViewState;
267
+ /** 笔刷参数,载入后可接着刷 */
268
+ brush: TerrainEditBrushState;
269
+ /** 导出时的土方统计,便于「不载入模型也能读数据」的展示场景 */
270
+ stats: TerrainEditStatsResult | null;
271
+ }
272
+ /**
273
+ * 内存形态的高度场(`getHeightField()` 的返回值)。
274
+ *
275
+ * 不需要序列化、只想马上算点东西时用它:数组是副本,改它不会影响场景。
276
+ */
277
+ interface TerrainHeightField {
278
+ /** 每边划分数(顶点数 = segments + 1) */
279
+ segments: number;
280
+ /** 格网覆盖的经纬度范围 */
281
+ bounds: TerrainBounds;
282
+ /** 原始地形高度(米) */
283
+ base: Float32Array;
284
+ /** 编辑后地形高度(米);与 `base` 之差即每点挖填量(负数挖、正数填) */
285
+ current: Float32Array;
286
+ }
187
287
  /** 创建地形编辑模块的参数 */
188
288
  interface TerrainEditModuleOptions {
189
289
  /** 复用 kit 的 ThreeJs 实例(必填,且需先调用 initThree) */
@@ -286,6 +386,72 @@ interface TerrainEditInstance {
286
386
  * 获取当前多边形(度)。
287
387
  */
288
388
  getPolygon(): TerrainLngLatHeight[];
389
+ /**
390
+ * 导出当前编辑结果,得到一份可直接 `JSON.stringify` 的数据包。
391
+ *
392
+ * **为什么是「返回数据」而不是「保存文件」**:这个模块跑在调用方的页面里,
393
+ * 数据落到哪儿(后端接口、localStorage、对象存储、GIS 文件、剪贴板)属于业务决定,
394
+ * 库不该替用户选。所以这里只产出**完整、自包含、可序列化**的快照,
395
+ * 存哪儿、存多久、要不要加密压缩,交给调用方;示例页里的「保存数据」
396
+ * 就是拿这个返回值自己做了个下载,而不是库内置了一套存储。
397
+ *
398
+ * 快照不只包含高度:二次编辑需要「原始地形 + 几何参数」才能正确重算挖填方、
399
+ * 重烘坡面明暗、继续用笔刷,所以 `grid.base` 与 `grid.current` 两份高度场都会带上
400
+ * (Float32 原样 base64,往返逐位无损),并附带多边形、区域参数、水面 / 等高线 /
401
+ * 贴图状态以及笔刷设置。
402
+ *
403
+ * 体量:`segments = 160` 时约 277KB(两份 161×161 的 Float32,base64 后),gzip 约 180KB。
404
+ * 这份开销是「无损」换来的:需要更小的载荷就降低 `setArea({ segments })`,
405
+ * 或者只用 `getHeightField()` 自己量化 / 转成 GeoTIFF 等格式。
406
+ *
407
+ * @returns 数据包;尚未圈定编辑范围时返回 null
408
+ * @example
409
+ * // 存到自己的后端
410
+ * const data = terrainEdit.exportData()
411
+ * await fetch('/api/terrain/1', { method: 'POST', body: JSON.stringify(data) })
412
+ *
413
+ * // 或者做成文件让用户下载(下载这一步属于业务侧,不在库里)
414
+ * const blob = new Blob([JSON.stringify(data)], { type: 'application/json' })
415
+ * const a = document.createElement('a')
416
+ * a.href = URL.createObjectURL(blob)
417
+ * a.download = 'terrain.json'
418
+ * a.click()
419
+ */
420
+ exportData(): TerrainEditSnapshot | null;
421
+ /**
422
+ * 载入 `exportData()` 导出的数据,恢复到可继续编辑的状态。
423
+ *
424
+ * 与 `setPolygon()` 的关键区别:**不会再采样地形**。高度直接从数据包里恢复,
425
+ * 所以即使此刻没有配置地形服务、或者原地形数据已经变了,也能一模一样地复原;
426
+ * 载入后笔刷、撤销、统计、水面、等高线照常工作,地表贴图按新范围在后台重新取。
427
+ *
428
+ * 数据包结构不对(不是本模块导出的、版本不匹配、base64 损坏、长度对不上、
429
+ * 范围与 polygon 不匹配)都会抛 `INVALID_ARGUMENT`,不会渲染出一块错位的地形。
430
+ *
431
+ * @param snapshot - `exportData()` 的返回值,或它 `JSON.parse` 之后的对象;
432
+ * 也可以直接给 JSON 字符串(例如 `localStorage.getItem()` 的返回值),内部会自己解析
433
+ * @example
434
+ * const data = await (await fetch('/api/terrain/1')).json()
435
+ * terrainEdit.importData(data).enableBrush(true)
436
+ *
437
+ * // 从 localStorage 读也一样
438
+ * terrainEdit.importData(localStorage.getItem('terrain-1') || '')
439
+ */
440
+ importData(snapshot: TerrainEditSnapshot | string): TerrainEditInstance;
441
+ /**
442
+ * 取当前高度场(Float32Array 副本),用于在内存里做二次计算。
443
+ *
444
+ * 不需要序列化、只要数值时用这个:不经过 base64,直接拿到 `base` / `current`,
445
+ * 两者之差就是每个顶点的挖填量(负数挖、正数填),可以直接喂给等高线、
446
+ * 坡度分析、导出成 GeoTIFF 或自己的格网格式。数组是副本,改它不影响场景。
447
+ *
448
+ * @returns 高度场;尚未圈定编辑范围时返回 null
449
+ * @example
450
+ * const field = terrainEdit.getHeightField()
451
+ * const delta = field.current.map((h, i) => h - field.base[i])
452
+ * console.log('最大挖深', Math.min(...delta))
453
+ */
454
+ getHeightField(): TerrainHeightField | null;
289
455
  /**
290
456
  * 就地开辟一块可连续涂抹的地形编辑区域(不需要先画多边形)。
291
457
  *
@@ -340,11 +506,10 @@ interface TerrainEditInstance {
340
506
  */
341
507
  setTextureEnabled(enabled: boolean): TerrainEditInstance;
342
508
  /**
343
- * 挖/填出来的坡面是否换成岩土材质(默认 true)。
509
+ * 挖/填出来的坡面是否叠加程序化岩土材质(默认 true)。
344
510
  *
345
- * 影像按经纬度平面取样,坡面越陡被拉得越长(拉伸比 = sqrt(1 + 坡度²)),
346
- * 挖到几百米深时坑壁会糊成一片色带。打开后按「坡度 + 挖填深度」把影像渐变成
347
- * 程序化岩土,消除这种拉伸;关掉则完全保留原始影像。
511
+ * 陡壁上的卫星影像是平面俯视图,近垂直面会发虚;打开后按「坡度 + 挖填深度」
512
+ * 在影像之上叠一层 3D 噪声岩土,更像真实的开挖断面。缓坡仍保留影像。
348
513
  * @example
349
514
  * terrainEdit.setCutSurfaceEnabled(false)
350
515
  */
@@ -671,4 +836,4 @@ interface InitCesiumConstructor {
671
836
  }
672
837
  declare const initCesium: InitCesiumConstructor;
673
838
 
674
- export { type CesiumContext, type CesiumContextOptions, CesiumDevKitError, type CesiumDevKitErrorCode, type CesiumDevKitErrorHandler, CesiumGlobal, type CreateKitOptions, type ResModulesType, TerrainEdit, type TerrainEditApplyOptions, type TerrainEditConstructor, type TerrainEditDrawOptions, type TerrainEditInstance, type TerrainEditMode, type TerrainEditModuleOptions, type TerrainEditPosition, type TerrainEditStatsResult, assertBrowser, createContext, createKit, disposeContext, getErrorHandler, initCesium, isBrowser, isCesiumDevKitError, reportError, setErrorHandler };
839
+ export { type CesiumContext, type CesiumContextOptions, CesiumDevKitError, type CesiumDevKitErrorCode, type CesiumDevKitErrorHandler, CesiumGlobal, type CreateKitOptions, type ResModulesType, TerrainEdit, type TerrainEditApplyOptions, type TerrainEditAreaInfo, type TerrainEditBrushState, type TerrainEditConstructor, type TerrainEditDrawOptions, type TerrainEditInstance, type TerrainEditMode, type TerrainEditModuleOptions, type TerrainEditPosition, type TerrainEditSnapshot, type TerrainEditStatsResult, type TerrainEditViewState, type TerrainHeightField, type TerrainHeightsPayload, assertBrowser, createContext, createKit, disposeContext, getErrorHandler, initCesium, isBrowser, isCesiumDevKitError, reportError, setErrorHandler };