feat: extend plugin API with camera control

src/components/molecules/Visualizer/Engine/Cesium/common.ts

@@ -20,8 +20,14 @@ import {
   Clock as CesiumClock,
   JulianDate,
   ClockStep,
+  Ellipsoid,
+  Quaternion,
+  Matrix3,
+  Cartographic,
+  EllipsoidTerrainProvider,
+  sampleTerrainMostDetailed,
 } from "cesium";
-import { useCallback } from "react";
+import { useCallback, MutableRefObject } from "react";
 
 import { useCanvas, useImage } from "@reearth/util/image";
 import { tweenInterval } from "@reearth/util/raf";
@@ -439,3 +445,145 @@ export function attachTag(entity: Entity | undefined, tag: string, value: any) {
     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 = viewer.scene.camera;
+  const height = await sampleTerrainHeight(viewer.scene, camera.position);
+  if (height && height !== 0) {
+    const innerCamera = getCamera(viewer);
+    if (innerCamera && innerCamera?.height < height + offset) {
+      camera.moveUp(height + offset - innerCamera.height);
+    }
+  }
+}
+
+export async function flyToGround(
+  viewer: Viewer,
+  cancelCameraFlight: MutableRefObject<(() => void) | undefined>,
+  camera?: {
+    lat?: number;
+    lng?: number;
+    height?: number;
+    heading?: number;
+    pitch?: number;
+    roll?: number;
+    fov?: number;
+  },
+  options?: {
+    duration?: number;
+    easing?: (time: number) => number;
+  },
+  offset = 0,
+) {
+  const height = await sampleTerrainHeight(viewer.scene, viewer.scene.camera.position);
+  const tarHeight = height ? height + offset : offset;
+  const groundCamera = { ...camera, height: tarHeight };
+  cancelCameraFlight.current?.();
+  cancelCameraFlight.current = flyTo(
+    viewer.scene?.camera,
+    { ...getCamera(viewer), ...groundCamera },
+    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;
+}
+
+async function sampleTerrainHeight(
+  scene: Scene,
+  position: Cartesian3,
+): Promise<number | undefined> {
+  const terrainProvider = scene.terrainProvider;
+  if (terrainProvider instanceof EllipsoidTerrainProvider) return 0;
+
+  const [sample] = await sampleTerrainMostDetailed(terrainProvider, [
+    Cartographic.fromCartesian(position, scene.globe.ellipsoid, new Cartographic()),
+  ]);
+  return sample.height;
+}

src/components/molecules/Visualizer/Engine/Cesium/useEngineRef.test.tsx

@@ -1,5 +1,12 @@
 import { renderHook } from "@testing-library/react";
-import { ClockStep, JulianDate, Viewer as CesiumViewer } from "cesium";
+import {
+  ClockStep,
+  JulianDate,
+  Viewer as CesiumViewer,
+  Cartesian3,
+  Globe,
+  Ellipsoid,
+} from "cesium";
 import { useRef } from "react";
 import type { CesiumComponentRef } from "resium";
 import { vi, expect, test } from "vitest";
@@ -134,15 +141,13 @@ test("requestRender", () => {
   const { result } = renderHook(() => {
     const cesium = useRef<CesiumComponentRef<CesiumViewer>>({
       cesiumElement: {
-        // eslint-disable-next-line @typescript-eslint/ban-ts-comment
-        // @ts-ignore
         scene: {
           requestRender: mockRequestRender,
         },
         isDestroyed: () => {
           return false;
         },
-      },
+      } as any,
     });
     const engineRef = useRef<EngineRef>(null);
     useEngineRef(engineRef, cesium);
@@ -158,11 +163,7 @@ test("zoom", () => {
   const { result } = renderHook(() => {
     const cesium = useRef<CesiumComponentRef<CesiumViewer>>({
       cesiumElement: {
-        // eslint-disable-next-line @typescript-eslint/ban-ts-comment
-        // @ts-ignore
         scene: {
-          // eslint-disable-next-line @typescript-eslint/ban-ts-comment
-          // @ts-ignore
           camera: {
             zoomIn: mockZoomIn,
             zoomOut: mockZoomOut,
@@ -171,7 +172,7 @@ test("zoom", () => {
         isDestroyed: () => {
           return false;
         },
-      },
+      } as any,
     });
     const engineRef = useRef<EngineRef>(null);
     useEngineRef(engineRef, cesium);
@@ -199,8 +200,6 @@ test("getClock", () => {
   const { result } = renderHook(() => {
     const cesium = useRef<CesiumComponentRef<CesiumViewer>>({
       cesiumElement: {
-        // eslint-disable-next-line @typescript-eslint/ban-ts-comment
-        // @ts-ignore
         clock: {
           startTime,
           stopTime,
@@ -209,8 +208,6 @@ test("getClock", () => {
           shouldAnimate: false,
           multiplier: 1,
           clockStep: ClockStep.SYSTEM_CLOCK,
-          // eslint-disable-next-line @typescript-eslint/ban-ts-comment
-          // @ts-ignore
           // TODO: should test cesium event
           onTick: {
             addEventListener: mockAddEventHandler,
@@ -220,7 +217,7 @@ test("getClock", () => {
         isDestroyed: () => {
           return false;
         },
-      },
+      } as any,
     });
     const engineRef = useRef<EngineRef>(null);
     useEngineRef(engineRef, cesium);
@@ -284,12 +281,10 @@ test("captureScreen", () => {
       cesiumElement: {
         render: mockViewerRender,
         isDestroyed: mockViewerIsDestroyed,
-        // eslint-disable-next-line @typescript-eslint/ban-ts-comment
-        // @ts-ignore
         canvas: {
           toDataURL: mockCanvasToDataURL,
         },
-      },
+      } as any,
     });
     const engineRef = useRef<EngineRef>(null);
     useEngineRef(engineRef, cesium);
@@ -303,3 +298,83 @@ test("captureScreen", () => {
   result.current.current?.captureScreen("image/jpeg", 0.8);
   expect(mockCanvasToDataURL).toHaveBeenCalledWith("image/jpeg", 0.8);
 });
+
+test("move", () => {
+  const mockMove = vi.fn(e => e);
+  const { result } = renderHook(() => {
+    const cesium = useRef<CesiumComponentRef<CesiumViewer>>({
+      cesiumElement: {
+        isDestroyed: () => false,
+        scene: {
+          camera: {
+            position: new Cartesian3(0, 0, 1),
+            direction: Cartesian3.clone(Cartesian3.UNIT_X),
+            up: Cartesian3.clone(Cartesian3.UNIT_Z),
+            right: Cartesian3.clone(Cartesian3.UNIT_Y),
+            move: mockMove,
+          },
+          globe: new Globe(Ellipsoid.UNIT_SPHERE),
+        },
+      } as any,
+    });
+    const engineRef = useRef<EngineRef>(null);
+    useEngineRef(engineRef, cesium);
+    return engineRef;
+  });
+
+  result.current.current?.moveForward(100);
+  expect(mockMove).toHaveBeenCalledTimes(1);
+  expect(mockMove).toHaveBeenLastCalledWith(new Cartesian3(1, 0, 0), 100);
+
+  result.current.current?.moveBackward(100);
+  expect(mockMove).toHaveBeenCalledTimes(2);
+  expect(mockMove).toHaveBeenLastCalledWith(new Cartesian3(1, 0, 0), -100);
+
+  result.current.current?.moveUp(100);
+  expect(mockMove).toHaveBeenCalledTimes(3);
+  expect(mockMove).toHaveBeenLastCalledWith(new Cartesian3(0, 0, 1), 100);
+
+  result.current.current?.moveDown(100);
+  expect(mockMove).toHaveBeenCalledTimes(4);
+  expect(mockMove).toHaveBeenLastCalledWith(new Cartesian3(0, 0, 1), -100);
+
+  result.current.current?.moveRight(100);
+  expect(mockMove).toHaveBeenCalledTimes(5);
+  expect(mockMove).toHaveBeenLastCalledWith(new Cartesian3(0, 1, 0), 100);
+
+  result.current.current?.moveLeft(100);
+  expect(mockMove).toHaveBeenCalledTimes(6);
+  expect(mockMove).toHaveBeenLastCalledWith(new Cartesian3(0, 1, 0), -100);
+});
+
+test("look", () => {
+  const mockLook = vi.fn(e => e);
+  const { result } = renderHook(() => {
+    const cesium = useRef<CesiumComponentRef<CesiumViewer>>({
+      cesiumElement: {
+        isDestroyed: () => false,
+        scene: {
+          camera: {
+            position: new Cartesian3(0, 0, 1),
+            direction: Cartesian3.clone(Cartesian3.UNIT_X),
+            up: Cartesian3.clone(Cartesian3.UNIT_Z),
+            right: Cartesian3.clone(Cartesian3.UNIT_Y),
+            look: mockLook,
+          },
+          globe: new Globe(Ellipsoid.UNIT_SPHERE),
+        },
+      } as any,
+    });
+    const engineRef = useRef<EngineRef>(null);
+    useEngineRef(engineRef, cesium);
+    return engineRef;
+  });
+
+  result.current.current?.lookHorizontal(90);
+  expect(mockLook).toHaveBeenCalledTimes(1);
+  expect(mockLook).toHaveBeenLastCalledWith(new Cartesian3(0, 0, 1), 90);
+
+  result.current.current?.lookVertical(90);
+  expect(mockLook).toHaveBeenCalledTimes(2);
+  expect(mockLook).toHaveBeenLastCalledWith(new Cartesian3(0, 1, 0), 90);
+});