@stampgis/webrtc 1.0.0 → 1.0.2

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.
Files changed (10) hide show
  1. package/README.md +114 -161
  2. package/assets/config/stamp_core_config.js +1 -26
  3. package/dist/index.cjs +16058 -6258
  4. package/dist/index.d.mts +8491 -1254
  5. package/dist/index.d.ts +8491 -1254
  6. package/dist/index.js +15826 -5989
  7. package/dist-cli/cli.js +220 -0
  8. package/package.json +29 -5
  9. package/dist/index.cjs.map +0 -1
  10. package/dist/index.js.map +0 -1
package/README.md CHANGED
@@ -1,22 +1,21 @@
1
1
  # @stampgis/webrtc
2
2
 
3
- StampGIS 私有地图 SDK npm 包，封装 `StampUtil.ts` 接口库与 `core/` + `config/` 脚本的动态加载逻辑。
3
+ StampGIS 三维地图 WebRTC（像素流）开发 SDK，对底层工具类、核心脚本加载与全局配置做模块化封装。
4
4
 
5
- ## 为什么需要这个包
5
+ 解决传统「多 `<script>` 标签按序引入 + 全局变量污染 + 无法通过 ES Module 导入」的痛点，开箱即用，支持按需加载、动态资源注入，适配 Vite / Webpack / CDN 多种接入方式。
6
6
 
7
- 原项目（MCPWebsite）中，地图加载需要在 `index.html` 的 `<head>` 里手动引入三个 `<script>` 标签：
7
+ ## 特性
8
8
 
9
- ```html
10
- <script src="config/stamp_core_config.js"></script>
11
- <script src="core/pixelstreaming.js"></script>
12
- <script src="core/playerControl.js"></script>
13
- ```
9
+ - 核心脚本（config / pixelstreaming / playerControl）已内置在 npm 包 `assets/` 目录，无需手动复制文件
10
+ - 提供 `loadCore()` 动态加载、`initMap()` 一键初始化，自动处理脚本依赖顺序与全局变量就绪等待
11
+ - 内置 `StampUtil` 接口库，提供 500+ 个地图操作方法（量算、图层管理、标绘标注、空间分析、视角控制等）
12
+ - ES Module（`import`）与 CommonJS（`require`）双格式，附带完整 TypeScript 类型声明
14
13
 
15
- 这三个脚本在 `window` 上注册全局变量（`stamp_core_config`、`StampPixelStreaming`、`StampAPI`），无法通过 ES module `import` 引入。而 `StampUtil.ts` 虽然是 TypeScript 模块，却依赖运行时的 `window.StampAPI` 全局变量。
14
+ ## 环境要求
16
15
 
17
- 本包解决两个问题：
18
- 1. 将三个脚本按正确顺序动态加载，等待全局变量就绪
19
- 2. 将 `StampUtil.ts` 编译为可 `import` 的 npm 模块
16
+ - **浏览器环境**：依赖 `window` / `document`，不支持 Node / SSR
17
+ - 使用 `useBundledAssets` 时需 Vite 或 Webpack 5+（依赖 `import.meta.url` 解析静态资源）
18
+ - 使用 `baseUrl` 或精确 URL 方式加载时，对打包器无特殊要求
20
19
 
21
20
  ## 安装
22
21
 
@@ -26,214 +25,168 @@ npm install @stampgis/webrtc
26
25
  pnpm add @stampgis/webrtc
27
26
  ```
28
27
 
29
- ## 脚本加载方式
30
-
31
- 核心脚本（`config/stamp_core_config.js`、`core/pixelstreaming.js`、`core/playerControl.js`）已内置在包的 `assets/` 目录中，支持 4 种加载方式：
32
-
33
- | 方式 | 适用场景 | 是否需复制文件 |
34
- |------|----------|--------------|
35
- | `useBundledAssets: true` | Vite 项目（推荐） | 不需要 |
36
- | `baseUrl` | 服务器/CDN 部署 | 需要 |
37
- | 精确 URL | 灵活控制 | 视情况 |
38
- | `import` 资源 URL | Webpack 5+ | 不需要 |
39
-
40
28
  ## 快速开始
41
29
 
42
30
  ### 1. HTML 中准备容器
43
31
 
44
32
  ```html
45
- <div id="earth" style="width: 100%; height: 100vh;"></div>
46
- <div id="error"></div>
33
+ <div id="earth" style="width: 100vw; height: 100vh;"></div>
47
34
  ```
48
35
 
49
- ### 2. 加载核心脚本 + 初始化地球
50
-
51
- #### 方式一：从包内 assets 加载（Vite 推荐）
36
+ > SDK 初始化时会自动补全 `width: 100%`、`overflow: hidden`、`position: absolute` 等样式，**容器高度需自行设置**（如 `height: 100vh` 或 flex 布局）。
52
37
 
53
- 脚本已内置在 npm 包中，无需手动复制任何文件：
38
+ ### 2. 加载核心脚本 + 初始化地球
54
39
 
55
40
  ```ts
56
- import { loadCore, initVideoPlayer } from '@stampgis/webrtc';
41
+ import { loadCore, initMap } from "@stampgis/webrtc";
57
42
 
58
- // 直接从包内 assets 加载，无需复制文件
43
+ // 从包内 assets 加载核心脚本（可选：不调用时 initMap 内部会自动加载）
59
44
  await loadCore({ useBundledAssets: true });
60
45
 
61
- initVideoPlayer({
62
- earthDomElement: document.getElementById('earth')!,
63
- errorDomElement: document.getElementById('error')!,
64
- iIndex: 0,
46
+ await initMap({
47
+ container: "earth", // 必填，支持 id 或 HTMLElement
48
+ mapIndex: 0,
65
49
  });
66
50
  ```
67
51
 
68
- #### 方式二：从服务器/CDN 加载
69
-
70
- 将 `config/` 和 `core/` 目录部署到服务器或 `public/` 目录：
52
+ ### 3. 使用 StampUtil 接口
71
53
 
72
54
  ```ts
73
- await loadCore({ baseUrl: '/gis/' });
74
- ```
55
+ import StampUtil from "@stampgis/webrtc";
75
56
 
76
- #### 方式三：精确指定 URL
57
+ // 水平距离量算
58
+ const result = await StampUtil.measureHorizontalDist(16, 0xffffffff);
59
+ console.log(result);
77
60
 
78
- ```ts
79
- await loadCore({
80
- configUrl: 'https://cdn.example.com/config/stamp_core_config.js',
81
- pixelstreamingUrl: 'https://cdn.example.com/core/pixelstreaming.js',
82
- playerControlUrl: 'https://cdn.example.com/core/playerControl.js',
83
- serverIp: '192.168.1.100',
84
- });
61
+ // 创建 GUID
62
+ const guid = StampUtil.createGuid();
63
+ console.log(guid);
85
64
  ```
86
65
 
87
- #### 方式四：通过打包器 import 获取 URL
66
+ ## 核心脚本加载
88
67
 
89
- ```ts
90
- import configUrl from '@stampgis/webrtc/assets/config/stamp_core_config.js';
91
- import pixelstreamingUrl from '@stampgis/webrtc/assets/core/pixelstreaming.js';
92
- import playerControlUrl from '@stampgis/webrtc/assets/core/playerControl.js';
68
+ 三个核心脚本按依赖顺序加载：`stamp_core_config.js` → `pixelstreaming.js` → `playerControl.js`，最终在 `window` 上注册 `StampAPI` 全局对象。
93
69
 
94
- await loadCore({ configUrl, pixelstreamingUrl, playerControlUrl });
95
- ```
70
+ `loadCore(options)` 支持四种加载方式：
96
71
 
97
- > Webpack 5 需要配置 `asset/resource` 规则：
98
- > ```js
99
- > module: { rules: [{ test: /@stampgis\/webrtc\/assets\/.*\.js$/, type: 'asset/resource' }] }
100
- > ```
72
+ ```ts
73
+ import { loadCore } from "@stampgis/webrtc";
101
74
 
102
- ### 3. 使用 StampUtil 接口
75
+ // 方式一：从包内 assets 加载（推荐，无需手动复制文件）
76
+ await loadCore({ useBundledAssets: true });
103
77
 
104
- ```ts
105
- import StampUtil from '@stampgis/webrtc';
78
+ // 方式二：从服务器 / CDN 加载（自动拼接固定相对路径）
79
+ await loadCore({ baseUrl: "/gis/" });
106
80
 
107
- // 水平距离量算
108
- const result = await StampUtil.measureHorizontalDist(16, 0xffffffff);
109
- console.log(result);
81
+ // 方式三：精确指定每个脚本 URL
82
+ await loadCore({
83
+ configUrl: "https://cdn.example.com/config/stamp_core_config.js",
84
+ pixelstreamingUrl: "https://cdn.example.com/core/pixelstreaming.js",
85
+ playerControlUrl: "https://cdn.example.com/core/playerControl.js",
86
+ });
110
87
 
111
- // 深拷贝
112
- const copy = StampUtil.deepCopy(someObject);
88
+ // 方式四：通过打包器 import 获取包内 assets 的 URL（最大灵活性）
89
+ import configUrl from "@stampgis/webrtc/assets/config/stamp_core_config.js";
90
+ import pixelstreamingUrl from "@stampgis/webrtc/assets/core/pixelstreaming.js";
91
+ import playerControlUrl from "@stampgis/webrtc/assets/core/playerControl.js";
92
+ await loadCore({ configUrl, pixelstreamingUrl, playerControlUrl });
113
93
  ```
114
94
 
115
95
  ## API
116
96
 
117
- ### `loadCore(options: CoreLoadOptions): Promise<void>`
97
+ ### `loadCore(options?: CoreLoadOptions): Promise<void>`
118
98
 
119
- 动态加载三个核心脚本，按依赖顺序执行。
99
+ 动态加载三个核心脚本，按依赖顺序执行，并等待对应全局变量就绪。
120
100
 
121
- | 参数 | 类型 | 说明 |
122
- |------|------|------|
123
- | `baseUrl` | `string` | 基础路径，自动拼接 `config/stamp_core_config.js` 等 |
124
- | `configUrl` | `string` | 精确指定 stamp_core_config.js 的 URL |
125
- | `pixelstreamingUrl` | `string` | 精确指定 pixelstreaming.js 的 URL |
126
- | `playerControlUrl` | `string` | 精确指定 playerControl.js 的 URL |
127
- | `serverIp` | `string` | 覆盖 stamp_core_config 中的服务器 IP |
128
- | `timeout` | `number` | 超时毫秒数，默认 30000 |
101
+ | 参数 | 类型 | 必填 | 说明 |
102
+ | ------------------- | --------- | ---- | ----------------------------------------------------------- |
103
+ | `useBundledAssets` | `boolean` | 否 | 从包内 `assets/` 目录加载脚本，默认 `false` |
104
+ | `baseUrl` | `string` | 否 | 基础路径，自动拼接 `config/stamp_core_config.js` 等相对路径 |
105
+ | `configUrl` | `string` | 否 | 精确指定 `stamp_core_config.js` 的 URL |
106
+ | `pixelstreamingUrl` | `string` | 否 | 精确指定 `pixelstreaming.js` 的 URL |
107
+ | `playerControlUrl` | `string` | 否 | 精确指定 `playerControl.js` 的 URL |
108
+ | `match_maker` | `string` | 否 | 覆盖 `stamp_core_config` 中的 matchmaker 地址 |
109
+ | `timeout` | `number` | 否 | 超时毫秒数，默认 `30000` |
129
110
 
130
- ### `initVideoPlayer(options: InitVideoPlayerOptions): void`
111
+ > 三种 URL 来源的优先级：显式 URL（`configUrl` 等）> `useBundledAssets` > `baseUrl` 拼接。
131
112
 
132
- 初始化地球渲染，对应 `StampAPI.initVideoPlayer()`。
113
+ ### `initMap(options: InitMapOptions): Promise<unknown>`
133
114
 
134
- | 参数 | 类型 | 说明 |
135
- |------|------|------|
136
- | `earthDomElement` | `HTMLElement` | 地球容器 DOM |
137
- | `errorDomElement` | `HTMLElement` | 错误提示容器 |
138
- | `iIndex` | `number` | 屏幕索引 0/1/2 |
139
- | `showTips` | `boolean` | 是否显示提示 |
115
+ 初始化地图渲染。若核心脚本尚未加载（`window.StampAPI` 不存在），会自动调用 `loadCore()`。`errorContainer` 不传则内部自动创建。
140
116
 
141
- ### `StampUtil`（默认导出）
117
+ | 参数 | 类型 | 必填 | 说明 |
118
+ | ---------------- | ----------------------- | ---- | ----------------------------------------------- |
119
+ | `container` | `string \| HTMLElement` | 是 | 地球容器，支持 DOM 元素或元素 id |
120
+ | `errorContainer` | `string \| HTMLElement` | 否 | 错误提示容器，不传则内部自动创建 |
121
+ | `mapIndex` | `number` | 否 | 屏幕索引（0=主屏、1=副屏1、2=副屏2），默认 `0` |
122
+ | `showTips` | `boolean` | 否 | 是否显示提示，默认 `true` |
123
+ | `coreOptions` | `CoreLoadOptions` | 否 | 核心脚本加载配置，默认 `useBundledAssets: true` |
142
124
 
143
- 包含数百个地图操作方法，详见 `StampUtil.ts` 源码中的 JSDoc 注释。
125
+ ### `StampUtil`（默认导出 / 命名导出）
144
126
 
145
- ### 其他导出
146
-
147
- | 导出 | 说明 |
148
- |------|------|
149
- | `STAMP_RTTI` | 图层类型枚举 |
150
- | `loadScript(url)` | 动态加载单个脚本 |
151
- | `waitForGlobal(name)` | 等待全局变量就绪 |
152
-
153
- ## 脚本加载顺序
127
+ 内置接口库，提供 500+ 个地图操作方法，覆盖：
154
128
 
155
- ```
156
- stamp_core_config.js → window.stamp_core_config
157
- ↓
158
- pixelstreaming.js → window.StampPixelStreaming
159
- ↓
160
- playerControl.js → window.StampAPI
161
- ↓
162
- StampUtil (import) → 读取 window.StampAPI
163
- ```
129
+ - **量算**：水平距离、面积、高度等
130
+ - **图层管理**：DEM / DOM / BIM / 倾斜摄影 / 点云 / 矢量瓦片等多种图层类型
131
+ - **标绘标注**：点 / 线 / 面 / 体 / 图标 / 模型等
132
+ - **空间分析**：通视、坡度、剖面等
133
+ - **视角控制**：飞行定位、视点获取等
134
+ - **工具函数**：GUID 生成、坐标转换、文件保存等
164
135
 
165
- `loadCore()` 严格按此顺序加载，每一步都等待全局变量就绪后才继续下一步。
136
+ 通过 IDE 的 TypeScript 类型提示可查看完整方法列表与参数签名。
166
137
 
167
- ## 从原项目迁移
138
+ ### 其他导出
168
139
 
169
- ### 原 index.html 写法（手动引入）
140
+ | 导出 | 说明 |
141
+ | ------------------------------------------- | ----------------------------------------- |
142
+ | `StampUtil` | 接口库（命名导出） |
143
+ | `STAMP_RTTI` | 图层 / 标绘对象 / 视角等类型常量枚举 |
144
+ | `ASSET_PATHS` | 包内 `assets/` 脚本路径常量 |
145
+ | `loadScript(url)` | 动态加载单个脚本（同 URL 自动去重） |
146
+ | `waitForGlobal(name, timeout?, interval?)` | 等待全局变量就绪，默认超时 10s |
147
+ | `CoreLoadOptions` / `InitMapOptions` 等类型 | 完整 TypeScript 类型定义（`import type`） |
170
148
 
171
- ```html
172
- <head>
173
- <script src="config/stamp_core_config.js"></script>
174
- <script src="core/pixelstreaming.js"></script>
175
- <script src="core/playerControl.js"></script>
176
- </head>
177
- ```
149
+ ## 代理配置（必读）
178
150
 
179
- ### 迁移后写法（动态加载）
151
+ 地图初始化时，像素流推流系统会请求 matchmaker 服务进行负载均衡。该请求是浏览器端 XHR，存在跨域问题，**使用方必须配置代理转发**。
180
152
 
181
- 删掉 `index.html` 中的三个 `<script>` 标签，改为：
153
+ ### 开发环境（Vite）
182
154
 
183
155
  ```ts
184
- import { loadCore, initVideoPlayer } from '@stampgis/webrtc';
185
-
186
- await loadCore({ baseUrl: '/' });
187
- initVideoPlayer({ earthDomElement: earthRef.value });
156
+ // vite.config.ts
157
+ server: {
158
+ proxy: {
159
+ "/matchmaker": {
160
+ target: "http://<推流服务器IP>:30080",
161
+ changeOrigin: true,
162
+ rewrite: (path) => path.replace(/^\/matchmaker/, ""),
163
+ },
164
+ },
165
+ }
188
166
  ```
189
167
 
190
- ### 原 StampUtil 引用
168
+ ### 生产环境（Nginx）
191
169
 
192
- ```ts
193
- // 原来
194
- import StampUtil from '@/utils/StampUtil';
195
-
196
- // 迁移后
197
- import StampUtil from '@stampgis/webrtc';
170
+ ```nginx
171
+ location /matchmaker/ {
172
+ proxy_pass http://<推流服务器IP>:30080/;
173
+ }
198
174
  ```
199
175
 
200
- ## 开发
176
+ ### 不想配代理？
201
177
 
202
- ```bash
203
- # 安装依赖
204
- npm install
178
+ 若 matchmaker 服务端开启了 CORS，可通过 `match_maker` 参数直连：
205
179
 
206
- # 构建
207
- npm run build
180
+ ```ts
181
+ await initMap({
182
+ container: "earth",
183
+ coreOptions: {
184
+ match_maker: "http://<推流服务器IP>:30080",
185
+ },
186
+ });
208
187
  ```
209
188
 
210
- 构建产物在 `dist/`，输出 ESM + CJS 两种格式 + TypeScript 类型声明。
211
-
212
- ## 目录结构
213
-
214
- ```
215
- @stampgis/webrtc/
216
- ├── src/
217
- │ ├── index.ts # 主入口：loadCore + initVideoPlayer + 导出 StampUtil
218
- │ ├── loader.ts # 动态脚本加载器（loadScript + waitForGlobal）
219
- │ ├── types.ts # 类型定义 + Window 全局变量声明
220
- │ ├── StampUtil.ts # 接口封装库（从 MCPWebsite/src/utils/ 复制）
221
- │ └── StampRtti.ts # 图层类型枚举（从 MCPWebsite/src/utils/ 复制）
222
- ├── assets/ # 内置静态资源（打包进 npm 包）
223
- │ ├── config/
224
- │ │ └── stamp_core_config.js
225
- │ └── core/
226
- │ ├── pixelstreaming.js
227
- │ ├── playerControl.js
228
- │ ├── worker.js / workerEx.js
229
- │ ├── gbk.js / shapefile.js
230
- │ ├── spark-md5.min.js / widgetConfig.js
231
- │ └── *.symlib
232
- ├── package.json
233
- ├── tsconfig.json
234
- ├── tsup.config.ts
235
- └── README.md
236
- ```
189
+ > 注意：`playerControl.js` 内部使用**同步 XHR** 请求 matchmaker，部分浏览器对同步跨域请求有限制，建议优先使用代理方案。
237
190
 
238
191
  ## License
239
192
 
package/assets/config/stamp_core_config.js CHANGED
@@ -5,35 +5,10 @@
5
5
  * 版权所有：Copyright by 睿城传奇
6
6
  * 使用单位：合作单位
7
7
  */
8
- var SYSTEMID = "";
9
- var SERVERIP = "192.168.100.134";
10
- SERVERIP = SERVERIP ? SERVERIP : window.location.host;
11
- var httpOrHttps = window.location.protocol;
12
8
  stamp_core_config = {
13
- match_maker: `/matchmaker`, //
9
+ match_maker: `/matchmaker`,
14
10
  use_match_maker: true, //：不使用matchmaker，底层调试用。正常部署给true即可。
15
11
  signal_streaming: "ws://localhost:81", //信令服务的IP和端口（use_match_maker为false时生效）
16
- gb28181ApacheUrl: `http://${SERVERIP}:8082`, //不需要https，因为是内网使用
17
- service_ip: httpOrHttps + "//" + SERVERIP, //通过exe客户端取服务器上文件用到
18
- soService_ip: httpOrHttps + "//" + SERVERIP, // stamp后台服务
19
- nodeservice_ip: "/nodeServer", // node业务服务"http://localhost:3003",
20
- updateLayerUrl: `${httpOrHttps}//${SERVERIP}:8881/api/UpdateLayer`, //图层更新服务
21
- highlightColor: [0xcc0000ff, 0xcc0000ff], //高亮色、发光色 0xccff0000, 0xccff3300
22
- userFolderName: "用户数据", //后台图层目录节点名称(用来存放导入的用户数据)
23
- sysTimeout: 30,
24
- checkTime: 5,
25
- hasLogin: false, //是否有登录页面
26
12
  windowDevicePixelRatio: window.devicePixelRatio || 1, //根据电脑分辨率大小和性能调整：清晰度
27
- initDateTime: [2024, 9, 23, 10, 0, 0], //底层配置的默认时间2024-9-23 10:00:00
28
- isRealSolarTime: true, //真太阳时间（本地时间），设置为true时可以设置时差
29
- timeDiffer: 0, //小时时差
30
- logo: "images/logo.png",
31
- title: ["云渲染", "三维基础平台"], //第一个名称会变色
32
- flyAPI: "https://flyseebeta.guihuao.com",
33
- token:
34
- "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VybmFtZSI6ImFkbWluIiwic2VydmljZWFwcGlkIjoiZGExM2NlNjYtZWY4My00MzUxLTgzMTUtNDhkNDBjZGYwMDUwIiwiaWF0IjoxNzc2Mzk4ODQ5LCJleHAiOjIwOTE5NzQ4NDl9.uONoiULmftrj_i4e02n_Yn6jS8LoUd5UjACXlXcbBz4",
35
13
  bigscreen: false,
36
- systemid: SYSTEMID,
37
- screenSizeType: 2, //1、屏幕原始分辨率 2、屏幕缩放后分辨率 3、浏览器3D视窗分辨率
38
- product: "三维基础平台应用系统",
39
14
  };