@reearth/core 0.0.7-alpha.62 → 0.0.7-alpha.63

package/src/Map/types/customProvider.ts

@@ -0,0 +1,32 @@
+/**
+ * Generic provider configuration for overriding external data sources.
+ *
+ * - imagery.providers: imagery tile providers keyed by id
+ * - layers.providers: 3D tileset providers keyed by id
+ *
+ * Terrain is configured via viewer/engine terrain settings (see useTerrainProviderPromise)
+ * or via each layer's own `url` field.
+ */
+
+export type ImageryProviderEntry = {
+  id: string;
+  url: string;
+  credit?: string;
+  maximumLevel?: number;
+  minimumLevel?: number;
+};
+
+export type LayerProviderEntry = {
+  id: string;
+  url: string;
+  options?: Record<string, unknown>;
+};
+
+export type CustomProviderConfig = {
+  imagery?: {
+    providers?: ImageryProviderEntry[];
+  };
+  layers?: {
+    providers?: LayerProviderEntry[];
+  };
+};

package/src/Map/types/index.ts

@@ -47,6 +47,7 @@ import {
 } from "../Sketch/types";
 import type { TimelineManagerRef } from "../useTimelineManager";
 
+import type { CustomProviderConfig } from "./customProvider";
 import type { SceneMode, ViewerProperty } from "./viewerProperty";
 
 export type {
@@ -79,6 +80,7 @@ export type {
 } from "../../mantle";
 export * from "./event";
 export * from "./viewerProperty";
+export * from "./customProvider";
 
 export type EngineRef = {
   name: string;
@@ -237,6 +239,7 @@ export type EngineProps = {
   isLayerDragging?: boolean;
   shouldRender?: boolean;
   meta?: Record<string, unknown>;
+  customProvider?: CustomProviderConfig;
   displayCredits?: boolean;
   layersRef?: RefObject<LayersRef | null>;
   requestingRenderMode?: MutableRefObject<RequestingRenderMode>;

package/src/Map/types/viewerProperty.ts

@@ -74,7 +74,7 @@ export type GlobeAtmosphereProperty = {
 
 export type TerrainProperty = {
   enabled?: boolean;
-  type?: "cesium" | "arcgis" | "cesiumion";
+  type?: "cesium" | "cesiumion" | "reearth_terrain";
   url?: string;
   normal?: boolean;
   elevationHeatMap?: ElevationHeatMapProperty;
@@ -130,6 +130,7 @@ export type TileProperty = {
   id: string;
   type?: string;
   url?: string;
+  cesiumIonAssetId?: number;
   opacity?: number;
   zoomLevel?: number[];
   zoomLevelForURL?: number[];

package/src/Visualizer/index.tsx

@@ -13,6 +13,7 @@ import {
   type Cluster,
   type ComputedLayer,
   type Credits,
+  type CustomProviderConfig,
 } from "../Map";
 import { SketchFeature, SketchType } from "../Map/Sketch/types";
 import type { InteractionModeType } from "../shared/interactionMode";
@@ -42,6 +43,7 @@ export type CoreVisualizerProps = {
   interactionMode?: InteractionModeType;
   shouldRender?: boolean;
   meta?: Record<string, unknown>;
+  customProvider?: CustomProviderConfig;
   style?: CSSProperties;
   small?: boolean;
   ready?: boolean;
@@ -85,6 +87,7 @@ export const CoreVisualizer = memo(
         interactionMode,
         shouldRender,
         meta,
+        customProvider,
         displayCredits = true,
         style,
         zoomedLayerId,
@@ -165,6 +168,7 @@ export const CoreVisualizer = memo(
                 isLayerDragging={isLayerDragging}
                 isLayerDraggable={isEditable}
                 meta={meta}
+                customProvider={customProvider}
                 displayCredits={displayCredits}
                 style={style}
                 featureFlags={featureFlags}

package/src/engines/Cesium/Feature/Tileset/hooks.ts

@@ -2,6 +2,7 @@ import {
   Cesium3DTileset as Cesium3DTilesetType,
   Cesium3DTileStyle,
   IonResource,
+  Resource,
   ClippingPlane,
   ClippingPlaneCollection as CesiumClippingPlaneCollection,
   Cartesian3,
@@ -75,6 +76,7 @@ const useData = (layer: ComputedLayer | undefined) => {
           : data?.layers
         : undefined,
       googleMapApiKey: data?.serviceTokens?.googleMapApiKey,
+      provider: data?.provider,
     };
   }, [layer]);
 };
@@ -457,7 +459,7 @@ export const useHooks = ({
 }) => {
   const { viewer } = useCesium();
   const tilesetRef = useRef<Cesium3DTilesetType>(undefined);
-  const { onLayerLoad, updateCredits } = useContext();
+  const { onLayerLoad, updateCredits, customProvider } = useContext();
   const layerIdRef = useRef(layer?.id);
   layerIdRef.current = layer?.id;
 
@@ -487,7 +489,7 @@ export const useHooks = ({
   } = useClippingBox({ clipping: experimental_clipping, boxId });
 
   const [style, setStyle] = useState<Cesium3DTileStyle>();
-  const { url, type, idProperty, googleMapApiKey } = useData(layer);
+  const { url, type, idProperty, googleMapApiKey, provider } = useData(layer);
   const shouldUseFeatureIndex = !disableIndexingFeature && !!idProperty;
 
   const [isTilesetReady, setIsTilesetReady] = useState(false);
@@ -752,20 +754,30 @@ export const useHooks = ({
     }
   }, [style, isTilesetReady]);
 
-  const googleMapPhotorealisticResource = useMemo(() => {
+  const googleMapPhotorealisticResource = useMemo((): string | Promise<Resource> | null => {
     if (type !== "google-photorealistic" || !isVisible) return null;
 
-    const loadTileset = async () => {
+    // For Re:Earth provider, use the custom URL from customProvider or layer data
+    if (provider === "reearth") {
+      // Try to get URL from customProvider first, then fall back to layer URL
+      const customUrl = customProvider?.layers?.providers?.find(
+        p => p.id === "reearth_google_photorealistic_3d_tiles",
+      )?.url;
+
+      return customUrl || url || null;
+    }
+
+    // Otherwise load via Google API key or Cesium Ion.
+    const loadTileset = async (): Promise<Resource> => {
       try {
-        if (googleMapApiKey) {
-          const tileset = await createGooglePhotorealistic3DTileset({ key: googleMapApiKey });
-          return tileset.resource;
-        } else {
-          const resource = IonResource.fromAssetId(2275207, {
+        if (provider === "cesium-ion" || !googleMapApiKey) {
+          const resource = await IonResource.fromAssetId(2275207, {
             accessToken: meta?.cesiumIonAccessToken as string | undefined,
           });
           return resource;
         }
+        const tileset = await createGooglePhotorealistic3DTileset({ key: googleMapApiKey });
+        return tileset.resource;
       } catch (error) {
         console.error(`Error loading Photorealistic 3D Tiles tileset: ${error}`);
         throw error;
@@ -773,19 +785,35 @@ export const useHooks = ({
     };
 
     return loadTileset();
-  }, [type, isVisible, googleMapApiKey, meta?.cesiumIonAccessToken]);
-
-  const tilesetUrl = useMemo(() => {
-    return type === "osm-buildings" && isVisible
-      ? IonResource.fromAssetId(96188, {
-          accessToken: meta?.cesiumIonAccessToken as string | undefined,
-        }) // https://github.com/CesiumGS/cesium/blob/main/packages/engine/Source/Scene/createOsmBuildings.js#L53
-      : googleMapPhotorealisticResource && isVisible
-        ? googleMapPhotorealisticResource
-        : type === "3dtiles" && isVisible
-          ? (url ?? tileset)
-          : null;
-  }, [type, isVisible, meta?.cesiumIonAccessToken, googleMapPhotorealisticResource, url, tileset]);
+  }, [type, isVisible, googleMapApiKey, meta?.cesiumIonAccessToken, provider, customProvider, url]);
+
+  const tilesetUrl = useMemo((): string | Resource | Promise<Resource> | null => {
+    if (!isVisible) return null;
+
+    // Google Photorealistic 3D Tiles
+    if (googleMapPhotorealisticResource) {
+      return googleMapPhotorealisticResource;
+    }
+
+    // Re:Earth Buildings — use layer's own url if provided, otherwise fall back to public service
+    if (type === "reearth-buildings") {
+      return url ?? "https://buildings.reearth.land/tileset.json";
+    }
+
+    // OSM Buildings — only available via Cesium Ion.
+    if (type === "osm-buildings") {
+      return IonResource.fromAssetId(96188, {
+        accessToken: meta?.cesiumIonAccessToken as string | undefined,
+      }); // https://github.com/CesiumGS/cesium/blob/main/packages/engine/Source/Scene/createOsmBuildings.js#L53
+    }
+
+    // Standard 3D Tiles with explicit URL
+    if (type === "3dtiles") {
+      return url ?? tileset ?? null;
+    }
+
+    return null;
+  }, [type, isVisible, googleMapPhotorealisticResource, url, tileset, meta?.cesiumIonAccessToken]);
 
   const imageBasedLighting = useMemo(() => {
     if (

package/src/engines/Cesium/Feature/context.ts

@@ -3,12 +3,14 @@ import { createContext, useContext as useReactContext } from "react";
 
 import type { Camera, LayerSelectionReason } from "../..";
 import { LayerEditEvent, LayerLoadEvent, LayerVisibilityEvent } from "../../../Map";
+import type { CustomProviderConfig } from "../../../Map/types/customProvider";
 import { TimelineManagerRef } from "../../../Map/useTimelineManager";
 import type { FlyTo } from "../../../types";
 
 export type Context = {
   selectionReason?: LayerSelectionReason;
   timelineManagerRef?: TimelineManagerRef;
+  customProvider?: CustomProviderConfig;
   getCamera?: () => Camera | undefined;
   flyTo?: FlyTo;
   onLayerEdit?: (e: LayerEditEvent) => void;

package/src/engines/Cesium/Feature/index.tsx

@@ -65,6 +65,7 @@ const displayConfig: Record<DataType, (keyof typeof components)[] | "auto"> = {
   tms: ["raster"],
   "3dtiles": ["3dtiles"],
   "osm-buildings": ["3dtiles"],
+  "reearth-buildings": ["3dtiles"],
   "google-photorealistic": ["3dtiles"],
   gpx: "auto",
   shapefile: "auto",

package/src/engines/Cesium/core/Globe/index.tsx

@@ -39,17 +39,13 @@ export default function Globe({
     providerPromise
       .then(resolvedProvider => {
         if (isCancelled) return;
-
-        // Only trigger callback if the resolved provider is actually different
         if (lastResolvedProviderRef.current !== resolvedProvider) {
           lastResolvedProviderRef.current = resolvedProvider;
           onTerrainProviderChange?.();
         }
       })
       .catch(error => {
-        if (!isCancelled) {
-          console.warn("Terrain provider failed to load:", error);
-        }
+        if (!isCancelled) console.warn("Terrain provider failed to load:", error);
       });
 
     return () => {

package/src/engines/Cesium/core/Globe/useTerrainProviderPromise.ts

@@ -1,5 +1,4 @@
 import {
-  ArcGISTiledElevationTerrainProvider,
   CesiumTerrainProvider,
   EllipsoidTerrainProvider,
   IonResource,
@@ -12,6 +11,8 @@ import { AssetsCesiumProperty } from "../../../../Map";
 
 type TerrainType = NonNullable<TerrainProperty["type"]>;
 
+const REEARTH_TERRAIN_URL = "https://terrain.reearth.land/cesium-mesh/ellipsoid";
+
 type ProviderOpts = Pick<TerrainProperty, "normal"> &
   AssetsCesiumProperty["terrain"] & {
     terrain?: boolean;
@@ -20,13 +21,11 @@ type ProviderOpts = Pick<TerrainProperty, "normal"> &
   };
 
 export default function useTerrainProviderPromise(opts: ProviderOpts) {
-  // Cache promises so we don’t recreate providers on every toggle
   const cacheRef = useRef(new Map<string, Promise<TerrainProvider>>());
   const ellipsoidRef = useRef<TerrainProvider>(undefined);
 
   return useMemo<Promise<TerrainProvider>>(() => {
     if (!opts.terrain) {
-      // single shared ellipsoid provider
       if (!ellipsoidRef.current) ellipsoidRef.current = new EllipsoidTerrainProvider();
       return Promise.resolve(ellipsoidRef.current);
     }
@@ -43,31 +42,30 @@ export default function useTerrainProviderPromise(opts: ProviderOpts) {
 }
 
 function makeKey(type: TerrainType, opts: ProviderOpts) {
-  // Key should change when output provider would differ
   const asset = opts.ionAsset ?? "";
   const url = opts.ionUrl ?? "";
+  const ionToken = opts.ionAccessToken ?? "";
   const normal = String(!!opts.normal);
-  return `${type}|asset:${asset}|url:${url}|normal:${normal}`;
+  return `${type}|asset:${asset}|url:${url}|ion:${ionToken}|normal:${normal}`;
 }
 
 function createProvider(type: TerrainType, opts: ProviderOpts): Promise<TerrainProvider> {
   switch (type) {
-    case "cesium":
+    case "reearth_terrain":
+      return CesiumTerrainProvider.fromUrl(REEARTH_TERRAIN_URL, {
+        requestVertexNormals: !!opts.normal,
+        requestWaterMask: false,
+      }) as Promise<TerrainProvider>;
+
+    case "cesium": {
       return CesiumTerrainProvider.fromUrl(
         IonResource.fromAssetId(1, { accessToken: opts.ionAccessToken }),
         { requestVertexNormals: !!opts.normal, requestWaterMask: false },
       ) as Promise<TerrainProvider>;
+    }
 
-    case "arcgis":
-      return ArcGISTiledElevationTerrainProvider.fromUrl(
-        "https://elevation3d.arcgis.com/arcgis/rest/services/WorldElevation3D/Terrain3D/ImageServer",
-      ) as Promise<TerrainProvider>;
-
-    case "cesiumion":
-      if (!opts.ionAsset && !opts.ionUrl) {
-        // Fallback to ellipsoid when misconfigured
-        return Promise.resolve(new EllipsoidTerrainProvider());
-      }
+    case "cesiumion": {
+      if (!opts.ionAsset && !opts.ionUrl) return Promise.resolve(new EllipsoidTerrainProvider());
       return CesiumTerrainProvider.fromUrl(
         opts.ionUrl ??
           IonResource.fromAssetId(parseInt(String(opts.ionAsset), 10), {
@@ -75,5 +73,9 @@ function createProvider(type: TerrainType, opts: ProviderOpts): Promise<TerrainP
           }),
         { requestVertexNormals: !!opts.normal },
       ) as Promise<TerrainProvider>;
+    }
+
+    default:
+      return Promise.resolve(new EllipsoidTerrainProvider());
   }
 }

package/src/engines/Cesium/core/Imagery.test.ts

@@ -1,119 +1,154 @@
 import { renderHook } from "@testing-library/react";
+import { UrlTemplateImageryProvider } from "cesium";
 import { expect, test, vi } from "vitest";
 
+import type { CustomProviderConfig } from "../../../Map/types/customProvider";
+
 import { type Tile, useImageryProviders } from "./Imagery";
 
 test("useImageryProviders", () => {
   const provider = vi.fn(({ url }: { url?: string } = {}): any => ({ hoge: url }));
-  const provider2 = vi.fn(({ url }: { url?: string } = {}): any => ({ hoge2: url }));
-  const presets = { default: provider, default_label: provider2 };
+  const osmProvider = vi.fn((): any => ({ osm: true }));
+
+  const presets = {
+    cesium_ion_default: provider,
+    open_street_map: osmProvider,
+  } as any;
+
   const { result, rerender } = renderHook(
-    ({ tiles, cesiumIonAccessToken }: { tiles: Tile[]; cesiumIonAccessToken?: string }) =>
+    ({
+      tiles,
+      cesiumIonAccessToken,
+      customProvider,
+    }: {
+      tiles: Tile[];
+      cesiumIonAccessToken?: string;
+      customProvider?: CustomProviderConfig;
+    }) =>
       useImageryProviders({
         tiles,
         presets,
         cesiumIonAccessToken,
+        customProvider,
       }),
-    { initialProps: { tiles: [{ id: "1", type: "default" }], cesiumIonAccessToken: undefined } },
+    {
+      initialProps: {
+        tiles: [{ id: "1", type: "cesium_ion_default" }],
+        cesiumIonAccessToken: undefined,
+        customProvider: undefined,
+      },
+    },
   );
 
   const typedRerender = rerender as (props: {
     tiles: Tile[];
     cesiumIonAccessToken?: string;
+    customProvider?: CustomProviderConfig;
   }) => void;
 
-  expect(result.current.providers).toEqual({ "1": ["default", undefined, { hoge: undefined }] });
+  expect(result.current.providers).toEqual({
+    "1": ["cesium_ion_default", undefined, undefined, { hoge: undefined }],
+  });
   expect(result.current.updated).toBe(true);
   expect(provider).toBeCalledTimes(1);
-  const prevImageryProvider = result.current.providers["1"][2];
+  const prevImageryProvider = result.current.providers["1"][3];
 
   // re-render with same tiles
-  typedRerender({ tiles: [{ id: "1", type: "default" }] });
+  typedRerender({ tiles: [{ id: "1", type: "cesium_ion_default" }] });
 
-  expect(result.current.providers).toEqual({ "1": ["default", undefined, { hoge: undefined }] });
-  expect(result.current.providers["1"][2]).toBe(prevImageryProvider); // 1's provider should be reused
+  expect(result.current.providers).toEqual({
+    "1": ["cesium_ion_default", undefined, undefined, { hoge: undefined }],
+  });
+  expect(result.current.providers["1"][3]).toBe(prevImageryProvider); // 1's provider should be reused
   expect(provider).toBeCalledTimes(1);
 
   // update a tile URL
-  typedRerender({ tiles: [{ id: "1", type: "default", url: "a" }] });
+  typedRerender({ tiles: [{ id: "1", type: "cesium_ion_default", url: "a" }] });
 
-  expect(result.current.providers).toEqual({ "1": ["default", "a", { hoge: "a" }] });
-  expect(result.current.providers["1"][2]).not.toBe(prevImageryProvider);
+  expect(result.current.providers).toEqual({
+    "1": ["cesium_ion_default", "a", undefined, { hoge: "a" }],
+  });
+  expect(result.current.providers["1"][3]).not.toBe(prevImageryProvider);
   expect(result.current.updated).toBe(true);
   expect(provider).toBeCalledTimes(2);
   expect(provider).toBeCalledWith({ url: "a" });
-  const prevImageryProvider2 = result.current.providers["1"][2];
+  const prevImageryProvider2 = result.current.providers["1"][3];
 
   // add a tile with URL
   typedRerender({
     tiles: [
-      { id: "2", type: "default" },
-      { id: "1", type: "default", url: "a" },
+      { id: "2", type: "cesium_ion_default" },
+      { id: "1", type: "cesium_ion_default", url: "a" },
     ],
   });
 
   expect(result.current.providers).toEqual({
-    "2": ["default", undefined, { hoge: undefined }],
-    "1": ["default", "a", { hoge: "a" }],
+    "2": ["cesium_ion_default", undefined, undefined, { hoge: undefined }],
+    "1": ["cesium_ion_default", "a", undefined, { hoge: "a" }],
   });
   expect(result.current.updated).toBe(true);
-  expect(result.current.providers["1"][2]).toBe(prevImageryProvider2); // 1's provider should be reused
+  expect(result.current.providers["1"][3]).toBe(prevImageryProvider2); // 1's provider should be reused
   expect(provider).toBeCalledTimes(3);
 
   // sort tiles
   typedRerender({
     tiles: [
-      { id: "1", type: "default", url: "a" },
-      { id: "2", type: "default" },
+      { id: "1", type: "cesium_ion_default", url: "a" },
+      { id: "2", type: "cesium_ion_default" },
     ],
   });
 
   expect(result.current.providers).toEqual({
-    "1": ["default", "a", { hoge: "a" }],
-    "2": ["default", undefined, { hoge: undefined }],
+    "1": ["cesium_ion_default", "a", undefined, { hoge: "a" }],
+    "2": ["cesium_ion_default", undefined, undefined, { hoge: undefined }],
   });
   expect(result.current.updated).toBe(true);
-  expect(result.current.providers["1"][2]).toBe(prevImageryProvider2); // 1's provider should be reused
+  expect(result.current.providers["1"][3]).toBe(prevImageryProvider2); // 1's provider should be reused
   expect(provider).toBeCalledTimes(3);
 
-  // delete a tile
+  // Ion token update triggers provider recreation for cesium_ion_* types
   typedRerender({
-    tiles: [{ id: "1", type: "default", url: "a" }],
+    tiles: [{ id: "1", type: "cesium_ion_default", url: "a" }],
     cesiumIonAccessToken: "a",
   });
 
   expect(result.current.providers).toEqual({
-    "1": ["default", "a", { hoge: "a" }],
+    "1": ["cesium_ion_default", "a", undefined, { hoge: "a" }],
   });
   expect(result.current.updated).toBe(true);
-  expect(result.current.providers["1"][2]).not.toBe(prevImageryProvider2);
+  expect(result.current.providers["1"][3]).not.toBe(prevImageryProvider2);
   expect(provider).toBeCalledTimes(4);
 
-  // update a tile type
+  // unknown type without customProvider: falls back directly to open_street_map
   typedRerender({
-    tiles: [{ id: "1", type: "default_label", url: "u" }],
-    cesiumIonAccessToken: "a",
+    tiles: [{ id: "1", type: "unexpected_type", url: "u" }],
   });
 
-  expect(result.current.providers).toEqual({
-    "1": ["default_label", "u", { hoge2: "u" }],
-  });
+  expect(result.current.providers["1"][0]).toBe("unexpected_type");
+  expect(result.current.providers["1"][3]).toEqual({ osm: true });
   expect(result.current.updated).toBe(true);
-  expect(provider).toBeCalledTimes(4);
-  expect(provider2).toBeCalledTimes(1);
+  expect(osmProvider).toBeCalledTimes(1);
 
-  // update a tile type to unexpected type
+  // unknown type with a matching customProvider entry: uses UrlTemplateImageryProvider
   typedRerender({
-    tiles: [{ id: "1", type: "unexpected_type", url: "u" }],
+    tiles: [{ id: "1", type: "my_custom_satellite", url: "u" }],
+    customProvider: {
+      imagery: {
+        providers: [
+          {
+            id: "my_custom_satellite",
+            url: "https://example.com/{z}/{x}/{y}.png",
+            credit: "© Example",
+          },
+        ],
+      },
+    },
   });
 
-  expect(result.current.providers).toEqual({
-    // unexpected type is treated as "default"
-    "1": ["unexpected_type", "u", { hoge: "u" }],
-  });
-  expect(result.current.updated).toBe(true);
-  expect(provider).toBeCalledTimes(5);
-  expect(provider2).toBeCalledTimes(1);
+  const dynamicProvider = result.current.providers["1"][3];
+  expect(dynamicProvider).toBeDefined();
+  expect(dynamicProvider).toBeInstanceOf(UrlTemplateImageryProvider);
+  expect(osmProvider).toBeCalledTimes(1); // osm not called again
 
   typedRerender({ tiles: [] });
   expect(result.current.providers).toEqual({});