@rtzh/cesium

本项目是基于 CesiumJS 的改版定制项目，在 CesiumJS 1.136.0 版本基础上扩展了模型线框显示、点光源照明等实用功能。

来源

| 项目 | 信息 | |------|------| | 原始项目 | CesiumGS/cesium | | 原始版本 | 1.136.0 | | 当前版本 | 0.0.11 |

包结构

本项目采用 monorepo 管理，包含以下子包：

| 包名 | 说明 | 原始包 | |------|------|--------| | @rtzh/engine | CesiumJS 核心渲染引擎，包含地形、影像、3D Tiles、模型等核心 API | @cesium/engine 22.1.0 | | @rtzh/widgets | UI 组件库，包含 Viewer、动画控件、图层选择器等组件 | @cesium/widgets 14.1.0 | | @rtzh/sandcastle | Sandcastle 示例应用（私有包，不发布） | @cesium/sandcastle |

安装

npm

# 安装完整包
npm install @rtzh/cesium --save

# 或按需安装子包
npm install @rtzh/engine @rtzh/widgets --save

快速上手

import { Viewer } from "@rtzh/widgets";
import "@rtzh/widgets/Source/widgets.css";

// 创建 Viewer
const viewer = new Viewer("cesiumContainer");

// 加载模型并显示线框
const model = await viewer.scene.primitives.add(
  await Cesium.Model.fromGltfAsync({
    url: "path/to/model.glb",
  })
);

// 启用科技感线框显示
model.showWireframe({
  color: Cesium.Color.CYAN,
  lineWidth: 2.0,
  mode: "barycentric",
  overlay: true,
  fillAlpha: 0.3,
});

变更日志

功能新增（Features）

1. 模型及 3D 图块线框显示功能

在 Model 和 Cesium3DTileset 类中新增便捷的线框显示切换方法：

• showWireframe(options) — 显示线框，支持丰富的配置参数
• hideWireframe() — 隐藏线框，恢复原始渲染状态
• toggleWireframe(options) — 切换线框显示状态，返回当前是否为线框模式

核心特性：

• 支持设置线框颜色、填充颜色及颜色混合模式
• 所有方法返回 this，支持链式调用
• WebGL1 环境需在加载时设置 enableDebugWireframe: true

// 显示红色线框（保留模型原色 30% 透明度）
model.showWireframe({
  color: Cesium.Color.RED,
  lineWidth: 2.0,
  mode: "barycentric",
  overlay: true,
  fillAlpha: 0.3,
});

// 链式调用
tileset.showWireframe({ color: Cesium.Color.CYAN })
       .hideWireframe()
       .showWireframe({ color: Cesium.Color.GREEN });

2. 基于重心坐标的线框调试模式支持

新增高性能线框渲染模式，解决 WebGL lines 模式线宽受限问题：

• 新增 debugWireframeMode 属性，支持 "lines" 和 "barycentric" 两种模式
• 新增 debugWireframeColor、debugWireframeFillAlpha、debugWireframeLineWidth、debugWireframeOverlay 配置属性
• 实现 BarycentricWireframePipelineStage 渲染管线阶段
• 修改顶点/片段着色器支持重心坐标线框效果
• "lines" 模式需启用 enableDebugWireframe，"barycentric" 模式无需前置配置

两种模式对比：

| 特性 | "lines" 模式 | "barycentric" 模式 | |------|----------------|----------------------| | 线宽控制 | 浏览器限制（多数仅 1px） | 支持任意线宽 | | WebGL1 | 需 enableDebugWireframe | 不支持 | | WebGL2 | 需 enableDebugWireframe | 完整支持 | | 性能 | 较高 | 首次开启需几何体展开 |

3. 线框扫描线和发光效果支持

为线框添加科技感动画效果：

• 在 Model 和 Cesium3DTileset 的 effects 参数中支持扫描线和发光配置
• 实现扫描线方向、速度和发光强度的实时计算
• 根据扫描方向动态计算扫描范围和模型高度范围
• 在片段着色器中实现扫描线高亮和发光效果的混合计算
• 顶点着色器传递模型世界坐标以支持空间扫描效果

4. 点光源照明支持

新增多光源系统，支持在场景中添加最多 8 个点光源：

• 新增 PointLight 类，描述点光源的位置、颜色、强度和范围
• Scene.pointLights 数组管理额外点光源，与原方向光共存
• UniformState 和 AutomaticUniforms 中添加点光状态及自动 uniform 支持
• LightingPipelineStage 使用条件编译（POINT_LIGHTS 宏），无点光源时零开销
• Model 检测点光变化并触发绘制命令重建
• 预计算眼坐标位置和 HDR 颜色，减少着色器计算
• 优化范围衰减和平滑过渡算法，保障渲染效果

// 创建点光源
const pointLight = new Cesium.PointLight({
  position: new Cesium.Cartesian3(1000, 2000, 3000),
  color: Cesium.Color.RED,
  intensity: 2.0,
  range: 5000.0,
});

// 添加到场景
viewer.scene.pointLights.push(pointLight);

Bug 修复（Fixes）

• 优化 Model 的调试线框属性设置逻辑
  • 修正 debugWireframeColor 赋值时避免无效克隆和重复设置
  • 添加 debugWireframeFillAlpha 赋值的重复值检测，减少不必要的重绘
  • 在 Model3DTileContent 中仅当 debugWireframe 开启时赋值相关调试线框属性
  • 移除未启用 debugWireframe 时对 model.color 的无效赋值
  • 统一默认的 _debugWireframeScanAxis 为 Cartesian3(0, 0, 1) 实例

重构（Refactors）

• 优化多个模块的代码结构和逻辑，提升可维护性
• 修正 Model 加载中 Feature ID 属性的类名称引用
• 移除调试扫描线相关的多余高度变量，优化着色器计算逻辑

杂项（Chores）

• 更新各包版本号，保持 @rtzh/engine、@rtzh/widgets、@rtzh/cesium 依赖一致
• 添加 .idea 文件夹到 .gitignore
• 新增 npm run push 脚本，一键发布所有包到 npm

License

Apache 2.0 — 与原始 CesiumJS 项目保持一致，可自由用于商业和非商业用途。