cesium-ws-patch/README.md

Cesium WebSocket 多连接补丁，支持请求耗时统计、负载均衡、超时重试等功能

# cesium-ws-patch

基于 `WebSocket `的 `Cesium `多连接模型加载插件，支持模型资源加速加载、任务智能调度、opfs缓存管理等功能。

npm安装使用，暂无`Cesium`版本限制

测试`Cesium`版本：

`V1.107`、`V1.107.1`、`V1.130`

---


## 🚀 功能新特性

- **🧩** 脱离`Cesium`源码，摆脱版本更新限制，插件安装使用。
- 🔁 `WebSocket` 多连接池请求调度（支持智能任务调度、重试、自动重连、并发加载、文件流传输、压缩传输···）
- 📦` OPFS`离线缓存，读写模型数据效率更高
- 📈 请求耗时统计、最小负载优先调度
- 🧠 `Worker `解压处理、读写缓存、减小客户端内存占用
- 👀 可视化监控界面（连接、耗时、任务量）
- 🧹 缓存文件管理 UI（查看、删除）

---


## **❎** 废除旧特性

- 废除模型数据缓存池，即用即销毁，减小客户端内存消耗
- 废除竞争加载机制，需要频繁进行数据监听，减小客户端内存消耗
- 废除Indexdb存储，换用OPFS存储，读写效率更高

---


## 📦 安装方式

安装 `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: 'ws://192.168.2.122:18888', maxConnections: 40, cesiumContainer: 'cesiumcontainer'})

// 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 {Object} options.Cesium      Cesium 对象                   【optional】
 * @param {Array} [options.filetypes=['.b3dm', '.glb', 'tileset.json']]  开启 WebSocket 传输的文件类型        【optional】
 * @param {Number} [options.maxConnections=20]    最大连接数         【optional】
 * @param {Function} [options.calllFn]       回调函数，加载完执行     【optional】
 * @param {Boolean} [options.useWsMonitor=true]    是否开启 WebSocket 监控    【optional】
 * @param {Boolean} [options.useOpfsManager=true]      是否开启 opfs 缓存管理  【optional】
 */

// 4、全局对象：WebSocketPoolDispatcher，支持控制台调用

// 调用方法
WebSocketPoolDispatcher
    .initWebSocketMonitor()：调出加载任务监控控件
    .initOPFSCacheManager()：调出缓存管理控件
    .destroyOPFSCacheManager(): 销毁缓存管理控件
    .destroyWebSocketMonitor(): 销毁加载任务监控控件
```

## 

---


## **⚙️** 其他配置

### 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代理：

```nginx
location ^~ /modelWs/ {
    alias   E:/modelSvr/modeldata/;
    #index  index.html index.htm;
    autoindex on;
}
```

3、模型文件路径：

![1750861442220](https://raw.github.com/ganggogo/assets/main/1750861442220.png)

---


## 📺模型加载效果

### ▶️首次加载：

![](https://raw.github.com/ganggogo/assets/main/珠海工程地质模型首次加载.png)

▶️演示视频：

github：https://ganggogo.github.io/assets/1.html

内网：http://192.168.2.122:18889/modelWsD/html/1.html

### ▶️二次加载：

![]( https://raw.github.com/ganggogo/assets/main/珠海工程地质模型二次加载.png)

▶️演示视频：

github：https://ganggogo.github.io/assets/2.html

内网：http://192.168.2.122:18889/modelWsD/html/2.html