3dsdk

3D SDK

一个基于 three.js 的轻量渲染与模型加载工具集，提供渲染循环、相机/轨道控制、环境贴图、事件拾取、以及高效的 GLB/DRACO 模型加载与克隆缓存。

• 核心类: Render, Model
• 渲染特性: 轨道控制、自动环境、环境光、坐标轴辅助、视图辅助、窗口自适应、渐进更新
• 模型能力: GLB 加载、DRACO 解码、缓存/克隆、统一变换、自动补光、批量移除、尺寸/姿态查询
• 交互事件: click/dblclick/contextmenu 基于射线拾取

安装

pnpm add three@0.164.1 @tweenjs/tween.js@23.1.2  uuid 3d_sdk
# 或者
npm i three@0.164.1 @tweenjs/tween.js@23.1.2  uuid 3d_sdk 
# 或者
yarn add three@0.164.1 @tweenjs/tween.js@23.1.2  uuid 3d_sdk  

浏览器直接使用（UMD）：

<script src="/dist/3d_sdk.umd.cjs"></script>

快速开始

HTML 容器：

<div id="app" style="width:100%;height:100%;position:relative"></div>

TypeScript/JavaScript：

import * as THREE from 'three'
import { Render, Model } from '3d_sdk'

class MyRender extends Render { containerId = 'app' }

const render = new MyRender({
  enableAntialias: true,
  enableAutoEnvironment: true,
  enableAmbientLight: true,
  enableViewHelper: true,
  enableAxesHelper: true,
  enableResize: true,
})

render.render()

const model = new Model(render.getScene(), '/public/test/')

// 加载并自动加入场景
model.add('room', {
  name: 'room',
  position: new THREE.Vector3(0, 0, 0),
  scale: new THREE.Vector3(1, 1, 1),
  event: true,
  click: ({ point }) => console.log('clicked at', point),
})

// 校准相机到目标点
render.calibrationCamera(new THREE.Vector3(0, 2.5, 6), {
  perspective: 'top',
  center: true,
})

API 概览

Render

抽象渲染基类，需继承并提供 containerId（容器元素的 id）。

• 构造：new (options?: RenderOptions)
• 主要方法：
  • render(options?): 初始化渲染上下文、相机、控制器、环境与循环
  • update()：每帧回调（可在子类中覆写）
  • getScene() / getRenderer() / getCamera() / getControls() / getOptions()
  • updateOptions(partial: Partial<RenderOptions>)
  • calibrationCamera(modelWorldPos: THREE.Vector3, options?): 依据模型尺寸/视角定位相机

RenderOptions：

interface RenderOptions {
  enableAutoRotate?: boolean
  enableAlpha?: boolean
  enableEvent?: boolean
  enableAntialias?: boolean
  enableAxesHelper?: boolean
  enableViewHelper?: boolean
  enableCss3_3d?: boolean
  enableCss3_2d?: boolean
  enableResize?: boolean
  enableTurnOver?: boolean
  enableAutoEnvironment?: boolean
  enableAmbientLight?: boolean
  environmentIntensity?: number
  resizeTime?: number
}

• enableAutoEnvironment: 加载 HDR 作为环境
• enableEvent: 开启交互事件拾取（配合 Model 的 event 和回调）

calibrationCamera 选项：

{
  center?: boolean
  room?: boolean // 预留：房间特殊处理
  modelSize?: THREE.Vector3
  distanceMultiplier?: number
  perspective?: 'top'|'bottom'|'left'|'right'|'front'|'back'
  animation?: boolean // 预留：动画
}

Model

面向 GLB 的模型加载器，封装缓存克隆、统一变换与事件绑定。

• 构造：new Model(scene: THREE.Scene, baseUrl = '/public/')
• 方法：
  • add(name: string, config?): Promise<ModelItem>：加载 baseUrl+name.glb，缓存原始场景，克隆入场
  • update(name: string, config?): Promise<ModelItem>：若在场则更新，否则等价于 add
  • remove(name: string): 从场景移除并释放几何/材质
  • removeAll() / removeCache(name) / removeCacheAll()
  • getSize(name) / getPosition(name) / getRotation(name) / getScale(name) / getModel(name)

ModelConfig（部分）：

interface ModelConfig {
  position?: THREE.Vector3
  rotation?: THREE.Euler
  scale?: THREE.Vector3
  name?: string
  onProgress?: (xhr: ProgressEvent) => void
  autoLinght?: number // 自动补光强度（>=1 开启）
  modelType?: 'css_3d'|'css_2d'|'webgl'
  autoAdd?: boolean // true 时 add() 内部自动加入场景
  [key: string]: unknown
}

• 当 event: true 时，可在配置中同时传入 click/dblclick/contextmenu 回调作为 userData 字段
• autoLinght 将在模型根节点添加点光/环境光/方向光组合

ModelItem：内部是 THREE.Group 的克隆，userData 会合并配置并包含 modelScene 指向克隆根。

事件系统

启用方式：在 Render 传入 { enableEvent: true } 或 render({ enableEvent: true })。事件通过 ThreeEvent 基于射线拾取触发：

• 在 Model.add() 的 config 中设置 event: true，并提供回调：click、dblclick、contextmenu
• 回调签名：(e: { point: Vector3; intersect: Object3D }) => void

示例：

model.add('room', {
  name: 'room',
  event: true,
  click: ({ point, intersect }) => {
    console.log(point, intersect)
  },
})

进阶示例

• 加载缓存复用（第二次同名 add 无网络请求，直接克隆原始缓存）：

await model.add('room', { name: 'room-1', position: new THREE.Vector3(0,0,0) })
await model.add('room', { name: 'room-2', position: new THREE.Vector3(2,0,0) })

• 查询尺寸并自动校准相机：

const size = model.getSize('room')
render.calibrationCamera(new THREE.Vector3(0, 0, 0), {
  modelSize: size,
  perspective: 'front',
  center: true,
  distanceMultiplier: 2,
})

• 移除与清理：

model.remove('room')
model.removeAll()
model.removeCache('room')
model.removeCacheAll()

常见问题

• HDR 环境不生效：检查 enableAutoEnvironment 与 lightroom_14b.hdr 路径。
• 事件无响应：需启用 enableEvent，模型配置 event: true，并提供对应回调。

许可证

MIT