easy-threesdk 1.0.0

package/README.md

@@ -0,0 +1,166 @@
+# ThreeSDK 使用文档
+
+## 1. 简介
+ThreeSDK 是一个基于 Three.js 的封装库，旨在简化 3D 场景的搭建、模型加载、交互控制以及标签系统的开发。通过封装常用的 Three.js 功能，开发者可以更快速地构建具有漫游、交互和标注功能的 3D 应用。
+
+## 2. 核心功能
+
+ThreeSDK 封装了以下核心能力：
+
+### 2.1 场景基础建设
+- **自动化初始化**：一键初始化 Scene、Camera、Renderer、OrbitControls 和 Lights。
+- **响应式适配**：自动处理窗口大小调整 (Resize)。
+- **光照系统**：内置环境光、方向光和边缘光 (Rim Light) 配置。
+
+### 2.2 摄像机与视角控制
+- **轨道控制器 (OrbitControls)**：默认支持旋转、缩放、平移。
+- **第一人称模式 (First Person Mode)**：
+  - 固定相机位置，仅允许围绕自身旋转查看。
+  - 适用于全景查看。
+- **漫游模式 (Roam Mode)**：
+  - 类似游戏的操作方式 (WASD / 方向键移动)。
+  - 鼠标拖拽改变视角朝向。
+  - 地面点击跳转 (Teleport)。
+- **视角动画 (flyTo)**：平滑过渡到指定位置和视角的动画功能。
+
+### 2.3 插件系统
+采用插件化架构，通过 `plugins()` 方法注册功能模块。目前内置插件包括：
+- **LabelControl**：基于 CSS3DRenderer 的 3D HTML 标签系统。
+- **ModelControl**：GLTF 模型加载、模型点击/悬停交互管理。
+
+### 2.4 其他工具
+- **全景球体 (Panorama Sphere)**：快速创建全景背景。
+- **场景组管理 (ThreeGroup)**：方便管理场景中的对象分组。
+
+---
+
+## 3. 快速上手 Demo
+
+以下代码展示了如何使用 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";
+
+// 1. 初始化 SDK
+const container = document.getElementById("canvas-container");
+const threeSdk = new ThreeSdk(container);
+
+// 2. 配置并启动场景
+threeSdk.init(
+  {
+    // 相机初始位置
+    position: new THREE.Vector3(0, 15, 20),
+    lookAt: new THREE.Vector3(0, 0, 0),
+  },
+  {
+    // 控制器配置
+    minDistance: 10,
+    maxDistance: 500,
+  },
+  {
+    // 灯光配置 (可选)
+    ambientLightIntensity: 0.8,
+  }
+);
+
+// 3. 注册插件
+threeSdk.plugins([LabelControl, ModelControl]);
+
+// 4. 创建全景背景 (可选)
+const textureLoader = new THREE.TextureLoader();
+textureLoader.load("/path/to/panorama.jpg", (texture) => {
+  threeSdk.createPanoramaSphere(texture);
+});
+
+// 5. 使用 ModelControl 插件加载 GLTF 模型
+const modelControl = threeSdk._PluginsManager.get("ModelControl");
+
+modelControl.loadGLTFBuilding(
+  {
+    ModelID: "MyCar",
+    modelPath: "./resource/car/scene.gltf",
+    position: [0, 0], // x, z 坐标
+    scale: 0.1,
+    clickable: true,
+  },
+  (percent) => {
+    console.log(`模型加载进度: ${Math.round(percent)}%`);
+  }
+);
+
+// 监听模型点击事件
+modelControl.onModelClickListener((object) => {
+  if (object) {
+    console.log("点击了模型:", object.userData.name);
+  }
+});
+
+// 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>
+  `,
+  new THREE.Vector3(0, 10, 0), // 标签位置
+  {
+    size: 0.02, // 缩放比例
+    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)
+      });
+    }
+  }
+);
+
+// 7. 切换视角模式示例
+// 开启漫游模式
+// threeSdk.enterRoamMode();
+// 开启第一人称模式
+// threeSdk.enterFirstPersonMode();
+```
+
+## 4. API 概览
+
+### ThreeSdk 类
+
+| 方法 | 描述 |
+|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
+
+| 方法 | 描述 |
+|---|---|
+| `loadGLTFBuilding(options, onLoadProcess)` | 加载 GLTF 模型，支持阴影和点击配置。 |
+| `onModelClickListener(callback)` | 监听模型点击事件。 |
+| `onModelMouseMoveListener(callback)` | 监听模型悬停事件。 |
+
+### Plugin: LabelControl
+
+| 方法 | 描述 |
+|---|---|
+| `create3DLabel(id, html, position, options, events)` | 创建 CSS3D 标签。 |