@stampgis/webrtc 1.0.1 → 1.0.2

package/README.md

@@ -1,7 +1,21 @@
 # @stampgis/webrtc
 
-StampGIS‑WebRTC 三维地图开发 SDK，对地图底层工具类、核心实例、全局配置进行模块化封装。
-解决传统脚本多‑script 标签顺序引入、全局变量污染、无法直接通过 ES‑Module 导入调用等痛点，开箱即用，支持按需加载、动态资源注入，适配 Vite / Webpack / CDN 多种接入方式。
+StampGIS 三维地图 WebRTC（像素流）开发 SDK，对底层工具类、核心脚本加载与全局配置做模块化封装。
+
+解决传统「多 `<script>` 标签按序引入 + 全局变量污染 + 无法通过 ES Module 导入」的痛点，开箱即用，支持按需加载、动态资源注入，适配 Vite / Webpack / CDN 多种接入方式。
+
+## 特性
+
+- 核心脚本（config / pixelstreaming / playerControl）已内置在 npm 包 `assets/` 目录，无需手动复制文件
+- 提供 `loadCore()` 动态加载、`initMap()` 一键初始化，自动处理脚本依赖顺序与全局变量就绪等待
+- 内置 `StampUtil` 接口库，提供 500+ 个地图操作方法（量算、图层管理、标绘标注、空间分析、视角控制等）
+- ES Module（`import`）与 CommonJS（`require`）双格式，附带完整 TypeScript 类型声明
+
+## 环境要求
+
+- **浏览器环境**：依赖 `window` / `document`，不支持 Node / SSR
+- 使用 `useBundledAssets` 时需 Vite 或 Webpack 5+（依赖 `import.meta.url` 解析静态资源）
+- 使用 `baseUrl` 或精确 URL 方式加载时，对打包器无特殊要求
 
 ## 安装
 
@@ -16,36 +30,25 @@ pnpm add @stampgis/webrtc
 ### 1. HTML 中准备容器
 
 ```html
-<div id="earth" style="width: 100vw;height: 100vh;"></div>
+<div id="earth" style="width: 100vw; height: 100vh;"></div>
 ```
 
-> SDK 初始化时会自动设置 `width: 100%; overflow: hidden; position: absolute;`，**容器高度需自行设置**（如 `height: 100vh` 或 flex 布局等）。
+> SDK 初始化时会自动补全 `width: 100%`、`overflow: hidden`、`position: absolute` 等样式，**容器高度需自行设置**（如 `height: 100vh` 或 flex 布局）。
 
 ### 2. 加载核心脚本 + 初始化地球
 
-#### 方式一：从包内 assets 加载（Vite 推荐）
-
-脚本已内置在 npm 包中，无需手动复制任何文件：
-
 ```ts
 import { loadCore, initMap } from "@stampgis/webrtc";
 
+// 从包内 assets 加载核心脚本（可选：不调用时 initMap 内部会自动加载）
 await loadCore({ useBundledAssets: true });
 
-initMap({
-  container: "earth",
+await initMap({
+  container: "earth", // 必填，支持 id 或 HTMLElement
   mapIndex: 0,
 });
 ```
 
-#### 方式二：从服务器/CDN 加载
-
-将 `config/` 和 `core/` 目录部署到服务器或 `public/` 目录：
-
-```ts
-await loadCore({ baseUrl: "/gis/" });
-```
-
 ### 3. 使用 StampUtil 接口
 
 ```ts
@@ -60,44 +63,88 @@ const guid = StampUtil.createGuid();
 console.log(guid);
 ```
 
+## 核心脚本加载
+
+三个核心脚本按依赖顺序加载：`stamp_core_config.js` → `pixelstreaming.js` → `playerControl.js`，最终在 `window` 上注册 `StampAPI` 全局对象。
+
+`loadCore(options)` 支持四种加载方式：
+
+```ts
+import { loadCore } from "@stampgis/webrtc";
+
+// 方式一：从包内 assets 加载（推荐，无需手动复制文件）
+await loadCore({ useBundledAssets: true });
+
+// 方式二：从服务器 / CDN 加载（自动拼接固定相对路径）
+await loadCore({ baseUrl: "/gis/" });
+
+// 方式三：精确指定每个脚本 URL
+await loadCore({
+  configUrl: "https://cdn.example.com/config/stamp_core_config.js",
+  pixelstreamingUrl: "https://cdn.example.com/core/pixelstreaming.js",
+  playerControlUrl: "https://cdn.example.com/core/playerControl.js",
+});
+
+// 方式四：通过打包器 import 获取包内 assets 的 URL（最大灵活性）
+import configUrl from "@stampgis/webrtc/assets/config/stamp_core_config.js";
+import pixelstreamingUrl from "@stampgis/webrtc/assets/core/pixelstreaming.js";
+import playerControlUrl from "@stampgis/webrtc/assets/core/playerControl.js";
+await loadCore({ configUrl, pixelstreamingUrl, playerControlUrl });
+```
+
 ## API
 
-### `loadCore(options: CoreLoadOptions): Promise<void>`
+### `loadCore(options?: CoreLoadOptions): Promise<void>`
+
+动态加载三个核心脚本，按依赖顺序执行，并等待对应全局变量就绪。
+
+| 参数                | 类型      | 必填 | 说明                                                        |
+| ------------------- | --------- | ---- | ----------------------------------------------------------- |
+| `useBundledAssets`  | `boolean` | 否   | 从包内 `assets/` 目录加载脚本，默认 `false`                 |
+| `baseUrl`           | `string`  | 否   | 基础路径，自动拼接 `config/stamp_core_config.js` 等相对路径 |
+| `configUrl`         | `string`  | 否   | 精确指定 `stamp_core_config.js` 的 URL                      |
+| `pixelstreamingUrl` | `string`  | 否   | 精确指定 `pixelstreaming.js` 的 URL                         |
+| `playerControlUrl`  | `string`  | 否   | 精确指定 `playerControl.js` 的 URL                          |
+| `match_maker`       | `string`  | 否   | 覆盖 `stamp_core_config` 中的 matchmaker 地址               |
+| `timeout`           | `number`  | 否   | 超时毫秒数，默认 `30000`                                    |
+
+> 三种 URL 来源的优先级：显式 URL（`configUrl` 等）> `useBundledAssets` > `baseUrl` 拼接。
 
-动态加载三个核心脚本，按依赖顺序执行。
+### `initMap(options: InitMapOptions): Promise<unknown>`
 
-| 参数                | 类型     | 说明                                                |
-| ------------------- | -------- | --------------------------------------------------- |
-| `baseUrl`           | `string` | 基础路径，自动拼接 `config/stamp_core_config.js` 等 |
-| `configUrl`         | `string` | 精确指定 stamp_core_config.js 的 URL                |
-| `pixelstreamingUrl` | `string` | 精确指定 pixelstreaming.js 的 URL                   |
-| `playerControlUrl`  | `string` | 精确指定 playerControl.js 的 URL                    |
-| `match_maker`       | `string` | 覆盖 stamp_core_config 中的matchmaker地址           |
-| `timeout`           | `number` | 超时毫秒数，默认 30000                              |
+初始化地图渲染。若核心脚本尚未加载（`window.StampAPI` 不存在），会自动调用 `loadCore()`。`errorContainer` 不传则内部自动创建。
 
-### `initMap(options: InitMapOptions): Promise<void>`
+| 参数             | 类型                    | 必填 | 说明                                            |
+| ---------------- | ----------------------- | ---- | ----------------------------------------------- |
+| `container`      | `string \| HTMLElement` | 是   | 地球容器，支持 DOM 元素或元素 id                |
+| `errorContainer` | `string \| HTMLElement` | 否   | 错误提示容器，不传则内部自动创建                |
+| `mapIndex`       | `number`                | 否   | 屏幕索引（0=主屏、1=副屏1、2=副屏2），默认 `0`  |
+| `showTips`       | `boolean`               | 否   | 是否显示提示，默认 `true`                       |
+| `coreOptions`    | `CoreLoadOptions`       | 否   | 核心脚本加载配置，默认 `useBundledAssets: true` |
 
-初始化地图渲染。如果核心脚本尚未加载会自动调用 `loadCore()`。`errorContainer` 不传则在内部自动创建。
+### `StampUtil`（默认导出 / 命名导出）
 
-| 参数             | 类型                    | 说明                                            |
-| ---------------- | ----------------------- | ----------------------------------------------- |
-| `container`      | `string \| HTMLElement` | 地球容器，支持 DOM 元素或元素 id                |
-| `errorContainer` | `string \| HTMLElement` | 错误提示容器（可选），不传则内部自动创建        |
-| `mapIndex`       | `number`                | 屏幕索引 0/1/2，默认 0                          |
-| `showTips`       | `boolean`               | 是否显示提示，默认 true                         |
-| `coreOptions`    | `CoreLoadOptions`       | 核心脚本加载配置（可选，默认 useBundledAssets） |
+内置接口库，提供 500+ 个地图操作方法，覆盖：
 
-### `StampUtil`（默认导出）
+- **量算**：水平距离、面积、高度等
+- **图层管理**：DEM / DOM / BIM / 倾斜摄影 / 点云 / 矢量瓦片等多种图层类型
+- **标绘标注**：点 / 线 / 面 / 体 / 图标 / 模型等
+- **空间分析**：通视、坡度、剖面等
+- **视角控制**：飞行定位、视点获取等
+- **工具函数**：GUID 生成、坐标转换、文件保存等
 
-包含数百个地图操作方法，提供地图操作、量算、图层管理、标注、分析等功能，通过 IDE 的 TypeScript 类型提示可查看完整方法列表。
+通过 IDE 的 TypeScript 类型提示可查看完整方法列表与参数签名。
 
 ### 其他导出
 
-| 导出                  | 说明             |
-| --------------------- | ---------------- |
-| `STAMP_RTTI`          | 图层类型枚举     |
-| `loadScript(url)`     | 动态加载单个脚本 |
-| `waitForGlobal(name)` | 等待全局变量就绪 |
+| 导出                                        | 说明                                      |
+| ------------------------------------------- | ----------------------------------------- |
+| `StampUtil`                                 | 接口库（命名导出）                        |
+| `STAMP_RTTI`                                | 图层 / 标绘对象 / 视角等类型常量枚举      |
+| `ASSET_PATHS`                               | 包内 `assets/` 脚本路径常量               |
+| `loadScript(url)`                           | 动态加载单个脚本（同 URL 自动去重）       |
+| `waitForGlobal(name, timeout?, interval?)`  | 等待全局变量就绪，默认超时 10s            |
+| `CoreLoadOptions` / `InitMapOptions` 等类型 | 完整 TypeScript 类型定义（`import type`） |
 
 ## 代理配置（必读）
 
@@ -109,10 +156,10 @@ console.log(guid);
 // vite.config.ts
 server: {
   proxy: {
-    '/matchmaker': {
-      target: 'http://<推流服务器IP>:30080',
+    "/matchmaker": {
+      target: "http://<推流服务器IP>:30080",
       changeOrigin: true,
-      rewrite: (path) => path.replace(/^\/matchmaker/, ''),
+      rewrite: (path) => path.replace(/^\/matchmaker/, ""),
     },
   },
 }
@@ -128,7 +175,7 @@ location /matchmaker/ {
 
 ### 不想配代理？
 
-如果 matchmaker 服务端开启了 CORS，可通过 `match_maker` 参数直连：
+若 matchmaker 服务端开启了 CORS，可通过 `match_maker` 参数直连：
 
 ```ts
 await initMap({