easy-threesdk快速一键搭建threejs3d可视化场景

ThreeSDK：让 Three.js 3D 开发更简单高效

还在为 Three.js 的复杂配置而烦恼？还在重复编写场景初始化、模型加载、交互控制的代码？ThreeSDK 帮你解决这些问题！

📖 什么是 ThreeSDK？

ThreeSDK 是一个基于 Three.js 的轻量级封装库，旨在简化 3D 场景开发流程。通过封装常用的 Three.js 功能，让开发者能够用更少的代码、更快的速度构建出功能丰富的 3D 应用。

当前版本： v1.0.9
NPM 包名： easy-threesdk
仓库地址： Gitee

✨ 核心优势

🚀 开箱即用，快速上手

传统 Three.js 开发需要手动配置场景、相机、渲染器、控制器、灯光等，代码冗长且容易出错。ThreeSDK 提供一键初始化，只需几行代码即可完成基础场景搭建：

javascript 复制代码

const threeSdk = new ThreeSdk(container);
threeSdk.init(
  { position: new THREE.Vector3(0, 15, 20) },
  { minDistance: 10, maxDistance: 500 },
  { ambientLightIntensity: 0.8 }
);

🎮 丰富的交互模式

内置三种视角控制模式，满足不同场景需求：

轨道控制器模式：经典的旋转、缩放、平移操作
第一人称模式：固定位置，适合全景查看
漫游模式：游戏式操作（WASD移动 + 鼠标拖拽），支持地面点击跳转

🏷️ 强大的标签系统

支持 2D/3D 两种标签类型，三种标签样式：

2D 标签：始终面向相机，可绑定到模型，跟随模型移动
3D 标签：具有透视效果，适合固定在场景中
标签样式：箭头标签、指示器标签、可展开标签

🎨 模型交互与特效

模型加载：支持 GLTF 格式，可选 Draco 压缩
交互管理：点击、悬停事件监听，自动高亮效果
辉光效果：模型轮廓辉光，提升视觉体验
变换控制：内置 TransformControls，支持平移、旋转、缩放

🌊 丰富的特效系统

水面材质：两种预设水面效果，自动天空盒和光照系统
波纹扩散：雷达扫描式波纹效果，可自定义参数
玻璃材质：HDR 环境贴图和实时镜面反射两种方式

🔌 插件化架构

采用插件化设计，功能模块化，易于扩展和维护。目前内置两个核心插件：

LabelControl：标签系统管理
ModelControl：模型加载与交互管理

🎯 适用场景

ThreeSDK 特别适合以下应用场景：

1. 3D 可视化项目

建筑展示、室内设计预览
产品 3D 展示、电商展示
数据可视化大屏

2. 虚拟漫游系统

虚拟展厅、虚拟博物馆
虚拟园区、智慧城市
全景漫游应用

3. 教育培训

3D 教学演示
虚拟实验环境
交互式学习系统

4. 游戏与娱乐

轻量级 3D 小游戏
互动展示应用
虚拟场景体验

5. 特效场景

水面、海洋场景渲染
玻璃材质、镜面反射效果
动态波纹、能量扩散动画

💡 核心功能详解

1. 场景基础建设

自动化初始化

一键创建 Scene、Camera、Renderer、OrbitControls
自动配置灯光系统（环境光、方向光、边缘光）
响应式适配，自动处理窗口大小变化

背景系统

支持全景球体背景（单张等距柱状投影图）
支持立方体贴图背景（六面体纹理）

2. 摄像机与视角控制

三种视角模式

javascript 复制代码

// 轨道控制器模式（默认）
// 无需额外操作，初始化后即可使用

// 第一人称模式
threeSdk.enterFirstPersonMode();
// 相机固定位置，只能旋转查看

// 漫游模式
threeSdk.enterRoamMode();
// WASD/方向键移动，鼠标拖拽旋转，双击地面跳转

视角动画

javascript 复制代码

// 平滑飞行到指定视角
await threeSdk.flyTo({
  position: new THREE.Vector3(10, 20, 30),
  target: new THREE.Vector3(0, 0, 0)
}, { duration: 2000 });

3. 标签系统

2D 标签（推荐用于模型标注）

javascript 复制代码

const labelControl = threeSdk._PluginsManager.get("LabelControl");

// 创建绑定到模型的 2D 标签
labelControl.createArrow2DLabel(
  "modelLabel",
  { template: "<div>模型名称</div>", data: {} },
  new THREE.Vector3(0, 5, 0), // 相对于模型中心的偏移
  {
    size: 0.02,
    model: model, // 绑定到模型，标签会跟随模型移动
  }
);

3D 标签（适合固定场景标注）

javascript 复制代码

// 箭头标签
labelControl.createArrow3DLabel(
  "ArrowLabel",
  { template: "<div>箭头标签</div>", data: {} },
  new THREE.Vector3(0, 5, 0),
  { size: 0.02 }
);

// 指示器标签（带折线指示器）
labelControl.createIndicator3DLabel(
  "IndicatorLabel",
  { template: "<div>指示器标签</div>", data: {} },
  new THREE.Vector3(5, 5, 0),
  { size: 0.02 }
);

// 可展开标签
labelControl.createExpand3DLabel(
  "ExpandLabel",
  {
    template: "<div>点击展开</div>",
    expandContentHtml: "<div>展开的内容</div>",
    data: {},
  },
  new THREE.Vector3(-5, 5, 0),
  { size: 0.02 }
);

4. 模型加载与交互

模型加载

javascript 复制代码

const modelControl = threeSdk._PluginsManager.get("ModelControl");

// 加载 GLTF 模型
const model = await modelControl.loadGLTFBuilding(
  {
    ModelID: "myModel",
    modelPath: "./models/model.gltf",
    position: [0, 0], // [x, z] 坐标
    scale: 1,
    clickable: true,
    openDraco: false, // 是否启用 Draco 压缩
  },
  (percent) => {
    console.log(`加载进度: ${percent}%`);
  }
);

模型交互

javascript 复制代码

// 点击事件监听
modelControl.onModelClickListener((object) => {
  if (object) {
    console.log("点击了模型:", object);
  }
});

// 悬停事件监听（自动高亮）
modelControl.onModelMouseMoveListener((object) => {
  if (object) {
    console.log("悬停在模型上");
  }
});

模型辉光效果

javascript 复制代码

// 启用辉光系统
modelControl.enableModelOutlinePass(0x00ffff); // 青色辉光

// 切换模型的辉光效果
modelControl.onModelClickListener((object) => {
  if (object) {
    modelControl.switchModelOutlinePass(object);
  }
});

5. 特效加载器（Loader）

ThreeSDK 提供了丰富的特效加载器，让场景更加生动真实。

5.1 水面材质（WaterMaterial）

创建逼真的水面效果，支持动态波纹、反射和天空环境。

javascript 复制代码

import { createWater1Loader, createWater2Loader } from './loader/WaterMaterial/index.js';

// 方式一：创建深蓝色水面（适合海洋、湖泊）
const water1 = createWater1Loader(threeSdk.scene, threeSdk.renderer);
// 特点：深蓝色（#187da0），波纹扭曲度 10，适合大场景

// 方式二：创建浅蓝色水面（适合游泳池、浅水区）
const water2 = createWater2Loader(threeSdk.scene, threeSdk.renderer);
// 特点：浅蓝色（#88d2f1），波纹扭曲度 3.7，更细腻

// 水面会自动添加：
// - 天空盒（Sky）环境
// - 太阳光照系统
// - 动态波纹动画
// - 环境反射效果

水面特性：

✨ 动态波纹动画，实时更新
🌅 自动生成天空盒环境
☀️ 可配置太阳位置和光照参数
🌊 支持大气散射效果（浑浊度、瑞利散射、米氏散射）
💧 真实的水面反射和折射效果

5.2 波纹扩散效果（RippleEffect）

创建雷达扫描式的波纹扩散效果，适合用于标记、定位、交互反馈等场景。

javascript 复制代码

import { createRippleEffect } from './loader/RippleEffect/index.js';

// 创建波纹效果
const ripple = createRippleEffect({
  ringCount: 3,        // 圆环数量
  radius: 1.0,         // 波纹半径
  color: "#004c99",     // 波纹颜色（深蓝色）
  speed: 0.2,          // 扩散速度
  gradientRange: 0.08   // 渐变范围
});

// 添加到场景
threeSdk.scene.add(ripple);
ripple.position.set(0, 0.01, 0); // 放置在地面上方

应用场景：

📍 地图标记点动画
🎯 点击交互反馈
📡 雷达扫描效果
⚡ 能量扩散动画

可配置参数：

ringCount: 同时显示的圆环数量（1-10）
radius: 波纹的最大半径
color: 波纹颜色（支持十六进制颜色）
speed: 波纹扩散速度
gradientRange: 波纹边缘渐变范围

5.3 玻璃表面效果（WindowSurface）

为模型添加真实的玻璃材质效果，支持 HDR 环境贴图和实时镜面反射。

javascript 复制代码

import { setMeshOfHDREnvironment, setMeshOfMirrorSurface } from './loader/WindowSurface/index.js';

// 方式一：使用 HDR 环境贴图（更真实，性能消耗较大）
// 适合：需要高质量玻璃效果的场景
setMeshOfHDREnvironment(glassMesh, threeSdk.renderer);
// 特点：
// - 使用 MeshPhysicalMaterial 材质
// - 支持透射、折射、反射
// - 可配置玻璃厚度、折射率等物理参数
// - 需要 HDR 环境贴图资源

// 方式二：使用实时镜面反射（性能更好）
// 适合：需要实时反射效果的场景
setMeshOfMirrorSurface(glassMesh, threeSdk.scene, threeSdk.camera, threeSdk.renderer);
// 特点：
// - 使用 CubeCamera 实时生成环境贴图
// - 自动跟随相机位置更新反射
// - 性能开销相对较小
// - 适合动态场景

玻璃材质参数（HDR 方式）：

transmission: 透射率（0-1），控制光线穿透程度
ior: 折射率，普通玻璃约 1.52
roughness: 粗糙度，0.05 为非常光滑的玻璃
thickness: 玻璃厚度，影响透射光衰减
opacity: 不透明度，与透射率配合使用

应用场景：

🏢 建筑窗户、玻璃幕墙
🚗 车辆玻璃
💎 展示柜、玻璃容器
🪟 室内设计中的玻璃元素

🚀 快速开始

安装

bash 复制代码

npm install easy-threesdk

或通过 Gitee 仓库：

bash 复制代码

git clone https://gitee.com/xieqianstudent/visual-learning.git

基础示例

javascript 复制代码

import * as THREE from "three";
import ThreeSdk from "easy-threesdk";
import LabelControl from "easy-threesdk/plugins/LabelControl.js";
import ModelControl from "easy-threesdk/plugins/ModelControl.js";

// 1. 初始化
const container = document.getElementById("canvas-container");
const threeSdk = new ThreeSdk(container);

threeSdk.init(
  {
    position: new THREE.Vector3(0, 15, 20),
    lookAt: new THREE.Vector3(0, 0, 0),
  },
  {
    minDistance: 10,
    maxDistance: 500,
  },
  {
    ambientLightIntensity: 0.8,
  }
);

// 2. 注册插件
threeSdk.plugins([LabelControl, ModelControl]);

// 3. 创建背景
threeSdk.createPanoramaSphere("/path/to/panorama.jpg");

// 4. 加载模型
const modelControl = threeSdk._PluginsManager.get("ModelControl");
const model = await modelControl.loadGLTFBuilding({
  ModelID: "house",
  modelPath: "./models/house.gltf",
  position: [0, 0],
  scale: 1,
  clickable: true,
});

// 5. 添加标签
const labelControl = threeSdk._PluginsManager.get("LabelControl");
labelControl.createArrow2DLabel(
  "houseLabel",
  { template: "<div>我的房子</div>", data: {} },
  new THREE.Vector3(0, 5, 0),
  { size: 0.02, model: model }
);

// 6. 添加特效（可选）
// 创建水面效果
import { createWater2Loader } from './loader/WaterMaterial/index.js';
const water = createWater2Loader(threeSdk.scene, threeSdk.renderer);

// 创建波纹效果
import { createRippleEffect } from './loader/RippleEffect/index.js';
const ripple = createRippleEffect({ ringCount: 3, radius: 1.0 });
threeSdk.scene.add(ripple);

🎁 为什么选择 ThreeSDK？

✅ 开发效率提升

减少 70% 的样板代码：场景初始化、灯光配置、控制器设置等常用功能一键完成
统一的 API 设计：学习成本低，上手快
完善的文档和示例：快速找到解决方案

✅ 功能丰富强大

多种交互模式：满足不同场景需求
灵活的标签系统：2D/3D 标签，多种样式
模型特效支持：辉光、高亮等视觉效果
丰富的特效系统：水面、波纹、玻璃材质等
插件化架构：易于扩展和维护

✅ 性能优化

响应式适配：自动处理窗口大小变化
2D 标签性能优化：CSS2DRenderer 比 CSS3DRenderer 性能更好
场景组管理：方便管理大量对象

✅ 持续更新

版本迭代快速，功能不断完善
社区支持，问题反馈及时
开源免费，可自由使用和修改

📚 更多资源

完整文档：查看项目 README.md 获取详细 API 文档
代码仓库 ：Gitee
NPM 包 ：easy-threesdk

💬 总结

ThreeSDK 是一个专注于简化 Three.js 开发的封装库，通过提供开箱即用的功能和统一的 API，让开发者能够更专注于业务逻辑的实现，而不是重复编写基础代码。

无论你是 Three.js 新手还是经验丰富的开发者，ThreeSDK 都能帮助你更快地构建出功能丰富、交互流畅的 3D 应用。

开始使用 ThreeSDK，让 3D 开发更简单！ 🎉

本文作者：coderxq
如有问题或建议，欢迎在仓库中提交 Issue 或 Pull Request