@reearth/core 0.0.1

package/src/engines/Cesium/common.ts

@@ -0,0 +1,901 @@
+import {
+  ColorBlendMode,
+  BoundingSphere,
+  HeadingPitchRange,
+  HorizontalOrigin,
+  VerticalOrigin,
+  Camera as CesiumCamera,
+  Math as CesiumMath,
+  Scene,
+  Cartesian2,
+  Cartesian3,
+  CesiumWidget,
+  PerspectiveFrustum,
+  OrthographicOffCenterFrustum,
+  Viewer,
+  HeightReference,
+  ClassificationType as CesiumClassificationType,
+  ShadowMode,
+  Entity,
+  PropertyBag,
+  Clock as CesiumClock,
+  JulianDate,
+  Ellipsoid,
+  Quaternion,
+  Matrix3,
+  Cartographic,
+  EllipsoidTerrainProvider,
+  sampleTerrainMostDetailed,
+  Ray,
+  IntersectionTests,
+  Matrix4,
+  Color,
+  SceneMode,
+  Cesium3DTileColorBlendMode,
+  Plane,
+  CameraEventType,
+  KeyboardEventModifier,
+} from "cesium";
+import { useCallback, MutableRefObject } from "react";
+
+import type { Camera, Clock } from "..";
+import { ClassificationType } from "../../mantle";
+import type {
+  CameraOptions,
+  FlyToDestination,
+  ModifiedCameraEventType,
+  OverideCameraEventType,
+  OverideKeyboardEventModifier,
+  ScreenSpaceCameraControllerOptions,
+} from "../../types";
+import { tweenInterval, useCanvas, useImage, LatLngHeight } from "../../utils";
+
+import { DEFAULT_SCREEN_SPACE_CAMERA_ASSIGNMENTS } from "./constants";
+
+export const layerIdField = `__reearth_layer_id`;
+
+const defaultImageSize = 50;
+
+export const drawIcon = (
+  c: HTMLCanvasElement,
+  image: HTMLImageElement | undefined,
+  w: number,
+  h: number,
+  crop: "circle" | "rounded" | "none" = "none",
+  shadow = false,
+  shadowColor = "rgba(0, 0, 0, 0.7)",
+  shadowBlur = 3,
+  shadowOffsetX = 0,
+  shadowOffsetY = 0,
+) => {
+  const ctx = c.getContext("2d");
+  if (!image || !ctx) return;
+
+  ctx.save();
+
+  c.width = w + shadowBlur;
+  c.height = h + shadowBlur;
+  ctx.shadowBlur = shadowBlur;
+  ctx.shadowOffsetX = shadowOffsetX;
+  ctx.shadowOffsetY = shadowOffsetY;
+  ctx.globalCompositeOperation = "source-over";
+  ctx.clearRect(0, 0, c.width, c.height);
+  ctx.drawImage(image, (c.width - w) / 2, (c.height - h) / 2, w, h);
+
+  if (crop === "circle") {
+    ctx.fillStyle = "black";
+    ctx.globalCompositeOperation = "destination-in";
+    ctx.arc(w / 2, h / 2, Math.min(w, h) / 2, 0, 2 * Math.PI);
+    ctx.fill();
+
+    if (shadow) {
+      ctx.shadowColor = shadowColor;
+      ctx.globalCompositeOperation = "destination-over";
+      ctx.fillStyle = "black";
+      ctx.arc(w / 2, h / 2, Math.min(w, h) / 2, 0, 2 * Math.PI);
+      ctx.fill();
+    }
+  } else if (shadow) {
+    ctx.shadowColor = shadowColor;
+    ctx.globalCompositeOperation = "destination-over";
+    ctx.fillStyle = "black";
+    ctx.rect((c.width - w) / 2, (c.height - h) / 2, w, h);
+    ctx.fill();
+  }
+
+  ctx.restore();
+};
+
+export const useIcon = ({
+  image,
+  imageSize,
+  crop,
+  shadow,
+  shadowColor,
+  shadowBlur,
+  shadowOffsetX,
+  shadowOffsetY,
+}: {
+  image?: string;
+  imageSize?: number;
+  crop?: "circle" | "rounded" | "none";
+  shadow?: boolean;
+  shadowColor?: string;
+  shadowBlur?: number;
+  shadowOffsetX?: number;
+  shadowOffsetY?: number;
+}): [string, number, number] => {
+  const img = useImage(image);
+
+  const w = !img
+    ? 0
+    : typeof imageSize === "number"
+      ? Math.floor(img.width * imageSize)
+      : Math.min(defaultImageSize, img.width);
+  const h = !img
+    ? 0
+    : typeof imageSize === "number"
+      ? Math.floor(img.height * imageSize)
+      : Math.floor((w / img.width) * img.height);
+
+  const draw = useCallback(
+    (can: HTMLCanvasElement) =>
+      drawIcon(can, img, w, h, crop, shadow, shadowColor, shadowBlur, shadowOffsetX, shadowOffsetY),
+    [crop, h, img, shadow, shadowBlur, shadowColor, shadowOffsetX, shadowOffsetY, w],
+  );
+  const canvas = useCanvas(draw);
+  return [canvas, w, h];
+};
+
+export const ho = (o: "left" | "center" | "right" | undefined): HorizontalOrigin | undefined =>
+  ({
+    left: HorizontalOrigin.LEFT,
+    center: HorizontalOrigin.CENTER,
+    right: HorizontalOrigin.RIGHT,
+    [""]: undefined,
+  })[o || ""];
+
+export const vo = (
+  o: "top" | "center" | "baseline" | "bottom" | undefined,
+): VerticalOrigin | undefined =>
+  ({
+    top: VerticalOrigin.TOP,
+    center: VerticalOrigin.CENTER,
+    baseline: VerticalOrigin.BASELINE,
+    bottom: VerticalOrigin.BOTTOM,
+    [""]: undefined,
+  })[o || ""];
+
+export const getLocationFromScreen = (
+  scene: Scene | undefined | null,
+  x: number,
+  y: number,
+  withTerrain = false,
+) => {
+  if (!scene) return undefined;
+  const camera = scene.camera;
+  const ellipsoid = scene.globe.ellipsoid;
+  let cartesian;
+  if (withTerrain) {
+    const ray = camera.getPickRay(new Cartesian2(x, y));
+    if (ray) {
+      cartesian = scene.globe.pick(ray, scene);
+    }
+  }
+  if (!cartesian) {
+    cartesian = camera?.pickEllipsoid(new Cartesian2(x, y), ellipsoid);
+  }
+  if (!cartesian) return undefined;
+  const { latitude, longitude, height } = ellipsoid.cartesianToCartographic(cartesian);
+  return {
+    lat: CesiumMath.toDegrees(latitude),
+    lng: CesiumMath.toDegrees(longitude),
+    height,
+  };
+};
+
+export const getRayEllipsoidIntersection = (
+  ray: Ray,
+  ellipsoid: Ellipsoid,
+  result?: Cartesian3,
+): Cartesian3 => {
+  const intersection = IntersectionTests.rayEllipsoid(ray, ellipsoid);
+  if (!intersection) {
+    const cartesian = IntersectionTests.grazingAltitudeLocation(ray, ellipsoid);
+    return result ? cartesian.clone(result) : cartesian;
+  }
+  return Ray.getPoint(ray, intersection.start, result);
+};
+
+const createRayFromCamera = (camera: CesiumCamera): Ray => {
+  const ray = new Ray();
+  camera.positionWC.clone(ray.origin);
+  camera.directionWC.clone(ray.direction);
+  return ray;
+};
+
+export const getCameraEllipsoidIntersection = (
+  scene: Scene,
+  resultOrWindowPosition?: Cartesian2 | Cartesian3,
+  result?: Cartesian3,
+): Cartesian3 | undefined => {
+  let ray: Ray | undefined;
+  const { camera, globe } = scene;
+
+  if (resultOrWindowPosition instanceof Cartesian2) {
+    ray = camera.getPickRay(resultOrWindowPosition, new Ray());
+    if (!ray) return undefined;
+  } else {
+    ray = createRayFromCamera(camera);
+    result = resultOrWindowPosition as Cartesian3;
+  }
+
+  return getRayEllipsoidIntersection(ray, globe.ellipsoid, result);
+};
+
+export const getCameraTerrainIntersection = (scene: Scene): Cartesian3 | undefined => {
+  const ray = createRayFromCamera(scene.camera);
+  return scene.globe.pick(ray, scene);
+};
+
+export const cartesianToLatLngHeight = (cartesian: Cartesian3, scene: Scene): LatLngHeight => {
+  const cartographic = Cartographic.fromCartesian(cartesian, scene.globe.ellipsoid);
+  return {
+    lng: CesiumMath.toDegrees(cartographic.longitude),
+    lat: CesiumMath.toDegrees(cartographic.latitude),
+    height: cartographic.height,
+  };
+};
+export const flyTo = (
+  cesiumCamera?: CesiumCamera,
+  camera?: {
+    /** degrees */
+    lat?: number;
+    /** degrees */
+    lng?: number;
+    /** meters */
+    height?: number;
+    /** radians */
+    heading?: number;
+    /** radians */
+    pitch?: number;
+    /** radians */
+    roll?: number;
+    /** Field of view expressed in radians */
+    fov?: number;
+  },
+  options?: {
+    /** Seconds */
+    duration?: number;
+    easing?: (time: number) => number;
+  },
+) => {
+  if (!cesiumCamera || !camera) return () => {};
+
+  const cancelFov = animateFOV({
+    fov: camera.fov,
+    camera: cesiumCamera,
+    duration: options?.duration,
+    easing: options?.easing,
+  });
+
+  const position =
+    typeof camera.lat === "number" &&
+    typeof camera.lng === "number" &&
+    typeof camera.height === "number"
+      ? Cartesian3.fromDegrees(camera.lng, camera.lat, camera.height)
+      : undefined;
+
+  if (position) {
+    cesiumCamera.flyTo({
+      destination: position,
+      orientation: {
+        heading: camera.heading,
+        pitch: camera.pitch,
+        roll: camera.roll,
+      },
+      duration: options?.duration ?? 0,
+      easingFunction: options?.easing,
+    });
+  }
+
+  return () => {
+    cancelFov?.();
+    cesiumCamera?.cancelFlight();
+  };
+};
+
+export const lookAt = (
+  cesiumCamera?: CesiumCamera,
+  camera?: {
+    /** degrees */
+    lat?: number;
+    /** degrees */
+    lng?: number;
+    /** meters */
+    height?: number;
+    /** radians */
+    heading?: number;
+    /** radians */
+    pitch?: number;
+    /** radians */
+    range?: number;
+    /** Field of view expressed in radians */
+    fov?: number;
+    /** Radius of bounding sphere */
+    radius?: number;
+  },
+  options?: {
+    /** Seconds */
+    duration?: number;
+    easing?: (time: number) => number;
+  },
+) => {
+  if (!cesiumCamera || !camera) return () => {};
+
+  const cancelFov = animateFOV({
+    fov: camera.fov,
+    camera: cesiumCamera,
+    duration: options?.duration,
+    easing: options?.easing,
+  });
+
+  const position =
+    typeof camera.lat === "number" &&
+    typeof camera.lng === "number" &&
+    typeof camera.height === "number"
+      ? Cartesian3.fromDegrees(camera.lng, camera.lat, camera.height)
+      : undefined;
+
+  if (position) {
+    cesiumCamera.flyToBoundingSphere(new BoundingSphere(position, camera.radius), {
+      offset:
+        camera.heading !== undefined || camera.pitch !== undefined || camera.range !== undefined
+          ? new HeadingPitchRange(camera.heading, camera.pitch, camera.range)
+          : undefined,
+      duration: options?.duration,
+      easingFunction: options?.easing,
+    });
+  }
+
+  return () => {
+    cancelFov?.();
+    cesiumCamera?.cancelFlight();
+  };
+};
+
+export const lookAtWithoutAnimation = (
+  scene: Scene,
+  camera?: {
+    /** degrees */
+    lat?: number;
+    /** degrees */
+    lng?: number;
+    /** meters */
+    height?: number;
+    /** radians */
+    heading?: number;
+    /** radians */
+    pitch?: number;
+    /** radians */
+    range?: number;
+    /** Field of view expressed in radians */
+    fov?: number;
+  },
+) => {
+  if (!camera) {
+    return;
+  }
+
+  const position =
+    typeof camera.lat === "number" && typeof camera.lng === "number"
+      ? Cartesian3.fromDegrees(camera.lng, camera.lat, camera.height)
+      : undefined;
+
+  if (position) {
+    scene.camera.lookAtTransform(Matrix4.fromTranslation(position));
+  }
+};
+
+export const animateFOV = ({
+  fov,
+  camera,
+  easing,
+  duration,
+}: {
+  fov?: number;
+  camera: CesiumCamera;
+  easing?: (t: number) => number;
+  duration?: number;
+}): (() => void) | undefined => {
+  // fov animation
+  if (
+    typeof fov === "number" &&
+    camera.frustum instanceof PerspectiveFrustum &&
+    typeof camera.frustum.fov === "number" &&
+    camera.frustum.fov !== fov
+  ) {
+    const fromFov = camera.frustum.fov;
+    return tweenInterval(
+      t => {
+        if (!(camera.frustum instanceof PerspectiveFrustum)) return;
+        camera.frustum.fov = (fov - fromFov) * t + fromFov;
+      },
+      easing || "inOutCubic",
+      (duration ?? 0) * 1000,
+    );
+  }
+  return undefined;
+};
+
+/**
+ * Get the center of globe.
+ */
+export const getCenterCamera = ({
+  camera,
+  scene,
+}: {
+  camera: CesiumCamera;
+  scene: Scene;
+}): Cartesian3 | void => {
+  const result = new Cartesian3();
+  const ray = camera.getPickRay(camera.positionWC);
+  if (ray) {
+    ray.origin = camera.positionWC;
+    ray.direction = camera.directionWC;
+    return scene.globe.pick(ray, scene, result);
+  }
+};
+
+export const zoom = (
+  { viewer, relativeAmount }: { viewer: Viewer; relativeAmount: number },
+  options?: CameraOptions,
+) => {
+  const { camera, scene } = viewer;
+  if (scene.mode !== SceneMode.SCENE3D) {
+    const pos = getCamera(viewer);
+    flyTo(camera, { ...pos, height: (pos?.height || 1) * relativeAmount }, { duration: 0.5 });
+    return;
+  }
+
+  const center = getCenterCamera({ camera, scene });
+  const target =
+    center ||
+    IntersectionTests.grazingAltitudeLocation(
+      // Get the ray from cartographic to the camera direction
+      new Ray(
+        // Get the cartographic position of camera on 3D space.
+        scene.globe.ellipsoid.cartographicToCartesian(camera.positionCartographic),
+        // Get the camera direction.
+        camera.directionWC,
+      ),
+      scene.globe.ellipsoid,
+    );
+
+  if (!target) {
+    return;
+  }
+
+  const orientation = {
+    heading: camera.heading,
+    pitch: camera.pitch,
+    roll: camera.roll,
+  };
+
+  const cartesian3Scratch = new Cartesian3();
+  const direction = Cartesian3.subtract(camera.position, target, cartesian3Scratch);
+  const movementVector = Cartesian3.multiplyByScalar(direction, relativeAmount, direction);
+  const endPosition = Cartesian3.add(target, movementVector, target);
+
+  camera.flyTo({
+    destination: endPosition,
+    orientation: orientation,
+    duration: options?.duration || 0.5,
+    convert: false,
+  });
+};
+
+export const getCamera = (viewer: Viewer | CesiumWidget | undefined): Camera | undefined => {
+  if (!viewer || viewer.isDestroyed() || !viewer.camera || !viewer.scene) return undefined;
+  const { camera } = viewer;
+  if (
+    !(
+      camera.frustum instanceof PerspectiveFrustum ||
+      camera.frustum instanceof OrthographicOffCenterFrustum
+    )
+  )
+    return;
+  const { latitude, longitude, height } = camera.positionCartographic;
+  const lat = CesiumMath.toDegrees(latitude);
+  const lng = CesiumMath.toDegrees(longitude);
+  const { heading, pitch, roll } = camera;
+  const fov = camera.frustum instanceof PerspectiveFrustum ? camera.frustum.fov : 1;
+  const aspectRatio = camera.frustum instanceof PerspectiveFrustum ? camera.frustum.aspectRatio : 1;
+  return { lng, lat, height, heading, pitch, roll, fov, aspectRatio };
+};
+
+export const getClock = (clock: CesiumClock | undefined): Clock | undefined => {
+  if (!clock) return undefined;
+  return {
+    get start() {
+      return JulianDate.toDate(clock.startTime);
+    },
+    get stop() {
+      return JulianDate.toDate(clock.stopTime);
+    },
+    get current() {
+      return JulianDate.toDate(clock.currentTime);
+    },
+    get playing() {
+      return clock.shouldAnimate;
+    },
+    get speed() {
+      return clock.multiplier;
+    },
+  };
+};
+
+export const colorBlendMode = (colorBlendMode?: "highlight" | "replace" | "mix" | "none") =>
+  (
+    ({
+      highlight: ColorBlendMode.HIGHLIGHT,
+      replace: ColorBlendMode.REPLACE,
+      mix: ColorBlendMode.MIX,
+    }) as { [key in string]?: ColorBlendMode }
+  )[colorBlendMode || ""];
+
+export const colorBlendModeFor3DTile = (
+  colorBlendMode?: "highlight" | "replace" | "mix" | "default",
+) =>
+  (
+    ({
+      highlight: Cesium3DTileColorBlendMode.HIGHLIGHT,
+      replace: Cesium3DTileColorBlendMode.REPLACE,
+      mix: Cesium3DTileColorBlendMode.MIX,
+    }) as { [key in string]?: Cesium3DTileColorBlendMode }
+  )[colorBlendMode || ""];
+
+export const heightReference = (
+  heightReference?: "none" | "clamp" | "relative",
+): HeightReference | undefined =>
+  (
+    ({
+      clamp: HeightReference.CLAMP_TO_GROUND,
+      relative: HeightReference.RELATIVE_TO_GROUND,
+      none: HeightReference.NONE,
+    }) as {
+      [key in string]?: HeightReference;
+    }
+  )[heightReference || ""];
+
+export const getOverriddenScreenSpaceCameraOptions = (
+  options?: ScreenSpaceCameraControllerOptions,
+) => {
+  if (!options) return;
+  const cameraEventTypeMap = new Map<OverideCameraEventType, CameraEventType>([
+    ["left_drag", CameraEventType.LEFT_DRAG],
+    ["right_drag", CameraEventType.RIGHT_DRAG],
+    ["middle_drag", CameraEventType.MIDDLE_DRAG],
+    ["wheel", CameraEventType.WHEEL],
+    ["pinch", CameraEventType.PINCH],
+  ]);
+
+  const keyboardEventModifierMap = new Map<OverideKeyboardEventModifier, KeyboardEventModifier>([
+    ["ctrl", KeyboardEventModifier.CTRL],
+    ["shift", KeyboardEventModifier.SHIFT],
+    ["alt", KeyboardEventModifier.ALT],
+  ]);
+
+  const convertOptions = (
+    arr: (OverideCameraEventType | ModifiedCameraEventType)[] | undefined,
+  ) => {
+    if (!arr) return;
+    return arr.map((v: OverideCameraEventType | ModifiedCameraEventType) => {
+      if (typeof v === "string") {
+        return cameraEventTypeMap.get(v);
+      } else {
+        return {
+          eventType: cameraEventTypeMap.get(v.eventType),
+          modifier: keyboardEventModifierMap.get(v.modifier),
+        };
+      }
+    });
+  };
+
+  const translateEventTypes = convertOptions(options.translateEventTypes);
+  const zoomEventTypes = convertOptions(options.zoomEventTypes);
+  const rotateEventTypes = convertOptions(options.rotateEventTypes);
+  const tiltEventTypes = convertOptions(options.tiltEventTypes);
+  const lookEventTypes = convertOptions(options.lookEventTypes);
+
+  return {
+    ...DEFAULT_SCREEN_SPACE_CAMERA_ASSIGNMENTS,
+    ...(translateEventTypes && { translateEventTypes }),
+    ...(zoomEventTypes && { zoomEventTypes }),
+    ...(rotateEventTypes && { rotateEventTypes }),
+    ...(tiltEventTypes && { tiltEventTypes }),
+    ...(lookEventTypes && { lookEventTypes }),
+    ...(options.minimumZoomDistance !== undefined && {
+      minimumZoomDistance: options.minimumZoomDistance,
+    }),
+    ...(options.maximumZoomDistance !== undefined && {
+      maximumZoomDistance: options.maximumZoomDistance,
+    }),
+    ...(options.enableCollisionDetection !== undefined && {
+      enableCollisionDetection: options.enableCollisionDetection,
+    }),
+  };
+};
+
+export const classificationType = (
+  classificationType?: ClassificationType,
+): CesiumClassificationType | undefined =>
+  (
+    ({
+      both: CesiumClassificationType.BOTH,
+      "3dtiles": CesiumClassificationType.CESIUM_3D_TILE,
+      terrain: CesiumClassificationType.TERRAIN,
+    }) as {
+      [key in ClassificationType | ""]?: CesiumClassificationType;
+    }
+  )[classificationType || ""];
+
+export const shadowMode = (
+  shadows?: "disabled" | "enabled" | "cast_only" | "receive_only",
+): ShadowMode | undefined =>
+  (
+    ({
+      enabled: ShadowMode.ENABLED,
+      cast_only: ShadowMode.CAST_ONLY,
+      receive_only: ShadowMode.RECEIVE_ONLY,
+      disabled: ShadowMode.DISABLED,
+    }) as {
+      [key in string]?: ShadowMode;
+    }
+  )[shadows || ""];
+
+export const unselectableTag = "reearth_unselectable";
+export const draggableTag = "reearth_draggable";
+
+export function isSelectable(e: Entity | undefined): boolean {
+  return !e?.properties?.hasProperty(unselectableTag);
+}
+
+export function isDraggable(e: Entity): string | undefined {
+  return e.properties?.[draggableTag];
+}
+
+export function attachTag(entity: Entity | undefined, tag: string, value: any) {
+  if (!entity) return;
+  if (typeof value !== "undefined" && !entity.properties) {
+    entity.properties = new PropertyBag({ [tag]: value });
+  } else if (typeof value === "undefined") {
+    entity.properties?.removeProperty(tag);
+  } else if (entity.properties?.hasProperty(tag)) {
+    entity.properties?.removeProperty(tag);
+    entity.properties?.addProperty(tag, value);
+  } else {
+    entity.properties?.addProperty(tag, value);
+  }
+}
+
+export function lookHorizontal(scene: Scene, amount: number) {
+  const camera = scene.camera;
+  const ellipsoid = scene.globe.ellipsoid;
+  const surfaceNormal = ellipsoid.geodeticSurfaceNormal(camera.position, new Cartesian3());
+  camera.look(surfaceNormal, amount);
+}
+
+export function lookVertical(scene: Scene, amount: number) {
+  const camera = scene.camera;
+  const ellipsoid = scene.globe.ellipsoid;
+  const lookAxis = projectVectorToSurface(camera.right, camera.position, ellipsoid);
+  const surfaceNormal = ellipsoid.geodeticSurfaceNormal(camera.position, new Cartesian3());
+  const currentAngle = CesiumMath.toDegrees(Cartesian3.angleBetween(surfaceNormal, camera.up));
+  const upAfterLook = rotateVectorAboutAxis(camera.up, lookAxis, amount);
+  const angleAfterLook = CesiumMath.toDegrees(Cartesian3.angleBetween(surfaceNormal, upAfterLook));
+  const friction = angleAfterLook < currentAngle ? 1 : (90 - currentAngle) / 90;
+  camera.look(lookAxis, amount * friction);
+}
+
+export function moveForward(scene: Scene, amount: number) {
+  const direction = projectVectorToSurface(
+    scene.camera.direction,
+    scene.camera.position,
+    scene.globe.ellipsoid,
+  );
+  scene.camera.move(direction, amount);
+}
+
+export function moveBackward(scene: Scene, amount: number) {
+  const direction = projectVectorToSurface(
+    scene.camera.direction,
+    scene.camera.position,
+    scene.globe.ellipsoid,
+  );
+  scene.camera.move(direction, -amount);
+}
+
+export function moveUp(scene: Scene, amount: number) {
+  const surfaceNormal = scene.globe.ellipsoid.geodeticSurfaceNormal(
+    scene.camera.position,
+    new Cartesian3(),
+  );
+  scene.camera.move(surfaceNormal, amount);
+}
+
+export function moveDown(scene: Scene, amount: number) {
+  const surfaceNormal = scene.globe.ellipsoid.geodeticSurfaceNormal(
+    scene.camera.position,
+    new Cartesian3(),
+  );
+  scene.camera.move(surfaceNormal, -amount);
+}
+
+export function moveLeft(scene: Scene, amount: number) {
+  const direction = projectVectorToSurface(
+    scene.camera.right,
+    scene.camera.position,
+    scene.globe.ellipsoid,
+  );
+  scene.camera.move(direction, -amount);
+}
+
+export function moveRight(scene: Scene, amount: number) {
+  const direction = projectVectorToSurface(
+    scene.camera.right,
+    scene.camera.position,
+    scene.globe.ellipsoid,
+  );
+  scene.camera.move(direction, amount);
+}
+
+export async function moveOverTerrain(viewer: Viewer, offset = 0) {
+  const camera = getCamera(viewer);
+  if (camera?.lng === undefined || camera?.lat === undefined) return;
+  const height = await sampleTerrainHeight(viewer.scene, camera.lng, camera.lat);
+  if (height && height !== 0) {
+    const innerCamera = getCamera(viewer);
+    if (innerCamera && innerCamera?.height < height + offset) {
+      viewer.scene.camera.moveUp(height + offset - innerCamera.height);
+    }
+  }
+}
+
+export async function flyToGround(
+  viewer: Viewer,
+  cancelCameraFlight: MutableRefObject<(() => void) | undefined>,
+  camera: FlyToDestination,
+  options?: {
+    duration?: number;
+    easing?: (time: number) => number;
+  },
+  offset = 0,
+) {
+  if (camera.lng === undefined || camera.lat === undefined) return;
+  const height = await sampleTerrainHeight(viewer.scene, camera.lng, camera.lat);
+  const tarHeight = height ? height + offset : offset;
+  cancelCameraFlight.current?.();
+  cancelCameraFlight.current = flyTo(
+    viewer.scene?.camera,
+    { ...getCamera(viewer), ...camera, height: tarHeight },
+    options,
+  );
+}
+
+function projectVectorToSurface(vector: Cartesian3, position: Cartesian3, ellipsoid: Ellipsoid) {
+  const surfaceNormal = ellipsoid.geodeticSurfaceNormal(position, new Cartesian3());
+  const magnitudeOfProjectionOnSurfaceNormal = Cartesian3.dot(vector, surfaceNormal);
+  const projectionOnSurfaceNormal = Cartesian3.multiplyByScalar(
+    surfaceNormal,
+    magnitudeOfProjectionOnSurfaceNormal,
+    new Cartesian3(),
+  );
+  return Cartesian3.subtract(vector, projectionOnSurfaceNormal, new Cartesian3());
+}
+
+function rotateVectorAboutAxis(vector: Cartesian3, rotateAxis: Cartesian3, rotateAmount: number) {
+  const quaternion = Quaternion.fromAxisAngle(rotateAxis, -rotateAmount, new Quaternion());
+  const rotation = Matrix3.fromQuaternion(quaternion, new Matrix3());
+  const rotatedVector = Matrix3.multiplyByVector(rotation, vector, vector.clone());
+  return rotatedVector;
+}
+
+export async function sampleTerrainHeight(
+  scene: Scene,
+  lng: number,
+  lat: number,
+): Promise<number | undefined> {
+  const terrainProvider = scene.terrainProvider;
+  if (terrainProvider instanceof EllipsoidTerrainProvider) return 0;
+
+  const [sample] = await sampleTerrainMostDetailed(terrainProvider, [
+    Cartographic.fromDegrees(lng, lat),
+  ]);
+  return sample.height;
+}
+
+export async function sampleTerrainHeightFromCartesian(scene: Scene, translation: Cartesian3) {
+  const cart = Cartographic.fromCartesian(translation);
+  const [lng, lat] = [
+    CesiumMath.toDegrees(cart?.longitude || 0),
+    CesiumMath.toDegrees(cart?.latitude || 0),
+  ];
+  if (!lng || !lat) {
+    return;
+  }
+  return await sampleTerrainHeight(scene, lng, lat);
+}
+
+export const isColor = (c?: string) => c?.match(/^#[A-Fa-f0-9]|^rgba?/);
+
+export const toColor = (c?: string) => {
+  if (!c || typeof c !== "string") return undefined;
+
+  // support alpha
+  const m = c.match(/^#([A-Fa-f0-9]{6})([A-Fa-f0-9]{2})$|^#([A-Fa-f0-9]{3})([A-Fa-f0-9])$/);
+  if (!m) return Color.fromCssColorString(c);
+
+  const alpha = parseInt(m[4] ? m[4].repeat(2) : m[2], 16) / 255;
+  return Color.fromCssColorString(`#${m[1] ?? m[3]}`).withAlpha(alpha);
+};
+
+export const updateMapController = (viewer: Viewer, enabled: boolean) => {
+  viewer.scene.screenSpaceCameraController.enableTranslate = enabled;
+  viewer.scene.screenSpaceCameraController.enableRotate = enabled;
+  viewer.scene.screenSpaceCameraController.enableLook = enabled;
+  viewer.scene.screenSpaceCameraController.enableTilt = enabled;
+  viewer.scene.screenSpaceCameraController.enableZoom = enabled;
+};
+
+export function getExtrudedHeight(
+  scene: Scene,
+  position: Cartesian3,
+  windowPosition: Cartesian2,
+): number | undefined {
+  const cartesianScratch = new Cartesian3();
+  const normalScratch = new Cartesian3();
+  const rayScratch = new Ray();
+  const planeScratch = new Plane(Cartesian3.UNIT_X, 0);
+  const cartographicScratch = new Cartographic();
+  let intersection;
+  try {
+    const normal = scene.globe.ellipsoid.geodeticSurfaceNormal(position, normalScratch);
+    const ray = scene.camera.getPickRay(windowPosition, rayScratch);
+    if (ray == null) {
+      return;
+    }
+    // Plane coincident with surface normal and perpendicular to another plane
+    // coincident with the ray direction.
+    const plane = Plane.fromPointNormal(
+      position,
+      Cartesian3.normalize(
+        Cartesian3.cross(
+          normal,
+          Cartesian3.cross(normal, ray.direction, cartesianScratch),
+          cartesianScratch,
+        ),
+        cartesianScratch,
+      ),
+      planeScratch,
+    );
+    intersection = IntersectionTests.rayPlane(ray, plane, cartesianScratch);
+    if (intersection == null) {
+      return;
+    }
+    const toHeight = Cartographic.fromCartesian(
+      intersection,
+      scene.globe.ellipsoid,
+      cartographicScratch,
+    ).height;
+    const fromHeight = Cartographic.fromCartesian(
+      position,
+      scene.globe.ellipsoid,
+      cartographicScratch,
+    ).height;
+    return Math.max(0, toHeight - fromHeight);
+  } catch (error) {
+    console.error(error);
+  }
+  return;
+}