# 3d-view-controls 中文文档

规范地址：https://npmcn.com/package/3d-view-controls/

版本：2\.2\.2
npm 元数据更新时间：2022-06-12T14:07:22.220Z
中文译文更新时间：2026-11-05T23:46:28.512Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/3d-view-controls
原文对照：https://npmcn.com/package/3d-view-controls/?lang=original
项目主页：https://github.com/mikolalysenko/3d-view-controls
源码仓库：https://github.com/mikolalysenko/3d-view-controls

## 关键信息（来自 npm 元数据）

- 模块格式：CommonJS
- TypeScript 类型：未声明
- 运行依赖：6 个
- 首次发布：2015-02-18T18:14:47.330Z
- 最新版本发布：2018-01-30T01:05:39.898Z
- 近 30 天下载量：9053（2026-10-04 至 2026-11-02，npm 官方下载统计）
- 已发布版本数：9（近 12 个月 0 个）

## 中文简介

装有钩子的3D相机进行输入处理

## 安装

```sh
npm install 3d-view-controls
```

也可以使用：`pnpm add 3d-view-controls`、`yarn add 3d-view-controls`、`bun add 3d-view-controls`

## README

# 三维视图控制

易于使用带有输入绑定的3D相机.

默认控制 :

| 按钮 | 互动 |
| --- | --- |
| 左侧鼠标 | 旋转 |
| 移动 + 左鼠标 _或者说_ 水平滚动 | 滚动 |
| 右侧鼠标 | 泛语 |
| 中间鼠标 _或者说_ 垂直滚动 | 缩放 |

# 示例

以下是应用程序中如何使用此模块的完整实例:

```javascript
var createCamera = require('3d-view-controls')
var bunny = require('bunny')
var perspective = require('gl-mat4/perspective')
var createMesh = require('gl-simplicial-complex')

var canvas = document.createElement('canvas')
document.body.appendChild(canvas)
window.addEventListener('resize', require('canvas-fit')(canvas))

var gl = canvas.getContext('webgl')

var camera = createCamera(canvas, {
  eye:    [50,0,0],
  center: [0,0,0],
  zoomMax: 500
})

var mesh = createMesh(gl, {
  cells:      bunny.cells,
  positions:  bunny.positions,
  colormap:   'jet'
})

function render() {
  requestAnimationFrame(render)
  if(camera.tick()) {
    gl.viewport(0, 0, canvas.width, canvas.height)
    gl.clear(gl.COLOR_BUFFER_BIT | gl.DEPTH_BUFFER_BIT)
    gl.enable(gl.DEPTH_TEST)
    mesh.draw({
      projection: perspective([], Math.PI/4, canvas.width/canvas.height, 0.01, 1000),
      view: camera.matrix
    })
  }
}
render()
```

[你可以在浏览器里试试看](https://mikolalysenko.github.io/3d-view-controls)。 。 。 .

# 安装

```
npm i 3d-view-controls
```

# API 密码

## 构造器

#### `var camera = require('3d-view-controls')(element[, options])`

创建新的相机对象.

-   `element` 是一个 DOM 节点,该节点上
-   `options` 是具有下列可选属性的对象:
    -   `eye` - 相机在世界坐标中的位置(默认) `[0,0,10]`(中文(简体) )
    -   `center` - 世界坐标中的相机目标(故障) `[0,0,0]`(中文(简体) )
    -   `up` - 相机的上升向量(默认) `[0,1,0]`(中文(简体) )
    -   `mode` - 相机的交互模式(默认) `'orbit'`(中文(简体) )
    -   `delay` - 以毫秒内插表示的延迟相互作用(过失) `16`(中文(简体) )
    -   `rotateSpeed` - 旋转缩放系数(默认) `1`(中文(简体) )
    -   `zoomSpeed` - 缩放系数(默认) `1`(中文(简体) )
    -   `translateSpeed` - 翻译/扩展尺度系数(默认) `1`(中文(简体) )
    -   `flipX` - 旋转的翻转 X 轴( 默认) `false`(中文(简体) )
    -   `flipY` - 旋转的倒转 Y 轴( 默认) `false`(中文(简体) )
    -   `zoomMin` - 最小缩放距离( 默认) `0.01`(中文(简体) )
    -   `zoomMax` - 最大缩放距离( 默认) `Infinity`(中文(简体) )

## 几何属性

请注意,您可以通过分配来更新任何属性 。 例如:

```javascript
camera.eye = [100, 100, 100]

camera.matrix = [
  1, 0, 0, 0,
  0, 1, 0, 0,
  0, 0, 1, 0,
  0, 0, 0, 1]
```

#### `camera.matrix`

4x4矩阵被编码为长度为16个阵列,代表了从世界坐标到取景(相机)坐标的等同变相.

#### `camera.mode`

当前相机的交互模式 。 可能的数值包括:

-   `orbit` - 自由轨道运行模式
-   `turntable` - 表现得像转盘/金巴
-   `matrix` - 人工矩阵控制

#### `camera.eye`

相机在世界坐标中的位置

#### `camera.up`

世界坐标的向量

#### `camera.center`

世界坐标中的相机目标

#### `camera.distance`

欧几利得相距 `eye` 改为 `center`

## 方法

#### `camera.tick()`

更新相机状态。 在每个帧被渲染前调用此来计算相机的当前状态.

**回返** `true` 如果相机状态自上次呼叫以来已经改变 `tick`

#### `camera.lookAt(center, eye, up)`

设置相机中心/ 视/ 上向量以查看固定目标

-   `center` 是相机的新中心/ 目标
-   `eye` 是相机在世界坐标中的位置
-   `up` 是一个向量指向上

#### `camera.rotate(yaw, pitch, roll)`

对相机采用递增旋转

-   `yaw` 是 y 轴的旋转量( 以相机的 xz 平面计)
-   `pitch` 是旋转 x 轴( 在相机的yz平面) 的量
-   `roll` 是围绕前向轴旋转的量(以相机的xy平面计)

#### `camera.pan(dx, dy, dz)`

在相机上应用相对运动, 在视图坐标中移动

-   `dx,dy,dz` 是相机运动向量的组件

#### `camera.translate(dx, dy, dz)`

翻译世界坐标中的相机

-   `dx,dy,dz` 是翻译向量的组件

## 调制参数

#### `camera.distanceLimits`

一个代表 `[lo,hi]` 以缩放距离为界. 请注意: `0 < lo < hi`。 。 。 .

#### `camera.flipX`

控制相机旋转是否沿x轴翻转的旗帜

#### `camera.flipY`

控制相机旋转是否沿Y轴翻转的旗帜

#### `camera.delay`

相机状态插值( ms)的延迟量

#### `camera.rotateSpeed`

相机旋转速度缩放系数

#### `camera.zoomSpeed`

相机缩放速度缩放系数

#### `camera.translateSpeed`

相机翻译速度缩放因子

#### `camera.element`

相机上的DOM元件

# 未来

扩展到支持更多输入类型 :

-   触摸
-   键盘
-   游戏Pad
-   VR吗?

# 许可证

(c) 2015年Mikola Lysenko。 MIT 许可证

## 常见问题

### 3d-view-controls 是什么？

装有钩子的3D相机进行输入处理

### 如何安装 3d-view-controls？

在项目目录运行 npm install 3d-view-controls，或使用 pnpm add / yarn add / bun add。

### 3d-view-controls 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/3d-view-controls 是否存在。

### 3d-view-controls 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### 3d-view-controls 可以商用吗？

3d-view-controls 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### 3d-view-controls 的下载量有多少？

根据 npm 官方下载统计，3d-view-controls 在 2026/10/04 – 2026/11/02 这 30 天内被下载 9,053 次，日均约 302 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### 3d-view-controls 还在维护吗？

最新版本 2\.2\.2 发布于 2018/01/30（8 年前）；至今共发布 9 个版本，其中过去 12 个月发布了 0 个；首次发布于 2015/02/19。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。