Changes between Version 10 and Version 11 of PetascopeTimeHandling

Timestamp:

Feb 27, 2014, 5:48:39 PM (10 years ago)

Author:

Piero Campalani

Comment:

second section on wcs

PetascopeTimeHandling

@@ -9 +9 @@
 Thanks to the [SecoreUserGuide SECORE] resolver, time can be embedded in the n-dimensional CRS space just as another dimension: temporal CRS definitions can be used in composition with geodetic ones to create a unique space-time aquarium for the coverage.
 
-Temporal CRSs (`gml:TemporalCRS`) are always 1D and are rather simple entities: in a few words, they count the amount of a certain time step from an epoch. No stratigraphic calendars, leap seconds, eras and eons are involved here: simple linear counting of time units. Time units are the Unit of Measure (UoM) of the reference system.
+Temporal CRSs (`gml:TemporalCRS`) are always 1D and are rather simple entities: in a few words, they count the amount of a certain time step from an epoch. No stratigraphic calendars, leap seconds, eras and eons are involved here: simple linear counting of time units. Time units are the Unit of Measure (!UoM) of the reference system.
 
 [[Image(temporalCrs.png, center, 70%)]]
@@ -21 +21 @@
 
    * [http://kahlua.eecs.jacobs-university.de:8080/def/crs/OGC/0/AnsiDate ANSI date] (`OGC:AnsiDate`) : linear count of days (labelled `'ansi'`) since 1^st^ of January 1601, 00h00 UTC (note that decimal coordinates are possible to reference fraction of the day).
-   * [http://kahlua.eecs.jacobs-university.de:8080/def/crs/OGC/0/AnsiDate ANSI date] (`OGC:Temporal`) : parametrized CRS for the user-friendly definition of a custom T-CRS: it resolves to a concrete definition of T-CRS as long as the ''epoch'' and the ''UoM'' are explicitly set in the query of the URI (and optionally an axis label and an axis direction: defaults are `'t'` and `'future'`). UoMs can be defines as either [http://unitsofmeasure.org/ucum.html UCUM] `c/s` codes or actionable URIs pointing to valid GML definition of UoMs; UCUM codes or URIs like http://www.opengis.net/def/uom/UCUM/0/<code> (which the OGC SISSVoc redirects to the UCUM web page) or codes are suggested here: our ISO timestamp parser relies on UCUM codes too.
+   * [http://kahlua.eecs.jacobs-university.de:8080/def/crs/OGC/0/AnsiDate ANSI date] (`OGC:Temporal`) : parametrized CRS for the user-friendly definition of a custom T-CRS: it resolves to a concrete definition of T-CRS as long as the ''epoch'' and the ''!UoM'' are explicitly set in the query of the URI (and optionally an axis label and an axis direction: defaults are `'t'` and `'future'`). !UoMs can be defines as either [http://unitsofmeasure.org/ucum.html UCUM] `c/s` codes or actionable URIs pointing to valid GML definition of !UoMs; UCUM codes or URIs like http://www.opengis.net/def/uom/UCUM/0/<code> (which the OGC SISSVoc redirects to the UCUM web page) or codes are suggested here: our ISO timestamp parser relies on UCUM codes too.
 
 For a full list of time resources under review by OGC-NA please visit [http://external.opengeospatial.org/twiki_public/TemporalDWG/TemporalCrsUris this page] (active participation is also appreciated via [https://lists.opengeospatial.org/mailman/listinfo/temporal mailing list]). After official acknowledgment of such resources, all of them will be provided by our resolver and additionally by the official 'opengis' servers.
@@ -30 +30 @@
 
    * the datum origin (we assume UTC default)
-   * the axis time step (`gml:CoordinateSystemAxis/@uom)
+   * the axis time step (`gml:CoordinateSystemAxis/@uom`)
    * the axis label (`gml:axisAbbrev`)
 
@@ -48 +48 @@
 == Using and understanding time in WCS/WCPS 
 
-..requests: double-quotes switch
-...support of time zones 
-...ISO date formatter with optional time (taken from [http://www.joda.org/joda-time/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateOptionalTimeParser() Joda-Time API]):
+Once a T-CRS has been successfully embedded in the overall native CRS of a coverage, the WCS/WCPS services will accept both numerical and time coordinates on the time axis/axes.
+
+In the first place, one should also be aware of the difference between the time resolution (!UoM) of the T-CRS and the adopted ''offset vector'' ruling the spacing along time for the coverage: on 1-norm vectors there is no such difference, however it is perfectly possible to use either a bigger vector (e.g. equal to 7 on a day-resolution T-CRS for weekly data) or a fractional one. For more on offset vectors l please refer to the ''Petascope'' [PetascopeUserGuide user guide].
+
+As with normal spatial axes, a WCS/WCPS subsets shall define numeric trimming and slicings on a CRS dimension. The [https://portal.opengeospatial.org/files/?artifact_id=50140 standard] however let the subset syntax adhere to EBNF [IETF 2616], allowing ''tokens'' inside double-quotes: on time dimensions then ISO:8601 datetime representations can be used in place of the usually less friendly numeric time coordinates. 
+
+Implementation-wise, the support for ISO datetime is extended by ''Petascope'' thanks to the [http://www.joda.org/joda-time/ Joda-Time] Java library. The datetime formatter used to convert literal to numeric time representations is the official ISO date formatter with optional time, which then permits dates only or dates plus time (plus time zone shits). When a time zone is not defined, the library takes the default time zone of the underlying JVM, hence it was decided to instead force a UTC default time zone, to avoid platform-dependent behaviors.
+
+Formally, the allowed input datetime strings are (taken from [http://www.joda.org/joda-time/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateOptionalTimeParser() Joda-Time API]):
  
 {{{
@@ -64 +70 @@
 }}}
 
-For examples see our WCS [browser:systemtest/testcases_services/test_wcs/queries systemtest queries] n: 27-28, 35-37.
+For practical examples see our related [browser:applications/petascope/src/test/java/petascope/util/TimeUtilTest.java unit tests] or our WCS [browser:systemtest/testcases_services/test_wcs/queries systemtest queries] n.{27-28, 35-37}.
 
-..responses: numeric time coords encoded with origin + offset vectors (+ foreseen the use of `gml:EnvelopeWithTimePeriod` #678)
+Regarding the responses to a WCS request, time is encoded in its numerical form. The T-CRS definition is the key to decode the meaning of such numbers: while sometimes well-known T-CRS can be used (as Unix time), the general formulas which is yielding time coordinate `t^` for a coverage `C` with offset vector `v_t` along time and using a T-CRS with epoch `O_t` and !UoM 't_uom`:
+
+{{{
+time(t^) = ("t^" - O_t)/(v_t*t_uom)
+"iso_datetime(t^)" = "O_t" + t^*("t_uom"*v_t)
+}}}
+
+Double quotes imply ISO:8601 representation, whereas unquoted variable refer to numeric time values.
+In order to ease the user, it is foreseen the use of `gml:EnvelopeWithTimePeriod` (see #678) to additionally provide literals of time in the bbox of a coverage.
+
 
 == Irregular time series