OrbitControls
Quick answer
OrbitControls rotates, pans, and zooms a camera around a target point, providing the standard mouse and touch navigation for 3D scenes. It ships in three/addons, so import it separately, and call update() every frame when enableDamping is true. Limit minDistance, maxDistance, and maxPolarAngle to keep the camera above ground.
import { OrbitControls } from 'three/addons/controls/OrbitControls.js'
Key points
- target is the orbit center; moving it re-centers rotation and zoom.
- maxPolarAngle set near Math.PI/2 prevents the camera from going below the ground.
- screenSpacePanning false pans along the ground plane, matching map conventions.
Example
const controls = new OrbitControls(camera, renderer.domElement);
controls.target.set(80, 12, -20);
controls.enableDamping = true;
controls.dampingFactor = 0.08;
controls.minDistance = 20;
controls.maxDistance = 600;
controls.maxPolarAngle = Math.PI * 0.495; // 禁止钻到地面以下
controls.screenSpacePanning = false; // 沿地面平移，符合地图操作习惯
controls.update();
renderer.setAnimationLoop(function () {
controls.update(); // 阻尼需要每帧调用
renderer.render(scene, camera);
});Notes
- With damping enabled, skipping controls.update() in the loop makes input feel frozen.
- Replacing the camera requires a new OrbitControls; dispose() the old one to drop listeners.
English edition written for Atlaslog. Code is taken from the original Chinese page and runs unchanged.
Atlaslog (2026). OrbitControls. https://www.jingweizhi.com/en/three/api/orbit-controls.html (accessed 2026-11-03).