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/CHANGELOG.md CHANGED
@@ -4,6 +4,37 @@
4
4
 
5
5
  ## [Unreleased]
6
6
 
7
+ ## [1.2.1] - 2026-11-22
8
+
9
+ ### 修复(Fixed)
10
+ - **笔刷圈外的地形不再被改动**:`applyBrush` 的塌方坡(`relaxTalus`)以前按「深度 ÷ tan(安息角)」往外铺、上限 3 倍半径,小半径笔刷(如 30m)会把圈外近百米的地形一起削平。现在 `radius` 是硬边界:塌方坡只铺在圈内,边缘噪声也只往圈内揉。`radius` 的文档同步改为「圈外不会被这一笔改动」。
11
+ - **地形笔刷的落笔点跟随指针**:`_pickLngLat` 原来只和 Cesium 的原始地形(`globe.pick`)求交;编辑区是叠在上面的 three 网格,挖下去以后射线先命中原始地表,落笔点和笔刷圈会比指针偏出一大截(坑越深偏得越远,视频里能偏出上百像素)。现在命中后再沿射线与「编辑后的高度场」迭代求交,笔刷圈始终落在指针下方的编辑面上。
12
+ - **陡壁贴图不再被竖向拉伸**:地表贴图原来只按经纬度做平面投影,挖深或堆高后立面接近垂直,同一个像元被摊到整条坡面上,看起来是一条条竖纹。现在 `_updateSurfaceUVs` 按坡面弧长重算 UV(只补「弧长 − 水平投影」的差值,缓坡 / 平台不受影响),立面纹理按 1:1 尺度铺开;接缝留在坑底 / 平台内侧的硬折边上,坑口与原地形仍然对齐。近垂直立面(约 49°~64°)会淡出弧长展开,交给岩土材质,避免竖直面上法线抖动把纹理折成锯齿。
13
+
14
+ ### 变更(Changed)
15
+ - **程序化岩土材质改为默认开启**:陡壁上的卫星影像是平面俯视图,无论怎么投影都容易发虚 / 折叠;现在默认按「坡度 + 挖填深度」在影像上叠一层 3D 噪声岩土,近垂直立面看起来像真实土石断面,缓坡仍以影像为主。需要完全保留影像时调用 `setCutSurfaceEnabled(false)` 或 `setArea({ cutSurface: false })`。
16
+
17
+ ## [1.2.0] - 2026-11-21
18
+
19
+ ### 新增(Added)
20
+ - 地形编辑新增**数据导出 / 载入**,用来保存编辑结果并支持二次编辑:
21
+ - `exportData()` 返回一份可直接 `JSON.stringify` 的数据包(`TerrainEditSnapshot`):多边形、格网参数、**原始与编辑后两份高度场**、水面 / 等高线 / 贴图状态、笔刷参数与土方统计。高度用 `base64(Float32 小端)`(`packHeights`)编码,往返逐位无损,反复存读不会漂移;`segments = 160` 时约 277KB(base64 后),gzip 约 180KB;需要更小就降 `segments` 或自行量化。
22
+ - `importData(snapshot)` 免采样直接复原:不依赖地形服务,换设备 / 原地形数据变了也能一模一样地恢复,载入后笔刷、撤销、统计、水面、贴图照常工作。数据校验失败(非本模块数据、版本不符、base64 损坏、长度或范围不匹配)抛 `INVALID_ARGUMENT`,不会渲染错位地形。
23
+ - `getHeightField()` 返回 `Float32Array` 副本(`base` / `current`),差值为每点挖填量,便于直接做坡度分析或转自己的格网格式。
24
+ - 新增纯算法层 `libs/terrain/terrainData.ts` 与单测 `tests/terrainData.test.ts`(无损往返、损坏数据、范围错位、`fillHoles` 一致性)。
25
+ - 不做内置 `save()` 写文件的原因:数据落到哪儿(后端 / localStorage / 对象存储 / GIS 文件)是业务决定,库只负责产出结构稳定、可序列化的数据;示例页的「保存数据」就是拿 `exportData()` 自己做下载。
26
+
27
+ ### 变更(Changed)
28
+ - **地形笔刷内核重写:从「按权重减量」改成「目标标高平台」**。以前每笔按 `w × maxDelta` 逐次减,一阶导永远连续,刷出来只是原曲面整体压低一点的缩放版 —— 这才是「模糊、不像地形」的根因,换贴图和加开关都补不回来。现在每次落笔把笔刷核心(默认占半径 0.9)**压到同一个绝对标高**,核心到外沿只留一圈宽度跟着台阶落差走的窄过渡带(`BRUSH_WALL_PER_STEP`),不用 `smoothstep`(两端零斜率会把坑底和坑沿都抹圆);超过 34° 安息角的壁由 `relaxTalus` 限坡侵蚀成一圈直的塌方坡。于是单笔就是「平底 + 直壁 + 两道硬坡折」。实测斜坡上 281 个平台顶点高度极差 0、全部落在目标标高;按住 12 级后 101m 处出现清晰坡折。
29
+ - **整条笔画锁定目标标高**:`beginStroke()` 按第一笔落笔处对齐到台阶标高,拖动时沿途所有落笔共用它(`applyBrush` 也支持显式 `targetHeight`);只有指针停住不动时,喷洒定时器每拍把锁定标高再推进一级。于是「拖动 = 平底平台」「按住 = 一层层往下掉」两种手感都成立。实测沿缓坡拖 6 笔锁同一标高,沟底 21 点极差 0。
30
+ - **默认参数收敛,示例页不再靠开关规避劣质效果**:`strength` 默认 1(小于 1 坑底永远压不平)、`hardness` 默认 0.9、`roughness` 默认 0.28(只轻微揉边界,不再承担「让笔迹显形」);程序化岩土材质默认关闭 —— 立面只有几米宽,影像几乎不被拉伸,台阶层次改由几何坡折 + 不依赖开关的方向性明暗(迎光/背光)表现。示例页删掉「笔刷强度」「边缘棱角」「开挖面岩土」三个控件,只留笔刷半径、台阶落差、目标高程与两个显示选项;`setCutSurfaceEnabled()` / `setArea({ cutSurface })` / `roughness` 保留为高级 API。
31
+ - 喷洒节拍由 **80ms 放缓到 140ms**:现在每拍推进一级台阶而不是连续磨高度,太快会把层次糊成一片。`maxDelta` 的语义由「单次施加强度」改为「一级台阶的落差」(默认 3m)。
32
+
33
+ ### 修复(Fixed)
34
+ - 修复 `setArea()` 之后改用 `setPolygon()` 时**范围边框不显示**:`_areaMode` 一直留在 `true`,而边框渲染会因区域模式直接跳过。现在 `setPolygon()` 会把范围重新标记为「手绘」,`_renderBoundary()` 也会先拆掉旧边框再决定是否重画;`setArea()` 在内部调用完 `setPolygon()` 后再标回区域模式。
35
+
36
+ ## [1.1.24] - 2026-11-21
37
+
7
38
  ### 新增(Added)
8
39
  - 示例页新增**源码面板**:每个 Demo 右下角多了一个 `</>` 图标,点开即在右侧展开与窗口等高的代码抽屉,顶部按目录展示当前示例的文件路径(如 `src/views/example/terrain/terrainEdit.vue`)、语言与行数,正文带行号与语法高亮(关键字、方法名、类名、变量、字符串、数字、注释分色),并支持一键复制全文;面板宽度可拖拽、`Esc` 关闭,首页 / 系统管理等非示例页面不显示入口。源码通过 `import.meta.glob('src/views/example/**/*.vue', { as: 'raw' })` 收集,新增示例无需维护映射表。
9
40
  - 新增 **`TerrainEdit`(地形笔刷)** 模块:`setArea()` 就地铺一块可编辑区域后,**按住左键拖动即可连续涂抹**(下沉 / 抬升 / 整平 / 平滑,笔刷半径、强度、单笔高度、硬边均可调),实时改地形并即时重绘;同时保留多边形框选 + 一次成型的 `setPolygon()` + `apply()` 用法(塌陷/堆高/平整/平滑、台阶量化、坑底水面、土方统计)。`createKit()` 返回值新增 `terrainEdit` 字段,也可 `new TerrainEdit(viewer)` 单独使用。
@@ -23,6 +54,8 @@
23
54
  - CI 升级为 Node 20/22/24 矩阵,并加入单测、类型检查、库构建、导出校验和 demo 构建。
24
55
 
25
56
  ### 变更(Changed)
57
+ - 地形笔刷的**地表贴图分辨率按范围自适应**:2400m 范围由 2048(约 1.2m/像素)提到 3072(约 0.8m/像素),超大范围给到 4096 / 256 张瓦片,并让画布分辨率与瓦片原生分辨率对齐;同时把 mipmap 与各向异性过滤开到显卡上限,斜视角不再糊成一片。
58
+ - 地形笔刷交互改为**「按住左键不放就持续开挖 / 抬高」**:指针停住不动由固定节拍逐级下挖,松开左键立即停止;移动时**按走过的地面距离**施加(每 `radius × 0.1` 刷一次),涂抹密度只与路程有关,快拖慢拖深浅一致。
26
59
  - CI 矩阵收敛为 **Node 20 / 22 / 24**,移除已停止维护的 18.x;`Release` 与 `Docs` 工作流统一使用 Node 24(自带 npm 11,可直接启用 Trusted Publishing)。
27
60
  - `package-lock.json` 纳入版本管理,三个工作流的安装步骤由 `npm install` 改为 `npm ci`,构建可复现、不再因依赖浮动而出现「本地能跑、CI 挂掉」;`.gitignore` 不再忽略 lockfile(仅挡 `pnpm-lock.yaml` / `yarn.lock`)。
28
61
  - **(破坏性)** 移除库内置的 Cesium Ion token。请通过 `extraConfig.AccessToken` 传入,或在应用入口设置 `Cesium.Ion.defaultAccessToken`。
@@ -34,14 +67,6 @@
34
67
  - 放宽 `engines`:`node` 由 `==16.0.0` 调整为 `>=16.0.0`,`npm` 由 `==8.19.4` 调整为 `>=8.0.0`。
35
68
  - `package.json` 补充 `description`、`keywords`、`repository`、`homepage`、`bugs` 等元数据,提升 npm 可发现性。
36
69
 
37
- ### 变更(Changed)
38
- - **地形笔刷内核重写:从「按权重减量」改成「目标标高平台」**。以前每笔按 `w × maxDelta` 逐次减,一阶导永远连续,刷出来只是原曲面整体压低一点的缩放版 —— 这才是「模糊、不像地形」的根因,换贴图和加开关都补不回来。现在每次落笔把笔刷核心(默认占半径 0.9)**压到同一个绝对标高**,核心到外沿只留一圈宽度跟着台阶落差走的窄过渡带(`BRUSH_WALL_PER_STEP`),不用 `smoothstep`(两端零斜率会把坑底和坑沿都抹圆);超过 34° 安息角的壁由 `relaxTalus` 限坡侵蚀成一圈直的塌方坡。于是单笔就是「平底 + 直壁 + 两道硬坡折」。实测斜坡上 281 个平台顶点高度极差 0、全部落在目标标高;按住 12 级后 101m 处出现清晰坡折。
39
- - **整条笔画锁定目标标高**:`beginStroke()` 按第一笔落笔处对齐到台阶标高,拖动时沿途所有落笔共用它(`applyBrush` 也支持显式 `targetHeight`);只有指针停住不动时,喷洒定时器每拍把锁定标高再推进一级。于是「拖动 = 平底平台」「按住 = 一层层往下掉」两种手感都成立。实测沿缓坡拖 6 笔锁同一标高,沟底 21 点极差 0。
40
- - **默认参数收敛,示例页不再靠开关规避劣质效果**:`strength` 默认 1(小于 1 坑底永远压不平)、`hardness` 默认 0.9、`roughness` 默认 0.28(只轻微揉边界,不再承担「让笔迹显形」);程序化岩土材质默认关闭 —— 立面只有几米宽,影像几乎不被拉伸,台阶层次改由几何坡折 + 不依赖开关的方向性明暗(迎光/背光)表现。示例页删掉「笔刷强度」「边缘棱角」「开挖面岩土」三个控件,只留笔刷半径、台阶落差、目标高程与两个显示选项;`setCutSurfaceEnabled()` / `setArea({ cutSurface })` / `roughness` 保留为高级 API。
41
- - 喷洒节拍由 **80ms 放缓到 140ms**:现在每拍推进一级台阶而不是连续磨高度,太快会把层次糊成一片。`maxDelta` 的语义由「单次施加强度」改为「一级台阶的落差」(默认 3m)。
42
- - 地形笔刷的**地表贴图分辨率按范围自适应**:2400m 范围由 2048(约 1.2m/像素)提到 3072(约 0.8m/像素),超大范围给到 4096 / 256 张瓦片,并让画布分辨率与瓦片原生分辨率对齐;同时把 mipmap 与各向异性过滤开到显卡上限,斜视角不再糊成一片。
43
- - 地形笔刷交互改为**「按住左键不放就持续开挖 / 抬高」**:指针停住不动由固定节拍逐级下挖,松开左键立即停止;移动时**按走过的地面距离**施加(每 `radius × 0.1` 刷一次),涂抹密度只与路程有关,快拖慢拖深浅一致。
44
-
45
70
  ### 修复(Fixed)
46
71
  - 修复**挖深之后坑壁糊成一片、越挖越不像**:地表贴图是按经纬度平面投影取样的,坡面越陡被拉得越长(拉伸比 = `sqrt(1 + 坡度²)`)。实测挖到 480m 深、坑口半径只有 150m 时,坑壁接近垂直,影像被拉长十几倍,整面墙成了一团放射状色带——这不是分辨率不够,把贴图提到 8192 也治不了,因为要摊薄的是同一批像素。现在按「坡度 + 挖填深度」把这类坡面渐变成程序化岩土(三维噪声 + 层理 + 碎屑凹凸,用 `fwidth` 做距离淡出避免远处变成毛毡),影像只在缓坡与未改动的地表保留。(后续笔刷改为「目标标高平台」模型后,立面只剩几米宽,投影拉伸自然消失,这项程序化岩土已降级为默认关闭的高级选项。)
47
72
  - 修复**下沉后坑底「顶出一块原地面」,看起来像叠加层被戳穿**:手绘范围一旦折返/自交,射线法的奇偶规则会把交点旁的一小块判成「区域外」,这块在格网里既没有面、笔刷也刷不到,于是它一直停在原始高度,周围挖下去之后就成了一块顶着原地面的孤岛。现在 `buildTerrainGrid` 默认做一次「从格网边界洪水填充」把被包住的内部空洞补成实心(补出来的点按内圈处理、给满权重、参与高度采样与笔刷),`setPolygon()` / `setArea()` 新增 `fillHoles` 开关(默认 `true`,需要镂空时显式关掉)。单测覆盖:`fillHoles: false` 复现空洞(`inside = 0`),默认情况下洞心被填平且能被笔刷挖动。