OrbitControls: вращение, зум, панорамирование

Для работы с OrbitControls необходимо подключить модуль отдельно, так как он не входит в основной пакет three.js:

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

После создания сцены, камеры и рендера создаётся контроллер:

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

Ключевой момент: OrbitControls привязывается к элементу DOM, через который будет происходить взаимодействие с пользователем. Обычно это renderer.domElement.

Вращение сцены

Вращение позволяет осматривать объекты вокруг целевой точки (target), которая по умолчанию находится в начале координат (0, 0, 0):

controls.target.set(0, 1, 0); // смещение центра вращения
controls.update();
  • controls.enableRotate — включение или отключение вращения.
  • controls.rotateSpeed — скорость вращения сцены. Значения >1 ускоряют, <1 замедляют вращение.

Особенности:

  • Вращение происходит вокруг точки controls.target.
  • Поворот с помощью мыши осуществляется за счёт удерживания левой кнопки.
  • Можно ограничить вертикальный угол с помощью controls.maxPolarAngle и controls.minPolarAngle:
controls.minPolarAngle = Math.PI / 4; // минимальный угол от вертикали
controls.maxPolarAngle = Math.PI / 2; // максимум

Это предотвращает переворот камеры под сценой.

Зумирование

Zoom позволяет приближать и удалять камеру относительно целевой точки:

controls.enableZoom = true;
controls.zoomSpeed = 1.2; // чувствительность колёсика мыши

Для перспективной камеры (THREE.PerspectiveCamera) зум реализуется как изменение позиции камеры. Для ортографической (THREE.OrthographicCamera) — изменение масштаба zoom.

Можно ограничить диапазон приближения:

controls.minDistance = 5;
controls.maxDistance = 50;

Это важно для предотвращения пересечения камеры с объектами или слишком большого удаления.

Панорамирование

Панорамирование перемещает камеру параллельно плоскости экрана, сохраняя ориентацию:

controls.enablePan = true;
controls.panSpeed = 0.8;
  • Движение осуществляется правой кнопкой мыши (по умолчанию).
  • Ограничение панорамирования можно реализовать вручную, следя за controls.target. Например:
const panLimit = 10;
controls.target.clamp(
    new THREE.Vector3(-panLimit, -panLimit, -panLimit),
    new THREE.Vector3(panLimit, panLimit, panLimit)
);

Интеграция с анимацией

Для плавного взаимодействия с камерой необходимо вызывать controls.update() на каждом кадре:

function animate() {
    requestAnimationFrame(animate);
    controls.update(); // синхронизация при инерции
    renderer.render(scene, camera);
}
animate();

Если включена инерция (controls.enableDamping = true), нужно настроить коэффициент демпфирования:

controls.enableDamping = true;
controls.dampingFactor = 0.05; // значение от 0 до 1, влияет на "торможение"

Настройка кнопок и поведения

OrbitControls поддерживает различные режимы мыши:

  • controls.mouseButtons.LEFT = THREE.MOUSE.ROTATE — левый крутит.
  • controls.mouseButtons.MIDDLE = THREE.MOUSE.DOLLY — средняя кнопка для зума.
  • controls.mouseButtons.RIGHT = THREE.MOUSE.PAN — правая кнопка для панорамирования.

Можно полностью переназначить действия или отключить ненужные:

controls.enableRotate = false; // отключение вращения
controls.enableZoom = true;    // включение зума
controls.enablePan = true;     // включение панорамирования

Дополнительные возможности

  • Авто-вращение: controls.autoRotate = true; и controls.autoRotateSpeed = 2.0;. Камера вращается без участия пользователя.
  • Ограничение расстояния: controls.minDistance и controls.maxDistance предотвращают выход за пределы сцены.
  • Ограничение углов: minPolarAngle и maxPolarAngle регулируют вертикальное вращение, minAzimuthAngle и maxAzimuthAngle — горизонтальное.

Практические рекомендации

  1. Всегда вызывать controls.update() в анимационном цикле, особенно при включенной инерции.
  2. Настраивать target для удобного вращения вокруг объекта сцены.
  3. Использовать ограничения на дистанцию и углы, чтобы избежать визуальных артефактов.
  4. Для интерактивных сцен с множеством объектов сочетать панорамирование, вращение и зум, сохраняя естественные ограничения, чтобы управление оставалось комфортным.
  5. При работе с мобильными устройствами учитывать touch события, которые поддерживаются OrbitControls автоматически (pinch для зума, one finger drag для вращения).

Эти методы делают OrbitControls универсальным инструментом для интерактивного осмотра 3D-сцен в Three.js, обеспечивая полное управление камерой с гибкой настройкой.

Оглавление