오빗 컨트롤

Orbit controls

드래그로 카메라를 대상 주위로 회전시키고 휠로 줌인·아웃하게 만드는, 3D 뷰어의 가장 기본적인 카메라 조작.

다른 이름: OrbitControlsCamera orbitDamping
···
js
import * as THREE from 'three';
import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
const renderer = new THREE.WebGLRenderer({ antialias: true });
renderer.setPixelRatio(Math.min(devicePixelRatio, 2));
document.body.appendChild(renderer.domElement);
const scene = new THREE.Scene();
scene.background = new THREE.Color(0x0c0c16);
const camera = new THREE.PerspectiveCamera(45, 1, 0.1, 100);
camera.position.set(3.2, 2, 4.2);

scene.add(new THREE.AmbientLight(0x556080, 1.2));
const dLight = new THREE.DirectionalLight(0xffffff, 1.1);
dLight.position.set(4, 6, 3);
scene.add(dLight);

const mesh = new THREE.Mesh(
  new THREE.TorusKnotGeometry(1, 0.3, 140, 20),
  new THREE.MeshStandardMaterial({ color: 0x8f7bff, roughness: 0.35, metalness: 0.3 })
);
scene.add(mesh);

const controls = new OrbitControls(camera, renderer.domElement);
controls.enableDamping = true;
controls.autoRotate = true;
controls.autoRotateSpeed = 1.4;
controls.minDistance = 3;
controls.maxDistance = 9;

function resize() { renderer.setSize(innerWidth, innerHeight); camera.aspect = innerWidth / innerHeight; camera.updateProjectionMatrix(); }
addEventListener('resize', resize); resize();
renderer.setAnimationLoop(() => {
  controls.update();
  renderer.render(scene, camera);
});

OrbitControls(camera, domElement)는 카메라 자체를 대상 지점(target) 주위의 구면 좌표(방위각·고도각·거리)로 다루면서, 포인터 드래그를 그 각도 변화로, 휠을 거리 변화로 변환해줍니다. 매 프레임 controls.update()를 불러줘야 실제로 카메라 위치가 갱신됩니다.

enableDamping을 켜면 손을 놓은 뒤에도 관성처럼 서서히 감속하며 멈춰서 훨씬 부드럽게 느껴집니다. autoRotate + autoRotateSpeed는 사용자가 조작하지 않을 때도 카메라가 스스로 천천히 공전하게 만듭니다 — 이 데모가 카드 미리보기에서도 움직이는 이유입니다. minDistance/maxDistance로 너무 가깝거나 멀리 줌되는 걸 막을 수 있습니다.

내부적으로는 카메라의 position만 바꾸고 회전은 항상 target을 바라보도록 lookAt을 자동 적용하므로, 직접 camera.rotation을 건드릴 필요가 없습니다.

언제 쓰나

제품 3D 뷰어, 모델 프리뷰어처럼 사용자가 대상을 자유롭게 둘러봐야 할 때.