CameraService

Manages the active camera, controls (TrackballControls by default), view presets, and fit-to-view. Keeps the controls bound to whichever camera the viewer currently exposes, even after switching projection.

Access

Registered under the name "camera". No service dependencies.

import { CameraService } from "@optellix/xviewr-sdk";

await viewer.ready();
const camera = viewer.getService<CameraService>("camera");
camera?.setView("iso");
camera?.fitToView();

Public API

Lifecycle

• init(context: ServiceContext): Promise<void>
• destroy(): Promise<void>
• getStatus(): ServiceStatus

Camera and controls

• getCamera(): THREE.Camera
• getControls(): any — the active controls instance. Type depends on the configured viewer.controls.type.
• switchCameraType(type: "perspective" | "orthographic"): void — preserves position and target, rebinds controls.
• initializeControls(type?: ControlsType): Promise<void> — disposes existing controls and creates the requested type. Supported: OrbitControls, ArcballControls, FlyControls, FirstPersonControls, MapControls, TrackballControls, PointerLockControls.
• updateAspect(width: number, height: number): void — call on canvas resize.

Framing

• setView(preset: ViewPreset): void — presets: top, bottom, left, right, front, back, iso.
• fitToView(target?: THREE.Object3D, options?: FitOptions): void — fits to target or the viewer root.
• fitToBox(box: THREE.Box3, options?: FitOptions): { maxSize: number; distance: number }

FitOptions:

• padding?: number — multiplier on computed distance. Default 1.2.
• sceneOrientation?: "current" | "default" — current preserves view direction.

Events

Event	Payload
camera:changed	{ position: THREE.Vector3; target: THREE.Vector3 }

Configuration

Read from viewer.controls.* on the viewer config at init:

• type — controls type (default TrackballControls).
• enableDamping, dampingFactor, enableZoom, enablePan, enableRotate (OrbitControls).
• staticMoving, dynamicDampingFactor, rotateSpeed, zoomSpeed, panSpeed (TrackballControls).
• minDistance, maxDistance, minZoom, maxZoom.
• zoomToCursor, cursorPan (custom TrackballControls).

Example

const camera = viewer.getService<CameraService>("camera");
if (!camera) throw new Error("camera service unavailable");

camera.setView("iso");
camera.fitToView(undefined, { padding: 1.4, sceneOrientation: "current" });

window.addEventListener("resize", () => {
  camera.updateAspect(window.innerWidth, window.innerHeight);
});