feat: support custom provider (#128)

Co-authored-by: airslice <icesunex@hotmail.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Author: 3 people

.env.example

@@ -1,2 +1,12 @@
-EXAMPLE_CESIUM_ION_ACCESS_TOKEN=your_access_token_here
-EXAMPLE_GOOGLE_MAP_API_KEY=your_google_map_api_key
+# Used by the google-photorealistic layer as a fallback when no custom Google 3D Tiles URL is configured
+EXAMPLE_GOOGLE_MAP_API_KEY=
+
+# Cesium Ion access token — required to test cesium_ion_* imagery tiles and osm-buildings layer
+EXAMPLE_CESIUM_ION_ACCESS_TOKEN=
+
+# Custom provider configuration — JSON object matching CustomProviderConfig type
+# Structure: { "imagery": { "providers": [...] } }
+# Each imagery provider: { "id": string, "url": string, "credit"?: string, "maximumLevel"?: number, "minimumLevel"?: number }
+# Note: Include authentication tokens directly in URLs if needed (e.g., ?token=xxx or ?key=yyy)
+# Example: {"imagery":{"providers":[{"id":"my_satellite","url":"https://tiles.example.com/{z}/{x}/{y}.png?token=abc123","credit":"© Example","maximumLevel":19}]}}
+EXAMPLE_CUSTOM_PROVIDER=

example/App.tsx

@@ -14,8 +14,12 @@ function App() {
     handleAPIReady,
     handleSelect,
     meta,
+    customProvider,
+    customTileIds,
     currentTile,
     setCurrentTile,
+    cesiumIonAssetId,
+    setCesiumIonAssetId,
     currentCamera,
     setCurrentCamera,
     terrainEnabled,
@@ -46,8 +50,11 @@ function App() {
   return (
     <div className="relative w-screen h-screen overflow-hidden">
       <OptionsPanel
+        customTileIds={customTileIds}
         currentTile={currentTile}
         setCurrentTile={setCurrentTile}
+        cesiumIonAssetId={cesiumIonAssetId}
+        setCesiumIonAssetId={setCesiumIonAssetId}
         terrainEnabled={terrainEnabled}
         setTerrainEnabled={setTerrainEnabled}
         hideUnderground={hideUnderground}
@@ -78,6 +85,7 @@ function App() {
         onLayerSelect={handleSelect}
         engine="cesium"
         meta={meta}
+        customProvider={customProvider}
         viewerProperty={isReady ? viewerProperty : undefined}
         camera={currentCamera}
         onCameraChange={setCurrentCamera}

example/components/OptionsPanel/index.tsx

@@ -21,8 +21,11 @@ import { SKETCH_TOOLS, TILES } from "@/constants";
 import { TEST_LAYERS } from "@/testLayers";
 
 type OptionsPanelProps = {
+  customTileIds?: string[];
   currentTile?: string;
   setCurrentTile: (v: string) => void;
+  cesiumIonAssetId?: number;
+  setCesiumIonAssetId: (v: number | undefined) => void;
   terrainEnabled: boolean;
   setTerrainEnabled: (v: boolean) => void;
   hideUnderground: boolean;
@@ -46,8 +49,11 @@ type OptionsPanelProps = {
 };
 
 const OptionsPanel: FC<OptionsPanelProps> = ({
+  customTileIds,
   currentTile,
   setCurrentTile,
+  cesiumIonAssetId,
+  setCesiumIonAssetId,
   terrainEnabled,
   setTerrainEnabled,
   hideUnderground,
@@ -92,13 +98,35 @@ const OptionsPanel: FC<OptionsPanelProps> = ({
                 <SelectValue />
               </SelectTrigger>
               <SelectContent>
+                {customTileIds?.map(tile => (
+                  <SelectItem key={tile} value={tile}>
+                    {tile}
+                  </SelectItem>
+                ))}
                 {TILES.map(tile => (
                   <SelectItem key={tile} value={tile}>
                     {tile}
                   </SelectItem>
                 ))}
               </SelectContent>
             </Select>
+            {currentTile === "cesium_ion" && (
+              <div className="flex items-center gap-2 mt-1">
+                <label className="text-sm font-medium leading-none opacity-70 shrink-0">
+                  Asset ID
+                </label>
+                <input
+                  type="number"
+                  className="w-full border rounded px-2 py-1 text-sm"
+                  placeholder="e.g. 3812"
+                  value={cesiumIonAssetId ?? ""}
+                  onChange={e => {
+                    const v = parseInt(e.target.value, 10);
+                    setCesiumIonAssetId(isNaN(v) ? undefined : v);
+                  }}
+                />
+              </div>
+            )}
           </OptionSection>
 
           <OptionSection title="Terrain">

example/constants.ts

@@ -12,15 +12,21 @@ export const DEFAULT_CAMERA = {
   roll: 6.2830631767616465,
 };
 
+// Static preset tile types — always available regardless of CustomProviderConfig.
+// Dynamic provider IDs (from EXAMPLE_CUSTOM_PROVIDER) are appended at runtime in hooks.ts.
 export const TILES = [
-  "default",
-  "default_label",
-  "default_road",
+  // Public (always available)
   "open_street_map",
-  "esri_world_topo",
-  "black_marble",
   "japan_gsi_standard",
-  "test_unexpected_type",
+  "stamen_watercolor",
+  "carto_light",
+  // Cesium Ion — custom asset ID (enter asset ID in the input below)
+  "cesium_ion",
+  // Cesium Ion — preset assets (requires user-provided Ion token in scene settings)
+  "cesium_ion_default",
+  "cesium_ion_labelled",
+  "cesium_ion_road",
+  "cesium_ion_earth_at_night",
 ];
 
 export const SKETCH_TOOLS: SketchType[] = [

example/hooks.ts

@@ -4,6 +4,7 @@ import {
   ComputedFeature,
   ComputedLayer,
   Credits,
+  CustomProviderConfig,
   LayerSelectionReason,
   LazyLayer,
   MapRef,
@@ -46,18 +47,33 @@ export default () => {
     setSelectedFeature(ref.current?.layers.selectedFeature() ?? feature);
   }, []);
 
+  const customProvider = useMemo(() => {
+    const envValue = import.meta.env.EXAMPLE_CUSTOM_PROVIDER;
+    if (!envValue) return undefined;
+    try {
+      return JSON.parse(envValue) as CustomProviderConfig;
+    } catch (error) {
+      console.warn("[example] Failed to parse EXAMPLE_CUSTOM_PROVIDER:", error);
+      return undefined;
+    }
+  }, []);
+
   const meta = useMemo(
     () => ({
       cesiumIonAccessToken: import.meta.env.EXAMPLE_CESIUM_ION_ACCESS_TOKEN || undefined,
     }),
     [],
   );
 
+  const customTileIds = customProvider?.imagery?.providers?.map((p: { id: string }) => p.id) ?? [];
+
+  const allTileIds = [...TILES, ...customTileIds];
   const [currentTile, setCurrentTile] = useState(
-    TILES.includes(DEFAULT_VIEWER_PROPERTY.tiles?.[0]?.type ?? "")
+    allTileIds.includes(DEFAULT_VIEWER_PROPERTY.tiles?.[0]?.type ?? "")
       ? DEFAULT_VIEWER_PROPERTY.tiles?.[0]?.type
       : undefined,
   );
+  const [cesiumIonAssetId, setCesiumIonAssetId] = useState<number | undefined>(undefined);
   const [currentCamera, setCurrentCamera] = useState(DEFAULT_CAMERA);
   const [terrainEnabled, setTerrainEnabled] = useState(true);
   const [hideUnderground, setHideUnderground] = useState(false);
@@ -71,6 +87,7 @@ export default () => {
             {
               id: "default",
               type: currentTile,
+              cesiumIonAssetId: currentTile === "cesium_ion" ? cesiumIonAssetId : undefined,
               opacity: 1,
             },
           ]
@@ -84,7 +101,7 @@ export default () => {
         depthTestAgainstTerrain: hideUnderground,
       },
     }),
-    [currentTile, terrainEnabled, hideUnderground],
+    [currentTile, cesiumIonAssetId, terrainEnabled, hideUnderground],
   );
 
   const layers = useMemo(
@@ -118,7 +135,10 @@ export default () => {
       !selectedFeature?.id
     )
       return;
-    ref.current?.sketch.editFeature({ layerId: selectedLayer.id, feature: selectedFeature });
+    ref.current?.sketch.editFeature({
+      layerId: selectedLayer.id,
+      feature: selectedFeature,
+    });
   }, [selectedLayer, selectedFeature]);
 
   const handleCancelEditSketchFeature = useCallback(() => {
@@ -165,8 +185,12 @@ export default () => {
     handleAPIReady,
     handleSelect,
     meta,
+    customProvider,
+    customTileIds,
     currentTile,
     setCurrentTile,
+    cesiumIonAssetId,
+    setCesiumIonAssetId,
     currentCamera,
     setCurrentCamera,
     terrainEnabled,

example/scene.ts

@@ -62,6 +62,7 @@ export const DEFAULT_VIEWER_PROPERTY: ViewerProperty = {
   terrain: {
     enabled: true,
     normal: true,
+    type: "reearth_terrain",
   },
   geoid: {
     server: {

example/testLayers/index.ts

@@ -6,6 +6,7 @@ import { GEOJSON_SIMPLE } from "./geojson_simple";
 import { GOOGLE_PHOTOREALISTIC_3DTILES } from "./google_photorealistic_3dtiles";
 import { LAND_USE, LSLD_SAPPORO, LSLD_NIJIMA } from "./mvt";
 import { OSM_BUILDINGS } from "./osm_buildings";
+import { REEARTH_BUILDINGS } from "./reearth_buildings";
 import { THREEDTILES_KUMAGAYA_LOD2 } from "./threedtiles_lod2";
 import { THREEDTILES_SIMPLE } from "./threedtiles_simple";
 import { THREEDTILES_SIMPLE_WITH_STYLE_URL } from "./threedtiles_simple_with_style_url";
@@ -18,6 +19,7 @@ export const TEST_LAYERS: Layer[] = [
   GEOJSON_SIMPLE,
   GOOGLE_PHOTOREALISTIC_3DTILES,
   OSM_BUILDINGS,
+  REEARTH_BUILDINGS,
   THREEDTILES_SIMPLE,
   THREEDTILES_SIMPLE_WITH_STYLE_URL,
   THREEDTILES_KUMAGAYA_LOD2,

example/testLayers/reearth_buildings.ts

@@ -0,0 +1,10 @@
+import { Layer } from "@reearth/core";
+
+export const REEARTH_BUILDINGS: Layer = {
+  id: "reearth_buildings",
+  type: "simple",
+  data: {
+    type: "reearth-buildings",
+  },
+  "3dtiles": {},
+};