@stampgis/webrtc

StampGIS 三维地图 WebRTC（像素流）开发 SDK，对底层工具类、核心脚本加载与全局配置做模块化封装。

解决传统「多 <script> 标签按序引入 + 全局变量污染 + 无法通过 ES Module 导入」的痛点，开箱即用，支持按需加载、动态资源注入，适配 Vite / Webpack / CDN 多种接入方式。

特性

• 核心脚本（config / pixelstreaming / playerControl）已内置在 npm 包 assets/ 目录，无需手动复制文件
• 提供 loadCore() 动态加载、initMap() 一键初始化，自动处理脚本依赖顺序与全局变量就绪等待
• 内置 StampUtil 接口库，提供 500+ 个地图操作方法（量算、图层管理、标绘标注、空间分析、视角控制等）
• 内置 StampGIS AI 助手：@stampgis/webrtc/ai（headless，可对话并驱动地图工具）+ @stampgis/webrtc/ai/ui（Vue 3 组件与 Web Component）
• ES Module（import）与 CommonJS（require）双格式，附带完整 TypeScript 类型声明

环境要求

• 浏览器环境：依赖 window / document，不支持 Node / SSR
• 使用 useBundledAssets 时需 Vite 或 Webpack 5+（依赖 import.meta.url 解析静态资源）
• 使用 baseUrl 或精确 URL 方式加载时，对打包器无特殊要求
• AI 子入口：@stampgis/webrtc/ai（headless）无框架依赖；@stampgis/webrtc/ai/ui（Vue 组件）需 Vue 3；图表功能运行时按需加载宿主的 echarts（不限制版本，不装也不影响对话与工具，仅图表不可用）

安装

npm install @stampgis/webrtc
# 或
pnpm add @stampgis/webrtc

快速开始

1. HTML 中准备容器

<div id="earth" style="width: 100vw; height: 100vh;"></div>

SDK 初始化时会自动补全 width: 100%、overflow: hidden、position: absolute 等样式，容器高度需自行设置（如 height: 100vh 或 flex 布局）。

2. 加载核心脚本 + 初始化地球

import { loadCore, initMap } from "@stampgis/webrtc";

// 从包内 assets 加载核心脚本（可选：不调用时 initMap 内部会自动加载）
await loadCore({ useBundledAssets: true });

await initMap({
  container: "earth", // 必填，支持 id 或 HTMLElement
  mapIndex: 0,
});

3. 使用 StampUtil 接口

import StampUtil from "@stampgis/webrtc";

// 水平距离量算
const result = await StampUtil.measureHorizontalDist(16, 0xffffffff);
console.log(result);

// 创建 GUID
const guid = StampUtil.createGuid();
console.log(guid);

核心脚本加载

三个核心脚本按依赖顺序加载：stamp_core_config.js → pixelstreaming.js → playerControl.js，最终在 window 上注册 StampAPI 全局对象。

loadCore(options) 支持四种加载方式：

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
//  Vite：import 加 ?url 即可
import configUrl from "@stampgis/webrtc/assets/config/stamp_core_config.js?url";
import pixelstreamingUrl from "@stampgis/webrtc/assets/core/pixelstreaming.js?url";
import playerControlUrl from "@stampgis/webrtc/assets/core/playerControl.js?url";
await loadCore({ configUrl, pixelstreamingUrl, playerControlUrl });

注意：方式四依赖打包器处理 import。纯原生 ESM 或 CDN <script> 引入（无打包器）时无法从 node_modules 引用脚本文件，请把 assets/ 下三个脚本部署到自己的服务器/CDN，改用方式二 baseUrl。

API

loadCore(options?: CoreLoadOptions): Promise<void>

动态加载三个核心脚本，按依赖顺序执行，并等待对应全局变量就绪。

| 参数 | 类型 | 必填 | 说明 | | ------------------- | --------- | ---- | -------------------------------------------------------------- | | useBundledAssets | boolean | 否 | 从包内 assets/ 目录加载脚本（仅 ESM 环境有效），默认 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>

初始化地图渲染。若核心脚本尚未加载（window.StampAPI 不存在），会自动调用 loadCore()。errorContainer 不传则内部自动创建。

| 参数 | 类型 | 必填 | 说明 | | ---------------- | ----------------------- | ---- | ----------------------------------------------- | | container | string \| HTMLElement | 是 | 地球容器，支持 DOM 元素或元素 id | | errorContainer | string \| HTMLElement | 否 | 错误提示容器，不传则内部自动创建 | | mapIndex | number | 否 | 屏幕索引（0=主屏、1=副屏1、2=副屏2），默认 0 | | showTips | boolean | 否 | 是否显示提示，默认 true | | coreOptions | CoreLoadOptions | 否 | 核心脚本加载配置，默认 useBundledAssets: true |

StampUtil（默认导出 / 命名导出）

内置接口库，提供 500+ 个地图操作方法，覆盖：

• 量算：水平距离、面积、高度等
• 图层管理：DEM / DOM / BIM / 倾斜摄影 / 点云 / 矢量瓦片等多种图层类型
• 标绘标注：点 / 线 / 面 / 体 / 图标 / 模型等
• 空间分析：通视、坡度、剖面等
• 视角控制：飞行定位、视点获取等
• 工具函数：GUID 生成、坐标转换、文件保存等

通过 IDE 的 TypeScript 类型提示可查看完整方法列表与参数签名。

其他导出

| 导出 | 说明 | | ------------------------------------------- | ----------------------------------------- | | StampUtil | 接口库（命名导出） | | STAMP_RTTI | 图层 / 标绘对象 / 视角等类型常量枚举 | | ASSET_PATHS | 包内 assets/ 脚本路径常量 | | loadScript(url) | 动态加载单个脚本（同 URL 自动去重） | | waitForGlobal(name, timeout?, interval?) | 等待全局变量就绪，默认超时 10s | | CoreLoadOptions / InitMapOptions 等类型 | 完整 TypeScript 类型定义（import type） |

AI 助手能力由独立子入口提供：@stampgis/webrtc/ai（headless）与 @stampgis/webrtc/ai/ui（Vue 组件与 Web Component），详见下方「AI 助手（可选）」。

AI 助手（可选）

SDK 内置 StampGIS AI 助手能力，按需从两个子入口引入：

| 子入口 | 内容 | 额外依赖 | | ------------------------ | ----------------------------------------------------------------------------- | ------------------------------------------------ | | @stampgis/webrtc/ai | headless 能力层：助手实例、工具执行器、对话/执行通道、事件总线 | 无（不依赖 Vue、不依赖 DOM 结构，Node 中可复用） | | @stampgis/webrtc/ai/ui | Vue 3 组件：StampAiPanel、StampAiButton、ChartCard + Web Component 封装 | vue（必需）、echarts（仅用到图表时） |

headless 用法

不用 Vue 组件、想自己控制对话流程时用这个子入口。下面每行都是独立能力，按需调用即可，不是必须依次执行的步骤：

import { createStampAiAssistant } from "@stampgis/webrtc/ai";

const ai = createStampAiAssistant({ accessKey: "default" }); // 创建即连接
ai.on("message", (msg) => console.log(msg)); // 订阅对话消息（可选）
ai.registerTool("my_tool", async (args) => "ok"); // 注册自定义工具（可选）
await ai.ask("开启地下浏览"); // 走大模型
await ai.executeTool("layer_visible", { guid: "x", bShow: false }); // 绕过大模型直调工具
ai.destroy(); // 断开两条通道

Vue 3 用法

<script setup lang="ts">
import { ref } from "vue";
import { createStampAiAssistant } from "@stampgis/webrtc/ai";
import { StampAiButton, StampAiPanel } from "@stampgis/webrtc/ai/ui";
import "@stampgis/webrtc/ai/ui/style.css"; // 组件样式，必须引入

const ai = createStampAiAssistant({ accessKey: "default" });
const visible = ref(false);
</script>

<template>
  <StampAiButton @click="visible = true" />
  <StampAiPanel v-if="visible" :assistant="ai" @close="visible = false" />
</template>

StampAiPanel 传入 assistant 时会复用宿主实例（推荐，与 executeTool/registerTool 共用）；不传则自行创建并在卸载时销毁。

非 Vue 页面（Web Component）

import { defineStampAiElement } from "@stampgis/webrtc/ai/ui";
import "@stampgis/webrtc/ai/ui/style.css";

defineStampAiElement(); // 注册 <stamp-ai>，只需一次

<stamp-ai access-key="default"></stamp-ai>
<!-- 关闭时由宿主移除：element.addEventListener("close", () => element.remove()) -->

两个后端地址（都是 WebSocket，默认走同源，开发环境需自行代理这两个前缀）：

| 默认地址 | 用途 | 对接的服务 | 覆盖参数 | | ----------- | ------------ | -------------------- | ------------ | | /agentwebsocket | 对话通道 | Agent 后台管理服务 | chatUrl | | /mcpwebsocket | 工具执行通道 | MCP 工具网关代理服务 | gatewayUrl |

代理配置（必读）

地图初始化时，像素流推流系统会请求 matchmaker 服务进行负载均衡。该请求是浏览器端 XHR，存在跨域问题，使用方必须配置代理转发。

开发环境（Vite）

// vite.config.ts
server: {
  proxy: {
    "/matchmaker": {
      target: "http://<推流服务器IP>:30080",
      changeOrigin: true,
      rewrite: (path) => path.replace(/^\/matchmaker/, ""),
    },
  },
}

生产环境（Nginx）

location /matchmaker/ {
    proxy_pass http://<推流服务器IP>:30080/;
}

不想配代理？

若 matchmaker 服务端开启了 CORS，可通过 match_maker 参数直连：

await initMap({
  container: "earth",
  coreOptions: {
    match_maker: "http://<推流服务器IP>:30080",
  },
});

注意：playerControl.js 内部使用同步 XHR 请求 matchmaker，部分浏览器对同步跨域请求有限制，建议优先使用代理方案。

常见问题

useBundledAssets 在 CommonJS 下不可用

useBundledAssets 依赖 ESM 的 import.meta.url，require() 环境会抛出明确错误。改用 baseUrl 或 configUrl/pixelstreamingUrl/playerControlUrl 精确指定脚本地址。

License

MIT