easy-threesdk 1.0.0 → 1.0.3

package/README.md

@@ -1,48 +1,74 @@
 # ThreeSDK 使用文档
 
 ## 1. 简介
+
 ThreeSDK 是一个基于 Three.js 的封装库，旨在简化 3D 场景的搭建、模型加载、交互控制以及标签系统的开发。通过封装常用的 Three.js 功能，开发者可以更快速地构建具有漫游、交互和标注功能的 3D 应用。
 
-## 2. 核心功能
+**当前版本：** 1.0.3
+
+## 2. 安装
+
+```bash
+npm install easy-threesdk
+```
+
+或直接通过 Gitee 仓库使用：
+
+```bash
+git clone https://gitee.com/xieqianstudent/visual-learning.git
+```
+
+## 3. 核心功能
 
 ThreeSDK 封装了以下核心能力：
 
-### 2.1 场景基础建设
-- **自动化初始化**：一键初始化 Scene、Camera、Renderer、OrbitControls 和 Lights。
-- **响应式适配**：自动处理窗口大小调整 (Resize)。
-- **光照系统**：内置环境光、方向光和边缘光 (Rim Light) 配置。
+### 3.1 场景基础建设
 
-### 2.2 摄像机与视角控制
-- **轨道控制器 (OrbitControls)**：默认支持旋转、缩放、平移。
+- **自动化初始化**：一键初始化 Scene、Camera、Renderer、OrbitControls 和 Lights
+- **响应式适配**：自动处理窗口大小调整 (Resize)
+- **光照系统**：内置环境光、方向光和边缘光 (Rim Light) 配置
+- **背景系统**：支持全景球体背景和立方体贴图背景
+
+### 3.2 摄像机与视角控制
+
+- **轨道控制器 (OrbitControls)**：默认支持旋转、缩放、平移
 - **第一人称模式 (First Person Mode)**：
-  - 固定相机位置，仅允许围绕自身旋转查看。
-  - 适用于全景查看。
+  - 固定相机位置，仅允许围绕自身旋转查看
+  - 适用于全景查看
 - **漫游模式 (Roam Mode)**：
-  - 类似游戏的操作方式 (WASD / 方向键移动)。
-  - 鼠标拖拽改变视角朝向。
-  - 地面点击跳转 (Teleport)。
-- **视角动画 (flyTo)**：平滑过渡到指定位置和视角的动画功能。
+  - 类似游戏的操作方式 (WASD / 方向键移动)
+  - 鼠标拖拽改变视角朝向
+  - 地面点击跳转 (Teleport)
+  - 实时显示地面指示圆圈
+- **视角动画 (flyTo)**：平滑过渡到指定位置和视角的动画功能，支持 Promise
+
+### 3.3 插件系统
 
-### 2.3 插件系统
 采用插件化架构，通过 `plugins()` 方法注册功能模块。目前内置插件包括：
-- **LabelControl**：基于 CSS3DRenderer 的 3D HTML 标签系统。
-- **ModelControl**：GLTF 模型加载、模型点击/悬停交互管理。
 
-### 2.4 其他工具
-- **全景球体 (Panorama Sphere)**：快速创建全景背景。
-- **场景组管理 (ThreeGroup)**：方便管理场景中的对象分组。
+- **LabelControl**：基于 CSS3DRenderer 的 3D HTML 标签系统，支持多种标签样式
+- **ModelControl**：GLTF 模型加载、模型点击/悬停交互管理、网格变换控制器
+
+### 3.4 其他工具
+
+- **全景球体 (Panorama Sphere)**：快速创建全景背景
+- **立方体贴图背景**：支持六面体背景纹理
+- **场景组管理 (ThreeGroup)**：方便管理场景中的对象分组
+- **地面平面管理**：支持设置地面平面用于漫游模式检测
 
 ---
 
-## 3. 快速上手 Demo
+## 4. 快速上手
+
+### 4.1 基础示例
 
 以下代码展示了如何使用 ThreeSDK 初始化场景、加载模型、添加标签以及启用交互。
 
 ```javascript
 import * as THREE from "three";
-import ThreeSdk from "./ThreeSdk/index.js";
-import LabelControl from "./ThreeSdk/plugins/LabelControl.js";
-import ModelControl from "./ThreeSdk/plugins/ModelControl.js";
+import ThreeSdk from "./index.js";
+import LabelControl from "./plugins/LabelControl.js";
+import ModelControl from "./plugins/ModelControl.js";
 
 // 1. 初始化 SDK
 const container = document.getElementById("canvas-container");
@@ -57,12 +83,21 @@ threeSdk.init(
   },
   {
     // 控制器配置
+    enableDamping: true,
+    dampingFactor: 0.05,
     minDistance: 10,
     maxDistance: 500,
+    maxPolarAngle: Math.PI / 2,
+    target: new THREE.Vector3(0, 0, 0),
   },
   {
     // 灯光配置 (可选)
+    ambientLight: 0xffffff,
     ambientLightIntensity: 0.8,
+    directionalLightColor: 0xa5f3fc,
+    directionalLightIntensity: 1.5,
+    rimLightColor: 0x0ea5e9,
+    rimLightIntensity: 3,
   }
 );
 
@@ -70,10 +105,17 @@ threeSdk.init(
 threeSdk.plugins([LabelControl, ModelControl]);
 
 // 4. 创建全景背景 (可选)
-const textureLoader = new THREE.TextureLoader();
-textureLoader.load("/path/to/panorama.jpg", (texture) => {
-  threeSdk.createPanoramaSphere(texture);
-});
+threeSdk.createPanoramaSphere("/path/to/panorama.jpg");
+
+// 或创建立方体贴图背景
+threeSdk.createBackground([
+  "/path/to/xpos.jpg", // 右
+  "/path/to/xneg.jpg", // 左
+  "/path/to/ypos.jpg", // 上
+  "/path/to/yneg.jpg", // 下
+  "/path/to/zpos.jpg", // 前
+  "/path/to/zneg.jpg", // 后
+]);
 
 // 5. 使用 ModelControl 插件加载 GLTF 模型
 const modelControl = threeSdk._PluginsManager.get("ModelControl");
@@ -82,7 +124,7 @@ modelControl.loadGLTFBuilding(
   {
     ModelID: "MyCar",
     modelPath: "./resource/car/scene.gltf",
-    position: [0, 0], // x, z 坐标
+    position: [0, 0], // [x, z] 坐标
     scale: 0.1,
     clickable: true,
   },
@@ -94,73 +136,543 @@ modelControl.loadGLTFBuilding(
 // 监听模型点击事件
 modelControl.onModelClickListener((object) => {
   if (object) {
-    console.log("点击了模型:", object.userData.name);
+    console.log("点击了模型:", object);
+  }
+});
+
+// 监听模型悬停事件
+modelControl.onModelMouseMoveListener((object) => {
+  if (object) {
+    console.log("悬停在模型上:", object);
   }
 });
 
 // 6. 使用 LabelControl 插件添加 3D 标签
 const labelControl = threeSdk._PluginsManager.get("LabelControl");
 
-labelControl.create3DLabel(
-  "CarLabel", // 标签 ID
-  `
-    <div style="color: white; background: rgba(0,0,0,0.6); padding: 10px; border-radius: 5px;">
-      <h3>My Car</h3>
-      <p>Click to view details</p>
-    </div>
-  `,
+// 创建箭头标签
+labelControl.createArrow3DLabel(
+  "CarLabel",
+  {
+    template: "<div>My Car</div>",
+    data: {},
+  },
   new THREE.Vector3(0, 10, 0), // 标签位置
   {
-    size: 0.02, // 缩放比例
+    size: 0.02,
+    backgroundColor: "rgba(20, 30, 50, 0.9)",
+    textColor: "#ffffff",
+    borderColor: "#22d3ee",
+    fontSize: 16,
     className: "my-label-class",
   },
   {
-    // 标签事件
     click: (e) => {
       console.log("点击了标签", e);
       // 视角飞向标签位置
       threeSdk.flyTo({
         position: new THREE.Vector3(10, 10, 10),
-        target: new THREE.Vector3(0, 0, 0)
+        target: new THREE.Vector3(0, 0, 0),
       });
-    }
+    },
+    mouseenter: (e) => {
+      console.log("鼠标进入标签", e);
+    },
+    mouseleave: (e) => {
+      console.log("鼠标离开标签", e);
+    },
   }
 );
 
 // 7. 切换视角模式示例
 // 开启漫游模式
-// threeSdk.enterRoamMode();
+threeSdk.enterRoamMode();
+
 // 开启第一人称模式
-// threeSdk.enterFirstPersonMode();
+threeSdk.enterFirstPersonMode();
+
+// 退出模式
+threeSdk.exitRoamMode();
+threeSdk.exitFirstPersonMode();
+```
+
+### 4.2 标签类型示例
+
+LabelControl 插件支持三种标签类型：
+
+```javascript
+const labelControl = threeSdk._PluginsManager.get("LabelControl");
+
+// 1. 箭头标签 - 带向下箭头指示器
+labelControl.createArrow3DLabel(
+  "ArrowLabel",
+  { template: "<div>箭头标签</div>", data: {} },
+  new THREE.Vector3(0, 5, 0),
+  { size: 0.02 }
+);
+
+// 2. 指示器标签 - 带折线指示器和背景图
+labelControl.createIndicator3DLabel(
+  "IndicatorLabel",
+  { template: "<div>指示器标签</div>", data: {} },
+  new THREE.Vector3(5, 5, 0),
+  { size: 0.02 }
+);
+
+// 3. 可展开标签 - 点击可展开显示更多内容
+labelControl.createExpand3DLabel(
+  "ExpandLabel",
+  {
+    template: "<div>点击展开</div>",
+    expandContentHtml: "<div>展开的内容</div>",
+    data: {},
+  },
+  new THREE.Vector3(-5, 5, 0),
+  { size: 0.02 }
+);
+```
+
+---
+
+## 5. API 详细文档
+
+### 5.1 ThreeSdk 类
+
+#### 构造函数
+
+```javascript
+new ThreeSdk(container);
+```
+
+- `container` (HTMLElement): 用于渲染 3D 场景的 DOM 容器
+
+#### 主要方法
+
+##### `init(cameraConfig, controlConfig, lightConfig)`
+
+初始化场景、相机、灯光和控制器。
+
+**参数：**
+
+- `cameraConfig` (Object, 可选):
+
+  - `position` (THREE.Vector3, 默认: `new THREE.Vector3(0, 280, 320)`): 相机初始位置
+  - `lookAt` (THREE.Vector3, 默认: `new THREE.Vector3(0, 0, 0)`): 相机初始朝向
+
+- `controlConfig` (Object, 可选):
+
+  - `enableDamping` (boolean, 默认: `true`): 是否启用阻尼
+  - `dampingFactor` (number, 默认: `0.05`): 阻尼因子
+  - `minDistance` (number, 默认: `50`): 最小缩放距离
+  - `maxDistance` (number, 默认: `800`): 最大缩放距离
+  - `maxPolarAngle` (number, 默认: `Math.PI / 2`): 最大极角
+  - `target` (THREE.Vector3, 默认: `new THREE.Vector3(0, 0, 0)`): 控制器目标位置
+
+- `lightConfig` (Object, 可选):
+  - `ambientLight` (THREE.Color, 默认: `0xffffff`): 环境光颜色
+  - `ambientLightIntensity` (number, 默认: `0.5`): 环境光强度
+  - `directionalLightColor` (THREE.Color, 默认: `0xa5f3fc`): 方向光颜色
+  - `directionalLightIntensity` (number, 默认: `1.5`): 方向光强度
+  - `rimLightColor` (THREE.Color, 默认: `0x0ea5e9`): 边缘光颜色
+  - `rimLightIntensity` (number, 默认: `3`): 边缘光强度
+  - `rimLightPosition` (THREE.Vector3, 默认: `new THREE.Vector3(0, 100, -100)`): 边缘光位置
+  - `mainLightPosition` (THREE.Vector3, 默认: `new THREE.Vector3(50, 100, 50)`): 主光位置
+
+##### `plugins(plugins)`
+
+注册插件。
+
+**参数：**
+
+- `plugins` (Array<Object> | Object): 插件类或插件类数组
+
+**示例：**
+
+```javascript
+threeSdk.plugins([LabelControl, ModelControl]);
+// 或
+threeSdk.plugins(LabelControl);
+```
+
+##### `createPanoramaSphere(textureImage)`
+
+创建全景球体背景。
+
+**参数：**
+
+- `textureImage` (string): 全景图片路径（单张等距柱状投影图片）
+
+**示例：**
+
+```javascript
+threeSdk.createPanoramaSphere("/path/to/panorama.jpg");
 ```
 
-## 4. API 概览
+##### `createBackground(textureImages)`
+
+创建立方体贴图背景。
+
+**参数：**
+
+- `textureImages` (string[]): 六面体图片路径数组，顺序为 [右, 左, 上, 下, 前, 后]
+
+**示例：**
+
+```javascript
+threeSdk.createBackground([
+  "/path/to/xpos.jpg",
+  "/path/to/xneg.jpg",
+  "/path/to/ypos.jpg",
+  "/path/to/yneg.jpg",
+  "/path/to/zpos.jpg",
+  "/path/to/zneg.jpg",
+]);
+```
+
+##### `enterRoamMode()`
+
+进入漫游模式。支持 WASD/方向键移动，鼠标拖拽旋转视角，双击地面跳转。
+
+**操作说明：**
+
+- WASD 或方向键：前后左右移动
+- 鼠标拖拽：旋转视角
+- 双击地面：跳转到点击位置
+- 鼠标悬停地面：显示指示圆圈
+
+##### `exitRoamMode()`
+
+退出漫游模式，恢复轨道控制器。
+
+##### `enterFirstPersonMode()`
+
+进入第一人称模式。相机位置固定，仅允许围绕自身旋转查看。
+
+**使用场景：** 全景查看、固定视角观察
+
+##### `exitFirstPersonMode()`
+
+退出第一人称模式，恢复原始控制状态。
+
+##### `flyTo(viewInfo, options)`
+
+相机平滑飞行到指定视角。返回 Promise。
+
+**参数：**
+
+- `viewInfo` (Object):
+  - `position` (THREE.Vector3): 目标相机位置
+  - `target` (THREE.Vector3): 目标朝向位置
+- `options` (Object, 可选):
+  - `duration` (number, 默认: `1500`): 动画时长（毫秒）
+
+**返回：** Promise
+
+**示例：**
+
+```javascript
+threeSdk
+  .flyTo(
+    {
+      position: new THREE.Vector3(10, 20, 30),
+      target: new THREE.Vector3(0, 0, 0),
+    },
+    {
+      duration: 2000,
+    }
+  )
+  .then(() => {
+    console.log("相机移动完成");
+  });
+```
+
+##### `createThreeGroup(name)`
+
+创建并获取一个 THREE.Group，用于管理场景中的对象分组。
+
+**参数：**
+
+- `name` (string): 组名称
+
+**返回：** THREE.Group
+
+**示例：**
+
+```javascript
+const buildingGroup = threeSdk.createThreeGroup("buildings");
+buildingGroup.add(someMesh);
+```
+
+#### 属性
+
+- `scene` (THREE.Scene): Three.js 场景对象
+- `camera` (THREE.PerspectiveCamera): 相机对象
+- `renderer` (THREE.WebGLRenderer): 渲染器对象
+- `controls` (OrbitControls): 轨道控制器对象
+- `raycaster` (THREE.Raycaster): 射线检测器
+- `_PluginsManager` (Map): 插件管理器，可通过此属性获取已注册的插件
+
+---
+
+### 5.2 Plugin: ModelControl
+
+#### 主要方法
+
+##### `loadGLTFBuilding(options, onLoadProcess)`
 
-### ThreeSdk 类
+加载 GLTF 格式的建筑物模型。
 
-| 方法 | 描述 |
-|Data Type| Description|
-|---|---|
-| `init(cameraConfig, controlConfig, lightConfig)` | 初始化场景、相机、灯光和控制器。 |
-| `plugins(pluginsList)` | 注册插件数组。 |
-| `createPanoramaSphere(texture)` | 创建全景球体背景。 |
-| `enterRoamMode()` | 进入漫游模式 (WASD移动)。 |
-| `exitRoamMode()` | 退出漫游模式。 |
-| `enterFirstPersonMode()` | 进入第一人称模式 (定点旋转)。 |
-| `exitFirstPersonMode()` | 退出第一人称模式。 |
-| `flyTo(viewInfo, options)` | 相机平滑飞行到指定视角。 |
-| `createThreeGroup(name)` | 创建并获取一个 Three.Group。 |
+**参数：**
 
-### Plugin: ModelControl
+- `options` (Object):
+  - `ModelID` (string): 模型唯一标识符
+  - `modelPath` (string): GLTF 模型文件路径
+  - `position` (Array, 默认: `[0, 0]`): 模型位置 `[x, z]` 坐标
+  - `scale` (number, 默认: `30`): 模型缩放比例
+  - `clickable` (boolean, 默认: `true`): 模型是否可点击
+- `onLoadProcess` (Function, 可选): 加载进度回调函数 `(percent) => {}`
 
-| 方法 | 描述 |
-|---|---|
-| `loadGLTFBuilding(options, onLoadProcess)` | 加载 GLTF 模型，支持阴影和点击配置。 |
-| `onModelClickListener(callback)` | 监听模型点击事件。 |
-| `onModelMouseMoveListener(callback)` | 监听模型悬停事件。 |
+**返回：** Promise<THREE.Object3D>
+
+**示例：**
+
+```javascript
+const model = await modelControl.loadGLTFBuilding(
+  {
+    ModelID: "building1",
+    modelPath: "./models/building.gltf",
+    position: [10, 20],
+    scale: 1.0,
+    clickable: true,
+  },
+  (percent) => {
+    console.log(`加载进度: ${percent}%`);
+  }
+);
+```
+
+##### `onModelClickListener(callback)`
+
+监听模型点击事件。
+
+**参数：**
+
+- `callback` (Function): 回调函数 `(object) => {}`，点击模型时触发，`object` 为被点击的网格对象，未点击模型时为 `null`
+
+**示例：**
+
+```javascript
+modelControl.onModelClickListener((object) => {
+  if (object) {
+    console.log("点击了模型:", object);
+    console.log("模型名称:", object.userData.name);
+  }
+});
+```
+
+##### `onModelMouseMoveListener(callback)`
+
+监听模型悬停事件。
+
+**参数：**
+
+- `callback` (Function): 回调函数 `(object) => {}`，悬停在模型上时触发，`object` 为被悬停的网格对象，未悬停时为 `null`
+
+**注意：** 此方法会为可点击的模型添加悬停高亮效果（青色发光）。
+
+**示例：**
+
+```javascript
+modelControl.onModelMouseMoveListener((object) => {
+  if (object) {
+    console.log("悬停在模型上:", object);
+  }
+});
+```
+
+##### `installMeshControls(mesh)`
+
+为指定网格安装变换控制器（TransformControls），支持平移、旋转、缩放。
+
+**参数：**
+
+- `mesh` (THREE.Mesh): 需要控制的网格对象
+
+**操作说明：**
+
+- 按 `G` 键：切换到平移模式
+- 按 `R` 键：切换到旋转模式
+- 按 `S` 键：切换到缩放模式
+
+**示例：**
+
+```javascript
+modelControl.installMeshControls(someMesh);
+```
+
+---
+
+### 5.3 Plugin: LabelControl
+
+#### 主要方法
+
+##### `createArrow3DLabel(LabelID, contentOptions, position, options, Events)`
+
+创建带向下箭头指示器的 3D 标签。
+
+**参数：**
+
+- `LabelID` (string): 标签唯一标识符
+- `contentOptions` (Object):
+  - `template` (string): HTML 模板字符串（支持 Vue 语法）
+  - `data` (Object): Vue 数据对象
+- `position` (THREE.Vector3 | Array): 标签 3D 位置，可以是 Vector3 对象或 `[x, y, z]` 数组
+- `options` (Object, 可选):
+  - `size` (number, 默认: `0.02`): 标签缩放大小
+  - `backgroundColor` (string, 默认: `"rgba(20, 30, 50, 0.9)"`): 背景颜色
+  - `textColor` (string, 默认: `"#ffffff"`): 文字颜色
+  - `borderColor` (string, 默认: `"#22d3ee"`): 边框颜色
+  - `fontSize` (number, 默认: `16`): 字体大小（px）
+  - `width` (string, 默认: `"auto"`): 标签宽度
+  - `className` (string, 默认: `"label-3d-arrow"`): 自定义 CSS 类名
+- `Events` (Object, 可选):
+  - `click` (Function): 点击事件回调
+  - `mouseenter` (Function): 鼠标进入事件回调
+  - `mouseleave` (Function): 鼠标离开事件回调
+
+**返回：** CSS3DObject
+
+##### `createIndicator3DLabel(LabelID, contentOptions, position, options, Events)`
+
+创建带折线指示器和背景图的 3D 标签。
+
+**参数：** 同 `createArrow3DLabel`，但 `className` 默认为 `"label-3d-Indicator"`
+
+**注意：** 此方法需要背景图片资源 `/ponit-ui-item.png`
+
+##### `createExpand3DLabel(LabelID, contentOptions, position, options, Events)`
+
+创建可展开的 3D 标签，点击标签可展开显示更多内容。
+
+**参数：**
+
+- `contentOptions` (Object):
+  - `template` (string): 标签显示的 HTML 模板
+  - `expandContentHtml` (string): 展开时显示的 HTML 内容
+  - `data` (Object): Vue 数据对象
+- 其他参数同 `createArrow3DLabel`，但 `className` 默认为 `"label-3d-Expand"`
+
+**返回：** CSS3DObject
+
+**示例：**
+
+```javascript
+labelControl.createExpand3DLabel(
+  "ExpandLabel",
+  {
+    template: "<div>点击展开</div>",
+    expandContentHtml: "<div>这是展开的内容</div>",
+    data: {},
+  },
+  new THREE.Vector3(0, 10, 0),
+  { size: 0.02 }
+);
+```
+
+---
+
+## 6. 完整示例
+
+```javascript
+import * as THREE from "three";
+import ThreeSdk from "./index.js";
+import LabelControl from "./plugins/LabelControl.js";
+import ModelControl from "./plugins/ModelControl.js";
+
+// 初始化
+const container = document.getElementById("app");
+const sdk = new ThreeSdk(container);
+
+sdk.init(
+  {
+    position: new THREE.Vector3(0, 50, 100),
+    lookAt: new THREE.Vector3(0, 0, 0),
+  },
+  {
+    minDistance: 10,
+    maxDistance: 1000,
+  },
+  {
+    ambientLightIntensity: 0.6,
+  }
+);
+
+// 注册插件
+sdk.plugins([LabelControl, ModelControl]);
+
+const labelControl = sdk._PluginsManager.get("LabelControl");
+const modelControl = sdk._PluginsManager.get("ModelControl");
+
+// 加载模型
+await modelControl.loadGLTFBuilding({
+  ModelID: "house",
+  modelPath: "./models/house.gltf",
+  position: [0, 0],
+  scale: 1,
+  clickable: true,
+});
+
+// 模型交互
+modelControl.onModelClickListener((object) => {
+  if (object) {
+    console.log("模型被点击");
+  }
+});
+
+// 创建标签
+labelControl.createArrow3DLabel(
+  "info",
+  {
+    template: "<div>{{ title }}</div>",
+    data: { title: "我的模型" },
+  },
+  new THREE.Vector3(0, 20, 0),
+  { size: 0.02 },
+  {
+    click: () => {
+      sdk.flyTo({
+        position: new THREE.Vector3(0, 30, 50),
+        target: new THREE.Vector3(0, 0, 0),
+      });
+    },
+  }
+);
+```
+
+---
+
+## 7. 注意事项
+
+1. **依赖要求**：需要安装 Three.js 和相关依赖
+2. **Vue 支持**：标签系统使用 Vue 2.x 进行渲染，需要确保项目中已引入 Vue
+3. **地面检测**：漫游模式需要设置 `_GroundPlane` 属性才能正常使用地面点击跳转功能
+4. **性能优化**：大量模型和标签时建议使用场景组管理，合理控制渲染对象数量
+5. **浏览器兼容性**：建议使用现代浏览器（Chrome、Firefox、Edge 等）
+
+---
+
+## 8. 许可证
+
+ISC
+
+---
+
+## 9. 作者
+
+coderxq
+
+---
 
-### Plugin: LabelControl
+## 10. 仓库地址
 
-| 方法 | 描述 |
-|---|---|
-| `create3DLabel(id, html, position, options, events)` | 创建 CSS3D 标签。 |
+- Gitee: https://gitee.com/xieqianstudent/visual-learning.git