# base-three

**Repository Path**: happychl/base-three

## Basic Information

- **Project Name**: base-three
- **Description**: three基本封装
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2024-06-04
- **Last Updated**: 2025-01-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# `base-three`

> `threejs`基本封装

## 使用说明

### 安装

```bash
npm install base-three
# OR
yarn add base-three
```

## `BaseThree`

`BaseThree`对`threejs`做了初始化封装，并添加了动画、事件等其他逻辑封装，并在`window`上挂载了`THREE`和`TWEEN`属性。

### 示例

```js
import BaseThree from 'base-three';
// OR
import { BaseThree } from 'base-three';

// 挂载
const threeIns = new BaseThree('#app', {
  // options
});

// 卸载
threeIns.dispose();
```

### 参数

| 参数    | 类型                | 描述                          |
| ------- | ------------------- | ----------------------------- |
| element | String\|HTMLElement | 挂载元素，选择器或者 dom 元素 |
| options | Object              | 配置项                        |

#### `options`

| 属性            | 类型    | 默认值   | 描述               |
| --------------- | ------- | -------- | ------------------ |
| debug           | Boolean | false    | 开启调试           |
| backgroundColor | String  | 0x000000 | 背景色             |
| interactive     | Boolean | false    | 开启交互           |
| css2DRenderer   | Boolean | false    | 开启 CSS2DRenderer |
| css3DRenderer   | Boolean | false    | 开启 CSS3DRenderer |
| camera          | Object  | 见下方   | 相机配置           |
| controls        | Object  | 见下方   | 控制器             |
| stats           | Object  | 见下方   | 监控器             |
| axes            | Object  | 见下方   | 坐标轴             |

##### `camera`

| 属性     | 类型   | 默认值      | 描述     |
| -------- | ------ | ----------- | -------- |
| fov      | Number | 45          | 相机视角 |
| near     | Number | 0.1         | 相机近距 |
| far      | Number | 1000        | 相机远距 |
| position | Number | [0, 10, 15] | 相机位置 |

##### `controls`

| 属性          | 类型    | 默认值 | 描述       |
| ------------- | ------- | ------ | ---------- |
| visible       | Boolean | true   | 开启控制器 |
| enableDamping | Boolean | true   | 启用惯性   |

以及`OrbitControls`的其他参数。

##### `stats`

| 属性    | 类型    | 默认值 | 描述       |
| ------- | ------- | ------ | ---------- |
| visible | Boolean | true   | 开启监控器 |

注意：监控器只在调试模式下显示。

##### `axes`

| 属性    | 类型    | 默认值 | 描述       |
| ------- | ------- | ------ | ---------- |
| visible | Boolean | true   | 开启坐标轴 |
| size    | Number  | 1      | 坐标轴尺寸 |

注意：坐标轴只在调试模式下显示。

### 实例方法

| 名称                        | 返回值 | 备注                           |
| --------------------------- | ------ | ------------------------------ |
| addModel(\<BaseModel>model) |        | 添加模型，挂载模型的动画和事件 |
| dispose                     |        | 销毁实例                       |

注意：模型为`BaseModel`实例，`BaseModel`见下方。

## `BaseModel`

`BaseModel`为模型基类，通过继承使用。该类继承了`tiny-emitter`事件库。

### 示例

```js
import { BaseModel } from 'base-three';

class Model extends BaseModel {
  constructor(options) {
    super();

    this.options = {
      size: 1,
      ...options,
    };

    this.#init();
  }

  #init() {
    // ...

    // 添加3D对象
    const mesh = new THREE.Mesh(geometry, material);
    this.object.add(mesh);

    // 3D对象绑定事件
    this.listen(mesh, 'mousemove', (intersects) => {
      const obj = intersects[0]?.object;
      // ...

      // 自定义事件，tiny-emitter提供支持
      this.emit('model:active', '123');
    });

    // 添加动画
    const tween = new TWEEN.Tween(texture.offset, this.tweenGroup).to({ x: -1 }, 3 * 1000).repeat(Infinity);
    this.tweenList.push(tween);
  }
}

const model = new Model({});
threeIns.scene.add(model.object);
threeIns.addModel(model);
model.start();
```

### 实例属性

| 属性       | 类型        | 描述       |
| ---------- | ----------- | ---------- |
| tweenGroup | TWEEN.Group | 动画分组   |
| tweenList  | Array       | 动画列表   |
| listener   | Object      | 监听事件   |
| object     | THREE.Group | three 分组 |
| disposed   | Boolean     | 是否销毁   |

### 实例方法

| 名称                                                      | 返回值 | 备注                                                   |
| --------------------------------------------------------- | ------ | ------------------------------------------------------ |
| listen(\<Object3D>obj, \<String>name, \<Function>handler) |        | 给 three 3D 对象绑定事件，支持`mousemove`和`click`事件 |
| tick(\<Number>time, \<Number>delta)                       |        | 动画钩子，每帧触发，可更新动画                         |
| start()                                                   |        | 开启动画                                               |
| stop()                                                    |        | 停止动画                                               |
| dispose()                                                 |        | 销毁实例                                               |

## `Label`

`Label`为`html`标签类，使用该功能需在`BaseThree`中开启`CSS2DRenderer`或`CSS3DRenderer`渲染器。

### 示例

```js
import { Label } from 'base-three';

// ...

const label = new Label({
  html: labelEl,
  position: position,
});
scene.add(label);
```

### 参数

| 参数    | 类型   | 描述   |
| ------- | ------ | ------ |
| options | Object | 配置项 |

#### `options`

| 属性         | 类型        | 默认值    | 描述                               |
| ------------ | ----------- | --------- | ---------------------------------- |
| renderer     | String      | 3d        | 渲染器类型，2d、3d                 |
| faceToCamera | Boolean     | true      | 是否始终朝向相机，只在 3d 模式生效 |
| scale        | Number      | 0.05      | 3d 渲染器下的缩放                  |
| position     | Array       | [0, 0, 0] | 标签位置                           |
| html         | HTMLElement | null      | 标签 dom 元素                      |

## `WallGeometry`

`WallGeometry`可根据`path`路径生成墙面几何体。

### 示例

```js
import { WallGeometry } from 'base-three';

const geometry = new WallGeometry({
  path: [
    [0, 0],
    [1, 0],
    [2, 0],
  ],
  height: 1,
});
// ...
const mesh = new THREE.Mesh(geometry, material);
scene.add(mesh);
```

### 参数

| 参数   | 类型   | 描述                                                                       |
| ------ | ------ | -------------------------------------------------------------------------- |
| path   | Array  | 墙面路径，[[0, 0], [1, 0], ...]、[[0, 0, 1], [1, 0, 2], ...]               |
| height | Number | 墙面高度，二维 path 必须设置高度；三维 path 可选，如果设置了将作为基础高度 |

## `ResourceTracker`

`ResourceTracker`用于资源跟踪与销毁。

### 示例

```js
import { ResourceTracker } from 'base-three';

const tracker = new ResourceTracker();

// 添加
tracker.add(mesh);

// 移除
tracker.remove(mesh);

// 销毁
tracker.dispose(mesh);

// 销毁所有
tracker.disposeAll();
```

### 实例方法

| 名称                         | 返回值 | 备注     |
| ---------------------------- | ------ | -------- |
| add(\<Object3D>resource)     |        | 添加     |
| remove(\<Object3D>resource)  |        | 移除     |
| dispose(\<Object3D>resource) |        | 销毁     |
| disposeAll()                 |        | 销毁所有 |

## `utils`

`utils`里提供了一些使用方法。

### 示例

```js
import { loadTexture, assignUVs, getProjection, log } from 'base-three';

// 加载纹理资源，同时设置colorSpace
const texture = loadTexture(url);

// 矫正几何体UV属性值，一般用于shape贴图
assignUVs(geometry);

// 将经纬度转为threejs坐标，参数为分区geojson数据和相对大小（用于控制缩放，默认40）
const projection = getProjection(boundData, baseSize);
const [x, y] = projection([lng, lat]);

// 封装的带标签的console.log
log('test');
```