<sk-camera-orbit-control>

← prev index next →

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.

JavaScript API: CameraOrbitControl

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.

Serve these docs to run the live example. WebGPU needs a secure context — open this page via grunt serve rather than double-clicking the file. The Markup tab works from disk.

Attributes

AttributeTypeDefaultDescription
id <id> — The element's unique identifier — the standard HTML global id attribute.
fit-targets <fit-targets> (auto | none | <id-ref-list> | <id-ref-list>) "none" Nodes whose bounds drive an auto-fit: 'auto', 'none', or id list.
fit-margin <number> 0 Padding fraction applied around fitted bounds.
freeze-on-fit <boolean> true Stop the fit observer after the first frame with real bounds.
azimuthanimatable <angle> 0 Initial/horizontal orbit angle (radians); animatable.
elevationanimatable <angle> 0 Initial/vertical orbit angle (radians); animatable.
radiusanimatable <number> 10 Orbit radius (distance from pivot); animatable.
orient-toward-pivot <boolean> false When true, the camera faces the pivot.
orientation-axis <orientation-axis> ("+x" | "-x" | "+y" | "-y" | "+z" | "-z") "-z" Optional orientation axis for orientTowardPivot.
pivot <id-ref> — The point the camera orbits around, as an element id reference (#id),
pan-x <length> — Post-fit horizontal pan (CSS length string), or null.
pan-y <length> — Post-fit vertical pan (CSS length string), or null.
zoom-factor <number> 1 Post-fit zoom multiplier (1 = no change).
orbit-sensitivity <number> 0.005 Sensitivity for orbit drag operations (radians per unit delta). Default: 0.005
pan-sensitivity <number> 0.01 Sensitivity for pan drag operations (world units per unit delta). Default: 0.01
zoom-sensitivity <number> 0.005 Sensitivity for zoom drag operations (scale factor per unit delta). Default: 0.005
min-zoom <number> 1 Minimum zoom level (orthographic height or perspective distance). Default: 1
max-zoom <number> 500 Maximum zoom level (orthographic height or perspective distance). Default: 500

Used in guides: Scene basics

↑ Documentation home · ← All elements