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

# 3D SDK

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

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

## 安装

```bash
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）：
```html
<script src="/dist/3d_sdk.umd.cjs"></script>
```

## 快速开始

HTML 容器：
```html
<div id="app" style="width:100%;height:100%;position:relative"></div>
```

TypeScript/JavaScript：
```ts
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：
```ts
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` 选项：
```ts
{
  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`（部分）：
```ts
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`

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

## 进阶示例

- 加载缓存复用（第二次同名 `add` 无网络请求，直接克隆原始缓存）：
```ts
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) })
```

- 查询尺寸并自动校准相机：
```ts
const size = model.getSize('room')
render.calibrationCamera(new THREE.Vector3(0, 0, 0), {
  modelSize: size,
  perspective: 'front',
  center: true,
  distanceMultiplier: 2,
})
```

- 移除与清理：
```ts
model.remove('room')
model.removeAll()
model.removeCache('room')
model.removeCacheAll()
```

## 常见问题

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

## 许可证

MIT