cesium_dev_kit 1.1.23 → 1.1.24

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.ts CHANGED
@@ -1,4 +1,4 @@
1
- import { C as CesiumGlobal, V as Viewer, S as StaticResourceConf, B as BaseInstance } from './Base-DH8H9suE.js';
1
+ import { V as Viewer, C as CesiumGlobal, S as StaticResourceConf, B as BaseInstance } from './Base-DH8H9suE.js';
2
2
  import { M as MaterialInstance } from './Material-Cqbyf2Pn.js';
3
3
  export { a as Material } from './Material-Cqbyf2Pn.js';
4
4
  import { G as GraphicsInstance } from './Graphics-CuFNsQ3b.js';
@@ -37,6 +37,336 @@ 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
+ type TerrainEditMode = 'sink' | 'raise' | 'flatten' | 'smooth';
58
+ /** 形变参数 */
59
+ interface TerrainDeformOptions {
60
+ /** 编辑模式,默认 `sink`(塌陷) */
61
+ mode?: TerrainEditMode;
62
+ /** 塌陷深度 / 抬升高度 / 平整偏移(米),默认 30 */
63
+ depth?: number;
64
+ /** 台阶高度(米),0 表示平滑过渡;矿山台阶常用 4~12 米 */
65
+ stepHeight?: number;
66
+ /** 平整目标高度(米),不传时取内圈平均高度 */
67
+ flattenHeight?: number;
68
+ /** 平滑迭代次数,默认 2 */
69
+ smoothIterations?: number;
70
+ }
71
+ /** 地形统计信息 */
72
+ interface TerrainStats {
73
+ /** 多边形面积(平方米) */
74
+ area: number;
75
+ /** 格网内最低点高度(米) */
76
+ minHeight: number;
77
+ /** 格网内最高点高度(米) */
78
+ maxHeight: number;
79
+ /** 相对原始地形挖掉的体积(立方米,正值表示挖方) */
80
+ cutVolume: number;
81
+ /** 相对原始地形填上的体积(立方米,正值表示填方) */
82
+ fillVolume: number;
83
+ /** 参与编辑的顶点数 */
84
+ vertexCount: number;
85
+ /** 单元边长(米) */
86
+ cellSize: number;
87
+ }
88
+ /** 笔刷模式:抬升 / 下沉 / 整平到目标高度 / 平滑 */
89
+ type TerrainBrushMode = 'raise' | 'lower' | 'level' | 'smooth';
90
+
91
+ /** 多边形顶点输入:`[lng, lat]`、`[lng, lat, height]`、`{lng, lat}` 或 Cesium.Cartesian3 */
92
+ type TerrainEditPosition = [number, number] | [number, number, number] | TerrainLngLat | TerrainLngLatHeight | any;
93
+ /** 绘制参数 */
94
+ interface TerrainEditDrawOptions {
95
+ /** 线条颜色,默认 `#7defff` */
96
+ color?: string;
97
+ /** 线宽(像素),默认 4 */
98
+ width?: number;
99
+ /** 绘制完成后回调,参数为经纬度顶点(度) */
100
+ callback?: (polygon: TerrainLngLatHeight[]) => void;
101
+ /** 网格分辨率(每边划分数),默认 64 */
102
+ segments?: number;
103
+ }
104
+ /** 形变参数(在地形模块基础上增加了水位) */
105
+ interface TerrainEditApplyOptions extends TerrainDeformOptions {
106
+ /**
107
+ * 水面高度:
108
+ * - `0~1` 视为相对坑底的相对水位(0.3 表示坑深的 30%)
109
+ * - 大于 `1` 视为绝对高程(米)
110
+ * - `'auto'` 自动取坑底以上 28%
111
+ * - `null` 不显示水面
112
+ */
113
+ waterLevel?: number | 'auto' | null;
114
+ /** 是否重建水面(默认 true) */
115
+ rebuildWater?: boolean;
116
+ }
117
+ /** 地形统计(附加水位信息) */
118
+ interface TerrainEditStatsResult extends TerrainStats {
119
+ /** 当前水面高程(米),无水面时为 null */
120
+ waterLevel: number | null;
121
+ /** 顶点数量 */
122
+ vertices: number;
123
+ }
124
+ /** 笔刷参数(对应「按住拖动连续刷」的交互) */
125
+ interface TerrainEditBrushOptions {
126
+ /** 笔刷模式,默认 `lower`(下沉) */
127
+ mode?: TerrainBrushMode;
128
+ /** 笔刷半径(米),默认 110 */
129
+ radius?: number;
130
+ /**
131
+ * 向目标标高推进的比例 0~1,默认 1(一步压到绝对平)。
132
+ *
133
+ * 小于 1 时坑底永远压不平、会留着原地面的起伏,看起来就是一片糊。
134
+ * 需要软笔触请换 `mode: 'smooth'`,不要调低这个值。
135
+ */
136
+ strength?: number;
137
+ /** 平整核心占半径的比例 0~1,默认 0.9:平台几乎铺满笔刷,边缘只留一圈窄立面 */
138
+ hardness?: number;
139
+ /**
140
+ * 坑口不规则度 0~1,默认 0.28。
141
+ *
142
+ * 用世界坐标的值噪声轻微掰动有效半径,让边界不是圆规画出来的。
143
+ * 它只负责「不那么规整」;让笔迹清楚的是一刀切平的标高,不是这个参数。
144
+ * 噪声按世界坐标取样,按住不放反复加深时图案固定,不会抖动或漂移。
145
+ */
146
+ roughness?: number;
147
+ /**
148
+ * 一级台阶的落差(米),默认 3。
149
+ *
150
+ * 每次落笔都把笔刷核心压到同一个**目标标高**,拖动时整条笔画锁这个值,
151
+ * 于是刷出来是平底平台而不是碗。按住不放由 `SPRAY_INTERVAL` 按拍逐级下降,
152
+ * 所以这个值同时决定台阶的高度和下挖速度。
153
+ */
154
+ maxDelta?: number;
155
+ /**
156
+ * 一笔之内的累计上限系数(`maxDelta × strokeLimit`)。
157
+ *
158
+ * 默认 `0` 表示**不限制**:按住左键就一直累加,松开才停,和地形软件一致。
159
+ * 只有需要「一刀最多挖多深」时才设置它。
160
+ */
161
+ strokeLimit?: number;
162
+ /** `level` 模式的目标高程(米),缺省取落笔处原地形高度 */
163
+ targetHeight?: number | null;
164
+ }
165
+ /** 笔刷区域参数 */
166
+ interface TerrainEditAreaOptions {
167
+ /** 区域边长(米),默认 2000 */
168
+ size?: number;
169
+ /** 每边划分数,默认 160 */
170
+ segments?: number;
171
+ /** 边缘过渡宽度(米),默认 80 */
172
+ feather?: number;
173
+ /** 是否取影像作为地表贴图,默认 true */
174
+ texture?: boolean;
175
+ /** 是否把区域内部被包住的空洞填平,默认 true(见 setPolygon) */
176
+ fillHoles?: boolean;
177
+ /**
178
+ * 是否启用程序化岩土材质,默认 false。
179
+ *
180
+ * 这是给「在近乎垂直的陡壁上强行贴影像」准备的高级选项,正常开挖不需要:
181
+ * 笔刷现在刷出的是平底平台 + 窄立面,立面只有几米宽,影像几乎不被拉伸;
182
+ * 台阶的层次靠几何坡折和方向性明暗表现,比换一张贴图清楚得多。
183
+ * 打开后按「坡度 + 挖填深度」把影像渐变成岩土。
184
+ */
185
+ cutSurface?: boolean;
186
+ }
187
+ /** 创建地形编辑模块的参数 */
188
+ interface TerrainEditModuleOptions {
189
+ /** 复用 kit 的 ThreeJs 实例(必填,且需先调用 initThree) */
190
+ threeJs?: ThreeJsInstance;
191
+ /** 默认网格分辨率,默认 64 */
192
+ segments?: number;
193
+ /** 默认边缘过渡宽度(米) */
194
+ slopeWidth?: number;
195
+ /** 默认线条颜色 */
196
+ color?: string;
197
+ }
198
+ /**
199
+ * TerrainEdit 实例类型
200
+ */
201
+ interface TerrainEditInstance {
202
+ _viewer: Viewer;
203
+ _threeJs: ThreeJsInstance | null;
204
+ /**
205
+ * 开始在地形上绘制编辑范围。
206
+ *
207
+ * 左键加点、移动鼠标实时预览、双击或右键结束;至少 3 个点才会生成地形块。
208
+ * 绘制时依赖 `scene.pickPosition` / `globe.pick` 贴合真实地形,因此需要先设置
209
+ * `viewer.terrainProvider`(真实地形)并开启 `depthTestAgainstTerrain`。
210
+ *
211
+ * @param options - 绘制样式与回调
212
+ * @example
213
+ * // 打开绘制:双击结束后会自动生成可编辑地形块
214
+ * terrainEdit.beginDraw({
215
+ * color: '#7defff',
216
+ * callback: (polygon) => console.log('绘制完成', polygon)
217
+ * })
218
+ */
219
+ beginDraw(options?: TerrainEditDrawOptions): TerrainEditInstance;
220
+ /**
221
+ * 手动结束绘制(等价于双击 / 右键)。
222
+ *
223
+ * 点数不足 3 个时会自动取消,并触发 `onError`。
224
+ */
225
+ finishDraw(): TerrainEditInstance;
226
+ /**
227
+ * 取消绘制并清除草稿线。
228
+ */
229
+ cancelDraw(): TerrainEditInstance;
230
+ /**
231
+ * 直接指定多边形范围(不经过鼠标绘制)。
232
+ *
233
+ * 生成过程会按格网采样真实地形高度,因此返回 Promise;
234
+ * 采样失败(例如没有配置地形)时自动退化为 0 高程平面。
235
+ *
236
+ * @param positions - 多边形顶点,支持 `[lng, lat]` / `{lng, lat}` / Cartesian3
237
+ * @param options - 网格分辨率等参数
238
+ * @example
239
+ * await terrainEdit.setPolygon([
240
+ * [117.095, 36.245],
241
+ * [117.105, 36.245],
242
+ * [117.105, 36.255],
243
+ * [117.095, 36.255]
244
+ * ])
245
+ */
246
+ setPolygon(positions: TerrainEditPosition[], options?: {
247
+ segments?: number;
248
+ slopeWidth?: number;
249
+ fillHoles?: boolean;
250
+ }): Promise<TerrainEditInstance>;
251
+ /**
252
+ * 对当前范围执行一次形变。
253
+ *
254
+ * @param options - 形变参数
255
+ * @example
256
+ * // 塌陷 60 米,台阶高 6 米,水面自动
257
+ * terrainEdit.apply({ mode: 'sink', depth: 60, stepHeight: 6, waterLevel: 'auto' })
258
+ * // 再往上堆 20 米
259
+ * terrainEdit.apply({ mode: 'raise', depth: 20 })
260
+ */
261
+ apply(options?: TerrainEditApplyOptions): TerrainEditInstance;
262
+ /**
263
+ * 设置水面高度并立即重绘。
264
+ * @param level - 相对水位(0~1)/ 绝对高程(米)/ 'auto' / null
265
+ */
266
+ setWaterLevel(level: number | 'auto' | null): TerrainEditInstance;
267
+ /**
268
+ * 显示 / 隐藏台阶等高线(青色网格线)。
269
+ * @param visible - true 显示,false 隐藏
270
+ */
271
+ setContourVisible(visible: boolean): TerrainEditInstance;
272
+ /**
273
+ * 撤销上一次形变(最多保留 20 步)。
274
+ */
275
+ undo(): TerrainEditInstance;
276
+ /**
277
+ * 清除地形块、水面与绘制状态。
278
+ */
279
+ clear(): TerrainEditInstance;
280
+ /**
281
+ * 读取当前范围的地形统计:面积、最高最低点、挖填方量、水面高程。
282
+ * @returns 统计结果;未设置范围时返回 null
283
+ */
284
+ getStats(): TerrainEditStatsResult | null;
285
+ /**
286
+ * 获取当前多边形(度)。
287
+ */
288
+ getPolygon(): TerrainLngLatHeight[];
289
+ /**
290
+ * 就地开辟一块可连续涂抹的地形编辑区域(不需要先画多边形)。
291
+ *
292
+ * 区域是一个边长 `size` 米的正方形,内部按 `segments` 划分成规则格网,
293
+ * 边缘按 `feather` 米羽化,因此刷到边界时不会出现断崖。
294
+ * 建好之后配合 `enableBrush()` + 鼠标拖动即可像地形笔刷一样连续涂抹。
295
+ *
296
+ * @param center - 区域中心:`[lng, lat]` / `{lng, lat}` / `Cartesian3`
297
+ * @param options - 区域尺寸与格网分辨率
298
+ * @example
299
+ * // 以当前视野中心为原点,铺一块 2km、160x160 的可编辑器
300
+ * await terrainEdit.setArea([117.1, 36.25], { size: 2000, segments: 160 })
301
+ * terrainEdit.setBrush({ mode: 'lower', radius: 150, maxDelta: 3 }).enableBrush(true)
302
+ */
303
+ setArea(center: TerrainEditPosition, options?: TerrainEditAreaOptions): Promise<TerrainEditInstance>;
304
+ /**
305
+ * 设置笔刷参数(不影响已刷出的地形)。
306
+ * @param options - 模式、半径、台阶落差、目标高度
307
+ * @example
308
+ * terrainEdit.setBrush({ mode: 'level', radius: 200, targetHeight: 900 })
309
+ */
310
+ setBrush(options?: TerrainEditBrushOptions): TerrainEditInstance;
311
+ /** 读取当前笔刷参数 */
312
+ getBrush(): Required<Omit<TerrainEditBrushOptions, 'targetHeight'>> & {
313
+ targetHeight: number | null;
314
+ };
315
+ /**
316
+ * 开启 / 关闭鼠标涂抹。
317
+ *
318
+ * 开启后会接管左键拖动(Cesium 的旋转相机被临时关闭,滚轮缩放仍可用),
319
+ * 并显示贴地的圆形笔刷光标;关闭后恢复相机操作。
320
+ * @param enabled - true 开启,false 关闭
321
+ */
322
+ enableBrush(enabled: boolean): TerrainEditInstance;
323
+ /**
324
+ * 手动落笔:在一次涂抹中连续调用即可画出连续轨迹(等价于按住拖动)。
325
+ *
326
+ * 只在 `beginStroke()` 与 `endStroke()` 之间调用才会被合并成一步撤销。
327
+ * @param lng - 经度
328
+ * @param lat - 纬度
329
+ */
330
+ strokeAt(lng: number, lat: number): TerrainEditInstance;
331
+ /** 开始一次涂抹(记录撤销快照) */
332
+ beginStroke(): TerrainEditInstance;
333
+ /** 结束一次涂抹(落定等高线与统计) */
334
+ endStroke(): TerrainEditInstance;
335
+ /**
336
+ * 是否用影像贴图显示编辑区(默认 true)。
337
+ *
338
+ * 开启后会向当前影像图层要瓦片,把地表纹理贴到编辑区,
339
+ * 挖开的地表仍是它本来的颜色,而不是一块纯色网格。
340
+ */
341
+ setTextureEnabled(enabled: boolean): TerrainEditInstance;
342
+ /**
343
+ * 挖/填出来的坡面是否换成岩土材质(默认 true)。
344
+ *
345
+ * 影像按经纬度平面取样,坡面越陡被拉得越长(拉伸比 = sqrt(1 + 坡度²)),
346
+ * 挖到几百米深时坑壁会糊成一片色带。打开后按「坡度 + 挖填深度」把影像渐变成
347
+ * 程序化岩土,消除这种拉伸;关掉则完全保留原始影像。
348
+ * @example
349
+ * terrainEdit.setCutSurfaceEnabled(false)
350
+ */
351
+ setCutSurfaceEnabled(enabled: boolean): TerrainEditInstance;
352
+ /**
353
+ * 重建地表贴图(例如切换了影像图层、或区域范围变了之后)。
354
+ */
355
+ refreshTexture(): Promise<TerrainEditInstance>;
356
+ /**
357
+ * 释放全部资源(three 网格、绘制的实体、事件监听)。
358
+ */
359
+ dispose(): void;
360
+ /** 兼容 kit 的统一销毁入口 */
361
+ destroy(): void;
362
+ }
363
+ /** TerrainEdit 构造函数类型 */
364
+ interface TerrainEditConstructor {
365
+ new (viewer?: Viewer, cesiumGlobal?: any, threeGlobal?: any, threeJs?: ThreeJsInstance, options?: TerrainEditModuleOptions): TerrainEditInstance;
366
+ prototype: TerrainEditInstance;
367
+ }
368
+ declare const TerrainEdit: TerrainEditConstructor;
369
+
40
370
  /**
41
371
  * 统一错误类型与错误上报出口。
42
372
  *
@@ -295,6 +625,12 @@ interface ResModulesType {
295
625
  pincerArrowObj: PincerArrowInstance;
296
626
  /** threejs 集成模块 */
297
627
  threeJs: ThreeJsInstance;
628
+ /**
629
+ * 地形编辑模块:圈定多边形后做塌陷 / 抬升 / 平整 / 平滑,并叠加水面。
630
+ *
631
+ * 依赖 three.js:需要 `createKit({ three })`,并在使用前调用 `kit.threeJs.initThree()`。
632
+ */
633
+ terrainEdit: TerrainEditInstance;
298
634
  }
299
635
  /**
300
636
  * 创建一个 Cesium 开发套件实例(推荐入口)。
@@ -335,4 +671,4 @@ interface InitCesiumConstructor {
335
671
  }
336
672
  declare const initCesium: InitCesiumConstructor;
337
673
 
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 };
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 };