@yangyongtao/gaea 1.1.26 → 1.1.27

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## [1.1.27] - 2026-09-01
+
+### Added
+- 新增 `loadingText` 配置项，可通过 `setConfig({ loadingText })` 自定义引擎加载提示文字（默认 `GAEA 引擎加载中...`）
+
 ## [1.1.19] - 2026-07-13
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yangyongtao/gaea",
-  "version": "1.1.26",
+  "version": "1.1.27",
   "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.cjs",

package/src/GaeaMethods.js

@@ -105,7 +105,7 @@ function showLoading() {
   if (document.getElementById('gaea-loading-overlay')) return;
   const overlay = document.createElement('div');
   overlay.id = 'gaea-loading-overlay';
-  overlay.innerHTML = '<div class="gaea-spinner"></div><div class="gaea-text">GAEA 引擎加载中...</div>';
+  overlay.innerHTML = `<div class="gaea-spinner"></div><div class="gaea-text">${_config.loadingText}</div>`;
   document.body.appendChild(overlay);
 }
 
@@ -160,6 +160,8 @@ const defaultConfig = {
   defaultCameraPosition: '27.3680928977018,120.414139621887,0,109379.690132486,0,0',
   /** 引擎加载进度回调 */
   onProgress: null,
+  /** 引擎加载提示文字 */
+  loadingText: 'GAEA 引擎加载中...',
   /** DataHub API 地址（图层树数据接口），为空则只用默认数据 */
   dataHubApiUrl: '',
   /** 是否显示图层树按钮（右上角重置按钮旁边） */
@@ -290,8 +292,6 @@ export class GaeaApp {
     this._screenIconList = [];
     this._hiddenCategories = new Set();
     this._tilesetMap = {}; // 已加载的 3D Tiles 引用，key 为 tileset 名称
-    this._flattenTool = null; // 压平工具
-    this._flattenPolygon = null; // 压平多边形元素
     this._secIsClickArr = [];
     this._secScreenIconKeyValue = {};
     this._groundPolygonElements = [];
@@ -630,6 +630,7 @@ export class GaeaApp {
       { name: '岭尾水闸游览模型',     position: { x: 27.215661, y: 120.462325, z: 34 },    rotate: [0, -66, 0], size: [1, 1, 1], show: false, url: 'gltf/box.gltf' },
       { name: '岭尾新闸游览模型',     position: { x: 27.21038,  y: 120.458513, z: 4 },     rotate: [0, 30, 0], size: [1, 1, 1], show: false, url: 'gltf/box.gltf' },
       { name: '盒子模型-yanpu',       position: { x: 27.231665, y: 120.456095, z: 48.608 }, rotate: [0, 90, 0], size: [10, 10, 10], show: true, url: 'gltf/box.gltf' },
+      { name: '防汛沙袋',             position: { x: 27.218723, y: 120.460473, z: 18 }, rotate: [0, 0, 0], size: [1, 1, 1], show: false, url: 'gltf/sanddai.glb' },
     ];
 
     this._gltfCfgMap = {};
@@ -1183,7 +1184,7 @@ export class GaeaApp {
     const tilesetUrl = typeof item === 'string' ? item : item.jsonUrl
     const name = typeof item === 'string' ? '' : (item.tilName || '')
     const height = typeof item === 'string' ? 0 : (item.height || 0)
-    const enableFlatten = typeof item === 'object' ? (item.enableFlatten || false) : false
+    const enabledClip = typeof item === 'object' ? (item.enabledClip || false) : false
     const tileset = new Gaea.Gaea3DTileset()
     tileset.Name = name
     tileset.TilesetUrl = tilesetUrl
@@ -1192,7 +1193,7 @@ export class GaeaApp {
     tileset.SkipLevelOfDetail = false
     tileset.IsZUp = true
     tileset.RecalculateNormals = true
-    tileset.EnabledFlatten = enableFlatten
+    tileset.EnabledClip = enabledClip
     tileset.BaseUrl = tilesetUrl.slice(0, tilesetUrl.lastIndexOf('/') + 1)
     tileset.InitTileSet(name, tilesetUrl)
     tileset.MaximumMemoryUsage = 512
@@ -1204,109 +1205,352 @@ export class GaeaApp {
     if (name) {
       this._tilesetMap[name] = tileset
     }
-    console.log('[GaeaApp] 3D Tiles 已加载:', name || tilesetUrl, height ? `高度: ${height}` : '', enableFlatten ? '(压平已启用)' : '')
+    console.log('[GaeaApp] 3D Tiles 已加载:', name || tilesetUrl, height ? `高度: ${height}` : '', enabledClip ? '(裁剪已启用)' : '')
     return tileset
   };
 
-  // ---- 倾斜摄影压平 ----
+  // ---- 倾斜挖方 ----
 
   /**
-   * 传入多边形坐标直接对倾斜摄影执行压平
-   * @param {Object} opts
-   * @param {string} [opts.tilesetName] - 目标 3D Tiles 名称（不传则默认使用第一个已加载的 tileset）
-   * @param {Array<{lat: number, lng: number}>} opts.polygon - 多边形顶点坐标数组，会自动闭合
-   * @param {number} opts.height - 压平目标高度
+   * 根据多边形坐标裁剪地形（倾斜挖方）
+   * @param {Array<{x: number, y: number, z: number}>} pointList - 多边形顶点坐标数组 [{x: 纬度, y: 经度, z: 高程}, ...]
+   * @param {number} height - 裁剪深度/高度
+   * @param {Function} [callback] - 完成后的回调函数，接收 _Holeitem
+   * @returns {boolean} 是否成功
    * @example
-   * app.flatten3DTiles({
-   *   tilesetName: '沿浦海塘倾斜',
-   *   polygon: [
-   *     { lat: 27.2205, lng: 120.456 },
-   *     { lat: 27.2210, lng: 120.458 },
-   *     { lat: 27.2195, lng: 120.458 },
-   *     { lat: 27.2190, lng: 120.456 }
-   *   ],
-   *   height: 30
-   * })
+   * app.editTerrainTool([
+   *   { x: 27.2205, y: 120.456, z: 10 },
+   *   { x: 27.2210, y: 120.458, z: 10 },
+   *   { x: 27.2195, y: 120.458, z: 10 }
+   * ], 50, (item) => { console.log('挖方完成', item) })
    */
-  flatten3DTiles = ({ tilesetName, polygon, height }) => {
-    if (!polygon || polygon.length < 3) {
-      console.warn('[GaeaApp] flatten3DTiles: polygon 至少需要3个顶点')
-      return
+  editTerrainTool = (pointList, height, callback) => {
+    if (!pointList || pointList.length === 0) {
+      console.warn('[GaeaApp] editTerrainTool: pointList 不能为空')
+      return false
     }
 
-    // 查找目标 tileset
-    let tileset = null
-    if (tilesetName) {
-      tileset = this._tilesetMap[tilesetName]
-      if (!tileset) {
-        console.warn(`[GaeaApp] flatten3DTiles: 未找到 tileset "${tilesetName}"`)
-        return
-      }
-    } else {
-      const keys = Object.keys(this._tilesetMap)
-      if (keys.length === 0) {
-        console.warn('[GaeaApp] flatten3DTiles: 没有已加载的 3D Tiles')
-        return
+    const Position = pointList.map(point => new Gaea.Vector3(point.x, point.y, point.z))
+
+    // 经纬度 → 笛卡尔坐标
+    const originPoint = pointList.map(p => Gaea.GaeaMath.SphericalToCartesianDeg(new Gaea.Vector3(p.x, p.y, p.z)))
+
+    // 启用 QueryServer
+    Gaea.QueryServer.Instance.Enable = true
+
+    // 清旧挖方
+    if (this._holeItem) {
+      Gaea.ExcavationManager.Instance.RemoveItem(this._holeItem)
+    }
+
+    // 创建挖方对象 (坐标点, 插值距离, 深度, UV缩放, 是否法线材质, 是否需要edge)
+    this._holeItem = Gaea.ExcavationManager.Instance.CreateItem(originPoint, 100, height, 100, true, true)
+    Gaea.ExcavationManager.Instance.ExposureLength = 0
+    Gaea.ExcavationManager.Instance.AddItem(this._holeItem)
+    Gaea.ExcavationManager.Instance.NeedFence = true
+
+    if (Gaea.QueryServer.Instance != null) {
+      Gaea.ExcavationManager.Instance.FenceHeight = 10
+      const box = Gaea.World.Instance.SimplePolygonGenerater(originPoint, false, false, false, false, Gaea.ExcavationManager.Instance.FenceHeight, 0, 2, Gaea.ExcavationManager.Instance.FenceHeight)
+      Gaea.World.Instance.AddChild(box, false)
+      Gaea.QueryServer.Instance.ClipBox = box
+    }
+
+    console.log('[GaeaApp] 挖方已执行:', `深度: ${height}`, `顶点数: ${pointList.length}`)
+
+    setTimeout(() => {
+      if (typeof callback === 'function') {
+        callback(this._holeItem)
       }
-      tileset = this._tilesetMap[keys[0]]
+    }, 1000)
+  };
+
+  /**
+   * 还原地形（清除所有挖方效果）
+   */
+  restoreTerrain = () => {
+    if (this._holeItem) {
+      Gaea.ExcavationManager.Instance.RemoveItem(this._holeItem)
+      this._holeItem = null
+    }
+    Gaea.ExcavationManager.Instance.Clear()
+    Gaea.World.Instance.SetCurrentTool(null)
+    if (Gaea.QueryServer.Instance != null && Gaea.QueryServer.Instance.ClipBox != null) {
+      Gaea.QueryServer.Instance.ClipBox.QueueFree()
+      Gaea.QueryServer.Instance.ClipBox = null
+    }
+    console.log('[GaeaApp] 地形已还原')
+  };
+
+  /**
+   * 监听画布鼠标点击，获取点击位置的经纬度坐标
+   * @example
+   * app.addMouseClick((pos) => {
+   *   console.log('点击位置:', pos) // { x: 纬度, y: 经度, z: 高程 }
+   * })
+   */
+  addMouseClick = (callback) => {
+    const canvas = document.getElementById('canvas')
+    if (!canvas) {
+      console.warn('[GaeaApp] addMouseClick: canvas 元素未找到')
+      return
     }
+    canvas.addEventListener('mousedown', (event) => {
+      const result = Gaea.GaeaMath.ProjectPosition(new Gaea.Vector2(event.offsetX, event.offsetY))
+      const lonlat = Gaea.GaeaMath.CartesianToSphericalDeg(result)
+      const pos = { x: lonlat.x, y: lonlat.y, z: lonlat.z }
+      console.log('[GaeaApp] 点击位置:', pos)
+      if (typeof callback === 'function') {
+        callback(pos)
+      }
+    })
+  };
 
-    tileset.EnabledFlatten = true
+  /**
+   * 获取已加载的模型元素
+   * @param {string} name - 模型名称
+   * @returns {object} GLTFElement 或 null
+   */
+  getModel = (name) => {
+    return this._gltfElements[name] || null
+  };
 
-    // 创建/更新压平工具
-    if (!this._flattenTool) {
-      this._flattenTool = new Gaea.FlattenTool()
-      this._flattenTool.NeedIntersectWithMesh = false
-      this._flattenTool.IsMovingIntersectWithMesh = false
+  /**
+   * 获取模型当前状态（位置、旋转、缩放）
+   * @param {string} name - 模型名称
+   * @returns {object|null} { position, rotate, scale, visible }
+   */
+  getModelInfo = (name) => {
+    const el = this._gltfElements[name]
+    if (!el) return null
+    return {
+      position: { x: el.GeographyPosition.x, y: el.GeographyPosition.y, z: el.GeographyPosition.z },
+      rotate: { x: el.TiltHeadingBank.x, y: el.TiltHeadingBank.y, z: el.TiltHeadingBank.z },
+      scale: { x: el.Root.Scale.x, y: el.Root.Scale.y, z: el.Root.Scale.z },
+      visible: el.Root.Visible,
     }
-    this._flattenTool.Gdtvalue = height
+  };
 
-    // 构建多边形坐标（经纬度 → Vector3，闭合多边形）
-    const positions = polygon.map(p => new Gaea.Vector3(p.lat, p.lng, height))
-    positions.push(new Gaea.Vector3(polygon[0].lat, polygon[0].lng, height))
+  /**
+   * 设置模型位置（经纬度 + 高程）
+   * @param {string} name - 模型名称
+   * @param {object} position - { x: 纬度, y: 经度, z: 高程 }
+   */
+  setModelPosition = (name, position) => {
+    const el = this._gltfElements[name]
+    if (!el) { console.warn(`[GaeaApp] 模型 "${name}" 未找到`); return }
+    el.GeographyPosition = new Gaea.Vector3(position.x, position.y, position.z)
+  };
 
-    // 创建几何体
-    const geometry = Gaea.Geometry.Create1(Gaea.GeometryType.Polygon, positions)
-    const polygonElement = new Gaea.PolygonGeometryElement()
-    polygonElement.Shape = geometry
-    polygonElement.EnablePick = false
-    polygonElement.EnableEdit = false
-    polygonElement.NeedIntersectWithMesh = true
-    polygonElement.EnableVirtualPoint = true
-    Gaea.SimpleFillSymbol.ConvertBy(polygonElement.Symbol).HasOutLine = true
+  /**
+   * 设置模型旋转
+   * @param {string} name - 模型名称
+   * @param {number[]} rotate - [pitch, yaw, roll]
+   */
+  setModelRotation = (name, rotate) => {
+    const el = this._gltfElements[name]
+    if (!el) { console.warn(`[GaeaApp] 模型 "${name}" 未找到`); return }
+    el.TiltHeadingBank = new Gaea.Vector3(rotate[0], rotate[1], rotate[2])
+  };
+
+  /**
+   * 设置模型缩放
+   * @param {string} name - 模型名称
+   * @param {number[]} size - [sx, sy, sz]
+   */
+  setModelScale = (name, size) => {
+    const el = this._gltfElements[name]
+    if (!el) { console.warn(`[GaeaApp] 模型 "${name}" 未找到`); return }
+    el.Root.Scale = new Gaea.Vector3(size[0], size[1], size[2])
+  };
 
-    // 移除旧的压平多边形
-    if (this._flattenPolygon) {
-      try { Gaea.World.Instance.RenderableObjectList.RemoveChild(this._flattenPolygon) } catch (e) { /* ignore */ }
+  /**
+   * 设置模型可见性
+   * @param {string} name - 模型名称
+   * @param {boolean} visible
+   */
+  setModelVisible = (name, visible) => {
+    const el = this._gltfElements[name]
+    if (!el) { console.warn(`[GaeaApp] 模型 "${name}" 未找到`); return }
+    el.Root.Visible = visible
+  };
+
+  /**
+   * 移除模型（参考 ht_3dview removeGltf）
+   * @param {string} name - 模型名称
+   */
+  removeGltf = (name) => {
+    const el = this._gltfElements[name]
+    if (!el) { console.warn(`[GaeaApp] 模型 "${name}" 未找到`); return }
+    Gaea.World.Instance.RenderableObjectList.Remove(el)
+    delete this._gltfElements[name]
+    delete this._gltfCfgMap[name]
+  };
+
+  /**
+   * 修改模型配置（位置/旋转/缩放一起设置，参考 ht_3dview updateElementPosition）
+   * @param {object} options
+   * @param {string} options.name - 模型名称
+   * @param {object} options.position - { x: 纬度, y: 经度, z: 高程 }
+   * @param {number[]} [options.rotate] - [pitch, yaw, roll]
+   * @param {number[]} [options.size] - [sx, sy, sz]
+   */
+  updateElementPosition = ({ name, position, rotate, size }) => {
+    const el = this._gltfElements[name]
+    if (!el) { console.warn(`[GaeaApp] 模型 "${name}" 未找到`); return }
+    if (position) {
+      el.GeographyPosition = new Gaea.Vector3(position.x, position.y, position.z)
+    }
+    if (rotate && rotate.length > 0) {
+      el.TiltHeadingBank = new Gaea.Vector3(rotate[0], rotate[1], rotate[2])
     }
+    if (size && size.length > 0) {
+      el.Root.Scale = new Gaea.Vector3(size[0], size[1], size[2])
+    }
+  };
 
-    Gaea.World.Instance.RenderableObjectList.AddLast(polygonElement)
-    this._flattenPolygon = polygonElement
-    console.log('[GaeaApp] 压平已执行:', tileset.Name || tileset.TilesetUrl, `高度: ${height}`, `顶点数: ${polygon.length}`)
+  /**
+   * 添加鼠标移动监听（参考 ht_3dview addMouseMove，使用 Gaea 引擎事件）
+   * 回调返回当前鼠标所在位置的经纬度坐标
+   * @param {function} cb - (pos: {x,y,z}) => void
+   * @returns {function} 调用可取消监听
+   */
+  addMouseMove = (cb = null) => {
+    const handle = Gaea.World.Instance.OnMouseMove((p, b) => {
+      const screenpos = new Gaea.Vector2(p.x, p.y)
+      const spacepos = Gaea.GaeaMath.ProjectPosition(screenpos)
+      const latlonalt = Gaea.GaeaMath.CartesianToSphericalDeg(spacepos)
+      const pos = { x: latlonalt.x, y: latlonalt.y, z: latlonalt.z }
+      if (typeof cb === 'function') cb(pos)
+    })
+    this._mouseMoveHandle = handle
+    return () => {
+      if (handle) Gaea.World.Instance.ClearEvent(handle)
+      this._mouseMoveHandle = null
+    }
   };
 
   /**
-   * 清除倾斜摄影压平效果
-   * @param {string} [tilesetName] - 目标 tileset 名称（不传则清除压平多边形并重置工具）
+   * 移除鼠标移动监听
    */
-  clearFlatten = (tilesetName) => {
-    // 移除压平多边形
-    if (this._flattenPolygon) {
-      try { Gaea.World.Instance.RenderableObjectList.RemoveChild(this._flattenPolygon) } catch (e) { /* ignore */ }
-      this._flattenPolygon = null
+  removeMouseMove = () => {
+    if (this._mouseMoveHandle) {
+      Gaea.World.Instance.ClearEvent(this._mouseMoveHandle)
+      this._mouseMoveHandle = null
     }
+  };
 
-    // 重置压平工具状态
-    this._flattenTool = null
-    Gaea.World.Instance.SetCurrentTool(null)
-    Gaea.World.Instance.CurrentTool = null
+  /**
+   * 添加鼠标抬起监听（参考 ht_3dview，使用 Gaea 引擎 OnMouseUp 事件）
+   * 回调返回点击位置的经纬度坐标
+   * @param {function} cb - (pos: {x,y,z}) => void
+   * @returns {function} 调用可取消监听
+   */
+  addMouseUp = (cb = null) => {
+    const handle = Gaea.World.Instance.OnMouseUp((p, b) => {
+      if (b !== 1) return // 仅左键
+      const screenpos = new Gaea.Vector2(p.x, p.y)
+      const spacepos = Gaea.GaeaMath.ProjectPosition(screenpos)
+      const latlonalt = Gaea.GaeaMath.CartesianToSphericalDeg(spacepos)
+      const pos = { x: latlonalt.x, y: latlonalt.y, z: latlonalt.z }
+      if (typeof cb === 'function') cb(pos)
+    })
+    this._mouseUpHandle = handle
+    return () => {
+      if (handle) Gaea.World.Instance.ClearEvent(handle)
+      this._mouseUpHandle = null
+    }
+  };
 
-    // 可选：禁用特定 tileset 的压平
-    if (tilesetName && this._tilesetMap[tilesetName]) {
-      this._tilesetMap[tilesetName].EnabledFlatten = false
+  /**
+   * 移除鼠标抬起监听
+   */
+  removeMouseUp = () => {
+    if (this._mouseUpHandle) {
+      Gaea.World.Instance.ClearEvent(this._mouseUpHandle)
+      this._mouseUpHandle = null
     }
+  };
 
-    console.log('[GaeaApp] 压平效果已清除')
+  /**
+   * 交互式拾取坐标（点击地图获取经纬度，参考 ht_3dview 选择坐标流程）
+   * 点击地图后回调返回坐标，自动取消监听
+   * @param {function} cb - (pos: {x,y,z}) => void
+   * @returns {function} 调用可取消拾取
+   */
+  pickPosition = (cb) => {
+    const cancel = this.addMouseUp((pos) => {
+      cancel()
+      if (typeof cb === 'function') cb(pos)
+    })
+    return cancel
+  };
+
+  /**
+   * 交互式拾取模型，返回模型信息
+   * @param {function} callback - (modelInfo) => void
+   * @returns {function} 调用可取消拾取
+   */
+  pickModel = (callback) => {
+    const canvas = document.getElementById('canvas')
+    if (!canvas) return () => {}
+
+    const onClick = (event) => {
+      const hit = Gaea.World.Instance.Pick(new Gaea.Vector2(event.offsetX, event.offsetY))
+      if (hit && hit.Element && hit.Element.Root) {
+        const modelName = hit.Element.Root.Name
+        const info = this.getModelInfo(modelName)
+        if (info) {
+          info.name = modelName
+          callback(info)
+        }
+      }
+    }
+
+    canvas.addEventListener('click', onClick)
+    return () => canvas.removeEventListener('click', onClick)
+  };
+
+  /**
+   * 获取所有可选模型列表（用于面板下拉选择，参考 ht_3dview gaeaData.gltfList）
+   * @returns {Array<{name: string, url: string, position?: object}>}
+   */
+  getGltfList = () => {
+    return Object.values(this._gltfCfgMap).map(cfg => ({
+      name: cfg.name,
+      url: cfg.url,
+    }));
+  };
+
+  /**
+   * 加载用户自定义模型（参考 ht_3dview addGltf）
+   * 新增模型到场景并记录到配置表
+   * @param {object} cfg
+   * @param {string} cfg.name - 模型实例名（不能重复）
+   * @param {string} cfg.url - 模型 URL
+   * @param {object} cfg.position - { x: 纬度, y: 经度, z: 高程 }
+   * @param {number[]} cfg.rotate - [pitch, yaw, roll]
+   * @param {number[]} cfg.size - [sx, sy, sz]
+   * @param {boolean} [cfg.show=true]
+   * @param {boolean} [cfg.enablePick=true]
+   * @returns {Promise<object>} gltf element
+   */
+  addGltf = async (cfg) => {
+    const { name, url, position, rotate, size, show = true, enablePick = true } = cfg;
+    if (!name || !url || !position || !rotate || !size) {
+      console.warn('[GaeaApp] addGltf: 缺少必要参数', cfg);
+      return null;
+    }
+    // 记录到配置表，供后续面板编辑
+    this._gltfCfgMap[name] = {
+      name, url, position: { ...position }, rotate: [...rotate], size: [...size],
+      show, enablePick, isUserAdd: true
+    };
+    const element = await this.AddGltf({
+      name, url, position, rotate, size, show, enablePick, useAbsoluteHeight: true,
+    });
+    if (element) this._gltfElements[name] = element;
+    return element;
   };
 
   /**
@@ -2195,8 +2439,9 @@ export class GaeaApp {
       Gaea.World.Instance.SetMtlFloat(material, 'flow_speed', flowSpeed)
       Gaea.World.Instance.SetMtlColor(material, 'color_shallow', new Gaea.Color(0 / 255, 157 / 255, 187 / 255, 1))
       Gaea.World.Instance.SetMtlColor(material, 'color_deep', new Gaea.Color(colorDeep[0] / 255, colorDeep[1] / 255, colorDeep[2] / 255, 1))
-      Gaea.World.Instance.SetMtlFloat(material, 'transparency_clarity', 3)
-      Gaea.World.Instance.SetMtlFloat(material, 'foam_amount', 0.9)
+      Gaea.World.Instance.SetMtlFloat(material, 'transparency_clarity', 0)
+      Gaea.World.Instance.SetMtlFloat(material, "transparency_refraction", 0); // 折射度
+      Gaea.World.Instance.SetMtlFloat(material, "foam_amount", 0.8); // 气泡大小
     })
 
     Gaea.World.Instance.RenderableObjectList.AddLast(element)