API
API|
@babylonjs/core|
GeospatialCameraMovement

Class GeospatialCameraMovement

Geospatial-specific camera movement system that extends the base movement with raycasting and altitude-aware zoom constraints.

This class encapsulates geospatial camera movement logic:

  • Dragging in a way which keeps cursor anchored to globe
  • Latitude-based pan speed dampening
  • Zoom speed scaling based on distance to center
  • Raycasting to determine zoom constraints based on terrain/globe
  • Altitude-based zoom clamping
  • Zoom direction calculation (towards cursor vs along look vector)

Hierarchy (View Summary)

Index
constructor
activeInput computedPerFrameZoomPickPoint? input limits panAccumulatedPixels panDeltaCurrentFrame panInertia panSpeed pickPredicate? referenceFrameRate rotationAccumulatedPixels rotationDeltaCurrentFrame rotationInertia rotationXSpeed rotationYSpeed speed zoomAccumulatedPixels zoomDeltaCurrentFrame zoomInertia zoomSpeed zoomToCursor
isDragging isInterpolating
calculateUpVectorFromPointToRef computeCurrentFrameDeltas getFrameIndependentDecay getFrameIndependentInputScale handleDrag handleZoom pickAlongVector resetPanVelocity resetRotationVelocity resetZoomVelocity startDrag stopDrag
activeInput: boolean = false

Should be set by input classes to indicate whether there is active input this frame. This helps differentiate between 0 pixel delta due to no input vs user actively holding still.

computedPerFrameZoomPickPoint?: Vector3

World-space picked point under the cursor, computed each frame that zoom input is active. Used to determine the zoom direction when zoomToCursor is true. Undefined when there is no active zoom or the pick misses the globe.

input: InputMapper<GeospatialHandlers>

Input system that maps physical inputs to interactions and dispatches to handlers.

limits: GeospatialLimits

Geospatial bounds (min/max latitude, longitude, altitude, etc.) used to clamp camera motion.

panAccumulatedPixels: Vector3 = ...

Accumulated pixel delta (by input classes) for panning this frame Read by computeCurrentFrameDeltas() function and converted into panDeltaCurrentFrame (taking speed into account) Reset to zero after each frame

panDeltaCurrentFrame: Vector3 = ...

Pan delta to apply to camera this frame, computed by computeCurrentFrameDeltas() from panPixelDelta (taking speed into account)

panInertia: number = 0.9

Inertia applied to the panning velocity when there is no user input. Higher inertia === slower decay, velocity retains more of its value each frame.

Note: ArcRotateCamera overrides this from camera.panningInertia (which defaults to camera.inertia).

panSpeed: number = 1

Desired coordinate unit movement per input pixel when panning

pickPredicate?: MeshPredicate

Predicate function to determine which meshes to pick against (e.g., globe mesh)

referenceFrameRate: number = DefaultReferenceFrameRate

Framerate (Hz) at which inertia values are calibrated. Default 60 matches legacy camera feel at any actual refresh rate. Override to 120, 144, etc. only if your app was tuned on that specific refresh rate under the legacy (framerate-dependent) camera math and you want to preserve that exact decay characteristic. Most applications should leave this at 60.

rotationAccumulatedPixels: Vector3 = ...

Accumulated pixel delta (by input classes) for rotation this frame Read by computeCurrentFrameDeltas() function and converted into rotationDeltaCurrentFrame (taking speed into account) Reset to zero after each frame

rotationDeltaCurrentFrame: Vector3 = ...

Rotation delta to apply to camera this frame, computed by computeCurrentFrameDeltas() from rotationPixelDelta (taking speed into account)

rotationInertia: number = 0.9

Inertia applied to the rotation velocity when there is no user input. Higher inertia === slower decay, velocity retains more of its value each frame.

Note: ArcRotateCamera syncs this from camera.inertia via an accessor on the camera class. To tune independently, override inside scene.onBeforeRenderObservable after camera.inertia is read.

rotationXSpeed: number = 1

Desired radians movement per input pixel when rotating along x axis

rotationYSpeed: number = 1

Desired radians movement per input pixel when rotating along y axis

speed: number = 1

Global speed multiplier applied to all movement (pan, rotation, zoom). Acts as a master scale factor on top of the individual speed properties.

zoomAccumulatedPixels: number = 0

Accumulated pixel delta (by input classes) for zoom this frame Read by computeCurrentFrameDeltas() function and converted into zoomDeltaCurrentFrame (taking speed into account) Reset to zero after each frame

zoomDeltaCurrentFrame: number = 0

Zoom delta to apply to camera this frame, computed by computeCurrentFrameDeltas() from zoomPixelDelta (taking speed into account)

zoomInertia: number = 0.9

Inertia applied to the zoom velocity when there is no user input. Higher inertia === slower decay, velocity retains more of its value each frame.

Note: ArcRotateCamera syncs this from camera.inertia via an accessor on the camera class. To tune independently, override inside scene.onBeforeRenderObservable after camera.inertia is read.

zoomSpeed: number = 1

Desired coordinate unit movement per input pixel when zooming

zoomToCursor: boolean = true

When true, zooming moves toward the point under the cursor. When false, zooming moves along the camera's look vector.

  • get isInterpolating(): boolean

    Returns true when the camera is playing an interpolating (fly-to) animation. Useful for suppressing user-input movement while a programmatic animation is active.

    Returns boolean

  • Function to calculate the up vector from a given point. Can be overridden to support non-spherical planets or custom up vector logic. Defaults to using the geocentric normal.

    Parameters

    • point: Vector3

      The point from which to calculate the up vector (e.g., camera position)

    • result: Vector3

      The vector to store the calculated up vector

    Returns Vector3

    The calculated up vector

  • Returns the per-frame decay factor for a given inertia, adjusted to this frame's dt. At the reference frame rate, returns inertia unchanged (matches legacy per-frame *= inertia). Use this when implementing custom decaying accumulators (e.g. zoom-to-cursor coupled pan) that need framerate-independent glide duration.

    Parameters

    • inertia: number

      The inertia value (0-1) whose per-frame decay factor is needed.

    Returns number

    The decay factor to multiply a value by this frame.

  • Returns the input-scale factor to apply to an impulse injected into a decaying accumulator so that the integrated total is framerate-independent and matches legacy at 60fps. At the reference frame rate, returns 1 (no-op). At high fps, scales the impulse down so the sum over the decay tail stays equal to impulse / (1 - inertia) — the legacy total.

    Parameters

    • inertia: number

      The inertia value (0-1) used by the accumulator.

    Returns number

    The scaling factor to multiply an impulse by before adding it to the accumulator.

  • Updates the drag gesture by recalculating the intersection with the drag plane and accumulating the resulting pan delta.

    Parameters

    • pointerX: number

      Current screen X coordinate

    • pointerY: number

      Current screen Y coordinate

    Returns void

  • Accumulates a zoom delta and determines the zoom target point via raycasting.

    Parameters

    • zoomDelta: number

      Signed zoom amount (positive = zoom in, negative = zoom out)

    • toCursor: boolean

      When true, zoom toward the point under the cursor; when false, zoom along the look vector

    Returns void

  • Begins a drag (pan) gesture by picking the globe at the given screen position and establishing a drag plane for subsequent updates.

    Parameters

    • pointerX: number

      Screen X coordinate of the pointer

    • pointerY: number

      Screen Y coordinate of the pointer

    Returns void