Support time window query

CHANGES.md

@@ -5,6 +5,7 @@
 - Fixed broken point dragging interaction for user drawing in 3D mode.
 - Fixed rectangle drawing in 2D mode.
 - Added EPSG:7855 to `Proj4Definitions`.
+- Add time window duration trait. The esri-mapServer type supports time window duration query via model dimensions.
 - [The next improvement]
 
 #### 8.3.2 - 2023-08-11

lib/Models/Catalog/Esri/ArcGisMapServerCatalogItem.ts

@@ -328,6 +328,12 @@ class MapServerStratum extends LoadableStratum(
 
 StratumOrder.addLoadStratum(MapServerStratum.stratumName);
 
+interface TimeParams {
+  currentTime: number | undefined;
+  timeWindowDuration: number | undefined;
+  timeUnit: string | undefined;
+}
+
 export default class ArcGisMapServerCatalogItem extends UrlMixin(
   DiscretelyTimeVaryingMixin(
     MinMaxLevelMixin(
@@ -393,14 +399,62 @@ export default class ArcGisMapServerCatalogItem extends UrlMixin(
     return result;
   }
 
-  @computed
-  private get _currentImageryParts(): ImageryParts | undefined {
-    const dateAsUnix: string | undefined =
+  private getTimeWindowDurationFromDimensions() {
+    if (
+      this.modelDimensions.length < 1 ||
+      this.modelDimensions[0].selectedId === undefined
+    ) {
+      return undefined;
+    }
+    const selectedId = this.modelDimensions[0].selectedId;
+    if (this.modelDimensions.length < 1 && selectedId === undefined) {
+      return undefined;
+    } else {
+      const dimOptions = this.modelDimensions[0].options.filter(
+        (opt) => opt.id === selectedId
+      );
+      if (dimOptions.length < 1) {
+        return undefined;
+      }
+      const selected = dimOptions[0] as any;
+      const timeWindowDuration: number | undefined =
+        selected.value.timeWindowDuration;
+      const timeUnit: string | undefined = selected.value.timeUnit;
+
+      if (
+        selected === undefined ||
+        timeWindowDuration === undefined ||
+        timeUnit === undefined
+      ) {
+        return undefined;
+      } else {
+        return {
+          timeWindowDuration,
+          timeUnit
+        };
+      }
+    }
+  }
+
+  private getCurrentTime() {
+    const dateAsUnix: number | undefined =
       this.currentDiscreteTimeTag === undefined
         ? undefined
-        : new Date(this.currentDiscreteTimeTag).getTime().toString();
+        : new Date(this.currentDiscreteTimeTag).getTime();
+    return dateAsUnix;
+  }
+
+  private getTimeParams(): TimeParams {
+    const timeWindowDuration = this.getTimeWindowDurationFromDimensions();
+    const currentTime = this.getCurrentTime();
+    const timeParams = { currentTime, ...timeWindowDuration } as TimeParams;
+    return timeParams;
+  }
 
-    const imageryProvider = this._createImageryProvider(dateAsUnix);
+  @computed
+  private get _currentImageryParts(): ImageryParts | undefined {
+    const timeParams = this.getTimeParams();
+    const imageryProvider = this._createImageryProvider(timeParams);
     if (imageryProvider === undefined) {
       return undefined;
     }
@@ -419,10 +473,8 @@ export default class ArcGisMapServerCatalogItem extends UrlMixin(
       !this.isPaused &&
       this.nextDiscreteTimeTag
     ) {
-      const dateAsUnix: number = new Date(this.nextDiscreteTimeTag).getTime();
-      const imageryProvider = this._createImageryProvider(
-        dateAsUnix.toString()
-      );
+      const timeParams = this.getTimeParams();
+      const imageryProvider = this._createImageryProvider(timeParams);
       if (imageryProvider === undefined) {
         return undefined;
       }
@@ -443,7 +495,9 @@ export default class ArcGisMapServerCatalogItem extends UrlMixin(
   }
 
   private _createImageryProvider = createTransformerAllowUndefined(
-    (time: string | undefined): ArcGisMapServerImageryProvider | undefined => {
+    (
+      timeParams: TimeParams | undefined
+    ): ArcGisMapServerImageryProvider | undefined => {
       const stratum = <MapServerStratum>(
         this.strata.get(MapServerStratum.stratumName)
       );
@@ -452,9 +506,51 @@ export default class ArcGisMapServerCatalogItem extends UrlMixin(
         return;
       }
 
+      function windowDurationInMs(
+        windowDuration: number | undefined,
+        timeUnit: string | undefined
+      ): number | undefined {
+        if (windowDuration === undefined || timeUnit === undefined) {
+          return undefined;
+        }
+        const msInOneHour = 3600 * 1000;
+        const theUnit = timeUnit.toLowerCase();
+        if (theUnit === "year") return windowDuration * 365 * 24 * msInOneHour;
+        else if (theUnit === "month")
+          return windowDuration * 30 * 24 * msInOneHour;
+        else if (theUnit === "week")
+          return windowDuration * 7 * 24 * msInOneHour;
+        else if (theUnit === "day") return windowDuration * 24 * msInOneHour;
+        else if (theUnit === "hour") return windowDuration * msInOneHour;
+        else if (theUnit === "minute") return windowDuration * 60 * 1000;
+        else if (theUnit === "second") return windowDuration * 1000;
+        else return undefined;
+      }
+
+      function getTimeWindowQueryString(
+        currentTime: number,
+        windowDuration: number
+      ) {
+        const timeBound = Number(currentTime) + windowDuration;
+        if (windowDuration >= 0) {
+          return currentTime + "," + timeBound;
+        } else {
+          return "" + timeBound + "," + currentTime;
+        }
+      }
+
       const params: any = Object.assign({}, this.parameters);
-      if (time !== undefined) {
-        params.time = time;
+      const currentTime = timeParams?.currentTime;
+      if (currentTime !== undefined) {
+        const windowDuration = windowDurationInMs(
+          timeParams?.timeWindowDuration,
+          timeParams?.timeUnit
+        );
+        if (windowDuration !== undefined) {
+          params.time = getTimeWindowQueryString(currentTime, windowDuration);
+        } else {
+          params.time = currentTime;
+        }
       }
 
       const maximumLevel = scaleDenominatorToLevel(

lib/Traits/TraitsClasses/TimeVaryingTraits.ts

@@ -71,4 +71,26 @@ export default class TimeVaryingTraits extends mixTraits(CatalogMemberTraits) {
     type: "string"
   })
   dateFormat?: string;
+
+  @primitiveTrait({
+    name: "Time Window Duration",
+    description:
+      "Specify a time window duration from the current time that this dataset is available. Positive: forward; negative: backward.",
+    type: "number"
+  })
+  timeWindowDuration?: number;
+
+  @primitiveTrait({
+    name: "Time Unit",
+    description:
+      "The time unit for the `Time Interval`. Valid values are <br/>" +
+      " * `year` <br/>" +
+      " * `month` <br/>" +
+      " * `day` <br/>" +
+      " * `hour` <br/>" +
+      " * `minute` <br/>" +
+      " * `second` <br/>",
+    type: "string"
+  })
+  timeUnit?: string;
 }

test/Models/Catalog/esri/ArcGisMapServerCatalogItemSpec.ts

@@ -6,6 +6,7 @@ import _loadWithXhr from "../../../../lib/Core/loadWithXhr";
 import ArcGisMapServerCatalogItem from "../../../../lib/Models/Catalog/Esri/ArcGisMapServerCatalogItem";
 import Terria from "../../../../lib/Models/Terria";
 import CommonStrata from "./../../../../lib/Models/Definition/CommonStrata";
+import updateModelFromJson from "../../../../lib/Models/Definition/updateModelFromJson";
 
 configure({
   enforceActions: "observed",
@@ -467,6 +468,115 @@ describe("ArcGisMapServerCatalogItem", function () {
       expect(item.startTime).toBe("2004-11-26T09:43:22.000000000Z");
       expect(item.stopTime).toBe("2019-11-03T14:00:00.000000000Z");
     });
+
+    it("can load a time-enabled layer without interval specified by model dimensions", async function () {
+      runInAction(() => {
+        item = new ArcGisMapServerCatalogItem("test", new Terria());
+        item.setTrait(
+          CommonStrata.definition,
+          "url",
+          "http://example.com/cadastre_history/MapServer"
+        );
+      });
+
+      const modelJson = {
+        modelDimensions: [
+          {
+            id: "Select time window duration",
+            name: "Select time window duration",
+            options: [
+              {
+                id: "no time window duration",
+                value: {}
+              }
+            ],
+            selectedId: "no time window duration"
+          }
+        ]
+      };
+      updateModelFromJson(item, CommonStrata.definition, modelJson);
+      await item.loadMapItems();
+      const expectedTimeQueryString = 1572789600000; // from json file
+      const imageryProvider = item.mapItems[0]
+        .imageryProvider as ArcGisMapServerImageryProvider;
+      expect(imageryProvider.parameters.time).toBe(expectedTimeQueryString);
+    });
+
+    it("can load a time-enabled layer with current time and forward interval specified by model dimensions", async function () {
+      runInAction(() => {
+        item = new ArcGisMapServerCatalogItem("test", new Terria());
+        item.setTrait(
+          CommonStrata.definition,
+          "url",
+          "http://example.com/cadastre_history/MapServer"
+        );
+      });
+      const modelJson = {
+        modelDimensions: [
+          {
+            id: "Select a forward time window duration",
+            name: "Select a forward time window duration",
+            options: [
+              {
+                id: "2 weeks",
+                value: {
+                  timeWindowDuration: 2,
+                  timeUnit: "week"
+                }
+              }
+            ],
+            selectedId: "2 weeks"
+          }
+        ]
+      };
+      updateModelFromJson(item, CommonStrata.definition, modelJson);
+      const defaultCurrentTime = 1572789600000; // from json file
+      const twoWeekTime = 14 * 24 * 3600 * 1000;
+      const toTime = defaultCurrentTime + twoWeekTime;
+      await item.loadMapItems();
+      const expectedTimeQueryString = `${defaultCurrentTime},${toTime}`;
+      const imageryProvider = item.mapItems[0]
+        .imageryProvider as ArcGisMapServerImageryProvider;
+      expect(imageryProvider.parameters.time).toBe(expectedTimeQueryString);
+    });
+
+    it("can load a time-enabled layer with current time and backward interval specified by model iimensions", async function () {
+      runInAction(() => {
+        item = new ArcGisMapServerCatalogItem("test", new Terria());
+        item.setTrait(
+          CommonStrata.definition,
+          "url",
+          "http://example.com/cadastre_history/MapServer"
+        );
+      });
+      const modelJson = {
+        modelDimensions: [
+          {
+            id: "Select a backward time window duration",
+            name: "Select a backward time window duration",
+            options: [
+              {
+                id: "2 weeks",
+                value: {
+                  timeWindowDuration: -2,
+                  timeUnit: "week"
+                }
+              }
+            ],
+            selectedId: "2 weeks"
+          }
+        ]
+      };
+      updateModelFromJson(item, CommonStrata.definition, modelJson);
+      const defaultCurrentTime = 1572789600000; // from json file
+      const twoWeekTime = 14 * 24 * 3600 * 1000;
+      const fromTime = defaultCurrentTime - twoWeekTime;
+      await item.loadMapItems();
+      const expectedTimeQueryString = `${fromTime},${defaultCurrentTime}`;
+      const imageryProvider = item.mapItems[0]
+        .imageryProvider as ArcGisMapServerImageryProvider;
+      expect(imageryProvider.parameters.time).toBe(expectedTimeQueryString);
+    });
   });
 
   describe("TilesOnly + single fused map cache server", function () {