Threejs OrbitControls API

---

构造函数

OrbitControls( object : Camera, domElement : HTMLDOMElement )

• 参数:

• object: （必填）被控制的相机（必须是场景的直接子级）。

• domElement: 用于绑定事件的 HTML 元素（可选）。

---

事件（Events）
• change: 当相机位置/角度变化时触发。

• start: 交互开始时触发（如鼠标按下）。

• end: 交互结束时触发（如鼠标松开）。

---

核心属性（Properties）

属性	类型	描述
.autoRotate	Boolean	是否自动绕目标旋转（默认 false）。需在动画循环中调用 .update()。
.autoRotateSpeed	Float	自动旋转速度（默认 2.0，60fps 下约 30 秒/圈）。
.enableDamping	Boolean	是否启用阻尼惯性效果（默认 false）。启用后需在动画循环中调用 .update()。
.dampingFactor	Float	阻尼系数（默认 0.05）。
.enablePan	Boolean	是否允许平移相机（默认 true）。
.enableRotate	Boolean	是否允许旋转相机（默认 true）。
.enableZoom	Boolean	是否允许缩放（推拉）相机（默认 true）。
.screenSpacePanning	Boolean	平移时是否基于屏幕空间（默认 true）。若为 false，平移方向将与相机上方向正交。
.target	Vector3	控制焦点（相机围绕此点旋转）。
.cursor	Vector3	.minTargetRadius 和 .maxTargetRadius 的限制中心点。

---

限制范围（Limits）

属性	类型	描述
.minDistance / .maxDistance	Float	相机与焦点的最小/最大距离（透视相机 PerspectiveCamera 专用）。
.minZoom / .maxZoom	Float	最小/最大缩放值（正交相机 OrthographicCamera 专用）。
.minAzimuthAngle / .maxAzimuthAngle	Float	水平旋转角度（弧度）的上下限。
.minPolarAngle / .maxPolarAngle	Float	垂直旋转角度（弧度）的上下限（默认垂直范围 0 到 π）。

---

交互速度（Speed）

属性	类型	描述
.panSpeed	Float	平移速度（默认 1）。
.rotateSpeed	Float	旋转速度（默认 1）。
.zoomSpeed	Float	缩放速度（默认 1）。
.keyPanSpeed	Float	键盘平移速度（默认 7.0）。
.keyRotateSpeed	Float	键盘旋转速度（默认 1）。

---

按键绑定（Key Mappings）

// 默认键盘按键
.controls.keys = {
  LEFT: 'ArrowLeft',   // 左箭头
  UP: 'ArrowUp',       // 上箭头
  RIGHT: 'ArrowRight', // 右箭头
  BOTTOM: 'ArrowDown'  // 下箭头
}

// 默认鼠标按键
.controls.mouseButtons = {
  LEFT: THREE.MOUSE.ROTATE,   // 左键旋转
  MIDDLE: THREE.MOUSE.DOLLY,  // 中键推拉
  RIGHT: THREE.MOUSE.PAN      // 右键平移
}

// 默认触摸手势
.controls.touches = {
  ONE: THREE.TOUCH.ROTATE,     // 单指旋转
  TWO: THREE.TOUCH.DOLLY_PAN   // 双指推拉/平移
}

---

方法（Methods）

方法	描述
.update( deltaTime : Number )	更新控制器。启用 autoRotate 或 enableDamping 时，必须在动画循环中调用此方法。deltaTime 参数（秒）用于帧率无关的自动旋转。
.reset()	将控制器状态重置为上一次调用 .saveState() 或初始状态。
.saveState()	保存当前控制器状态（供 .reset() 恢复）。
.getAzimuthalAngle()	获取当前水平旋转角度（弧度）。
.getPolarAngle()	获取当前垂直旋转角度（弧度）。
.getDistance()	获取相机与目标点的距离。
.listenToKeyEvents( domElement )	为指定 DOM 元素绑定键盘事件监听（通常传入 window）。

---

代码示例

// 初始化控制器
const controls = new OrbitControls( camera, renderer.domElement );
controls.enableDamping = true;
controls.dampingFactor = 0.05;

// 动画循环
function animate() {
  requestAnimationFrame( animate );
  controls.update(); // 启用阻尼或自动旋转时必须调用
  renderer.render( scene, camera );
}

---

注意事项

1. 若修改相机位置（如 camera.position.set(...)），需手动调用 controls.update()。
2. 正交相机（OrthographicCamera）的缩放通过 .minZoom 和 .maxZoom 控制。
3. 阻尼（Damping） 功能会带来平滑的惯性效果，但会消耗额外性能。

弧度与角度的转换

// ============
// 弧度转角度
// ============
const convertRadToDeg = (rad:any) => {
    return rad * (180 / Math.PI);
}

// ============
// 角度转弧度
// ============
const convertDegToRad = (deg:any) => {
    return deg * (Math.PI / 180);
}