Web 图形与 3D / 系统课时

OrbitControls 如何限制视角

OrbitControls 如何限制视角

产品展示页如果允许相机任意翻转、无限缩放或随意平移,用户很容易看不到产品主体。本课使用 Three.js 的 OrbitControls 固定观察中心,限制水平与垂直旋转角度、镜头距离和平移权限,并加入阻尼效果,完成一个可直接运行的受限三维浏览场景。

学习目标

  • 理解 OrbitControls 的观察目标、极角、方位角与距离限制。
  • 配置适合产品展示的旋转范围、缩放边界、平移权限和阻尼参数。
  • 运行完整示例,通过鼠标操作和控制台数据验证视角约束。

视角限制如何工作

OrbitControls 通过调整相机位置,让相机围绕 controls.target 指定的观察点运动。用户拖拽时,相机会改变方位角和极角;滚动鼠标滚轮时,透视相机会靠近或远离观察点。

理解以下三个量,才能正确设置限制:

  • 极角(Polar Angle):相机方向与世界坐标正 Y 轴之间的夹角。0° 表示位于观察点正上方,90° 表示与观察点等高,180° 表示正下方。
  • 方位角(Azimuth Angle):相机围绕 Y 轴的水平旋转角度。默认以正 Z 方向为 0°,向正 X 方向旋转为正角度。
  • 距离(Distance):相机到 target 的空间距离,使用场景世界单位,并非镜头到模型表面的距离。

对于一个宽约 1.6、高 2、深 1.2 个世界单位的桌面产品,可以采用下面的限制:

控制属性 设置值 作用
target (0, 1, 0) 围绕产品几何中心观察
minPolarAngle 25° 避免过度俯视
maxPolarAngle 85° 不允许相机转到产品下方
minAzimuthAngle -70° 限制向一侧旋转
maxAzimuthAngle 70° 限制向另一侧旋转
minDistance 3 防止镜头过度贴近
maxDistance 9 防止产品缩得过小
enablePan false 禁止用户平移观察中心
enableDamping true 松开鼠标后平滑减速
dampingFactor 0.08 控制阻尼衰减速度

角度限制的 API 使用弧度,因此代码中需要通过 THREE.MathUtils.degToRad() 转换。极角限制必须位于 0 到 π 之间;方位角区间需要满足控制器的有效范围要求,本例采用对称的 -70° 到 70°。

OrbitControls 观察中心、旋转角度和镜头距离的空间约束

在项目中接入 OrbitControls

下面使用 Vite 和 Three.js 创建一个最小产品展示场景。适用于支持 three/addons/controls/OrbitControls.js 导入路径的现代 Three.js npm 版本。

先在终端创建原生 JavaScript 项目并安装依赖:

bash
npm create vite@latest orbit-limits-demo -- --template vanilla
cd orbit-limits-demo
npm install
npm install three

预期结果:创建 orbit-limits-demo 项目目录,生成 package.json 并安装 Three.js。npm 可能询问是否安装项目初始化工具,按提示确认即可;具体安装日志随环境和版本变化。

将 src/main.js 替换为以下完整代码:

js
import * as THREE from 'three';
import { OrbitControls } from 'three/addons/controls/OrbitControls.js';

const scene = new THREE.Scene();
scene.background = new THREE.Color(0xf5f7f9);

const camera = new THREE.PerspectiveCamera(
  45,
  window.innerWidth / window.innerHeight,
  0.1,
  100
);
camera.position.set(4, 3, 6);

const renderer = new THREE.WebGLRenderer({ antialias: true });
renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));
renderer.setSize(window.innerWidth, window.innerHeight);
document.body.style.margin = '0';
document.body.appendChild(renderer.domElement);

// 用长方体模拟一件放在地面上的展示产品。
const product = new THREE.Mesh(
  new THREE.BoxGeometry(1.6, 2, 1.2),
  new THREE.MeshStandardMaterial({
    color: 0x27a99b,
    roughness: 0.42,
    metalness: 0.25
  })
);
product.position.y = 1;
scene.add(product);

const floor = new THREE.Mesh(
  new THREE.PlaneGeometry(20, 20),
  new THREE.MeshStandardMaterial({ color: 0xe7ebef })
);
floor.rotation.x = -Math.PI / 2;
scene.add(floor);

scene.add(new THREE.HemisphereLight(0xffffff, 0x9fb0bd, 2));
const light = new THREE.DirectionalLight(0xffffff, 2);
light.position.set(4, 8, 5);
scene.add(light);

const controls = new OrbitControls(camera, renderer.domElement);

// 固定观察中心,并把角度限制转换为弧度。
controls.target.set(0, 1, 0);
controls.minPolarAngle = THREE.MathUtils.degToRad(25);
controls.maxPolarAngle = THREE.MathUtils.degToRad(85);
controls.minAzimuthAngle = THREE.MathUtils.degToRad(-70);
controls.maxAzimuthAngle = THREE.MathUtils.degToRad(70);

// 限制透视相机距离,禁止平移并保留旋转与缩放。
controls.minDistance = 3;
controls.maxDistance = 9;
controls.enablePan = false;
controls.enableDamping = true;
controls.dampingFactor = 0.08;
controls.update();

// 交互结束时记录角度和距离,便于检查约束。
controls.addEventListener('end', () => {
  console.log({
    polar: THREE.MathUtils.radToDeg(controls.getPolarAngle()).toFixed(1),
    azimuth: THREE.MathUtils.radToDeg(controls.getAzimuthalAngle()).toFixed(1),
    distance: controls.getDistance().toFixed(2)
  });
});

window.addEventListener('resize', () => {
  camera.aspect = window.innerWidth / window.innerHeight;
  camera.updateProjectionMatrix();
  renderer.setSize(window.innerWidth, window.innerHeight);
});

// 开启阻尼后,每帧都需要更新控制器。
renderer.setAnimationLoop(() => {
  controls.update();
  renderer.render(scene, camera);
});

预期结果:在浏览器中能够看到青绿色长方体产品及浅灰色地面。鼠标左键拖拽可以旋转,滚轮可以缩放,右键拖拽无法平移场景。每次交互结束,开发者工具 Console 会输出包含 polar、azimuth、distance 三个字段的对象,具体数值由当前操作决定。

执行 npm run dev 启动项目,并访问终端显示的本地地址。服务端口可能不同,记为 <PORT>,不要假设所有环境都使用同一端口。

验证旋转、缩放与阻尼

打开浏览器开发者工具 Console,分别进行以下检查:

  1. 水平角度:按住鼠标左键持续向左右拖拽。镜头到达两侧边界后不应继续绕到产品背面。交互结束后,Console 中的 azimuth 应在 -70 到 70 之间。
  2. 垂直角度:上下拖动鼠标。相机不能移动到产品正上方或地面下方,polar 应保持在 25 到 85 之间。
  3. 距离限制:反复滚动滚轮,直到画面不再明显放大或缩小。distance 应保持在 3 到 9 之间,允许显示精度产生的微小舍入差异。
  4. 禁止平移:按住鼠标右键拖动。观察目标仍应固定在产品中心;触控设备上也应检查双指操作不能将目标移走。
  5. 阻尼效果:拖动后松开左键,观察镜头是否逐渐停止。将 dampingFactor 从 0.08 调到 0.2,再次测试,通常会感觉旋转更快停下。

阻尼系数越大,每次更新时衰减越明显;较小的系数通常会保留更长的滑动尾迹。产品精细检查适合较快停下,展厅漫游则可以使用更柔和的阻尼。

如果项目还提供切换产品的按钮,切换产品后应同步更新 controls.target 到新产品的中心。对于已加载的模型,可通过 THREE.Box3().setFromObject(model).getCenter(center) 计算其世界空间包围盒中心,避免相机继续围绕旧产品旋转。

常见视角异常与修正

拖动后视角立刻停住,没有惯性。 检查 enableDamping 是否为 true,以及渲染循环里是否调用 controls.update()。只在初始化阶段调用一次 update(),无法持续处理阻尼衰减。

镜头围绕产品底部旋转。 通常是 target 仍停留在世界原点,而模型中心位于 (0, 1, 0)。应该调整观察目标,而不是不断调用 camera.lookAt() 与控制器争夺相机朝向。

缩放限制没有达到预期。 minDistance 和 maxDistance 限制的是透视相机到目标点的距离,不保证模型永不被裁切。模型尺寸、视场角和相机裁剪面仍需分别检查。如果改用 OrthographicCamera,通常应改用 minZoom、maxZoom 约束缩放。

镜头到达边界后仍然无法看到模型某一侧。 先确认水平范围是否过窄,再检查模型默认朝向。对于需要完整 360° 展示的商品,可以不设置方位角上下限,仅保留极角、距离和禁止平移约束。

禁用了平移但相机仍能穿过其他模型。 OrbitControls 的角度和距离限制不是碰撞检测。复杂展厅需要额外使用射线检测或场景碰撞约束;不能把 minDistance 当作所有障碍物的防穿透机制。

产品单体展示通常可以从本课的 25°~85° 极角、±70° 方位角、3~9 单位距离和 enablePan=false 开始,再根据模型尺寸、默认朝向及实际交互测试调整。属性定义与不同版本支持情况可查阅 OrbitControls 官方文档。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

OrbitControls 如何限制视角

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通