cesium-ws-patch
Version:
Cesium WebSocket 多连接补丁，支持请求耗时统计、负载均衡、超时重试等功能
245 lines (167 loc) • 6.63 kB
Markdown
# cesium-ws-patch
基于 `WebSocket `的 `Cesium `多连接模型加载插件，支持模型资源加速加载、任务智能调度、opfs缓存管理等功能。
npm安装使用，暂无`Cesium`版本限制
测试`Cesium`版本：
`V1.107`、`V1.107.1`、`V1.130`
---
## **⚙️** 相关配置
### 1、worker-loader配置
`vue.config.js`：
```javascript
// worker配置
config.output.globalObject('this')
config.module
.rule('worker')
.test(/\.worker\.js$/)
.use('worker-loader')
.loader('worker-loader')
.options({
filename: '[name].[contenthash].worker.js',
inline: 'no-fallback',
esModule: false
})
.end();
```
### 2、代理
1、本地代理：
```javascript
'/modelWsOnline': {
target: 'http://192.168.2.122:18889/modelWs/',
changeOrigin: true,
pathRewrite: {
'^/modelWsOnline': '/'
}
}
```
2、业务系统服务器nginx（以224服务器为例）：
```nginx
# 指向模型路径
location ^~ /gisxycsdz/modelWsOnline/ {
proxy_pass http://192.168.2.122:18889/modelWs/;
autoindex on;
}
```
## ℹ️使用说明
安装 `cesium-ws-patch`
```bash
npm install cesium-ws-patch@latest
```
安装 `worker-loader`
```bash
npm install worker-loader@3.0.8
```
安装 `pako`
```bash
npm install pako@2.1.0
```
1、引入插件依赖：
```js
import patchCesium from 'cesium-ws-patch'
```
2、使用插件：
```javascript
// 1、初始化
await patchCesium({
Cesium,
serverUrl: $g.syscfg.modelwsipset, // 模型加载服务ip端口
modelWsLibPort：$g.syscfg.modelWsLibPort // 模型配置ip端口
maxConnections: 40, // ws连接池数量
cesiumContainer: 'cesiumcontainer', // cesiumcontainer为容器id名
calllFn // 模型加载完的回调函数
})
// 1.1 在加载模型之前做初始化判断
if (!WebSocketPoolDispatcher.STATUS_CODE) return this.$message.warning('初始化中，请稍后')
// 2、初始化完毕，加载模型
let url = 'modelWsOnline/gis_zhcsdz/工程地质模型.json'
let tileset = await Cesium.Cesium3DTileset.fromUrl(
url, {
...params
}
)
tileset.allTilesLoaded.addEventListener(function() {
console.log('加载完成');
});
// 3、参数说明：
/**
* @method
* @param {Object} options
* @param {String} options.cesiumContainer Cesium 容器 ID 【required】
* @param {String} options.serverUrl WebSocket 服务地址 【required】
* @param {Number} options.modelWsLibPort 模型传输端口 【required】
* @param {Object} options.Cesium Cesium 对象 【optional】
* @param {Array} [options.filetypes=['.b3dm', '.glb', 'tileset.json']] 开启 WebSocket 传输的文件类型 【optional】
* @param {Number} [options.maxConnections=30] 最大连接数 【optional】
* @param {Function} [options.calllFn] 回调函数，加载完执行 【optional】
* @param {Boolean} [options.useWsMonitor=false] 是否开启 WebSocket 监控 【optional】
* @param {Boolean} [options.useOpfsManager=false] 是否开启 opfs 缓存管理 【optional】
*/
// 4、全局对象：WebSocketPoolDispatcher，支持控制台调用
// 调用方法
WebSocketPoolDispatcher
.initWebSocketMonitor()：调出加载任务监控控件
.initOPFSCacheManager()：调出缓存管理控件
.destroyOPFSCacheManager(): 销毁缓存管理控件
.destroyWebSocketMonitor(): 销毁加载任务监控控件
```
---
## 📺模型加载效果
### ▶首次加载：
▶️演示视频：
github：https://ganggogo.github.io/assets/1.html
内网：http://192.168.2.122:18889/modelWsD/html/1.html
### ▶二次加载：
▶️演示视频：
github：https://ganggogo.github.io/assets/2.html
内网：http://192.168.2.122:18889/modelWsD/html/2.html
------
## 🚀 功能新特性
- **🧩** 脱离`Cesium`源码，摆脱版本更新限制，插件安装使用。
- 🔁 `WebSocket` 多连接池请求调度（支持智能任务调度、重试、自动重连、并发加载、文件流传输、压缩传输···）
- 📦` OPFS`离线缓存，读写模型数据效率更高
- 📈 请求耗时统计、最小负载优先调度
- 🧠 `Worker `解压处理、读写缓存、减小客户端内存占用
- 👀 可视化监控界面（连接、耗时、任务量）
- 🧹 缓存文件管理 UI（查看、删除）
---
## **❎** 废除旧特性
- 废除模型数据缓存池，即用即销毁，减小客户端内存消耗
- 废除竞争加载机制，需要频繁进行数据监听，减小客户端内存消耗
- 废除Indexdb存储，换用OPFS存储，读写效率更高
------
## 后端服务部署
参考：https://doc.weixin.qq.com/doc/w3_AIAAGgbFAAYCNYuMzl17EQqOMiihx?scode=AL4AywcjAAoQZVhU0nAIAAGgbFAAY
## 🔄更新记录
`20250710`：
1、增加初始化插件进度条到三维视窗右下角显示。
2、增加模型加载加载进度条到三维视窗右下角显示，适配多模型加载任务数累计。
3、该表初始化调用方法，调用`patchCesium`返回初始化成功状态：`WebSocketPoolDispatcher.STATUS_CODE`，无须调用者手动判断是否初始化完。
```js
let readyMsg = await patchCesium({
Cesium,
serverUrl: 'ws://192.168.2.122:18888',
maxConnections: 50,
cesiumContainer: 'cesiumcontainer',
calllFn
})
if (readyMsg.statuscode === 1)
self.$message.success(readyMsg.message)
else
self.$message.error(readyMsg.message)
```
4、修改`WebSocketMonitor`中对剩余任务的统计从`requestsMap.reduce`到读取`pendingRequestsCount`，优化性能。
`20250731`：
1、全局挂载patchCesium方法，支持script脚本嵌入使用。
`20250818`：
1、修改`pako.min`配置，支持全局配置和系统syscfg表配置
2、添加后端服务部署说明
3、修改说明文档结构
`20250819`：
1、添加`indexdb`缓存，适配http和https环境
`20250820`：
1、更新文档
2、修改modelWsLibPort外面传入
`20250929`：
1、更新文档，新增后端部署文档。
2、修改后端服务配置读取模型数据路径为外部配置文件可配置。