目标

• 了解轨道控制器（OrbitControls与TrackballControls）
• 开始使用轨道控制器OrbitControls（TrackballControls只介绍其功能，不实现其功能）

轨道控制器（OrbitControls）介绍

基本功能

OrbitControls 是 Three.js 库中提供的一个控制器组件，主要用于实现三维场景的交互式观察功能。它允许用户通过鼠标或触摸屏控制相机在3D场景中的位置和视角，从而实现对场景的自由探索。

主要特点

• 旋转控制：用户可以通过拖拽鼠标左键（或单指触摸）来旋转相机，围绕场景中心点进行360度全方位观察。
• 缩放控制：通过鼠标滚轮（或双指捏合）可以放大或缩小场景，改变相机与目标点之间的距离。
• 平移控制：按住鼠标右键（或双指拖动）可以平移整个场景，改变观察的中心位置。
• 阻尼效果：控制器内置了平滑的阻尼效果，使操作更加自然，不会突然停止。
• 限制范围：可以设置旋转角度、缩放距离和平移范围的限制，防止相机移动到不合理的位置。

适用场景

3D 场景导航、模型查看、交互式演示

实现及演示过程

• 引入 OrbitControls 模块
• 初始化控制器并与相机、渲染器绑定

// 轨道控制
import { OrbitControls } from 'three/addons/controls/OrbitControls.js'

// 轨道控制器
let controls: OrbitControls

// 添加控制器
function initControls() {
  controls = new OrbitControls(camera, canvasThree.value)
}

阻尼效果

// 阻尼
controls.enableDamping = true // 开启阻尼效果
controls.dampingFactor = 0.05 // 停下来的速度，设置的越小，效果越明显

在我们用鼠标去旋转物体时，当我们松开鼠标，物体会缓慢的停下来，如下图所示：

旋转

controls.autoRotate = true // 开启自动旋转
controls.autoRotateSpeed = 0.5 // 设置旋转速度

这里我们开启自动旋转的效果，是绕y轴的旋转，如下图，另外，我们按住鼠标左键上下移动鼠标，可以实现绕x轴的旋转；至于绕z轴的旋转，可以通过其他的方式实现。

平移

// controls.enablePan = false
// controls.panSpeed = 0.05

平移是默认开启的，我们按住鼠标右键就可以拖动，效果如下，当然，也可使用上面代码去禁止拖动

缩放

// controls.enableZoom = false
// controls.zoomSpeed = 0.05

默认开启
我们可以根据上面代码进行关闭，这里效果就略了，就是使用鼠标滚轮来进行缩放。

控制范围

  // 范围
  // 缩放范围
  controls.minDistance = 1
  controls.maxDistance = 100

  // 角度范围（垂直角度：x轴）—— 极角（Polar angle）：绕X轴旋转（上下移动视角）
  controls.maxPolarAngle = Math.PI / 2
  controls.minPolarAngle = 0

  // 角度范围（水平角度：y轴）—— 方位角（Azimuth angle）：绕Y轴旋转（左右移动视角）
  controls.maxAzimuthAngle = Math.PI
  controls.minAzimuthAngle = -Math.PI

• 通过以上代码对范围进行控制
• 1.缩放范围的控制到1-100，到一定程度就不能再缩放了，这个没有默认，但是有设置的必要。
• 2.角度范围，上面分别给出了绕x轴与绕y轴的旋转角度范围，设置之后，也是会控制到一定范围，不可以继续旋转。

完整代码

在完整代码中，除了实现上述的效果代码，另外，可以开启绕z轴的自动旋转，自己参考：

<script setup lang="ts">
import type { GLTF } from 'three/addons/loaders/GLTFLoader.js'
import * as THREE from 'three'

// 轨道控制
import { OrbitControls } from 'three/addons/controls/OrbitControls.js'

// RoomEnvironment用于创建一个室内环境，通常用来为3D场景提供基础的环境光照和反射效果，让3D模型在场景中看起来更加真实自然。
import { RoomEnvironment } from 'three/addons/environments/RoomEnvironment.js'
// DRACOLoader是一个用于加载和解码Google Draco压缩格式3D模型的加载器，可以减小3D模型文件大小，提高加载效率。
import { DRACOLoader } from 'three/addons/loaders/DRACOLoader.js'
// GLTFLoader用于加载GLTF格式的3D模型文件，这是Three.js的一个扩展加载器。
import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js'

// 该组件用于在3D场景中提供变换控制功能（如移动、旋转、缩放），允许用户通过可视化控件直接操作3D对象。
import { TransformControls } from 'three/examples/jsm/controls/TransformControls.js'

import { onMounted, ref } from 'vue'

const canvasThree = ref()

// 创建scene、camera、renderer
let scene: THREE.Scene, camera: THREE.PerspectiveCamera, renderer: THREE.WebGLRenderer, model: THREE.Group

let transformControls: TransformControls
// 添加Z轴旋转变量
const autoRotateZ = false
const rotationSpeedZ = 0.01

// 轨道控制器
let controls: OrbitControls
// 动画混合器
let mixer: THREE.AnimationMixer

// 添加控制器
function initControls() {
  controls = new OrbitControls(camera, canvasThree.value)
  // 阻尼
  controls.enableDamping = true
  controls.dampingFactor = 0.05

  // 旋转
  // 自动旋转（绕y轴）
  // controls.autoRotate = true
  // controls.autoRotateSpeed = 0.5

  // z轴旋转使用TransformControls或自定义控制逻辑来实现绕Z轴旋转。

  // 平移
  // controls.enablePan = false
  // controls.panSpeed = 0.05

  // 缩放
  // controls.enableZoom = false
  // controls.zoomSpeed = 0.05

  // 范围
  // 缩放范围
  controls.minDistance = 1
  controls.maxDistance = 100

  // 角度范围（垂直角度：x轴）—— 极角（Polar angle）：绕X轴旋转（上下移动视角）
  controls.maxPolarAngle = Math.PI / 2
  controls.minPolarAngle = 0

  // 角度范围（水平角度：y轴）—— 方位角（Azimuth angle）：绕Y轴旋转（左右移动视角）
  controls.maxAzimuthAngle = Math.PI
  controls.minAzimuthAngle = -Math.PI
}

// 1.创建场景
function initScene() {
  scene = new THREE.Scene()
}

// 2.创建相机
function initCamera() {
  camera = new THREE.PerspectiveCamera(
    75,
    window.innerWidth / window.innerHeight,
    0.1,
    1000,
  )
  camera.position.set(0, 0, 10)
  scene.add(camera)
}

// 3.创建物体(几何体 + 材质 = 物体)
// function initCube() {
//   const boxWidth = 1
//   const boxHeight = 1
//   const boxDepth = 1
//   const geometry = new THREE.BoxGeometry(boxWidth, boxHeight, boxDepth)

//   const material = new THREE.MeshBasicMaterial({ color: 0x44AA88 })

//   cube = new THREE.Mesh(geometry, material)

//   scene.add(cube)
// }

// 添加模型
function initModel() {
  const loader = new GLTFLoader()
  loader.setDRACOLoader(new DRACOLoader().setDecoderPath('../jsm/'))
  loader.load('../models/gltf/LittlestTokyo.glb', setModel, undefined, (e) => {
    console.error(e)
  })

  // 初始化模型
  function setModel(gltf: GLTF) {
    model = gltf.scene
    model.position.set(2, 1, 0)
    model.scale.set(0.02, 0.02, 0.02)
    scene.add(model)

    initMixer(gltf)

    // 将TransformControls附加到模型上，这样你就可以手动操作它了
    if (transformControls) {
      transformControls.attach(model)
    }
  }

  // 初始化动画混合器
  function initMixer(gltf: GLTF) {
    mixer = new THREE.AnimationMixer(gltf.scene) // 创建动画混合器播放模型动画
    if (gltf.animations[0]) {
      mixer.clipAction(gltf.animations[0]).play()
    }
  }
}

// 添加环境
function initEenvironment() {
  scene.environment = new THREE.PMREMGenerator(renderer).fromScene(new RoomEnvironment(), 0.04).texture
}

function initTransformControls() {
  transformControls = new TransformControls(camera, renderer.domElement)

  // Attach to an object to control it
  // transformControls.attach(objectToControl);

  // Switch between modes
  transformControls.mode = 'translate' // or 'rotate' or 'scale'

  scene.add(transformControls as unknown as THREE.Object3D)

  // Listen for changes and disable orbit controls while transforming
  transformControls.addEventListener('dragging-changed', (event) => {
    controls.enabled = !event.value
  })

  // 添加键盘控制来切换模式
  window.addEventListener('keydown', (event) => {
    switch (event.key) {
      case 't': // Translate mode
        transformControls.mode = 'translate'
        break
      case 'r': // Rotate mode
        transformControls.mode = 'rotate'
        break
      case 's': // Scale mode
        transformControls.mode = 'scale'
        break
    }
  })
}

// 4.渲染场景
function initRenderer() {
  // 创建渲染器
  renderer = new THREE.WebGLRenderer({ antialias: true, canvas: canvasThree.value })

  // 设置渲染器尺寸
  renderer.setSize(window.innerWidth, window.innerHeight)
}

const clock = new THREE.Clock()
// 5.动画循环渲染场景
function animate() {
  requestAnimationFrame(animate)

  mixer && mixer.update(clock.getDelta()) // 更新3D模型的动画
  controls.update()

  // 如果启用了自动绕Z轴旋转
  if (autoRotateZ && model) {
    model.rotation.z += rotationSpeedZ
  }

  // 渲染场景
  renderer.render(scene, camera)
}

onMounted(() => {
  // 初始化场景、相机、渲染器、物体
  initScene()
  initCamera()
  initRenderer()
  initControls()
  initTransformControls
  initModel()
  initEenvironment()

  // 启动动画循环
  animate()
})
</script>

<template>
  <canvas id="canvasThree" ref="canvasThree" />
</template>

TrackballControls 介绍（与OrbitControls的差异）

• TrackballControls 也是 Three.js 中常用的控制器之一，主要用于实现三维场景的交互控制。以下是与 OrbitControls 的详细对比：

控制方式差异

• TrackballControls：允许摄像机自由旋转，不受"上下"方向的限制，可以全方位旋转
• OrbitControls：模拟轨道运动，保持固定的上下方向（类似地球绕太阳旋转）

使用场景

• TrackballControls 更适合：
  • 需要完全自由旋转的3D展示（如产品全方位展示）
  • 科学可视化应用中需要任意角度观察数据
  • 3D建模工具中的自由视角查看
• OrbitControls 更适合：
  • 建筑可视化中的固定视角浏览
  • 地图类应用的有限角度查看
  • 需要保持"地面在下"的常规3D场景

技术特性

• TrackballControls 提供：
  • 动态阻尼效果（可配置阻尼系数）
  • 可调节的旋转速度（通过设置rotateSpeed参数）
  • 缩放限制控制（minDistance/maxDistance）
  • 平移限制控制（maxDistance）
• OrbitControls 提供：
  • 自动水平面保持
  • 明确的旋转范围限制
  • 更简单的API配置

性能表现

• TrackballControls 计算量稍大，因为需要处理更复杂的旋转逻辑
• OrbitControls 性能略优，适合性能敏感场景

代码配置示例

// TrackballControls 配置
controls = new THREE.TrackballControls(camera, renderer.domElement);
controls.rotateSpeed = 2.0;
controls.zoomSpeed = 1.2;
controls.panSpeed = 0.8;
controls.noZoom = false;
controls.noPan = false;
controls.staticMoving = true;
controls.dynamicDampingFactor = 0.3;

// OrbitControls 配置
controls = new THREE.OrbitControls(camera, renderer.domElement);
controls.enableDamping = true;
controls.dampingFactor = 0.05;
controls.screenSpacePanning = false;
controls.minDistance = 1;
controls.maxDistance = 1000;
controls.maxPolarAngle = Math.PI;

选择建议

• 当需要完全自由的3D观察体验时选择TrackballControls
• 当需要保持常规视角和简单控制时选择OrbitControls
• 在移动设备上，OrbitControls通常能提供更好的用户体验TrackballControls 比较
• PointerLockControls 适用场景
• 自定义控制器开发思路