@stampgis/webrtc 1.0.0 → 1.0.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.
Files changed (9) hide show
  1. package/README.md +64 -158
  2. package/assets/config/stamp_core_config.js +1 -26
  3. package/dist/index.cjs +3596 -1209
  4. package/dist/index.cjs.map +1 -1
  5. package/dist/index.d.mts +48 -23
  6. package/dist/index.d.ts +48 -23
  7. package/dist/index.js +3627 -1203
  8. package/dist/index.js.map +1 -1
  9. package/package.json +2 -2
package/README.md CHANGED
@@ -1,22 +1,7 @@
1
1
  # @stampgis/webrtc
2
2
 
3
- StampGIS 私有地图 SDK npm 包，封装 `StampUtil.ts` 接口库与 `core/` + `config/` 脚本的动态加载逻辑。
4
-
5
- ## 为什么需要这个包
6
-
7
- 原项目（MCPWebsite）中，地图加载需要在 `index.html` 的 `<head>` 里手动引入三个 `<script>` 标签：
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
- ```
14
-
15
- 这三个脚本在 `window` 上注册全局变量（`stamp_core_config`、`StampPixelStreaming`、`StampAPI`），无法通过 ES module `import` 引入。而 `StampUtil.ts` 虽然是 TypeScript 模块，却依赖运行时的 `window.StampAPI` 全局变量。
16
-
17
- 本包解决两个问题：
18
- 1. 将三个脚本按正确顺序动态加载，等待全局变量就绪
19
- 2. 将 `StampUtil.ts` 编译为可 `import` 的 npm 模块
3
+ StampGIS‑WebRTC 三维地图开发 SDK，对地图底层工具类、核心实例、全局配置进行模块化封装。
4
+ 解决传统脚本多‑script 标签顺序引入、全局变量污染、无法直接通过 ES‑Module 导入调用等痛点，开箱即用，支持按需加载、动态资源注入，适配 Vite / Webpack / CDN 多种接入方式。
20
5
 
21
6
  ## 安装
22
7
 
@@ -26,26 +11,16 @@ npm install @stampgis/webrtc
26
11
  pnpm add @stampgis/webrtc
27
12
  ```
28
13
 
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
14
  ## 快速开始
41
15
 
42
16
  ### 1. HTML 中准备容器
43
17
 
44
18
  ```html
45
- <div id="earth" style="width: 100%; height: 100vh;"></div>
46
- <div id="error"></div>
19
+ <div id="earth" style="width: 100vw;height: 100vh;"></div>
47
20
  ```
48
21
 
22
+ > SDK 初始化时会自动设置 `width: 100%; overflow: hidden; position: absolute;`，**容器高度需自行设置**（如 `height: 100vh` 或 flex 布局等）。
23
+
49
24
  ### 2. 加载核心脚本 + 初始化地球
50
25
 
51
26
  #### 方式一：从包内 assets 加载（Vite 推荐）
@@ -53,15 +28,13 @@ pnpm add @stampgis/webrtc
53
28
  脚本已内置在 npm 包中，无需手动复制任何文件：
54
29
 
55
30
  ```ts
56
- import { loadCore, initVideoPlayer } from '@stampgis/webrtc';
31
+ import { loadCore, initMap } from "@stampgis/webrtc";
57
32
 
58
- // 直接从包内 assets 加载，无需复制文件
59
33
  await loadCore({ useBundledAssets: true });
60
34
 
61
- initVideoPlayer({
62
- earthDomElement: document.getElementById('earth')!,
63
- errorDomElement: document.getElementById('error')!,
64
- iIndex: 0,
35
+ initMap({
36
+ container: "earth",
37
+ mapIndex: 0,
65
38
  });
66
39
  ```
67
40
 
@@ -70,46 +43,21 @@ initVideoPlayer({
70
43
  将 `config/` 和 `core/` 目录部署到服务器或 `public/` 目录：
71
44
 
72
45
  ```ts
73
- await loadCore({ baseUrl: '/gis/' });
74
- ```
75
-
76
- #### 方式三：精确指定 URL
77
-
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
- });
85
- ```
86
-
87
- #### 方式四：通过打包器 import 获取 URL
88
-
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';
93
-
94
- await loadCore({ configUrl, pixelstreamingUrl, playerControlUrl });
46
+ await loadCore({ baseUrl: "/gis/" });
95
47
  ```
96
48
 
97
- > Webpack 5 需要配置 `asset/resource` 规则：
98
- > ```js
99
- > module: { rules: [{ test: /@stampgis\/webrtc\/assets\/.*\.js$/, type: 'asset/resource' }] }
100
- > ```
101
-
102
49
  ### 3. 使用 StampUtil 接口
103
50
 
104
51
  ```ts
105
- import StampUtil from '@stampgis/webrtc';
52
+ import StampUtil from "@stampgis/webrtc";
106
53
 
107
54
  // 水平距离量算
108
55
  const result = await StampUtil.measureHorizontalDist(16, 0xffffffff);
109
56
  console.log(result);
110
57
 
111
- // 深拷贝
112
- const copy = StampUtil.deepCopy(someObject);
58
+ // 创建 GUID
59
+ const guid = StampUtil.createGuid();
60
+ console.log(guid);
113
61
  ```
114
62
 
115
63
  ## API
@@ -118,122 +66,80 @@ const copy = StampUtil.deepCopy(someObject);
118
66
 
119
67
  动态加载三个核心脚本，按依赖顺序执行。
120
68
 
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 |
69
+ | 参数 | 类型 | 说明 |
70
+ | ------------------- | -------- | --------------------------------------------------- |
71
+ | `baseUrl` | `string` | 基础路径，自动拼接 `config/stamp_core_config.js` 等 |
72
+ | `configUrl` | `string` | 精确指定 stamp_core_config.js 的 URL |
73
+ | `pixelstreamingUrl` | `string` | 精确指定 pixelstreaming.js 的 URL |
74
+ | `playerControlUrl` | `string` | 精确指定 playerControl.js 的 URL |
75
+ | `match_maker` | `string` | 覆盖 stamp_core_config 中的matchmaker地址 |
76
+ | `timeout` | `number` | 超时毫秒数，默认 30000 |
129
77
 
130
- ### `initVideoPlayer(options: InitVideoPlayerOptions): void`
78
+ ### `initMap(options: InitMapOptions): Promise<void>`
131
79
 
132
- 初始化地球渲染，对应 `StampAPI.initVideoPlayer()`。
80
+ 初始化地图渲染。如果核心脚本尚未加载会自动调用 `loadCore()`。`errorContainer` 不传则在内部自动创建。
133
81
 
134
- | 参数 | 类型 | 说明 |
135
- |------|------|------|
136
- | `earthDomElement` | `HTMLElement` | 地球容器 DOM |
137
- | `errorDomElement` | `HTMLElement` | 错误提示容器 |
138
- | `iIndex` | `number` | 屏幕索引 0/1/2 |
139
- | `showTips` | `boolean` | 是否显示提示 |
82
+ | 参数 | 类型 | 说明 |
83
+ | ---------------- | ----------------------- | ----------------------------------------------- |
84
+ | `container` | `string \| HTMLElement` | 地球容器，支持 DOM 元素或元素 id |
85
+ | `errorContainer` | `string \| HTMLElement` | 错误提示容器（可选），不传则内部自动创建 |
86
+ | `mapIndex` | `number` | 屏幕索引 0/1/2，默认 0 |
87
+ | `showTips` | `boolean` | 是否显示提示，默认 true |
88
+ | `coreOptions` | `CoreLoadOptions` | 核心脚本加载配置（可选，默认 useBundledAssets） |
140
89
 
141
90
  ### `StampUtil`（默认导出）
142
91
 
143
- 包含数百个地图操作方法，详见 `StampUtil.ts` 源码中的 JSDoc 注释。
92
+ 包含数百个地图操作方法，提供地图操作、量算、图层管理、标注、分析等功能，通过 IDE 的 TypeScript 类型提示可查看完整方法列表。
144
93
 
145
94
  ### 其他导出
146
95
 
147
- | 导出 | 说明 |
148
- |------|------|
149
- | `STAMP_RTTI` | 图层类型枚举 |
150
- | `loadScript(url)` | 动态加载单个脚本 |
96
+ | 导出 | 说明 |
97
+ | --------------------- | ---------------- |
98
+ | `STAMP_RTTI` | 图层类型枚举 |
99
+ | `loadScript(url)` | 动态加载单个脚本 |
151
100
  | `waitForGlobal(name)` | 等待全局变量就绪 |
152
101
 
153
- ## 脚本加载顺序
154
-
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
- ```
164
-
165
- `loadCore()` 严格按此顺序加载，每一步都等待全局变量就绪后才继续下一步。
166
-
167
- ## 从原项目迁移
168
-
169
- ### 原 index.html 写法（手动引入）
170
-
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
- ```
102
+ ## 代理配置（必读）
178
103
 
179
- ### 迁移后写法（动态加载）
104
+ 地图初始化时，像素流推流系统会请求 matchmaker 服务进行负载均衡。该请求是浏览器端 XHR，存在跨域问题，**使用方必须配置代理转发**。
180
105
 
181
- 删掉 `index.html` 中的三个 `<script>` 标签，改为：
106
+ ### 开发环境（Vite）
182
107
 
183
108
  ```ts
184
- import { loadCore, initVideoPlayer } from '@stampgis/webrtc';
185
-
186
- await loadCore({ baseUrl: '/' });
187
- initVideoPlayer({ earthDomElement: earthRef.value });
109
+ // vite.config.ts
110
+ server: {
111
+ proxy: {
112
+ '/matchmaker': {
113
+ target: 'http://<推流服务器IP>:30080',
114
+ changeOrigin: true,
115
+ rewrite: (path) => path.replace(/^\/matchmaker/, ''),
116
+ },
117
+ },
118
+ }
188
119
  ```
189
120
 
190
- ### 原 StampUtil 引用
191
-
192
- ```ts
193
- // 原来
194
- import StampUtil from '@/utils/StampUtil';
121
+ ### 生产环境（Nginx）
195
122
 
196
- // 迁移后
197
- import StampUtil from '@stampgis/webrtc';
123
+ ```nginx
124
+ location /matchmaker/ {
125
+ proxy_pass http://<推流服务器IP>:30080/;
126
+ }
198
127
  ```
199
128
 
200
- ## 开发
129
+ ### 不想配代理？
201
130
 
202
- ```bash
203
- # 安装依赖
204
- npm install
131
+ 如果 matchmaker 服务端开启了 CORS，可通过 `match_maker` 参数直连：
205
132
 
206
- # 构建
207
- npm run build
133
+ ```ts
134
+ await initMap({
135
+ container: "earth",
136
+ coreOptions: {
137
+ match_maker: "http://<推流服务器IP>:30080",
138
+ },
139
+ });
208
140
  ```
209
141
 
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
- ```
142
+ > 注意：`playerControl.js` 内部使用**同步 XHR** 请求 matchmaker，部分浏览器对同步跨域请求有限制，建议优先使用代理方案。
237
143
 
238
144
  ## License
239
145
 
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
  };