CameraOrbitControl

Turns the camera into an interactive turntable — orbit, pan, zoom, and auto-fit around a pivot — so you frame a scene without hand-placing the camera.

Declarative element: <sk-camera-orbit-control>

Global: available as sk.CameraOrbitControl inside a scene <script>.

Remarks

This is the camera-control companion to the AbstractCamera family: rather than a camera itself, it takes over aiming one. Presence of a camera-orbit-control alongside the camera opts the scene into interactive orbit / pan / zoom plus an optional auto-fit that frames the scene for you — the easy way to get a good shot, since a bare camera has to be positioned and rotated by hand.

Key attributes. The pose is azimuth (turn around the pivot), elevation (height above it), and radius (distance from it) — all animatable, so an animation can sweep the camera on a turntable. fit-targets / fit-margin turn on the auto-fit that keeps the subject framed, and orient-toward-pivot keeps the camera aimed at the pivot as it moves. Reflection and animation are handled by the shared SkenraAnimatable machinery, and orbit-pose writes drive the camera through the underlying Orbit node; the fit-backed properties re-arm the auto-fit at runtime.

Lifecycle: The browser upgrade path constructs the element with NO arguments, so it must be valid uninitialized — it has no camera until attachCamera binds one (the declarative scene bootstrap or an imperative caller). The canonical Orbit node is created lazily on connect (so an animation always has a real animatable to target) and survives camera detach/re-attach, preserving its identity and pose subscription.

Animation: an animation on this control is redirected onto the canonical Orbit (see _resolveAnimationEffectTarget), the true animatable owning azimuth / elevation / radius. Fit-backed properties (fitTargets, fitMargin, freezeOnFit, pivot, panX, panY, zoomFactor) are live and scriptable but NOT animatable.

Interactive input composes with animation. Orbit drag, zoom, and inertia contribute a persistent additive offset through the same effect stack the animation uses (see CameraOrbitUserOffset), so you can grab and orbit the camera while a turntable animation is playing and the gesture simply shifts the framing — the animation keeps running underneath without a frame-to-frame fight. Because the gesture is a separate effect layer, a drag does NOT rewrite the authored azimuth / elevation / radius attributes; the authored pose stays the base the animation and the offset compose onto. resetView and setViewDirection clear the accumulated offset.

This class owns the orbit setup/lifecycle, pivot management, zoom/radius state, reset state, pan-direction vector extraction, sensitivity configs, and min/max clamping. It owns NO DOM event listeners and has no knowledge of pointer/wheel/touch events.

Constructor

constructor(config?: { camera?: AbstractCamera; orbitSensitivity?: number; panSensitivity?: number; zoomSensitivity?: number; minZoom?: number; maxZoom?: number; orientationAxis?: '-x' | '+x' | '-y' | '+y' | '-z' | '+z'; pivotNode?: SceneNode; orbitNode?: Orbit })

Inherited from: SkenraAnimatable — see those pages for inherited members.

Properties

Config Properties

Other Properties

Methods

Example

import { CameraOrbitControl } from '/js/skenra/camera/camera-orbit-control.js';

const controller = new CameraOrbitControl({ camera: camera,
    panSensitivity: 0.02
});
controller.radius = 15;   // camera-to-pivot distance

controller.orbit(Math.PI / 4, 0);   // Orbit 45° horizontally
controller.pan(10, 5);              // Pan 10px right, 5px up
controller.zoom(0.5);              // Zoom in by 50%
controller.resetView();           // Reset to initial state
controller.dispose();

Used in guides: Scene basics

↑ Documentation home · ← All classes