/cesiumjs-camera

name: cesiumjs-camera
description: "CesiumJS camera control - Camera, flyTo, lookAt, setView, ScreenSpaceCameraController, composable Controller camera controllers (1.144), CameraEventAggregator, flight animation. Use when positioning the camera, creating flyTo animations, constraining user navigation, adding custom or asset-inspection camera controllers, tracking entities, or converting between screen and world coordinates."

CesiumJS Camera & Navigation

> **Baseline:** CesiumJS v1.144 -- 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 are more realistic with 3D buildings.** For production skyline, > street-level, or urban panorama views, use a tileset that is actually available > in the target environment. `Cesium.createOsmBuildingsAsync()` and Google > Photorealistic 3D Tiles are ion-entitlement-backed; avoid them in public or > no-token examples unless the caller explicitly asks for those services. For > portable examples, use an OpenStreetMap/ArcGIS basemap, visible markers, public > URL-backed 3D Tiles, or a higher-altitude city overview.

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 | |---|---|---|---| | **Tourist / monument standoff** | 50 -- 500 | -5 to -20 | Camera at near-ground level, offset laterally from the landmark. Subject fills the frame with sky visible above. Use `lookAt` with HeadingPitchRange pitch near -10°. **Never place the camera directly overhead at this range.** | | **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. Use an available 3D Tiles source only when the environment provides one. | | **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. Add wall/rim entity overlays and a river polyline to make canyon structure visible. | | **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.

> **Target intent vs. camera position:** In `setView` and `flyTo`, a Cartesian > `destination` is the camera's final position, not the point it should look at. > For requests such as "fly to Los Angeles" or "show the Eiffel Tower", treat > the named coordinates as a target to frame. Prefer `viewBoundingSphere` for > an instant view or `flyToBoundingSphere` for an animated flight.

**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 an available 3D Tiles source for a true 3D silhouette; otherwise make the > screenshot goal honest by using a higher-altitude map/marker view. Pitch too > horizontal (-5) at moderate altitude shows a flat grid, not a skyline.

> **Public visual eval rule for landmarks:** OpenStreetMap imagery alone does > not render the Eiffel Tower, Empire State Building, Statue of Liberty, or a > skyline as recognizable 3D subjects. When a public/no-token scenario asks for > an identifiable landmark or skyline, add an explicit visual surrogate at the > target: a tall cylinder/box/polyline tower, colored mast, skyline bar cluster, > or large labeled marker. Frame that surrogate so it is inspectable, roughly > one-third to two-thirds of the frame height for landmark views. Do not rely on > a map label or 10 px point as the subject.

> **Canyon / cliff rim views**: pitch -15 to -25. Near-horizontal pitch (-5 to > -8) looks flat across terrain and misses the vertical drop. Always add entity > overlays (rim wall polygons, river polyline) so the canyon structure is > visible -- without entities the scene shows only a flat basemap regardless > of camera angle.

> **CRITICAL -- Never place the camera directly above a landmark** when a > standoff / perspective view is intended. Positioning the camera at > `Cartesian3.fromDegrees(lon, lat, 1000)` pointing straight down > (`pitch: -Math.PI/2`) puts the camera overhead the subject (`up_alignment=1`) > and fails landmark-view checks. Always offset the camera laterally: > use `lookAt` with a HeadingPitchRange pitch of -10° to -45°, or place the > `destination` 500--2,000 m to the side of the landmark and aim the heading > toward i