cesium_dev_kit 1.1.23 → 1.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 +47 -2
- package/README.md +12 -6
- package/README.zh-CN.md +11 -6
- package/dist/control.cjs +2 -2
- package/dist/control.mjs +2 -2
- package/dist/custom-cesium-plugin.cjs +5 -5
- package/dist/custom-cesium-plugin.mjs +5 -5
- package/dist/graphics.cjs +2 -2
- package/dist/graphics.mjs +2 -2
- package/dist/index.cjs +117 -35
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.mts +505 -2
- package/dist/index.d.ts +505 -2
- package/dist/index.mjs +117 -35
- package/dist/index.mjs.map +1 -1
- package/dist/pass-effect.cjs +5 -5
- package/dist/pass-effect.mjs +5 -5
- package/dist/plugin.cjs +2 -2
- package/dist/plugin.mjs +2 -2
- package/dist/primitive.cjs +6 -6
- package/dist/primitive.cjs.map +1 -1
- package/dist/primitive.mjs +6 -6
- package/dist/primitive.mjs.map +1 -1
- package/dist/three.cjs +2 -2
- package/dist/three.cjs.map +1 -1
- package/dist/three.mjs +2 -2
- package/dist/three.mjs.map +1 -1
- package/package.json +5 -4
package/dist/index.d.mts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import {
|
|
1
|
+
import { V as Viewer, C as CesiumGlobal, S as StaticResourceConf, B as BaseInstance } from './Base-DH8H9suE.mjs';
|
|
2
2
|
import { M as MaterialInstance } from './Material-CeZ4l-tY.mjs';
|
|
3
3
|
export { a as Material } from './Material-CeZ4l-tY.mjs';
|
|
4
4
|
import { G as GraphicsInstance } from './Graphics-QE3Gb43w.mjs';
|
|
@@ -37,6 +37,503 @@ interface ShadersInstance {
|
|
|
37
37
|
_getCircleScanShader(options?: any): any;
|
|
38
38
|
}
|
|
39
39
|
|
|
40
|
+
/**
|
|
41
|
+
* 地形编辑的纯几何工具。
|
|
42
|
+
*
|
|
43
|
+
* 这里只做与渲染无关的计算:多边形判定、编辑格网生成、塌陷 / 抬升 / 平整 / 平滑的
|
|
44
|
+
* 高度形变、台阶量化、三角剖分、顶点配色和土方量统计。
|
|
45
|
+
* 不依赖 Cesium / Three.js,可以直接在 Node 里做单元测试。
|
|
46
|
+
*/
|
|
47
|
+
/** 经纬度点(单位:度) */
|
|
48
|
+
interface TerrainLngLat {
|
|
49
|
+
lng: number;
|
|
50
|
+
lat: number;
|
|
51
|
+
}
|
|
52
|
+
/** 带高度的经纬度点(高度单位:米) */
|
|
53
|
+
interface TerrainLngLatHeight extends TerrainLngLat {
|
|
54
|
+
height: number;
|
|
55
|
+
}
|
|
56
|
+
/** 经纬度包围盒 */
|
|
57
|
+
interface TerrainBounds {
|
|
58
|
+
minLng: number;
|
|
59
|
+
minLat: number;
|
|
60
|
+
maxLng: number;
|
|
61
|
+
maxLat: number;
|
|
62
|
+
}
|
|
63
|
+
/** 地形编辑模式的字面量类型 */
|
|
64
|
+
type TerrainEditMode = 'sink' | 'raise' | 'flatten' | 'smooth';
|
|
65
|
+
/** 形变参数 */
|
|
66
|
+
interface TerrainDeformOptions {
|
|
67
|
+
/** 编辑模式,默认 `sink`(塌陷) */
|
|
68
|
+
mode?: TerrainEditMode;
|
|
69
|
+
/** 塌陷深度 / 抬升高度 / 平整偏移(米),默认 30 */
|
|
70
|
+
depth?: number;
|
|
71
|
+
/** 台阶高度(米),0 表示平滑过渡;矿山台阶常用 4~12 米 */
|
|
72
|
+
stepHeight?: number;
|
|
73
|
+
/** 平整目标高度(米),不传时取内圈平均高度 */
|
|
74
|
+
flattenHeight?: number;
|
|
75
|
+
/** 平滑迭代次数,默认 2 */
|
|
76
|
+
smoothIterations?: number;
|
|
77
|
+
}
|
|
78
|
+
/** 地形统计信息 */
|
|
79
|
+
interface TerrainStats {
|
|
80
|
+
/** 多边形面积(平方米) */
|
|
81
|
+
area: number;
|
|
82
|
+
/** 格网内最低点高度(米) */
|
|
83
|
+
minHeight: number;
|
|
84
|
+
/** 格网内最高点高度(米) */
|
|
85
|
+
maxHeight: number;
|
|
86
|
+
/** 相对原始地形挖掉的体积(立方米,正值表示挖方) */
|
|
87
|
+
cutVolume: number;
|
|
88
|
+
/** 相对原始地形填上的体积(立方米,正值表示填方) */
|
|
89
|
+
fillVolume: number;
|
|
90
|
+
/** 参与编辑的顶点数 */
|
|
91
|
+
vertexCount: number;
|
|
92
|
+
/** 单元边长(米) */
|
|
93
|
+
cellSize: number;
|
|
94
|
+
}
|
|
95
|
+
/** 笔刷模式:抬升 / 下沉 / 整平到目标高度 / 平滑 */
|
|
96
|
+
type TerrainBrushMode = 'raise' | 'lower' | 'level' | 'smooth';
|
|
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
|
+
|
|
120
|
+
/** 多边形顶点输入:`[lng, lat]`、`[lng, lat, height]`、`{lng, lat}` 或 Cesium.Cartesian3 */
|
|
121
|
+
type TerrainEditPosition = [number, number] | [number, number, number] | TerrainLngLat | TerrainLngLatHeight | any;
|
|
122
|
+
/** 绘制参数 */
|
|
123
|
+
interface TerrainEditDrawOptions {
|
|
124
|
+
/** 线条颜色,默认 `#7defff` */
|
|
125
|
+
color?: string;
|
|
126
|
+
/** 线宽(像素),默认 4 */
|
|
127
|
+
width?: number;
|
|
128
|
+
/** 绘制完成后回调,参数为经纬度顶点(度) */
|
|
129
|
+
callback?: (polygon: TerrainLngLatHeight[]) => void;
|
|
130
|
+
/** 网格分辨率(每边划分数),默认 64 */
|
|
131
|
+
segments?: number;
|
|
132
|
+
}
|
|
133
|
+
/** 形变参数(在地形模块基础上增加了水位) */
|
|
134
|
+
interface TerrainEditApplyOptions extends TerrainDeformOptions {
|
|
135
|
+
/**
|
|
136
|
+
* 水面高度:
|
|
137
|
+
* - `0~1` 视为相对坑底的相对水位(0.3 表示坑深的 30%)
|
|
138
|
+
* - 大于 `1` 视为绝对高程(米)
|
|
139
|
+
* - `'auto'` 自动取坑底以上 28%
|
|
140
|
+
* - `null` 不显示水面
|
|
141
|
+
*/
|
|
142
|
+
waterLevel?: number | 'auto' | null;
|
|
143
|
+
/** 是否重建水面(默认 true) */
|
|
144
|
+
rebuildWater?: boolean;
|
|
145
|
+
}
|
|
146
|
+
/** 地形统计(附加水位信息) */
|
|
147
|
+
interface TerrainEditStatsResult extends TerrainStats {
|
|
148
|
+
/** 当前水面高程(米),无水面时为 null */
|
|
149
|
+
waterLevel: number | null;
|
|
150
|
+
/** 顶点数量 */
|
|
151
|
+
vertices: number;
|
|
152
|
+
}
|
|
153
|
+
/** 笔刷参数(对应「按住拖动连续刷」的交互) */
|
|
154
|
+
interface TerrainEditBrushOptions {
|
|
155
|
+
/** 笔刷模式,默认 `lower`(下沉) */
|
|
156
|
+
mode?: TerrainBrushMode;
|
|
157
|
+
/** 笔刷半径(米),默认 110 */
|
|
158
|
+
radius?: number;
|
|
159
|
+
/**
|
|
160
|
+
* 向目标标高推进的比例 0~1,默认 1(一步压到绝对平)。
|
|
161
|
+
*
|
|
162
|
+
* 小于 1 时坑底永远压不平、会留着原地面的起伏,看起来就是一片糊。
|
|
163
|
+
* 需要软笔触请换 `mode: 'smooth'`,不要调低这个值。
|
|
164
|
+
*/
|
|
165
|
+
strength?: number;
|
|
166
|
+
/** 平整核心占半径的比例 0~1,默认 0.9:平台几乎铺满笔刷,边缘只留一圈窄立面 */
|
|
167
|
+
hardness?: number;
|
|
168
|
+
/**
|
|
169
|
+
* 坑口不规则度 0~1,默认 0.28。
|
|
170
|
+
*
|
|
171
|
+
* 用世界坐标的值噪声轻微掰动有效半径,让边界不是圆规画出来的。
|
|
172
|
+
* 它只负责「不那么规整」;让笔迹清楚的是一刀切平的标高,不是这个参数。
|
|
173
|
+
* 噪声按世界坐标取样,按住不放反复加深时图案固定,不会抖动或漂移。
|
|
174
|
+
*/
|
|
175
|
+
roughness?: number;
|
|
176
|
+
/**
|
|
177
|
+
* 一级台阶的落差(米),默认 3。
|
|
178
|
+
*
|
|
179
|
+
* 每次落笔都把笔刷核心压到同一个**目标标高**,拖动时整条笔画锁这个值,
|
|
180
|
+
* 于是刷出来是平底平台而不是碗。按住不放由 `SPRAY_INTERVAL` 按拍逐级下降,
|
|
181
|
+
* 所以这个值同时决定台阶的高度和下挖速度。
|
|
182
|
+
*/
|
|
183
|
+
maxDelta?: number;
|
|
184
|
+
/**
|
|
185
|
+
* 一笔之内的累计上限系数(`maxDelta × strokeLimit`)。
|
|
186
|
+
*
|
|
187
|
+
* 默认 `0` 表示**不限制**:按住左键就一直累加,松开才停,和地形软件一致。
|
|
188
|
+
* 只有需要「一刀最多挖多深」时才设置它。
|
|
189
|
+
*/
|
|
190
|
+
strokeLimit?: number;
|
|
191
|
+
/** `level` 模式的目标高程(米),缺省取落笔处原地形高度 */
|
|
192
|
+
targetHeight?: number | null;
|
|
193
|
+
}
|
|
194
|
+
/** 笔刷区域参数 */
|
|
195
|
+
interface TerrainEditAreaOptions {
|
|
196
|
+
/** 区域边长(米),默认 2000 */
|
|
197
|
+
size?: number;
|
|
198
|
+
/** 每边划分数,默认 160 */
|
|
199
|
+
segments?: number;
|
|
200
|
+
/** 边缘过渡宽度(米),默认 80 */
|
|
201
|
+
feather?: number;
|
|
202
|
+
/** 是否取影像作为地表贴图,默认 true */
|
|
203
|
+
texture?: boolean;
|
|
204
|
+
/** 是否把区域内部被包住的空洞填平,默认 true(见 setPolygon) */
|
|
205
|
+
fillHoles?: boolean;
|
|
206
|
+
/**
|
|
207
|
+
* 是否启用程序化岩土材质,默认 false。
|
|
208
|
+
*
|
|
209
|
+
* 这是给「在近乎垂直的陡壁上强行贴影像」准备的高级选项,正常开挖不需要:
|
|
210
|
+
* 笔刷现在刷出的是平底平台 + 窄立面,立面只有几米宽,影像几乎不被拉伸;
|
|
211
|
+
* 台阶的层次靠几何坡折和方向性明暗表现,比换一张贴图清楚得多。
|
|
212
|
+
* 打开后按「坡度 + 挖填深度」把影像渐变成岩土。
|
|
213
|
+
*/
|
|
214
|
+
cutSurface?: boolean;
|
|
215
|
+
}
|
|
216
|
+
/** 笔刷参数快照(不含只在一次笔画内有效的 `targetHeight`) */
|
|
217
|
+
type TerrainEditBrushState = Required<Omit<TerrainEditBrushOptions, 'targetHeight'>>;
|
|
218
|
+
/** 笔刷区域参数快照,便于按同样的范围重建 */
|
|
219
|
+
interface TerrainEditAreaInfo {
|
|
220
|
+
/** 区域中心 */
|
|
221
|
+
center: TerrainLngLat;
|
|
222
|
+
/** 边长(米) */
|
|
223
|
+
size: number;
|
|
224
|
+
/** 每边划分数 */
|
|
225
|
+
segments: number;
|
|
226
|
+
/** 边缘过渡宽度(米) */
|
|
227
|
+
feather: number;
|
|
228
|
+
}
|
|
229
|
+
/** 导出时一并带走的表现状态 */
|
|
230
|
+
interface TerrainEditViewState {
|
|
231
|
+
/** 水面高程(米),null 表示没有水面 */
|
|
232
|
+
waterLevel: number | null;
|
|
233
|
+
/** 是否显示等高线 */
|
|
234
|
+
contour: boolean;
|
|
235
|
+
/** 等高距(米),0 表示按高差自动取 */
|
|
236
|
+
contourInterval: number;
|
|
237
|
+
/** 是否使用影像贴图 */
|
|
238
|
+
texture: boolean;
|
|
239
|
+
/** 是否启用程序化岩土材质 */
|
|
240
|
+
cutSurface: boolean;
|
|
241
|
+
}
|
|
242
|
+
/**
|
|
243
|
+
* 地形编辑数据包(`exportData()` 的返回值)。
|
|
244
|
+
*
|
|
245
|
+
* 整体是可 `JSON.stringify` 的纯数据:没有类实例、没有 TypedArray、没有 DOM 引用,
|
|
246
|
+
* 所以能直接 `POST` 给后端、塞进 `localStorage`、写进 IndexedDB 或做成文件下载。
|
|
247
|
+
*
|
|
248
|
+
* 高度场是 **base + current** 两份:只存 current 的话,载入后就没法再算挖填方、
|
|
249
|
+
* 也没法把坡面明暗重新烘对,二次编辑会「看起来一样、但所有统计都变 0」。
|
|
250
|
+
*/
|
|
251
|
+
interface TerrainEditSnapshot {
|
|
252
|
+
/** 固定标识:`cesium-dev-kit:terrain-edit`,用来识别数据来源 */
|
|
253
|
+
kind: 'cesium-dev-kit:terrain-edit';
|
|
254
|
+
/** 数据格式版本,当前为 1;结构不兼容变更时递增 */
|
|
255
|
+
version: number;
|
|
256
|
+
/** 导出时间(ISO 8601) */
|
|
257
|
+
createdAt: string;
|
|
258
|
+
/** `area`:`setArea()` 铺的矩形;`polygon`:手绘 / `setPolygon()` 的范围 */
|
|
259
|
+
mode: 'area' | 'polygon';
|
|
260
|
+
/** `setArea()` 的原始参数,`polygon` 模式下为 null */
|
|
261
|
+
area: TerrainEditAreaInfo | null;
|
|
262
|
+
/** 编辑范围顶点(含高度) */
|
|
263
|
+
polygon: TerrainLngLatHeight[];
|
|
264
|
+
/** 高度场与重建格网所需的参数 */
|
|
265
|
+
grid: TerrainHeightsPayload;
|
|
266
|
+
/** 表现状态 */
|
|
267
|
+
view: TerrainEditViewState;
|
|
268
|
+
/** 笔刷参数,载入后可接着刷 */
|
|
269
|
+
brush: TerrainEditBrushState;
|
|
270
|
+
/** 导出时的土方统计,便于「不载入模型也能读数据」的展示场景 */
|
|
271
|
+
stats: TerrainEditStatsResult | null;
|
|
272
|
+
}
|
|
273
|
+
/**
|
|
274
|
+
* 内存形态的高度场(`getHeightField()` 的返回值)。
|
|
275
|
+
*
|
|
276
|
+
* 不需要序列化、只想马上算点东西时用它:数组是副本,改它不会影响场景。
|
|
277
|
+
*/
|
|
278
|
+
interface TerrainHeightField {
|
|
279
|
+
/** 每边划分数(顶点数 = segments + 1) */
|
|
280
|
+
segments: number;
|
|
281
|
+
/** 格网覆盖的经纬度范围 */
|
|
282
|
+
bounds: TerrainBounds;
|
|
283
|
+
/** 原始地形高度(米) */
|
|
284
|
+
base: Float32Array;
|
|
285
|
+
/** 编辑后地形高度(米);与 `base` 之差即每点挖填量(负数挖、正数填) */
|
|
286
|
+
current: Float32Array;
|
|
287
|
+
}
|
|
288
|
+
/** 创建地形编辑模块的参数 */
|
|
289
|
+
interface TerrainEditModuleOptions {
|
|
290
|
+
/** 复用 kit 的 ThreeJs 实例(必填,且需先调用 initThree) */
|
|
291
|
+
threeJs?: ThreeJsInstance;
|
|
292
|
+
/** 默认网格分辨率,默认 64 */
|
|
293
|
+
segments?: number;
|
|
294
|
+
/** 默认边缘过渡宽度(米) */
|
|
295
|
+
slopeWidth?: number;
|
|
296
|
+
/** 默认线条颜色 */
|
|
297
|
+
color?: string;
|
|
298
|
+
}
|
|
299
|
+
/**
|
|
300
|
+
* TerrainEdit 实例类型
|
|
301
|
+
*/
|
|
302
|
+
interface TerrainEditInstance {
|
|
303
|
+
_viewer: Viewer;
|
|
304
|
+
_threeJs: ThreeJsInstance | null;
|
|
305
|
+
/**
|
|
306
|
+
* 开始在地形上绘制编辑范围。
|
|
307
|
+
*
|
|
308
|
+
* 左键加点、移动鼠标实时预览、双击或右键结束;至少 3 个点才会生成地形块。
|
|
309
|
+
* 绘制时依赖 `scene.pickPosition` / `globe.pick` 贴合真实地形,因此需要先设置
|
|
310
|
+
* `viewer.terrainProvider`(真实地形)并开启 `depthTestAgainstTerrain`。
|
|
311
|
+
*
|
|
312
|
+
* @param options - 绘制样式与回调
|
|
313
|
+
* @example
|
|
314
|
+
* // 打开绘制:双击结束后会自动生成可编辑地形块
|
|
315
|
+
* terrainEdit.beginDraw({
|
|
316
|
+
* color: '#7defff',
|
|
317
|
+
* callback: (polygon) => console.log('绘制完成', polygon)
|
|
318
|
+
* })
|
|
319
|
+
*/
|
|
320
|
+
beginDraw(options?: TerrainEditDrawOptions): TerrainEditInstance;
|
|
321
|
+
/**
|
|
322
|
+
* 手动结束绘制(等价于双击 / 右键)。
|
|
323
|
+
*
|
|
324
|
+
* 点数不足 3 个时会自动取消,并触发 `onError`。
|
|
325
|
+
*/
|
|
326
|
+
finishDraw(): TerrainEditInstance;
|
|
327
|
+
/**
|
|
328
|
+
* 取消绘制并清除草稿线。
|
|
329
|
+
*/
|
|
330
|
+
cancelDraw(): TerrainEditInstance;
|
|
331
|
+
/**
|
|
332
|
+
* 直接指定多边形范围(不经过鼠标绘制)。
|
|
333
|
+
*
|
|
334
|
+
* 生成过程会按格网采样真实地形高度,因此返回 Promise;
|
|
335
|
+
* 采样失败(例如没有配置地形)时自动退化为 0 高程平面。
|
|
336
|
+
*
|
|
337
|
+
* @param positions - 多边形顶点,支持 `[lng, lat]` / `{lng, lat}` / Cartesian3
|
|
338
|
+
* @param options - 网格分辨率等参数
|
|
339
|
+
* @example
|
|
340
|
+
* await terrainEdit.setPolygon([
|
|
341
|
+
* [117.095, 36.245],
|
|
342
|
+
* [117.105, 36.245],
|
|
343
|
+
* [117.105, 36.255],
|
|
344
|
+
* [117.095, 36.255]
|
|
345
|
+
* ])
|
|
346
|
+
*/
|
|
347
|
+
setPolygon(positions: TerrainEditPosition[], options?: {
|
|
348
|
+
segments?: number;
|
|
349
|
+
slopeWidth?: number;
|
|
350
|
+
fillHoles?: boolean;
|
|
351
|
+
}): Promise<TerrainEditInstance>;
|
|
352
|
+
/**
|
|
353
|
+
* 对当前范围执行一次形变。
|
|
354
|
+
*
|
|
355
|
+
* @param options - 形变参数
|
|
356
|
+
* @example
|
|
357
|
+
* // 塌陷 60 米,台阶高 6 米,水面自动
|
|
358
|
+
* terrainEdit.apply({ mode: 'sink', depth: 60, stepHeight: 6, waterLevel: 'auto' })
|
|
359
|
+
* // 再往上堆 20 米
|
|
360
|
+
* terrainEdit.apply({ mode: 'raise', depth: 20 })
|
|
361
|
+
*/
|
|
362
|
+
apply(options?: TerrainEditApplyOptions): TerrainEditInstance;
|
|
363
|
+
/**
|
|
364
|
+
* 设置水面高度并立即重绘。
|
|
365
|
+
* @param level - 相对水位(0~1)/ 绝对高程(米)/ 'auto' / null
|
|
366
|
+
*/
|
|
367
|
+
setWaterLevel(level: number | 'auto' | null): TerrainEditInstance;
|
|
368
|
+
/**
|
|
369
|
+
* 显示 / 隐藏台阶等高线(青色网格线)。
|
|
370
|
+
* @param visible - true 显示,false 隐藏
|
|
371
|
+
*/
|
|
372
|
+
setContourVisible(visible: boolean): TerrainEditInstance;
|
|
373
|
+
/**
|
|
374
|
+
* 撤销上一次形变(最多保留 20 步)。
|
|
375
|
+
*/
|
|
376
|
+
undo(): TerrainEditInstance;
|
|
377
|
+
/**
|
|
378
|
+
* 清除地形块、水面与绘制状态。
|
|
379
|
+
*/
|
|
380
|
+
clear(): TerrainEditInstance;
|
|
381
|
+
/**
|
|
382
|
+
* 读取当前范围的地形统计:面积、最高最低点、挖填方量、水面高程。
|
|
383
|
+
* @returns 统计结果;未设置范围时返回 null
|
|
384
|
+
*/
|
|
385
|
+
getStats(): TerrainEditStatsResult | null;
|
|
386
|
+
/**
|
|
387
|
+
* 获取当前多边形(度)。
|
|
388
|
+
*/
|
|
389
|
+
getPolygon(): TerrainLngLatHeight[];
|
|
390
|
+
/**
|
|
391
|
+
* 导出当前编辑结果,得到一份可直接 `JSON.stringify` 的数据包。
|
|
392
|
+
*
|
|
393
|
+
* **为什么是「返回数据」而不是「保存文件」**:这个模块跑在调用方的页面里,
|
|
394
|
+
* 数据落到哪儿(后端接口、localStorage、对象存储、GIS 文件、剪贴板)属于业务决定,
|
|
395
|
+
* 库不该替用户选。所以这里只产出**完整、自包含、可序列化**的快照,
|
|
396
|
+
* 存哪儿、存多久、要不要加密压缩,交给调用方;示例页里的「保存数据」
|
|
397
|
+
* 就是拿这个返回值自己做了个下载,而不是库内置了一套存储。
|
|
398
|
+
*
|
|
399
|
+
* 快照不只包含高度:二次编辑需要「原始地形 + 几何参数」才能正确重算挖填方、
|
|
400
|
+
* 重烘坡面明暗、继续用笔刷,所以 `grid.base` 与 `grid.current` 两份高度场都会带上
|
|
401
|
+
* (Float32 原样 base64,往返逐位无损),并附带多边形、区域参数、水面 / 等高线 /
|
|
402
|
+
* 贴图状态以及笔刷设置。
|
|
403
|
+
*
|
|
404
|
+
* 体量:`segments = 160` 时约 277KB(两份 161×161 的 Float32,base64 后),gzip 约 180KB。
|
|
405
|
+
* 这份开销是「无损」换来的:需要更小的载荷就降低 `setArea({ segments })`,
|
|
406
|
+
* 或者只用 `getHeightField()` 自己量化 / 转成 GeoTIFF 等格式。
|
|
407
|
+
*
|
|
408
|
+
* @returns 数据包;尚未圈定编辑范围时返回 null
|
|
409
|
+
* @example
|
|
410
|
+
* // 存到自己的后端
|
|
411
|
+
* const data = terrainEdit.exportData()
|
|
412
|
+
* await fetch('/api/terrain/1', { method: 'POST', body: JSON.stringify(data) })
|
|
413
|
+
*
|
|
414
|
+
* // 或者做成文件让用户下载(下载这一步属于业务侧,不在库里)
|
|
415
|
+
* const blob = new Blob([JSON.stringify(data)], { type: 'application/json' })
|
|
416
|
+
* const a = document.createElement('a')
|
|
417
|
+
* a.href = URL.createObjectURL(blob)
|
|
418
|
+
* a.download = 'terrain.json'
|
|
419
|
+
* a.click()
|
|
420
|
+
*/
|
|
421
|
+
exportData(): TerrainEditSnapshot | null;
|
|
422
|
+
/**
|
|
423
|
+
* 载入 `exportData()` 导出的数据,恢复到可继续编辑的状态。
|
|
424
|
+
*
|
|
425
|
+
* 与 `setPolygon()` 的关键区别:**不会再采样地形**。高度直接从数据包里恢复,
|
|
426
|
+
* 所以即使此刻没有配置地形服务、或者原地形数据已经变了,也能一模一样地复原;
|
|
427
|
+
* 载入后笔刷、撤销、统计、水面、等高线照常工作,地表贴图按新范围在后台重新取。
|
|
428
|
+
*
|
|
429
|
+
* 数据包结构不对(不是本模块导出的、版本不匹配、base64 损坏、长度对不上、
|
|
430
|
+
* 范围与 polygon 不匹配)都会抛 `INVALID_ARGUMENT`,不会渲染出一块错位的地形。
|
|
431
|
+
*
|
|
432
|
+
* @param snapshot - `exportData()` 的返回值,或它 `JSON.parse` 之后的对象;
|
|
433
|
+
* 也可以直接给 JSON 字符串(例如 `localStorage.getItem()` 的返回值),内部会自己解析
|
|
434
|
+
* @example
|
|
435
|
+
* const data = await (await fetch('/api/terrain/1')).json()
|
|
436
|
+
* terrainEdit.importData(data).enableBrush(true)
|
|
437
|
+
*
|
|
438
|
+
* // 从 localStorage 读也一样
|
|
439
|
+
* terrainEdit.importData(localStorage.getItem('terrain-1') || '')
|
|
440
|
+
*/
|
|
441
|
+
importData(snapshot: TerrainEditSnapshot | string): TerrainEditInstance;
|
|
442
|
+
/**
|
|
443
|
+
* 取当前高度场(Float32Array 副本),用于在内存里做二次计算。
|
|
444
|
+
*
|
|
445
|
+
* 不需要序列化、只要数值时用这个:不经过 base64,直接拿到 `base` / `current`,
|
|
446
|
+
* 两者之差就是每个顶点的挖填量(负数挖、正数填),可以直接喂给等高线、
|
|
447
|
+
* 坡度分析、导出成 GeoTIFF 或自己的格网格式。数组是副本,改它不影响场景。
|
|
448
|
+
*
|
|
449
|
+
* @returns 高度场;尚未圈定编辑范围时返回 null
|
|
450
|
+
* @example
|
|
451
|
+
* const field = terrainEdit.getHeightField()
|
|
452
|
+
* const delta = field.current.map((h, i) => h - field.base[i])
|
|
453
|
+
* console.log('最大挖深', Math.min(...delta))
|
|
454
|
+
*/
|
|
455
|
+
getHeightField(): TerrainHeightField | null;
|
|
456
|
+
/**
|
|
457
|
+
* 就地开辟一块可连续涂抹的地形编辑区域(不需要先画多边形)。
|
|
458
|
+
*
|
|
459
|
+
* 区域是一个边长 `size` 米的正方形,内部按 `segments` 划分成规则格网,
|
|
460
|
+
* 边缘按 `feather` 米羽化,因此刷到边界时不会出现断崖。
|
|
461
|
+
* 建好之后配合 `enableBrush()` + 鼠标拖动即可像地形笔刷一样连续涂抹。
|
|
462
|
+
*
|
|
463
|
+
* @param center - 区域中心:`[lng, lat]` / `{lng, lat}` / `Cartesian3`
|
|
464
|
+
* @param options - 区域尺寸与格网分辨率
|
|
465
|
+
* @example
|
|
466
|
+
* // 以当前视野中心为原点,铺一块 2km、160x160 的可编辑器
|
|
467
|
+
* await terrainEdit.setArea([117.1, 36.25], { size: 2000, segments: 160 })
|
|
468
|
+
* terrainEdit.setBrush({ mode: 'lower', radius: 150, maxDelta: 3 }).enableBrush(true)
|
|
469
|
+
*/
|
|
470
|
+
setArea(center: TerrainEditPosition, options?: TerrainEditAreaOptions): Promise<TerrainEditInstance>;
|
|
471
|
+
/**
|
|
472
|
+
* 设置笔刷参数(不影响已刷出的地形)。
|
|
473
|
+
* @param options - 模式、半径、台阶落差、目标高度
|
|
474
|
+
* @example
|
|
475
|
+
* terrainEdit.setBrush({ mode: 'level', radius: 200, targetHeight: 900 })
|
|
476
|
+
*/
|
|
477
|
+
setBrush(options?: TerrainEditBrushOptions): TerrainEditInstance;
|
|
478
|
+
/** 读取当前笔刷参数 */
|
|
479
|
+
getBrush(): Required<Omit<TerrainEditBrushOptions, 'targetHeight'>> & {
|
|
480
|
+
targetHeight: number | null;
|
|
481
|
+
};
|
|
482
|
+
/**
|
|
483
|
+
* 开启 / 关闭鼠标涂抹。
|
|
484
|
+
*
|
|
485
|
+
* 开启后会接管左键拖动(Cesium 的旋转相机被临时关闭,滚轮缩放仍可用),
|
|
486
|
+
* 并显示贴地的圆形笔刷光标;关闭后恢复相机操作。
|
|
487
|
+
* @param enabled - true 开启,false 关闭
|
|
488
|
+
*/
|
|
489
|
+
enableBrush(enabled: boolean): TerrainEditInstance;
|
|
490
|
+
/**
|
|
491
|
+
* 手动落笔:在一次涂抹中连续调用即可画出连续轨迹(等价于按住拖动)。
|
|
492
|
+
*
|
|
493
|
+
* 只在 `beginStroke()` 与 `endStroke()` 之间调用才会被合并成一步撤销。
|
|
494
|
+
* @param lng - 经度
|
|
495
|
+
* @param lat - 纬度
|
|
496
|
+
*/
|
|
497
|
+
strokeAt(lng: number, lat: number): TerrainEditInstance;
|
|
498
|
+
/** 开始一次涂抹(记录撤销快照) */
|
|
499
|
+
beginStroke(): TerrainEditInstance;
|
|
500
|
+
/** 结束一次涂抹(落定等高线与统计) */
|
|
501
|
+
endStroke(): TerrainEditInstance;
|
|
502
|
+
/**
|
|
503
|
+
* 是否用影像贴图显示编辑区(默认 true)。
|
|
504
|
+
*
|
|
505
|
+
* 开启后会向当前影像图层要瓦片,把地表纹理贴到编辑区,
|
|
506
|
+
* 挖开的地表仍是它本来的颜色,而不是一块纯色网格。
|
|
507
|
+
*/
|
|
508
|
+
setTextureEnabled(enabled: boolean): TerrainEditInstance;
|
|
509
|
+
/**
|
|
510
|
+
* 挖/填出来的坡面是否换成岩土材质(默认 true)。
|
|
511
|
+
*
|
|
512
|
+
* 影像按经纬度平面取样,坡面越陡被拉得越长(拉伸比 = sqrt(1 + 坡度²)),
|
|
513
|
+
* 挖到几百米深时坑壁会糊成一片色带。打开后按「坡度 + 挖填深度」把影像渐变成
|
|
514
|
+
* 程序化岩土,消除这种拉伸;关掉则完全保留原始影像。
|
|
515
|
+
* @example
|
|
516
|
+
* terrainEdit.setCutSurfaceEnabled(false)
|
|
517
|
+
*/
|
|
518
|
+
setCutSurfaceEnabled(enabled: boolean): TerrainEditInstance;
|
|
519
|
+
/**
|
|
520
|
+
* 重建地表贴图(例如切换了影像图层、或区域范围变了之后)。
|
|
521
|
+
*/
|
|
522
|
+
refreshTexture(): Promise<TerrainEditInstance>;
|
|
523
|
+
/**
|
|
524
|
+
* 释放全部资源(three 网格、绘制的实体、事件监听)。
|
|
525
|
+
*/
|
|
526
|
+
dispose(): void;
|
|
527
|
+
/** 兼容 kit 的统一销毁入口 */
|
|
528
|
+
destroy(): void;
|
|
529
|
+
}
|
|
530
|
+
/** TerrainEdit 构造函数类型 */
|
|
531
|
+
interface TerrainEditConstructor {
|
|
532
|
+
new (viewer?: Viewer, cesiumGlobal?: any, threeGlobal?: any, threeJs?: ThreeJsInstance, options?: TerrainEditModuleOptions): TerrainEditInstance;
|
|
533
|
+
prototype: TerrainEditInstance;
|
|
534
|
+
}
|
|
535
|
+
declare const TerrainEdit: TerrainEditConstructor;
|
|
536
|
+
|
|
40
537
|
/**
|
|
41
538
|
* 统一错误类型与错误上报出口。
|
|
42
539
|
*
|
|
@@ -295,6 +792,12 @@ interface ResModulesType {
|
|
|
295
792
|
pincerArrowObj: PincerArrowInstance;
|
|
296
793
|
/** threejs 集成模块 */
|
|
297
794
|
threeJs: ThreeJsInstance;
|
|
795
|
+
/**
|
|
796
|
+
* 地形编辑模块:圈定多边形后做塌陷 / 抬升 / 平整 / 平滑,并叠加水面。
|
|
797
|
+
*
|
|
798
|
+
* 依赖 three.js:需要 `createKit({ three })`,并在使用前调用 `kit.threeJs.initThree()`。
|
|
799
|
+
*/
|
|
800
|
+
terrainEdit: TerrainEditInstance;
|
|
298
801
|
}
|
|
299
802
|
/**
|
|
300
803
|
* 创建一个 Cesium 开发套件实例(推荐入口)。
|
|
@@ -335,4 +838,4 @@ interface InitCesiumConstructor {
|
|
|
335
838
|
}
|
|
336
839
|
declare const initCesium: InitCesiumConstructor;
|
|
337
840
|
|
|
338
|
-
export { type CesiumContext, type CesiumContextOptions, CesiumDevKitError, type CesiumDevKitErrorCode, type CesiumDevKitErrorHandler, CesiumGlobal, type CreateKitOptions, type ResModulesType, assertBrowser, createContext, createKit, disposeContext, getErrorHandler, initCesium, isBrowser, isCesiumDevKitError, reportError, setErrorHandler };
|
|
841
|
+
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 };
|