easy-threesdk 1.0.0

package/index.js

@@ -0,0 +1,898 @@
+import * as THREE from "three";
+import { OrbitControls } from "three/examples/jsm/controls/OrbitControls.js";
+import { GLTFLoader } from "three/examples/jsm/loaders/GLTFLoader.js";
+import { OBJLoader } from "three/examples/jsm/loaders/OBJLoader.js";
+import { MTLLoader } from "three/examples/jsm/loaders/MTLLoader.js";
+import {
+  CSS3DRenderer,
+  CSS3DObject,
+} from "three/examples/jsm/renderers/CSS3DRenderer.js";
+import { ThreeMFLoader } from "three/examples/jsm/Addons.js";
+
+/**
+ * @typedef {Object} CameraConfig
+ * @property {THREE.Vector3} position 相机位置
+ * @property {THREE.Vector3} lookAt 相机朝向
+ */
+/**
+ * @typedef {Object} ControlConfig
+ * @property {boolean} enableDamping 是否启用阻尼
+ * @property {number} dampingFactor 阻尼因子
+ * @property {number} minDistance 最小距离
+ * @property {number} maxDistance 最大距离
+ * @property {number} maxPolarAngle 最大极角
+ * @property {THREE.Vector3} target 目标位置
+ */
+/**
+ * @typedef {Object} LightConfig
+ * @property {THREE.Color} ambientLight 环境光颜色
+ * @property {number} ambientLightIntensity 环境光强度
+ * @property {THREE.Color} directionalLightColor 方向光颜色
+ * @property {number} directionalLightIntensity 方向光强度
+ * @property {THREE.Color} rimLightColor 边缘光颜色
+ * @property {number} rimLightIntensity 边缘光强度
+ * @property {THREE.Vector3} rimLightPosition 边缘光位置
+ * @property {THREE.Vector3} mainLightPosition 主光位置
+ */
+
+class ThreeSdk {
+  //插件Map
+  _PluginsManager = new Map();
+
+  // 相机配置
+  _CameraConfig = {
+    fixedCameraPosition: null,
+    rotateAroundSelf: false, // 是否围绕自身旋转
+    isRoamMode: false, // 是否为漫游模式
+    isCameraAnimating: false, // 是否正在执行相机动画
+    cameraAnimationId: null, // 动画ID，用于取消动画
+  };
+
+  // 漫游模式配置
+  _RoamConfig = {
+    cameraHeight: 2, // 漫游相机高度（距离地面的高度）
+    // 地面圆圈
+    groundCircle: null, //地面圆圈Mesh 网格对象
+    moveSpeed: 0.1,
+    rotateSpeed: 0.002, //旋转视角的速度
+  };
+
+  // 轨道控制器配置
+  _OrbitControlsConfig = {
+    enablePan: null,
+    enableZoom: null,
+    minDistance: null,
+    maxDistance: null,
+    maxPolarAngle: null,
+    target: null,
+  };
+
+  //全景球体
+  _PanoramaSphere = null;
+
+  // 3d场景组 map
+  _ThreeGroupMap = new Map();
+
+  // 地面平面网格 可以是一个Mesh，也可以是一个 Mesh List，Mesh List 是多个Mesh的集合
+  _GroundPlane = null;
+
+  //键盘事件处理
+  _KeyboardEventHandler = {
+    w: false,
+    a: false,
+    s: false,
+    d: false,
+    ArrowUp: false,
+    ArrowDown: false,
+    ArrowLeft: false,
+    ArrowRight: false,
+    isDragging: false,
+    previousMousePosition: { x: 0, y: 0 },
+  };
+
+  constructor(container) {
+    this.container = container;
+  }
+  /**
+   * 初始化3d场景
+   * @param {CameraConfig} cameraConfig 相机配置
+   * @param {ControlConfig} controlConfig 控制器配置
+   * @param {LightConfig} lightConfig 灯光配置
+   */
+  init(cameraConfig = {}, controlConfig = {}, lightConfig = {}) {
+    let { position, lookAt } = Object.assign(
+      {
+        position: new THREE.Vector3(0, 280, 320),
+        lookAt: new THREE.Vector3(0, 0, 0),
+      },
+      cameraConfig
+    );
+
+    let {
+      enableDamping,
+      dampingFactor,
+      minDistance,
+      maxDistance,
+      maxPolarAngle,
+      target,
+    } = Object.assign(
+      {
+        enableDamping: true,
+        dampingFactor: 0.05,
+        minDistance: 50,
+        maxDistance: 800,
+        maxPolarAngle: Math.PI / 2,
+        target: new THREE.Vector3(0, 0, 0),
+      },
+      controlConfig
+    );
+
+    let {
+      ambientLight,
+      ambientLightIntensity,
+      directionalLightColor,
+      directionalLightIntensity,
+      rimLightColor,
+      rimLightIntensity,
+      rimLightPosition,
+      mainLightPosition,
+    } = Object.assign(
+      {
+        ambientLight: 0xffffff,
+        ambientLightIntensity: 0.5,
+        directionalLightColor: 0xa5f3fc,
+        directionalLightIntensity: 1.5,
+        rimLightColor: 0x0ea5e9,
+        rimLightIntensity: 3,
+        rimLightPosition: new THREE.Vector3(0, 100, -100),
+        mainLightPosition: new THREE.Vector3(50, 100, 50),
+      },
+      lightConfig
+    );
+
+    //初始化场景
+    this.scene = new THREE.Scene();
+    const width = this.container.clientWidth;
+    const height = this.container.clientHeight;
+
+    //初始化摄像机
+    this.camera = new THREE.PerspectiveCamera(75, width / height, 0.1, 1000);
+    this.camera.position.set(position.x, position.y, position.z);
+    this.camera.lookAt(lookAt.x, lookAt.y, lookAt.z);
+
+    //初始化渲染器
+    this.renderer = new THREE.WebGLRenderer({ antialias: true, alpha: true });
+    this.renderer.setSize(width, height);
+    this.renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));
+    this.container.appendChild(this.renderer.domElement);
+
+    //初始化控制器
+    this.controls = new OrbitControls(this.camera, this.renderer.domElement);
+    this.controls.target.set(target.x, target.y, target.z);
+    this.controls.enableDamping = enableDamping;
+    this.controls.dampingFactor = dampingFactor;
+    this.controls.minDistance = minDistance;
+    this.controls.maxDistance = maxDistance;
+    this.controls.maxPolarAngle = maxPolarAngle;
+
+    // 保存 OrbitControls 的原始配置（用于退出第一人称模式时恢复）
+    this._OrbitControlsConfig.enablePan = this.controls.enablePan;
+    this._OrbitControlsConfig.enableZoom = this.controls.enableZoom;
+    this._OrbitControlsConfig.minDistance = this.controls.minDistance;
+    this._OrbitControlsConfig.maxDistance = this.controls.maxDistance;
+    this._OrbitControlsConfig.maxPolarAngle = this.controls.maxPolarAngle;
+    this._OrbitControlsConfig.target = this.controls.target.clone();
+
+    // 初始化场景灯光
+    this.scene.add(new THREE.AmbientLight(ambientLight, ambientLightIntensity)); // 调亮环境光
+    const mainLight = new THREE.DirectionalLight(
+      directionalLightColor,
+      directionalLightIntensity
+    );
+    mainLight.position.set(
+      mainLightPosition.x,
+      mainLightPosition.y,
+      mainLightPosition.z
+    );
+    this.scene.add(mainLight);
+    const rimLight = new THREE.SpotLight(rimLightColor, rimLightIntensity);
+    rimLight.position.set(
+      rimLightPosition.x,
+      rimLightPosition.y,
+      rimLightPosition.z
+    );
+    this.scene.add(rimLight);
+
+    // 初始化射线 Raycaster
+    this.raycaster = new THREE.Raycaster();
+
+    window.addEventListener("resize", () => {
+      const w = this.container.clientWidth;
+      const h = this.container.clientHeight;
+      this.camera.aspect = w / h;
+      this.camera.updateProjectionMatrix();
+      this.renderer.setSize(w, h);
+    });
+
+    this._handleWindowEvent();
+    this._animate();
+  }
+
+  /**
+   * 注册插件
+   * @param {Array<Object>|Object} plugins 插件列表或单个插件
+   * @returns {void}
+   */
+  plugins(plugins = []) {
+    if (Array.isArray(plugins)) {
+      plugins.forEach((plugin) => {
+        this._PluginsManager.set(
+          plugin.name || plugin.constructor.name,
+          new plugin(this.container, this)
+        );
+      });
+    } else {
+      this._PluginsManager.set(
+        plugins.name || plugins.constructor.name,
+        new plugins(this.container, this)
+      );
+    }
+  }
+
+  _handleWindowEvent() {
+    // ==================== 事件监听 ====================
+
+    window.addEventListener("mousemove", (event) => {
+      const mouse = new THREE.Vector2();
+      // 计算鼠标在标准化设备坐标中的位置 (-1 到 +1)
+      mouse.x = (event.clientX / window.innerWidth) * 2 - 1;
+      mouse.y = -(event.clientY / window.innerHeight) * 2 + 1;
+
+      // 更新射线
+      this.raycaster.setFromCamera(mouse, this.camera);
+
+      // 漫游模式：显示地面圆圈
+      if (this._CameraConfig.isRoamMode) {
+        // 只检测地面网格
+        const groundIntersects = this.raycaster.intersectObjects(
+          this._GroundPlane,
+          false
+        );
+        if (groundIntersects.length > 0) {
+          const point = groundIntersects[0].point;
+          this._RoamConfig.groundCircle.position.set(
+            point.x,
+            point.y + 0.01,
+            point.z
+          ); // 稍微抬高避免z-fighting
+          this._RoamConfig.groundCircle.visible = true;
+          this.renderer.domElement.style.cursor = "pointer";
+        } else {
+          this._RoamConfig.groundCircle.visible = false;
+          this.renderer.domElement.style.cursor = "default";
+        }
+
+        // 处理鼠标拖拽旋转视角
+        if (this._KeyboardEventHandler.isDragging) {
+          const deltaX =
+            event.clientX - this._KeyboardEventHandler.previousMousePosition.x;
+          const deltaY =
+            event.clientY - this._KeyboardEventHandler.previousMousePosition.y;
+
+          if (Math.abs(deltaX) > 0 || Math.abs(deltaY) > 0) {
+            // 水平旋转（左右拖拽）
+            const rotationY = deltaX * this._RoamConfig.rotateSpeed;
+            const rotationX = deltaY * this._RoamConfig.rotateSpeed;
+
+            // 获取相机的当前方向
+            const direction = new THREE.Vector3();
+            this.camera.getWorldDirection(direction);
+
+            // 创建旋转轴（垂直轴用于水平旋转）
+            const verticalAxis = new THREE.Vector3(0, 1, 0);
+            const horizontalAxis = new THREE.Vector3();
+            horizontalAxis.crossVectors(direction, verticalAxis).normalize();
+
+            // 应用水平旋转
+            direction.applyAxisAngle(verticalAxis, rotationY);
+            direction.applyAxisAngle(horizontalAxis, -rotationX);
+
+            // 限制垂直角度（防止翻转）
+            const currentAngle = Math.asin(direction.y);
+            const maxAngle = Math.PI / 2 - 0.1; // 限制在接近90度
+            if (currentAngle > maxAngle) direction.y = Math.sin(maxAngle);
+            if (currentAngle < -maxAngle) direction.y = Math.sin(-maxAngle);
+            direction.normalize();
+
+            // 更新相机朝向
+            const target = this.camera.position
+              .clone()
+              .add(direction.multiplyScalar(10));
+            this.camera.lookAt(target);
+          }
+
+          // 更新上一次鼠标位置（在拖拽时）
+          this._KeyboardEventHandler.previousMousePosition.x = event.clientX;
+          this._KeyboardEventHandler.previousMousePosition.y = event.clientY;
+        } else {
+          // 非拖拽时也更新，以便下次拖拽时能正确计算
+          this._KeyboardEventHandler.previousMousePosition.x = event.clientX;
+          this._KeyboardEventHandler.previousMousePosition.y = event.clientY;
+        }
+        return; // 漫游模式下不处理其他悬停效果
+      }
+    });
+
+    window.addEventListener("dblclick", (event) => {
+      const mouse = new THREE.Vector2();
+      // 计算鼠标位置
+      mouse.x = (event.clientX / window.innerWidth) * 2 - 1;
+      mouse.y = -(event.clientY / window.innerHeight) * 2 + 1;
+
+      // 更新射线
+      this.raycaster.setFromCamera(mouse, this.camera);
+
+      // 漫游模式：点击地面跳转视角
+      if (this._CameraConfig.isRoamMode) {
+        const groundIntersects = this.raycaster.intersectObjects(
+          this._GroundPlane,
+          false
+        );
+        if (groundIntersects.length > 0) {
+          // 如果正在动画中，取消之前的动画
+          if (
+            this._CameraConfig.isCameraAnimating &&
+            this._CameraConfig.cameraAnimationId !== null
+          ) {
+            window.cancelAnimationFrame(this._CameraConfig.cameraAnimationId);
+            this._CameraConfig.isCameraAnimating = false;
+            this._CameraConfig.cameraAnimationId = null;
+          }
+
+          const point = groundIntersects[0].point;
+
+          // 保存当前相机位置和朝向
+          const startPosition = this.camera.position.clone();
+          const currentDirection = new THREE.Vector3();
+          this.camera.getWorldDirection(currentDirection);
+
+          // 计算目标位置
+          const targetPosition = new THREE.Vector3(
+            point.x,
+            point.y + this._RoamConfig.cameraHeight,
+            point.z
+          );
+
+          // 计算目标朝向（保持视角朝向不变）
+          const targetLookAt = targetPosition
+            .clone()
+            .add(currentDirection.multiplyScalar(10));
+          this._animateCameraToPosition(
+            startPosition,
+            targetPosition,
+            targetLookAt,
+            currentDirection
+          );
+
+          console.log("✅ 视角跳转到:", point);
+          console.log("   起始位置:", startPosition);
+          console.log("   目标位置:", targetPosition);
+          console.log("   视角朝向:", currentDirection);
+        }
+        return; // 漫游模式下不处理其他点击事件
+      }
+    });
+
+    window.addEventListener("mousedown", (event) => {
+      if (this._CameraConfig.isRoamMode && event.button === 0) {
+        // 左键按下，开始拖拽
+        this._KeyboardEventHandler.isDragging = true;
+        this._KeyboardEventHandler.previousMousePosition.x = event.clientX;
+        this._KeyboardEventHandler.previousMousePosition.y = event.clientY;
+        this.renderer.domElement.style.cursor = "grabbing";
+      }
+    });
+
+    window.addEventListener("mouseup", (event) => {
+      if (this._CameraConfig.isRoamMode && event.button == 0) {
+        // 左键抬起，结束拖拽
+        this._KeyboardEventHandler.isDragging = false;
+        this.renderer.domElement.style.cursor = "default";
+      }
+    });
+
+    window.addEventListener("keydown", (event) => {
+      // 只在漫游模式下处理移动键
+      if (
+        this._CameraConfig.isRoamMode &&
+        this._KeyboardEventHandler.hasOwnProperty(event.key) &&
+        !this._CameraConfig.isCameraAnimating
+      ) {
+        this._KeyboardEventHandler[event.key] = true;
+      }
+    });
+    window.addEventListener("keyup", (event) => {
+      // 只在漫游模式下处理移动键
+      if (
+        this._CameraConfig.isRoamMode &&
+        this._KeyboardEventHandler.hasOwnProperty(event.key) &&
+        !this._CameraConfig.isCameraAnimating
+      ) {
+        this._KeyboardEventHandler[event.key] = false;
+      }
+    });
+  }
+
+  /**
+   * 场景帧率渲染函数
+   */
+  _animate() {
+    requestAnimationFrame(this._animate.bind(this));
+
+    // 如果启用了围绕自身旋转模式
+    if (
+      this._CameraConfig.rotateAroundSelf &&
+      this._CameraConfig.fixedCameraPosition
+    ) {
+      // 先更新控制器
+      this.controls.update();
+
+      // 强制重置相机位置到固定位置（这样相机只能旋转，不能移动）
+      this.camera.position.copy(this._CameraConfig.fixedCameraPosition);
+
+      // 获取相机当前朝向，将target设置为相机前方一个固定距离的位置
+      const direction = new THREE.Vector3();
+      this.camera.getWorldDirection(direction);
+      this.controls.target
+        .copy(this.camera.position)
+        .add(direction.multiplyScalar(0.001));
+
+      // 再次更新控制器以确保正确
+      this.controls.update();
+    } else if (this._CameraConfig.isRoamMode) {
+      // 更新漫游相机
+
+      const direction = new THREE.Vector3();
+      this.camera.getWorldDirection(direction);
+      direction.y = 0; // 只在水平面移动
+      direction.normalize();
+
+      // 计算右方向（用于左右移动）
+      const right = new THREE.Vector3();
+      right.crossVectors(direction, new THREE.Vector3(0, 1, 0)).normalize();
+
+      let moveVector = new THREE.Vector3(0, 0, 0);
+
+      // 前后移动（W/S 或 上/下箭头）
+      if (this._KeyboardEventHandler.w || this._KeyboardEventHandler.ArrowUp) {
+        moveVector.add(direction);
+      }
+      if (
+        this._KeyboardEventHandler.s ||
+        this._KeyboardEventHandler.ArrowDown
+      ) {
+        moveVector.sub(direction);
+      }
+
+      // 左右移动（A/D 或 左/右箭头）
+      if (
+        this._KeyboardEventHandler.a ||
+        this._KeyboardEventHandler.ArrowLeft
+      ) {
+        moveVector.sub(right);
+      }
+      if (
+        this._KeyboardEventHandler.d ||
+        this._KeyboardEventHandler.ArrowRight
+      ) {
+        moveVector.add(right);
+      }
+
+      // 应用移动
+      if (moveVector.length() > 0) {
+        moveVector.normalize().multiplyScalar(this._RoamConfig.moveSpeed);
+        this.camera.position.add(moveVector);
+
+        // 保持相机高度
+        if (this.camera.position.y < this._RoamConfig.cameraHeight) {
+          this.camera.position.y = this._RoamConfig.cameraHeight;
+        }
+
+        // 更新相机朝向（保持看向相同方向）
+        const target = this.camera.position
+          .clone()
+          .add(direction.multiplyScalar(10));
+        this.camera.lookAt(target);
+      }
+    } else {
+      // 更新 OrbitControls（当启用阻尼时必须调用）
+      this.controls.update();
+    }
+
+    // 先渲染 3D 场景，再渲染标签（顺序很重要）
+    this.renderer.render(this.scene, this.camera);
+  }
+
+  /**
+   * 创建全景球体场景
+   * @param {*} texture
+   * @returns
+   */
+  createPanoramaSphere(texture) {
+    if (!texture) return;
+
+    // 移除旧的球体
+    if (this._PanoramaSphere) {
+      this.scene.remove(this._PanoramaSphere);
+      this._PanoramaSphere.geometry.dispose();
+      this._PanoramaSphere.material.dispose();
+    }
+
+    //--------------------   方法1：使用 EquirectangularReflectionMapping + 翻转X轴
+
+    console.log(
+      "🔧 使用方法1: EquirectangularReflectionMapping + scale(1,-1,-1)"
+    );
+
+    texture.mapping = THREE.EquirectangularReflectionMapping;
+    texture.minFilter = THREE.LinearFilter;
+    texture.magFilter = THREE.LinearFilter;
+    texture.flipY = false;
+
+    const geometry = new THREE.SphereGeometry(1000, 64, 32);
+    geometry.scale(1, -1, -1); // 沿Y，Z轴翻转
+
+    const material = new THREE.MeshBasicMaterial({
+      map: texture,
+      side: THREE.BackSide,
+    });
+
+    this._PanoramaSphere = new THREE.Mesh(geometry, material);
+    //-------------------------------------------------
+
+    //------------------- 方法2：使用默认UV映射 + 负半径
+    // console.log("🔧 使用方法2: 默认UV映射 + 负半径");
+    // texture.mapping = THREE.UVMapping; // 使用默认UV映射
+    // texture.minFilter = THREE.LinearFilter;
+    // texture.magFilter = THREE.LinearFilter;
+    // texture.flipY = false;
+    // // 使用负半径创建球体（Three.js会自动翻转）
+    // const geometry = new THREE.SphereGeometry(-1000, 64, 32);
+
+    // const material = new THREE.MeshBasicMaterial({
+    //   map: texture,
+    //   side: THREE.FrontSide, // 使用正面，因为几何体已经翻转
+    // });
+    // panoramaSphere = new THREE.Mesh(geometry, material);
+    //------------------------------------------------
+
+    this.scene.add(this._PanoramaSphere);
+
+    console.log("✅ 全景球体创建成功！");
+    console.log("球体位置:", this._PanoramaSphere.position);
+    console.log("相机位置:", this.camera.position);
+    console.log("材质配置:", {
+      hasTexture: !!this._PanoramaSphere.material.map,
+      side: this._PanoramaSphere.material.side,
+      mapping: texture.mapping,
+      textureSize: texture.image
+        ? `${texture.image.width}x${texture.image.height}`
+        : "未知",
+    });
+
+    // 确保相机朝向正确
+    // this.camera.lookAt(0, 0, -1);
+  }
+
+  /**
+   * 进入第一人称模式
+   */
+  enterFirstPersonMode() {
+    if (this._CameraConfig.isRoamMode) {
+      this.exitRoamMode();
+    }
+
+    // 动画完成后，启用围绕自身旋转模式
+    // 保存相机固定位置
+    this._CameraConfig.fixedCameraPosition = this.camera.position.clone();
+
+    // 获取相机当前朝向，将target设置在相机前方
+    const direction = new THREE.Vector3();
+    this.camera.getWorldDirection(direction);
+    this.controls.target
+      .copy(this.camera.position)
+      .add(direction.multiplyScalar(1));
+    this.controls.update();
+
+    // 启用围绕自身旋转模式（在动画循环中会持续同步target并限制位置）
+    this._CameraConfig.rotateAroundSelf = true;
+
+    // 禁用平移功能，只允许旋转（围绕自身）
+    this.controls.enablePan = false; // 禁用平移
+
+    // 保持缩放功能，但限制距离范围（让相机位置尽量固定）
+    this.controls.minDistance = 0.001;
+    this.controls.maxDistance = 0.001;
+
+    // 允许用户从各个角度查看（移除垂直角度限制）
+    this.controls.maxPolarAngle = Math.PI; // 允许从下方查看
+    console.log(
+      `   相机位置: (${this.camera.position.x.toFixed(
+        2
+      )}, ${this.camera.position.y.toFixed(
+        2
+      )}, ${this.camera.position.z.toFixed(2)})`
+    );
+    console.log(
+      `   控制器目标: (${this.controls.target.x.toFixed(
+        2
+      )}, ${this.controls.target.y.toFixed(
+        2
+      )}, ${this.controls.target.z.toFixed(2)})`
+    );
+    console.log(`💡 现在可以用鼠标拖拽围绕相机自身旋转查看四周，滚轮缩放`);
+  }
+
+  /**
+   * 退出第一人称模式
+   */
+  exitFirstPersonMode() {
+    if (!this.controls || !this._OrbitControlsConfig) {
+      console.error("❌ 控制器或原始配置未初始化");
+      return;
+    }
+
+    console.log("🔄 退出第一人称模式，恢复原始控制状态");
+
+    // 禁用围绕自身旋转模式
+    this._CameraConfig.rotateAroundSelf = false;
+    this._CameraConfig.fixedCameraPosition = null;
+
+    // 恢复 OrbitControls 的原始配置
+    this.controls.enablePan = this._OrbitControlsConfig.enablePan;
+    this.controls.enableZoom = this._OrbitControlsConfig.enableZoom;
+    this.controls.minDistance = this._OrbitControlsConfig.minDistance;
+    this.controls.maxDistance = this._OrbitControlsConfig.maxDistance;
+    this.controls.maxPolarAngle = this._OrbitControlsConfig.maxPolarAngle;
+    this.controls.target.copy(this._OrbitControlsConfig.target);
+    this.controls.update();
+
+    console.log("✅ 已退出第一人称模式，现在可以自由移动和旋转相机");
+  }
+
+  /**
+   * 进入漫游模式
+   */
+  enterRoamMode() {
+    // 如果第一人称视角已启用，先退出
+    if (this._CameraConfig.rotateAroundSelf) {
+      this.exitFirstPersonMode();
+    }
+
+    if (!this._RoamConfig.groundCircle) {
+      // 创建地面圆圈（用于漫游模式 的地面圆圈指示器）
+      const circleGeometry = new THREE.RingGeometry(0.3, 0.5, 32);
+      const circleMaterial = new THREE.MeshBasicMaterial({
+        color: 0x00ffff,
+        side: THREE.DoubleSide,
+        transparent: true,
+        opacity: 0.6,
+      });
+      this._RoamConfig.groundCircle = new THREE.Mesh(
+        circleGeometry,
+        circleMaterial
+      );
+      this._RoamConfig.groundCircle.rotation.x = -Math.PI / 2; // 旋转使其水平
+      this._RoamConfig.groundCircle.visible = false; // 默认隐藏
+      this.scene.add(this._RoamConfig.groundCircle);
+      console.log("✅ 地面圆圈指示器创建成功");
+    }
+
+    this._CameraConfig.isRoamMode = true;
+
+    // 启用漫游模式
+    this.controls.enabled = false; // 禁用轨道控制器
+
+    this._RoamConfig.groundCircle.visible = false; // 初始隐藏圆圈
+
+    // 如果相机位置太低，调整到合适高度
+    if (this.camera.position.y < this._RoamConfig.cameraHeight) {
+      this.camera.position.y = this._RoamConfig.cameraHeight;
+    }
+
+    console.log("✅ 进入视角漫游模式");
+    console.log("📍 当前相机位置:", this.camera.position);
+    console.log("⌨️  操作说明：");
+    console.log("   • 鼠标悬停地面显示圆圈");
+    console.log("   • 点击地面跳转视角");
+    console.log("   • WASD/方向键移动");
+    console.log("   • 鼠标拖拽改变朝向");
+  }
+
+  exitRoamMode() {
+    // 退出漫游模式
+    this.controls.enabled = true;
+    this._RoamConfig.groundCircle.visible = false;
+    this._CameraConfig.isRoamMode = false;
+    console.log("✅ 退出视角漫游模式");
+  }
+
+  /**
+   * 创建3d场景组
+   * @param {string} name - 场景组名称
+   * @returns {THREE.Group} - 返回创建的3d场景组
+   */
+  createThreeGroup(name) {
+    if (this._ThreeGroupMap.has(name)) {
+      return this._ThreeGroupMap.get(name);
+    }
+    const threeGroup = new THREE.Group();
+    this.scene.add(threeGroup);
+    this._ThreeGroupMap.set(name, threeGroup);
+    return threeGroup;
+  }
+
+  /**
+   * 将相机平滑移动到指定位置，并可以围绕位置旋转查看
+   * @param {THREE.Vector3} position - 标签的3D位置
+   * @param {string} contentHtml - 标签显示的HTML内容
+   * @param {Object} options - 可选配置项
+   * @param {number} options.heightOffset - 相机在标签下方的距离，默认50
+   * @param {number} options.distance - 相机与标签的水平距离，默认100
+   * @param {number} options.duration - 动画时长（毫秒），默认1500
+   */
+  flyTo(viewInfo = {}, options = {}) {
+    return new Promise((resolve, reject) => {
+      if (!this.camera || !this.controls) {
+        reject("❌ 相机或控制器未初始化");
+        console.error("❌ 相机或控制器未初始化");
+        return;
+      }
+      const { position, target } = viewInfo;
+      if (!position || !target) {
+        console.error("❌ 视图信息格式错误，需要包含 position 和 target");
+        reject("❌ 视图信息格式错误，需要包含 position 和 target");
+        return;
+      }
+      const { x: positionX = 0, y: positionY = 0, z: positionZ = 0 } = position;
+      const { x: targetX = 0, y: targetY = 0, z: targetZ = 0 } = target;
+
+      const {
+        heightOffset = 50, // 相机在标签下方的距离
+        distance = 0, // 相机与标签的水平距离
+        duration = 1500, // 动画时长（毫秒）
+      } = options;
+
+      const targetPosition = new THREE.Vector3(positionX, positionY, positionZ);
+
+      const targetLookAt = new THREE.Vector3(targetX, targetY, targetZ);
+
+      // 保存初始位置和目标
+      const startPosition = this.camera.position.clone();
+      const startTarget = this.controls.target.clone();
+
+      // 动画参数
+      let startTime = null;
+
+      // 缓动函数（ease-in-out）
+      function easeInOutCubic(t) {
+        return t < 0.5 ? 4 * t * t * t : 1 - Math.pow(-2 * t + 2, 3) / 2;
+      }
+
+      // 动画函数
+      function animateCamera(currentTime) {
+        if (!startTime) startTime = currentTime;
+        const elapsed = currentTime - startTime;
+        const progress = Math.min(elapsed / duration, 1);
+        const easedProgress = easeInOutCubic(progress);
+
+        // 插值计算当前位置和目标
+        this.camera.position.lerpVectors(
+          startPosition,
+          targetPosition,
+          easedProgress
+        );
+        this.controls.target.lerpVectors(
+          startTarget,
+          targetLookAt,
+          easedProgress
+        );
+        this.controls.update();
+
+        // 如果动画未完成，继续下一帧
+        if (progress < 1) {
+          requestAnimationFrame(animateCamera.bind(this));
+        } else {
+          resolve();
+          console.log("✅ 摄像头已移动到指定位置");
+          console.log(
+            `   位置: (${targetPosition.x.toFixed(
+              2
+            )}, ${targetPosition.y.toFixed(2)}, ${targetPosition.z.toFixed(2)})`
+          );
+          console.log(
+            `   目标: (${targetLookAt.x.toFixed(2)}, ${targetLookAt.y.toFixed(
+              2
+            )}, ${targetLookAt.z.toFixed(2)})`
+          );
+        }
+      }
+
+      // 开始动画
+      requestAnimationFrame(animateCamera.bind(this));
+    });
+  }
+
+  _getCameraInfo() {
+    if (!this.camera || !this.controls) return;
+
+    const pos = this.camera.position;
+    const target = this.controls.target;
+    const distance = pos.distanceTo(target);
+    return {
+      position: {
+        x: parseFloat(pos.x.toFixed(2)),
+        y: parseFloat(pos.y.toFixed(2)),
+        z: parseFloat(pos.z.toFixed(2)),
+      },
+      target: {
+        x: parseFloat(target.x.toFixed(2)),
+        y: parseFloat(target.y.toFixed(2)),
+        z: parseFloat(target.z.toFixed(2)),
+      },
+      distance: parseFloat(distance.toFixed(2)),
+    };
+  }
+
+  /**
+   * 相机平滑过渡动画
+   * @param {THREE.Camera} camera - 相机
+   * @param {THREE.Vector3} startPos - 起始位置
+   * @param {THREE.Vector3} targetPos - 目标位置
+   * @param {THREE.Vector3} targetLookAt - 目标朝向
+   * @param {THREE.Vector3} direction - 方向
+   */
+  _animateCameraToPosition(startPos, targetPos, targetLookAt, direction) {
+    this._CameraConfig.isCameraAnimating = true;
+
+    const duration = 1000; // 动画持续时间（毫秒）
+    const startTime = performance.now();
+
+    // 缓动函数：easeInOutCubic（平滑的加速和减速）
+    function easeInOutCubic(t) {
+      return t < 0.5 ? 4 * t * t * t : 1 - Math.pow(-2 * t + 2, 3) / 2;
+    }
+
+    const animate = (currentTime) => {
+      const elapsed = currentTime - startTime;
+      const progress = Math.min(elapsed / duration, 1);
+      const easedProgress = easeInOutCubic(progress);
+
+      // 使用 lerp 插值计算当前位置
+      this.camera.position.lerpVectors(startPos, targetPos, easedProgress);
+
+      // 保持视角朝向不变（看向相同方向）
+      const currentLookAt = this.camera.position
+        .clone()
+        .add(direction.multiplyScalar(10));
+      this.camera.lookAt(currentLookAt);
+
+      // 如果动画未完成，继续下一帧
+      if (progress < 1) {
+        this._CameraConfig.cameraAnimationId = requestAnimationFrame(animate);
+      } else {
+        // 动画完成，确保最终位置精确
+        this.camera.position.copy(targetPos);
+        this.camera.lookAt(targetLookAt);
+        this._CameraConfig.isCameraAnimating = false;
+        this._CameraConfig.cameraAnimationId = null;
+        console.log("✅ 视角平滑跳转完成");
+      }
+    };
+
+    // 开始动画
+    this._CameraConfig.cameraAnimationId = requestAnimationFrame(animate);
+  }
+}
+
+export default ThreeSdk;