Support time window query

CHANGES.md

@@ -9,6 +9,7 @@
 - Fixed broken point dragging interaction for user drawing in 3D mode.
 - Fixed rectangle drawing in 2D mode.
 - Added EPSG:7855 to `Proj4Definitions`.
+- Add optional `timeWindowDuration` and `timeUnit` traits to esri-mapServer type to support time window query.
 - Fix multi level nesting in ArcGIS Mapserver.
 - [The next improvement]
 

lib/Models/Catalog/Esri/ArcGisMapServerCatalogItem.ts

@@ -36,6 +36,7 @@ import getToken from "../../getToken";
 import proxyCatalogItemUrl from "../proxyCatalogItemUrl";
 import MinMaxLevelMixin from "./../../../ModelMixins/MinMaxLevelMixin";
 import { Extent, Layer, MapServer } from "./ArcGisInterfaces";
+import moment from "moment";
 
 const proj4 = require("proj4").default;
 
@@ -328,6 +329,12 @@ class MapServerStratum extends LoadableStratum(
 
 StratumOrder.addLoadStratum(MapServerStratum.stratumName);
 
+interface TimeParams {
+  currentTime: number | undefined;
+  timeWindowDuration: number | undefined;
+  timeWindowUnit: string | undefined;
+}
+
 export default class ArcGisMapServerCatalogItem extends UrlMixin(
   DiscretelyTimeVaryingMixin(
     MinMaxLevelMixin(
@@ -393,14 +400,30 @@ export default class ArcGisMapServerCatalogItem extends UrlMixin(
     return result;
   }
 
-  @computed
-  private get _currentImageryParts(): ImageryParts | undefined {
-    const dateAsUnix: string | undefined =
+  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 currentTime = this.getCurrentTime();
+    const timeWindowDuration = this.timeWindowDuration;
+    const timeWindowUnit = this.timeWindowUnit;
+    const timeParams = {
+      currentTime,
+      timeWindowDuration,
+      timeWindowUnit
+    } 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 +442,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 +464,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 +475,52 @@ export default class ArcGisMapServerCatalogItem extends UrlMixin(
         return;
       }
 
+      function windowDurationInMs(
+        windowDuration: number | undefined,
+        timeWindowUnit: string | undefined
+      ): number | undefined {
+        if (
+          windowDuration === undefined ||
+          windowDuration === 0 ||
+          timeWindowUnit === undefined
+        ) {
+          return undefined;
+        }
+
+        const rawTimeWindowData: any = {};
+        rawTimeWindowData[timeWindowUnit] = windowDuration;
+        const duration = moment.duration(rawTimeWindowData).asMilliseconds();
+        if (duration === 0) {
+          return undefined;
+        } else {
+          return duration;
+        }
+      }
+
+      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?.timeWindowUnit
+        );
+        if (windowDuration !== undefined) {
+          params.time = getTimeWindowQueryString(currentTime, windowDuration);
+        } else {
+          params.time = currentTime;
+        }
       }
 
       const maximumLevel = scaleDenominatorToLevel(

lib/Traits/TraitsClasses/ArcGisMapServerCatalogItemTraits.ts

@@ -57,4 +57,20 @@ export default class ArcGisMapServerCatalogItemTraits extends mixTraits(
       "date range when layer in time-enabled."
   })
   maxRefreshIntervals: number = 1000;
+
+  @primitiveTrait({
+    name: "Time Window Duration",
+    description:
+      "Specify a time window duration when querying a time-enabled layer. A positive value for forward window from current time; A negative value for backward window.",
+    type: "number"
+  })
+  timeWindowDuration?: number;
+
+  @primitiveTrait({
+    name: "Time Window Unit",
+    description:
+      "The time window unit for the `Time Window Duration`. Any units supported by `moment` module are valid, such as, `year`, `month`, `week`, `day`, `hour`, etc. Will not query time with window if the unit is invalid or undefined.",
+    type: "string"
+  })
+  timeWindowUnit?: string;
 }

test/Models/Catalog/esri/ArcGisMapServerCatalogItemSpec.ts

@@ -451,7 +451,7 @@ describe("ArcGisMapServerCatalogItem", function () {
   });
 
   describe("time-enabled layer", function () {
-    it("can load a time-enabled layer", async function () {
+    it("can load a layer, querying time without window", async function () {
       runInAction(() => {
         item = new ArcGisMapServerCatalogItem("test", new Terria());
         item.setTrait(
@@ -466,6 +466,124 @@ describe("ArcGisMapServerCatalogItem", function () {
       }
       expect(item.startTime).toBe("2004-11-26T09:43:22.000000000Z");
       expect(item.stopTime).toBe("2019-11-03T14:00:00.000000000Z");
+      const expectedTimeQueryString = 1572789600000; // from json file
+      const imageryProvider = item.mapItems[0]
+        .imageryProvider as ArcGisMapServerImageryProvider;
+      expect(imageryProvider.parameters.time).toBe(expectedTimeQueryString);
+    });
+
+    it("can load a layer, querying time without window if timeWindowDuration is not defined", async function () {
+      runInAction(() => {
+        item = new ArcGisMapServerCatalogItem("test", new Terria());
+        item.setTrait(
+          CommonStrata.definition,
+          "url",
+          "http://example.com/cadastre_history/MapServer"
+        );
+        item.setTrait(CommonStrata.user, "timeWindowUnit", "year");
+      });
+      const defaultCurrentTime = 1572789600000; // from json file
+      await item.loadMapItems();
+      const expectedTimeQueryString = defaultCurrentTime;
+      const imageryProvider = item.mapItems[0]
+        .imageryProvider as ArcGisMapServerImageryProvider;
+      expect(imageryProvider.parameters.time).toBe(expectedTimeQueryString);
+    });
+
+    it("can load a layer, querying time without window if timeWindowUnit is not defined", async function () {
+      runInAction(() => {
+        item = new ArcGisMapServerCatalogItem("test", new Terria());
+        item.setTrait(
+          CommonStrata.definition,
+          "url",
+          "http://example.com/cadastre_history/MapServer"
+        );
+        item.setTrait(CommonStrata.user, "timeWindowDuration", 2);
+      });
+      const defaultCurrentTime = 1572789600000; // from json file
+      await item.loadMapItems();
+      const expectedTimeQueryString = defaultCurrentTime;
+      const imageryProvider = item.mapItems[0]
+        .imageryProvider as ArcGisMapServerImageryProvider;
+      expect(imageryProvider.parameters.time).toBe(expectedTimeQueryString);
+    });
+
+    it("can load a layer, querying time with forward window", async function () {
+      runInAction(() => {
+        item = new ArcGisMapServerCatalogItem("test", new Terria());
+        item.setTrait(
+          CommonStrata.definition,
+          "url",
+          "http://example.com/cadastre_history/MapServer"
+        );
+        item.setTrait(CommonStrata.user, "timeWindowDuration", 2);
+        item.setTrait(CommonStrata.user, "timeWindowUnit", "week");
+      });
+      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 layer, querying time with backward time window", async function () {
+      runInAction(() => {
+        item = new ArcGisMapServerCatalogItem("test", new Terria());
+        item.setTrait(
+          CommonStrata.definition,
+          "url",
+          "http://example.com/cadastre_history/MapServer"
+        );
+        item.setTrait(CommonStrata.user, "timeWindowDuration", -2);
+        item.setTrait(CommonStrata.user, "timeWindowUnit", "week");
+      });
+      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);
+    });
+
+    it("can load a layer, querying time without window if timeWindowDuration is 0", async function () {
+      runInAction(() => {
+        item = new ArcGisMapServerCatalogItem("test", new Terria());
+        item.setTrait(
+          CommonStrata.definition,
+          "url",
+          "http://example.com/cadastre_history/MapServer"
+        );
+        item.setTrait(CommonStrata.user, "timeWindowDuration", 0);
+        item.setTrait(CommonStrata.user, "timeWindowUnit", "year");
+      });
+      const defaultCurrentTime = 1572789600000; // from json file
+      await item.loadMapItems();
+      const imageryProvider = item.mapItems[0]
+        .imageryProvider as ArcGisMapServerImageryProvider;
+      expect(imageryProvider.parameters.time).toBe(defaultCurrentTime);
+    });
+
+    it("can load a layer, querying time without window if timeWindowUnit is invalid", async function () {
+      runInAction(() => {
+        item = new ArcGisMapServerCatalogItem("test", new Terria());
+        item.setTrait(
+          CommonStrata.definition,
+          "url",
+          "http://example.com/cadastre_history/MapServer"
+        );
+        item.setTrait(CommonStrata.user, "timeWindowDuration", 2);
+        item.setTrait(CommonStrata.user, "timeWindowUnit", "fortnight");
+      });
+      const defaultCurrentTime = 1572789600000; // from json file
+      await item.loadMapItems();
+      const imageryProvider = item.mapItems[0]
+        .imageryProvider as ArcGisMapServerImageryProvider;
+      expect(imageryProvider.parameters.time).toBe(defaultCurrentTime);
     });
   });