@yangyongtao/gaea 1.1.10 → 1.1.11

package/USAGE.md

@@ -0,0 +1,200 @@
+# @yangyongtao/gaea 使用文档
+
+基于 Godot WASM 引擎的 Vue 3 三维可视化组件库。提供影像/地形/贴地线加载、相机视角控制、图层树、天气控制、沿线飞行、断面游览、室内游览等能力，并内置 Vite 插件自动注入引擎资源。
+
+> 完整可运行示例见 `gaea-ground-test/src/App.vue`，本文所有片段均以其为参考。
+
+---
+
+## 1. 安装
+
+```bash
+npm install @yangyongtao/gaea
+```
+
+peerDependencies（按需安装）：`vue ^3.4`、`element-plus ^2.6`（可选）、`pinia ^2.1`（可选）。
+
+---
+
+## 2. Vite 配置
+
+引入并注册 `gaeaVitePlugin`，它会自动注入 `Gaea.js`、提供引擎静态资源、设置 SharedArrayBuffer 所需的跨域隔离响应头。
+
+```js
+// vite.config.js
+import { defineConfig } from 'vite';
+import vue from '@vitejs/plugin-vue';
+import { gaeaVitePlugin } from '@yangyongtao/gaea/plugin';
+
+export default defineConfig({
+  plugins: [vue(), gaeaVitePlugin()],
+  resolve: { preserveSymlinks: true },
+  optimizeDeps: { exclude: ['@yangyongtao/gaea'] },
+});
+```
+
+---
+
+## 3. 快速开始
+
+页面里需要一个 `id="canvas"` 的画布。调用 `setConfig(...)` 后 `new GaeaApp()` 即可自动完成「引擎启动 → 环境初始化 → 图层加载 → 模型加载」。
+
+```vue
+<template>
+  <div id="gaea-app">
+    <div class="toolbar">
+      <button @click="showWeather = !showWeather">天气控制</button>
+      <button @click="showFly = !showFly">沿线飞行</button>
+      <button @click="showLayerTree = !showLayerTree">图层控制</button>
+      <WaterGateTour />
+    </div>
+
+    <div class="canvas-area" id="canvas-container">
+      <canvas id="canvas"></canvas>
+    </div>
+
+    <WeatherControl v-if="showWeather" :appInstance="app" @close="showWeather = false" />
+    <FlyAlongRoute v-if="showFly" :appInstance="app" @close="showFly = false" />
+    <LayerTree v-if="showLayerTree" :appInstance="app" @close="showLayerTree = false" @node-click="onLayerNodeClick" />
+    <HydrologicStationDialog />
+    <SecTourView />
+  </div>
+</template>
+
+<script setup>
+import { ref } from 'vue';
+import { GaeaApp, setConfig } from '@yangyongtao/gaea';
+import { WeatherControl, FlyAlongRoute, HydrologicStationDialog, SecTourView, WaterGateTour } from '@yangyongtao/gaea/components';
+import LayerTree from '@yangyongtao/gaea/components/LayerTree.vue';
+
+setConfig({
+  serveLocal: `${window.location.origin}/static`,
+  serveUrl: 'http://192.168.3.151:8088/gaeaExplorerServer/',
+  serviceMode: 'platform',
+  defaultCameraPosition: '27.3680928977018,120.414139621887,0,109379.690132486,0,0',
+});
+
+const app = new GaeaApp();
+window.APP = app;               // 组件内部通过 window.APP 兜底获取实例
+
+const showWeather = ref(false);
+const showFly = ref(false);
+const showLayerTree = ref(false);
+
+function onLayerNodeClick({ node }) {
+  app.flyToNode(node);
+}
+</script>
+```
+
+---
+
+## 4. setConfig 配置项
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `serveLocal` | string | `''` | 引擎本地静态资源地址（AssetHost），一般为 `${origin}/static` |
+| `serveUrl` | string | `''` | 服务平台地址（WMTS 影像 / 地形 / 贴地线均基于此） |
+| `serviceMode` | `'platform' \| 'online'` | `'platform'` | **服务模式**：见下方说明 |
+| `tiandituToken` | string | — | 在线模式的天地图 token |
+| `tiandituLevelRange` | [number,number] | `[0,18]` | 天地图层级范围 |
+| `defaultLayers` | Array | 见下 | 服务平台模式下加载的影像图层 |
+| `defaultTerrains` | Array | 见下 | 服务平台模式下加载的地形服务 |
+| `defaultGroundLines` | Array | 见下 | 服务平台模式下加载的贴地线 |
+| `defaultCameraPosition` | string | — | 初始相机视角：`纬度,经度,高程,相机高,俯仰,朝向` |
+| `layerCategories` | Array | 内置 | 图层树分类数据（接口数据会合并进来） |
+| `dataHubApiUrl` | string | `''` | 图层树数据接口地址，为空则只用默认数据 |
+| `onProgress` | function | — | 引擎加载进度回调 `(cur, total) => {}` |
+
+### 4.1 serviceMode —— 服务模式（区分「服务平台」与「在线」）
+
+- `'platform'`（服务平台）：影像走 `serveUrl` 的 WMTS，并加载 `defaultTerrains` 地形、`defaultGroundLines` 贴地线。
+- `'online'`（在线）：**仅加载天地图影像**，不加载地形和贴地线（在线模式目前只有天地图一种影像来源）。
+
+```js
+setConfig({ serviceMode: 'platform' });  // 内网/服务平台
+// 或
+setConfig({ serviceMode: 'online', tiandituToken: '你的token' }); // 在线（天地图）
+```
+
+### 4.2 defaultLayers —— 影像图层（服务平台模式）
+
+```js
+defaultLayers: [
+  { layerName: 'earthland', forMat: 'image/png', min: 0, max: 18, transparency: 0.3 },
+  { layerName: '苍南L19',   forMat: 'image/png', min: 5, max: 17 },
+]
+```
+- `layerName`：WMTS 服务里的图层名（Title）
+- `forMat`：影像格式，如 `image/png`、`image/jpeg`
+- `min` / `max`：显示层级范围
+- `transparency`：透明度（可选）
+
+### 4.3 defaultTerrains —— 地形服务（服务平台模式）
+
+```js
+defaultTerrains: [
+  { name: '苍南县地形', url: 'htc/service/tms/1.0.0/苍南县地形@EPSG%3A4326@terrain/' },
+]
+```
+- `name`：地形名称
+- `url`：相对 `serveUrl` 的路径（也支持传完整 `http(s)://` 地址）
+- 空数组 `[]` 则不加载地形
+
+### 4.4 defaultGroundLines —— 贴地线（服务平台模式）
+
+依赖 `serveUrl` 的 WMTS 矢量线服务（自动通过 `getAllServe` 获取服务列表后按名匹配）。
+
+```js
+defaultGroundLines: [
+  { name: '苍南县边界',        range: [0, 9],   color: [255, 255, 0],   index: 100 },
+  { name: '苍南县镇边界',      range: [9, 15],  color: [0, 255, 0],     index: 80 },
+  { name: '苍南县村边界',      range: [15, 19], color: [255, 255, 255], index: 60 },
+  { name: '沿浦海塘工程范围线', range: [0, 21],  color: [0, 255, 255],   index: 120 },
+]
+```
+- `name`：矢量线服务名（Title）
+- `range`：显示层级范围 `[min, max]`
+- `color`：线颜色 `[r, g, b]`（0-255）
+- `index`：渲染优先级
+- 每项可加 `isInitLoad: false` 跳过该条
+
+---
+
+## 5. 组件说明
+
+组件从 `@yangyongtao/gaea/components` 导入；`LayerTree` 需按路径单独导入。多数交互组件接收 `:appInstance="app"`，未传时内部回退到 `window.APP`。
+
+| 组件 | 说明 | 主要事件 |
+|------|------|----------|
+| `WeatherControl` | 天气/台风控制面板（含台风路线拾取与播放） | `@close` |
+| `FlyAlongRoute` | 沿线飞行：地图拾取点位，可设飞行高度/时长 | `@close` |
+| `LayerTree` | 图层树，点击节点飞行定位 | `@close`、`@node-click` |
+| `HydrologicStationDialog` | 水文测站弹窗，自监听 `gaea-icon-click` 事件 | — |
+| `SecTourView` | 断面游览滚动条，模型锁定后显示 | — |
+| `WaterGateTour` | 室内游览按钮（下拉选择水闸模型） | — |
+
+---
+
+## 6. 常用实例方法（window.APP / app）
+
+| 方法 | 说明 |
+|------|------|
+| `SetPosition('纬度,经度,高程,相机高,俯仰,朝向')` | 定位到指定视角 |
+| `flyToNode({ position:{x,y,z} })` | 飞到指定位置 |
+| `flyAlongPath(lineData, options)` | 沿线飞行，`lineData=[{x:纬度,y:经度,z:高度}]`，`options={duration,xrotation,lockEye,...}` |
+| `stopFlyAlongPath()` | 停止沿线飞行 |
+| `cameraReset()` | 相机复位到 `defaultCameraPosition` |
+| `addInitTerrainServer(terrains?)` | 手动加载地形（不传则用 `defaultTerrains`） |
+| `addGroundLines(lines?)` | 手动加载贴地线（不传则用 `defaultGroundLines`） |
+| `addTyphoonRoute(pointList, options)` | 加载台风路线并播放动画 |
+| `clearTyphoonRoute()` | 清除台风路线 |
+
+---
+
+## 7. 注意事项
+
+- 页面必须存在 `id="canvas"` 的 `<canvas>`，引擎会挂载到它上面。
+- 需要跨域隔离（COOP/COEP）才能启用 SharedArrayBuffer，`gaeaVitePlugin` 已自动处理；首次进入若未隔离会自动刷新一次。
+- 服务平台模式下地形/贴地线依赖 `serveUrl` 对应服务，若服务器无对应服务名，控制台会打印「未找到/加载失败」警告，不影响其它功能。
+- 大体积引擎资源（`Gaea.pck` / `Gaea.wasm` / `1111.res` 等）通过 postinstall 脚本下载到本地静态目录，请确保下载源可访问。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yangyongtao/gaea",
-  "version": "1.1.10",
+  "version": "1.1.11",
   "description": "Gaea 3D visualization component library - Vue 3 components based on Godot WASM engine. Includes WMTS layer loading, camera view control, Vite plugin auto-injection, etc.",
   "type": "module",
   "main": "src/index.js",
@@ -14,6 +14,7 @@
       "import": "./src/components/index.js",
       "default": "./src/components/index.js"
     },
+    "./components/*": "./src/components/*",
     "./plugin": {
       "import": "./src/plugin.js",
       "default": "./src/plugin.js"
@@ -23,6 +24,7 @@
     "src/",
     "scripts/",
     "README.md",
+    "USAGE.md",
     "CHANGELOG.md",
     "public/*.js",
     "public/*.html",
@@ -70,7 +72,8 @@
     }
   },
   "dependencies": {
-    "@tweenjs/tween.js": "^25.0.0"
+    "@tweenjs/tween.js": "^25.0.0",
+    "echarts": "^5.5.0"
   },
   "license": "MIT",
   "publishConfig": {

package/public/static/css/main.css

@@ -168,3 +168,114 @@ input {
 a {
   color: #fcdab7;
 }
+
+/* daba-tooltip 断面标签 hover 提示框 */
+.daba-tooltip {
+  position: fixed;
+  z-index: 99999;
+  transform: translate(-50%, -100%);
+  pointer-events: none;
+  display: none;
+  min-width: 200px;
+  max-width: 320px;
+  background: rgba(2, 62, 138, 0.95);
+  border: 1px solid rgba(14, 165, 233, 0.6);
+  border-radius: 6px;
+  padding: 14px 18px;
+  box-shadow: 0 4px 20px rgba(0, 50, 100, 0.4);
+  font-size: 18px;
+  animation: dabaTooltipFadeIn 0.15s ease-out;
+}
+.daba-tooltip::after {
+  content: '';
+  position: absolute;
+  bottom: -6px;
+  left: 50%;
+  transform: translateX(-50%);
+  width: 0;
+  height: 0;
+  border-left: 6px solid transparent;
+  border-right: 6px solid transparent;
+  border-top: 6px solid rgba(2, 62, 138, 0.95);
+}
+@keyframes dabaTooltipFadeIn {
+  from { opacity: 0; transform: translate(-50%, calc(-100% - 4px)); }
+  to { opacity: 1; transform: translate(-50%, -100%); }
+}
+.daba-tooltip-title {
+  font-size: 17px; font-weight: 600; color: #e0f7ff;
+  padding-bottom: 8px; margin-bottom: 10px;
+  border-bottom: 1px solid rgba(255, 255, 255, 0.15);
+}
+.daba-tooltip-item {
+  position: relative; padding: 3px 0 3px 14px;
+  font-size: 15px; line-height: 1.7; color: #cbd5e1; word-break: break-word;
+}
+.daba-tooltip-item::before {
+  content: ''; position: absolute; left: 0; top: 11px;
+  width: 5px; height: 5px; border-radius: 50%; background: #38bdf8;
+}
+
+/* 断面标签样式 */
+.waterLevel {
+  position: absolute;
+  z-index: 1000;
+  width: 7rem;
+  top: 16%;
+  left: 30%;
+}
+.waterLevel img {
+  width: 100%;
+}
+.waterLevel .content {
+  position: absolute;
+  top: 16%;
+  left: 25%;
+  white-space: nowrap;
+}
+.waterLevel .content .text {
+  font-size: 20px;
+}
+
+.damScreen {
+  position: absolute;
+  box-sizing: border-box;
+  top: 431.312px;
+  left: 630.192px;
+  width: 18rem;
+  height: 3rem;
+  padding: 0px;
+  margin: 0px;
+  overflow: hidden;
+  display: block;
+  z-index: 3;
+}
+.damScreen img {
+  position: absolute;
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+  z-index: 1;
+}
+.damScreen .content {
+  display: flex;
+  position: relative;
+  width: 100%;
+  min-height: 100%;
+  z-index: 2;
+  align-items: center;
+}
+.damScreen .content .box {
+  width: 2.2rem;
+  height: 100%;
+  box-sizing: border-box;
+}
+.damScreen .content .text {
+  flex: 1 1 0%;
+  height: 100%;
+  display: flex;
+  font-size: 18px;
+  align-items: center;
+  justify-content: center;
+  box-sizing: border-box;
+}