cesiumgs/cesiumjs-skills/cesiumjs-camera

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:

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 it.

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";
// Landmark standoff: camera placed south of Eiffel Tower, facing north
// Offset the destination AWAY from the landmark -- do NOT place directly above it
viewer.camera.setView({
  destination: Cartesian3.fromDegrees(2.2945, 48.847, 300.0), // ~1.2 km south
  orientation: {
    heading: CesiumMath.toRadians(0.0),    // facing north toward tower
    pitch: CesiumMath.toRadians(-20.0),    // slightly down -- tower visible above horizon
    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.

Use flyTo when destination intentionally describes the camera's final position. For a named city, landmark, entity, or coordinate that must remain centered, use flyToBoundingSphere.

import {
  BoundingSphere,
  Cartesian3,
  HeadingPitchRange,
  Math as CesiumMath,
} from "cesium";
// Keep the Eiffel Tower centered while approaching from 1500 m altitude
const target = Cartesian3.fromDegrees(2.2945, 48.8584);
const pitch = CesiumMath.toRadians(-35.0);
const desiredHeight = 1500.0;
// HeadingPitchRange.range is the slant distance to the target, not altitude.
const range = desiredHeight / Math.abs(Math.sin(pitch));
viewer.camera.flyToBoundingSphere(new BoundingSphere(target, 0.0), {
  offset: new HeadingPitchRange(0.0, pitch, range),
  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),
    roll: 0.0,
  },
  duration: 3,
  complete() {
    viewer.camera.flyTo({
      destination: Cartesian3.fromDegrees(-73.9857, 40.758, 600.0),
      orientation: {
        heading: CesiumMath.toRadians(0.0),
        pitch: CesiumMath.toRadians(-40.0),
        roll: 0.0,
      },
      duration: 2,
    });
  },
});

Altitude tip for tours: keep each stop at 600 m+ so tiles and imagery

load. Below 400 m, expect blurry tiles on fast successive flights.

// Long-distance flight: LA to Tokyo via Europe
viewer.camera.flyTo({
  destination: Cesium.Cartesian3.fromDegrees(139.815, 35.714, 20000.0),
  duration: 20,
  flyOverLongitude: Cesium.Math.toRadians(60.0), // eastward via Europe
  pitchAdjustHeight: 1000, // look down at high altitude
});

Control in-progress flights with completeFlight() (jumps to end state) and cancelFlight() (stays at current position).

flyHome

Fly to the default view. Override with Camera.DEFAULT_VIEW_RECTANGLE.

import { Camera, Rectangle } from "cesium";
Camera.DEFAULT_VIEW_RECTANGLE = Rectangle.fromDegrees(-10.0, 35.0, 40.0, 60.0);
viewer.camera.flyHome(2.0); // duration in seconds; omit for auto

Limitation: flyHome() always produces a top-down, north-up view --

no orientation control. Workaround: intercept `viewer.homeButton.viewModel

.command.beforeExecute, cancel it, and call flyTo` with custom orientation.

lookAt -- Lock Camera to Target

Positions camera to look at a target from an offset (HeadingPitchRange or Cartesian3). Locks the camera until `lookAtTransform(Matrix4.IDENTITY)`.

Overhead trap with `lookAt`: A HeadingPitchRange pitch of -Math.PI/2

positions the camera directly above the target (up_alignment ≈ 1), which

fails landmark-view checks. For any perspective or tourist view, use pitch

between -10° and -45°. Only use pitch near -90° for intentional top-down

map views.

import { Cartesian3, Math as CesiumMath, HeadingPitchRange, Matrix4 } from "cesium";
// View from the south, looking north (heading 0 = facing north = camera is south)
const target = Cartesian3.fromDegrees(2.2945, 48.8584, 300.0);
viewer.camera.lookAt(
  target,
  new HeadingPitchRange(
    CesiumMath.toRadians(0.0),   // heading 0 = north-facing
    CesiumMath.toRadians(-20.0), // pitch -- 20 deg down (NOT -90; that would be overhead)
    1500.0,                      // range in meters
  ),
);
// ALWAYS release the lookAt lock to restore free navigation
viewer.camera.lookAtTransform(Matrix4.IDENTITY);

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