/cesiumjs-camera

name: cesiumjs-camera
description: "CesiumJS camera control - Camera, flyTo, lookAt, setView, ScreenSpaceCameraController, CameraEventAggregator, flight animation. Use when positioning the camera, creating flyTo animations, constraining user navigation, tracking entities, or converting between screen and world coordinates."

CesiumJS Camera & Navigation

> **Baseline:** CesiumJS v1.143 -- ES module imports (`import { ... } from "cesium";`)

Camera Fundamentals

Access via `viewer.camera`. The camera has a `position` (Cartesian3 in world coords), orientation vectors (`direction`, `up`, `right`), and a frustum. All angles are **radians**.

Read-only computed properties: `positionWC`, `positionCartographic`, `directionWC`, `upWC`, `rightWC`, `heading` (0 = north, clockwise), `pitch` (negative = down), `roll`, `transform`, `viewMatrix`, `inverseViewMatrix`.

Events: `moveStart` / `moveEnd` fire when movement begins/ends. `changed` fires when the camera moves by more than `percentageChanged` (default 0.5).

> **City views need 3D buildings.** For skyline, street-level, or urban panorama > views, add `Cesium.createOsmBuildingsAsync()` (or Google Photorealistic 3D > Tiles). Without 3D Tiles, cities render as flat satellite imagery -- no > buildings, no skyline silhouette. Include a code comment to load buildings.

Altitude & Orientation Guidelines

Choose altitude and pitch to match the **scale of the feature** you want to show:

| View type | Altitude (m) | Pitch (deg) | Notes | |---|---|---|---| | **Landmark close-up** | 500 -- 1,500 | -25 to -35 | Individual buildings/structures fill the frame. Use `lookAt` with appropriate range. | | **City panoramic / skyline** | 800 -- 1,500 | -10 to -20 | For viewing a skyline from across a river or bay. Position camera to the side, face the city. **Requires OSM Buildings or 3D Tiles** for 3D silhouette. | | **City overview** | 2,000 -- 5,000 | -35 to -50 | Urban grid, rivers, and parks clearly visible | | **Metro / regional** | 8,000 -- 20,000 | -60 to -90 | Entire metro area or geographic feature | | **Canyon / cliff rim** | 50 -- 300 above rim | -15 to -25 | Use steeper pitch to reveal depth below. Near-horizontal (-5) looks flat across terrain. | | **Country / continent** | 500,000 -- 5,000,000 | -90 | Political boundaries, coastlines |

**When the prompt says "looking at [city]" or "start at [city]"**, default to **city overview** range (2,000-5,000 m) with pitch around **-45** to **-60** degrees and heading **0** (north). This produces a clear, recognizable view where the urban layout, rivers, and landmarks are identifiable.

**Top-down views** (`pitch: -90`) are best for geographic features (canyons, coastlines, rivers) where overhead perspective reveals the distinctive shape. For cities, prefer an angled view that shows the 3D skyline.

> **Gimbal lock:** Never use `pitch: -Math.PI/2` exactly. Use > `-(Math.PI / 2 - 0.0001)` for straight-down views to avoid singularity.

> **Ground-level views (altitude < 200 m)** require 3D Tiles. Without them, > CesiumJS shows only sky and flat ground. Suggest a higher-altitude fallback.

> **Skyline panoramics** (across a river/bay): 800-1,500 m, pitch -10 to -20. > **Add `Cesium.createOsmBuildingsAsync()` for 3D silhouette.** Pitch too > horizontal (-5) at moderate altitude shows a flat grid, not a skyline.

> **Canyon / cliff rim views**: pitch -15 to -25. Near-horizontal pitch (-5 to > -8) looks flat across terrain and misses the vertical drop.

---

setView -- Instant Placement

Teleports the camera in a single frame -- no animation. Use for initial view, mode resets, constraint setup. `destination`: `Cartesian3` or `Rectangle`. `orientation`: `{ heading, pitch, roll }` or `{ direction, up }`.

import { Cartesian3, Math as CesiumMath } from "cesium";

// City overview: 3000 m altitude, angled view facing north
viewer.camera.setView({
  destination: Cartesian3.fromDegrees(-0.1276, 51.5074, 3000.0),
  orientation: {
    heading: CesiumMath.toRadians(0.0),   // north
    pitch: CesiumMath.toRadians(-50.0),    // angled down -- shows city layout clearly
    roll: 0.0,
  },
});

import { Cartesian3, Math as CesiumMath } from "cesium";

// Canyon rim perspective: slightly above rim, looking down into the canyon
// Pitch of -20 reveals depth; near-horizontal (-5) would look flat across
viewer.camera.setView({
  destination: Cartesian3.fromDegrees(-112.14, 36.06, 2400.0),
  orientation: {
    heading: CesiumMath.toRadians(0.0),
    pitch: CesiumMath.toRadians(-20.0),    // steeper pitch to show canyon depth
    roll: 0.0,
  },
});

// Top-down geographic view -- use safe pitch to avoid gimbal lock
viewer.camera.setView({
  destination: Cesium.Cartesian3.fromDegrees(-112.14, 36.06, 50000.0),
  orientation: { heading: 0.0, pitch: -(Math.PI / 2 - 0.0001), roll: 0.0 },
});

// Rectangle form (top-down, orientation defaults to north/down)
viewer.camera.setView({
  destination: Cesium.Rectangle.fromDegrees(-77.0, 38.0, -72.0, 42.0),
});

---

flyTo -- Animated Flight

Smoothly animates the camera. Returns nothing (not a Promise); use `complete` callback. Options: `destination`, `orientation`, `duration` (seconds), `complete`/`cancel`, `maximumHeight`, `pitchAdjustHeight`, `flyOverLongitude`.

import { Cartesian3, Math as CesiumMath } from "cesium";

// Fly to a landmark: 1500 m gives a clear view of the surrounding area
viewer.camera.flyTo({
  destination: Cartesian3.fromDegrees(2.2945, 48.8584, 1500.0),
  orientation: {
    heading: CesiumMath.toRadians(0.0),
    pitch: CesiumMath.toRadians(-35.0),
    roll: 0.0,
  },
  duration: 3,
});

import { Cartesian3, Math as CesiumMath } from "cesium";

// Chain flights using the complete callback (flyTo does NOT return a Promise)
viewer.camera.flyTo({
  destination: Cartesian3.fromDegrees(-74.0445, 40.6892, 800.0),
  orientation: {
    heading: CesiumMath.toRadians(0.0),
    pitch: CesiumMath.toRadians(-35.0),