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. 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 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 . 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) . import { Cartesian3 , Math as CesiumMath , HeadingPitchRange } 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 1500.0 , // range in meters ), ); import { Cartesian3 , Math as CesiumMath , HeadingPitchRange } from "cesium" ; // View from the east, looking west (heading 270 = facing west = camera is east) const target = Cartesian3 . fromDegrees (- 73.9857 , 40.7484 , 200.0 ); viewer. camera . lookAt ( target, new HeadingPitchRange ( CesiumMath . toRadians ( 270.0 ), // heading -- west CesiumMath . toRadians (- 25.0 ), // pitch -- 25 deg down 800.0 , // range in meters ), ); Cardinal direction reference for lookAt heading: To view from... Camera faces... Heading (deg) Heading (rad) South North 0 0 West East 90 Math.PI / 2 North South 180 Math.PI East West 270 3 * Math.PI / 2 Heading = direction camera faces . Camera is opposite that direction from the target. import { Matrix4 } from "cesium" ; // ALWAYS release the lookAt lock when done to restore free navigation viewer. camera . lookAtTransform ( Matrix4 . IDENTITY ); Trap: Every lookAt call MUST have a matching lookAtTransform(Matrix4.IDENTITY) . Without the release, mouse/touch/keyboard navigation is permanently disabled. Use setTimeout , complete callback, or an event to trigger the release. lookAtTransform -- Custom Reference Frames Set camera position relative to an arbitrary transform matrix. import { Cartesian3 , Transforms , HeadingPitchRange , Math as CesiumMath } from "cesium" ; // View in an east-north-up frame centered on a point const center = Cartesian3 . fromDegrees (- 75.598 , 40.039 ); const transform = Transforms . eastNorthUpToFixedFrame (center); viewer. camera . lookAtTransform ( transform, new HeadingPitchRange ( 0.0 , CesiumMath . toRadians (- 45.0 ), 5000.0 ), ); For ICRF (inertial) frame: use Transforms.computeIcrfToFixedMatrix(time) in a postUpdate listener, apply via lookAtTransform(Matrix4.fromRotationTranslation(icrfToFixed), offset) . flyToBoundingSphere / viewBoundingSphere Frame the camera around a BoundingSphere . Range is auto-computed when 0. Prefer these methods when a prompt names a target that must remain visible. The sphere center is the target; the offset places the camera relative to it. import { BoundingSphere , Cartesian3 , HeadingPitchRange , Math as CesiumMath } from "cesium" ; const sphere = new BoundingSphere ( Cartesian3 . fromDegrees (- 117.16 , 32.71 ), 1000.0 ); // Animated viewer. camera . flyToBoundingSphere (sphere, { offset : new HeadingPitchRange ( 0.0 , CesiumMath . toRadians (- 45.0 ), 0.0 ), duration : 2.0 , }); // Instant viewer. camera . viewBoundingSphere (sphere); Movement, Rotation, Look, and Zoom Methods Movement (translate position by meters, default defaultMoveAmount = 100 km): moveForward , moveBackward , moveUp , moveDown , moveLeft , moveRight , move(direction, amount) . Rotation (orbit around reference frame center, preserves distance, default defaultRotateAmount = PI/3600 rad): rotateUp , rotateDown , rotateLeft , rotateRight , rotate(axis, angle) . Look (first-person rotate-in-place, default defaultLookAmount = PI/60 rad): lookUp , lookDown , lookLeft , lookRight , look(axis, angle) , twistLeft , twistRight . Zoom (along view direction, default defaultZoomAmount = 100 km): zoomIn(amount) , zoomOut(amount) . // Scale movement speed to altitude for natural feel const height = viewer. scene . globe . ellipsoid