feat(terrain): add configurable waterMask prop to TerrainProperty

Replaces the hardcoded requestWaterMask: true (added in #158) with an
optional waterMask?: boolean on TerrainProperty. Defaults to true so
existing behavior is preserved. Consumers can now pass waterMask: false
to disable the water surface effect.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: ZTongci

src/Map/types/viewerProperty.ts

@@ -77,6 +77,7 @@ export type TerrainProperty = {
   type?: "cesium" | "cesiumion" | "reearth_terrain";
   url?: string;
   normal?: boolean;
+  waterMask?: boolean;
   elevationHeatMap?: ElevationHeatMapProperty;
 };
 

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

@@ -22,6 +22,7 @@ export default function Globe({
     terrain: property?.terrain?.enabled,
     terrainType: property?.terrain?.type,
     normal: property?.terrain?.normal,
+    waterMask: property?.terrain?.waterMask,
     ionAccessToken: property?.assets?.cesium?.terrain?.ionAccessToken || cesiumIonAccessToken,
     ionAsset: property?.assets?.cesium?.terrain?.ionAsset,
     ionUrl: property?.assets?.cesium?.terrain?.ionUrl,

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

@@ -13,7 +13,7 @@ type TerrainType = NonNullable<TerrainProperty["type"]>;
 
 const REEARTH_TERRAIN_URL = "https://terrain.reearth.land/cesium-mesh/ellipsoid";
 
-type ProviderOpts = Pick<TerrainProperty, "normal"> &
+type ProviderOpts = Pick<TerrainProperty, "normal" | "waterMask"> &
   AssetsCesiumProperty["terrain"] & {
     terrain?: boolean;
     terrainType?: TerrainType | null | undefined;
@@ -46,21 +46,22 @@ function makeKey(type: TerrainType, opts: ProviderOpts) {
   const url = opts.ionUrl ?? "";
   const ionToken = opts.ionAccessToken ?? "";
   const normal = String(!!opts.normal);
-  return `${type}|asset:${asset}|url:${url}|ion:${ionToken}|normal:${normal}`;
+  const wm = String(opts.waterMask ?? true);
+  return `${type}|asset:${asset}|url:${url}|ion:${ionToken}|normal:${normal}|wm:${wm}`;
 }
 
 function createProvider(type: TerrainType, opts: ProviderOpts): Promise<TerrainProvider> {
   switch (type) {
     case "reearth_terrain":
       return CesiumTerrainProvider.fromUrl(REEARTH_TERRAIN_URL, {
         requestVertexNormals: !!opts.normal,
-        requestWaterMask: true,
+        requestWaterMask: opts.waterMask ?? true,
       }) as Promise<TerrainProvider>;
 
     case "cesium": {
       return CesiumTerrainProvider.fromUrl(
         IonResource.fromAssetId(1, { accessToken: opts.ionAccessToken }),
-        { requestVertexNormals: !!opts.normal, requestWaterMask: true },
+        { requestVertexNormals: !!opts.normal, requestWaterMask: opts.waterMask ?? true },
       ) as Promise<TerrainProvider>;
     }
 
@@ -71,7 +72,7 @@ function createProvider(type: TerrainType, opts: ProviderOpts): Promise<TerrainP
           IonResource.fromAssetId(parseInt(String(opts.ionAsset), 10), {
             accessToken: opts.ionAccessToken,
           }),
-        { requestVertexNormals: !!opts.normal, requestWaterMask: true },
+        { requestVertexNormals: !!opts.normal, requestWaterMask: opts.waterMask ?? true },
       ) as Promise<TerrainProvider>;
     }