| 3 | | The incoming `rasdaman 8.4` release will represent a watershed-release with respect to how ''Petascope'' handles time and more generally on how ''Petascope'' manages the coordinate reference systems of the coverages. That said, two separate sections are provided here to give guidance from both client and server viewpoint ''before'' and ''after'' the `8.4` release. |
| | 5 | In this page we will describe how time can be embedded in the definition of a spatio-temporal coverage for WCS and WCPS web services, by means of temporal Coordinate Reference Systems (CRSs). |
| | 6 | |
| | 7 | == Temporal CRSs |
| | 8 | |
| | 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. |
| | 10 | |
| | 11 | 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. |
| | 12 | |
| | 13 | [[Image(temporalCrs.png, center, 70%)]] |
| | 14 | |
| | 15 | Like geodetic datums bind the set of geographic coordinates to an absolute position on Earth (or planetary object), temporal datums link the temporal axis to an absolute moment in time. Indeed a temporal datum is essentially an "origin" (the epoch) expressed through an ISO:8601 datetime representation. Technically, this representation is of type [http://www.schemacentral.com/sc/xsd/t-xsd_dateTime.html xsd:dateTime], which says: |
| | 16 | |
| | 17 | ''The type `xsd:dateTime` represents a specific date and time in the format `CCYY-MM-DDThh:mm:ss.sss`, which is a concatenation of the date and time forms, separated by a literal letter `T`. All of the same rules that apply to the date and time types are applicable to `xsd:dateTime` as well. |
| | 18 | An optional time zone expression may be added at the end of the value. The letter `Z` is used to indicate Coordinated Universal Time (UTC). All other time zones are represented by their difference from Coordinated Universal Time in the format `+hh:mm`, or `-hh:mm`. These values may range from `-14:00` to `14:00`. For example, US Eastern Standard Time, which is five hours behind UTC, is represented as `-05:00`. If no time zone value is present, it is considered unknown; it is not assumed to be UTC.'' |
| | 19 | |
| | 20 | At the time being, [http://kahlua.eecs.jacobs-university.de:8080/def/crs/OGC/0/ we provide] a first basic set of Temporal CRSs (T-CRSs) which (among others) are under review process by the OGC-NA authority and represents part of the effort of the newly born (public) OGC [http://external.opengeospatial.org/twiki_public/TemporalDWG/WebHome Temporal Domain Working Group]. These definitions are: |
| | 21 | |
| | 22 | * [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). |
| | 23 | * [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. |
| | 24 | |
| | 25 | 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. |
| | 26 | |
| | 27 | Still, especially thanks to our customizable `OGC:Temporal` CRS, it is possible to start deploying spatio-temporal (but also purely temporal) coverages via `rasdaman`/''Petascope''. |
| | 28 | |
| | 29 | While all kinds of T-CRS are possible with `OGC:Temporal`, you might decide to create your own definitin so to have a more meaningful URI. This can be easily achieved: in spite of the verbose GML representation, what is actually important for Petascope in a T-CRS is: |
| | 30 | |
| | 31 | * the datum origin (we assume UTC default) |
| | 32 | * the axis time step (`gml:CoordinateSystemAxis/@uom) |
| | 33 | * the axis label (`gml:axisAbbrev`) |
| | 34 | |
| | 35 | After defining it, then you might want to replace the equivalent Unix Time T-CRS with `OGC:Temporal` with your URI: |
| | 36 | |
| | 37 | * ~~[http://kahlua.eecs.jacobs-university.de:8080/def/crs/OGC/0/Temporal?epoch=%222013-02-20T00:00:00Z%22%26uom=%22min%22%26label=%22simulation_time%22 http://kahlua.eecs.jacobs-university.de:8080/def/crs/OGC/0/Temporal?epoch="1970-01-01T00:00:00Z"&uom="s"&label="unix_time"]~~ |
| | 38 | * [http://www.schemacentral.com/sc/niem21/e-gml32_TemporalCRS.html http://mydomain.com/def/crs/MYAUTHORITY/<version>/UnixTime] |
| | 39 | |
| | 40 | '''Parametrizations''' are also useful when one needs to compound together more than one T-CRS of the same kind: this can happen especially e.g. when numerical models are applied daily (real time axis) targeting a set of future days (simulation time axis). Using the same T-CRS makes sense here (let's pick `OGC:AnsiDate` for example), but in order to avoid a clash in the labels of the axes we need to actually use two different URIs in the composition of the CRS, for instance: |
| | 41 | |
| | 42 | * real-time : [http://kahlua.eecs.jacobs-university.de:8080/def/crs/OGC/0/AnsiDate?axis-label=%22real_time%22 http://kahlua.eecs.jacobs-university.de:8080/def/crs/OGC/0/AnsiDate?axis-label="real_time"] |
| | 43 | * simulation-time : [http://kahlua.eecs.jacobs-university.de:8080/def/crs/OGC/0/AnsiDate?axis-label=%22simulation_time%22 http://kahlua.eecs.jacobs-university.de:8080/def/crs/OGC/0/AnsiDate?axis-label="simulation_time"] |
| | 44 | |
| | 45 | For further info on CRS parametrization and composition, see the SECORE [SecoreUserGuide user guide] and also [wiki:IndexCrss#Changingaxislabels] section. |
| 6 | | [[span(NOTE: ''No improvements or feature changes will be applied for maintenance of the 8.4 release.'', style=color: Black; font-size: 80%)]] |
| | 48 | == Using and understanding time in WCS/WCPS |
| | 49 | |
| | 50 | ..requests: double-quotes switch |
| | 51 | ...support of time zones |
| | 52 | ...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]): |
| | 53 | |
| | 54 | {{{ |
| | 55 | date-opt-time = date-element ['T' [time-element] [offset]] |
| | 56 | date-element = std-date-element | ord-date-element | week-date-element |
| | 57 | std-date-element = yyyy ['-' MM ['-' dd]] |
| | 58 | ord-date-element = yyyy ['-' DDD] |
| | 59 | week-date-element = xxxx '-W' ww ['-' e] |
| | 60 | time-element = HH [minute-element] | [fraction] |
| | 61 | minute-element = ':' mm [second-element] | [fraction] |
| | 62 | second-element = ':' ss [fraction] |
| | 63 | fraction = ('.' | ',') digit+ |
| | 64 | }}} |
| | 65 | |
| | 66 | For examples see our WCS [browser:systemtest/testcases_services/test_wcs/queries systemtest queries] n: 27-28, 35-37. |
| | 67 | |
| | 68 | ..responses: numeric time coords encoded with origin + offset vectors (+ foreseen the use of `gml:EnvelopeWithTimePeriod` #678) |
| | 69 | |
| | 70 | == Irregular time series |
| | 71 | |
| | 72 | ..independent of time: irregular aligned grids can be defined (see ''Petascope'' [PetascopeUserGuide user guide].) the CRS is also independent of the topology of the referenced grid.. |
| | 73 | To import ... additional coefficients will be ... so that the numerical coordinate is: |
| | 74 | `formula: ...` |
| | 75 | See also ''rasgeo'' [RasgeoUserGuide user guide]. |
| 9 | | == How `rasdaman_8.4` handles time == |
| 10 | | |
| 11 | | A temporal dimension is used to integrate time into the [https://portal.opengeospatial.org/modules/admin/license_agreement.php?suppressHeaders=0&access_license_id=3&target=http://portal.opengeospatial.org/files/?artifact_id=41438 coverage model] in case of series of spatial datasets. [[BR]] |
| 12 | | __'''Dates'''__ in ''WCS !GetCoverage'' subsettings are currently supported in the format |
| 13 | | `"`'''[[span(`t(YYYY-MM-DD[,YYYY-MM-DD])`, style=color: DodgerBlue; font-size: 90%)]]'''`"` |
| 14 | | on a temporal axis. |
| 15 | | |
| 16 | | Finer temporal resolutions (hour, minutes, etc.) or irregular time spacing are __not__ supported, however ''N''-days resolution are accepted. |
| 17 | | |
| 18 | | A KVP ''!GetCoverage'' example: |
| 19 | | {{{ |
| 20 | | #!div style="background: GhostWhite; border: 5px ridge; text-align: center; width: 70%; margin-left: auto ; margin-right: auto ;" |
| 21 | | {{{ |
| 22 | | #!html |
| 23 | | <h2>...&service=WCS&request=GetCoverage&<u><span style="color: MediumBlue;">subset=<span style="color: DodgerBlue;">t</span>(2010-06-19)</span></u>&...</h2> |
| 24 | | }}} |
| 25 | | }}} |
| 26 | | |
| 27 | | |
| 28 | | A temporal axis is thus recognized by ''Petascope'' by its |
| 29 | | "'''[[span(`t`, style=color: DodgerBlue; font-size: 90%)]]'''" label (binding the label in the request subset and the value in |
| 30 | | [[span(`petascopedb::ps_domain.name`, style=color: IndianRed; font-size: 90%)]]), on which it assumes its coordinates are [http://en.wikipedia.org/wiki/Julian_day#Alternatives ANSI date] numbers. [[BR]] |
| 31 | | The `gml:RectifiedGridCoverage` of a response including a time-dimension fills temporal coordinates with ANSI integers at the domain ''"external CRS"'' level (e.g. `gml:offsetVector`, `gml:boundedBy`), and `rasdaman` indexes at the grid level (`gml:GridEnvelope`). [[BR]] |
| 32 | | Direct grid indexes can as well be directly set in the WCS request by forcing the "CRS:1" coordinate system (the current label for the internal grid-CRS of a coverage), like: "`...subset=t,CRS:1(0,10)...`") #298. |
| 33 | | |
| 34 | | The recommended setup for enabling such behavior in ''Petascope'' is to: |
| 35 | | |
| 36 | | * have a regular time axis labeled __''t''__; |
| 37 | | * set the CRS associated with the temporal axis to some __CRS≠"CRS:1"__ (the current label for the internal grid-CRS of a coverage); |
| 38 | | * set proper ANSI bounds in [[span(`petascopedb::ps_domain`, style=color: IndianRed; font-size: 90%)]]: the ratio between these bounds and the `sdom` along the temporal dimension in `rasdaman` will determine the resolution. |
| 39 | | |
| 40 | | Alternatively, a user could define own out of band time management by either: |
| 41 | | * publishing temporal metadata inside the [[span(`gmlcov:metadata`, style=color: SeaGReen; font-size: 90%)]] of a ''WCS !DescribeCoverage'' response; |
| 42 | | * manage time entirely ''"in house"''. |
| 43 | | |
| 44 | | The features in future releases are going to provide custom temporal resolutions with regular/irregular spacing, by implementing a new design for the management of spatiotemporal CRSs, and supporting the new [[span(`GML 3.3`, style=color: SeaGReen; font-size: 90%)]] [https://portal.opengeospatial.org/files/?artifact_id=46568 referenceable grids]. See next section for further insight. |
| 45 | | |
| 46 | | === Numerical examples === |
| 47 | | |
| 48 | | ==== 1-day resolution : __Time series of ''daily'' 2D aggregates from 1st January 2010 to 31st December 2010__ ==== |
| 49 | | i. set the ''label'' ([[span(`petascopedb::ps_domain.name`, style=color: IndianRed; font-size: 90%)]]) of the temporal axis to "'''[[span(`t`, style=color: DodgerBlue; font-size: 90%)]]'''"; |
| 50 | | i. set [[span(`ps_domain`, style=color: IndianRed; font-size: 90%)]] bounds ([[span(`numlo`, style=color: IndianRed; font-size: 90%)]], [[span(`numhi`, style=color: IndianRed; font-size: 90%)]]) to the correspondent ANSI dates [[span([`149385:149749]`, style=color: black; font-size: 90%)]]; |
| 51 | | i. set the CRS of the temporal axis to some value other than `CRS:1`; |
| 52 | | i. now requests can be done with [[span(`YYYY-MM-DD`, style=color: DodgerBlue; font-size: 90%)]] temporal subsets. |
| 53 | | |
| 54 | | ==== N-days resolution : __Time series of ''weekly'' 2D aggregates from 1st January 2010 to 31st December 2010__ ==== |
| 55 | | i. set the ''label'' ([[span(`petascopedb::ps_domain.name`, style=color: IndianRed; font-size: 90%)]]) of the temporal axis to "'''[[span(`t`, style=color: DodgerBlue; font-size: 90%)]]'''"; |
| 56 | | i. set [[span(`ps_domain`, style=color: IndianRed; font-size: 90%)]] bounds ([[span(`numlo`, style=color: IndianRed; font-size: 90%)]], [[span(`numhi`, style=color: IndianRed; font-size: 90%)]]) to the correspondent ANSI dates [[span(`[149385:`, style=color: black; font-size: 90%)]][[span(`149748`, style=color: black; font-size: 90%; text-decoration:underline)]][[span(`]`, style=color: black; font-size: 90%)]]; |
| 57 | | i. set the CRS of the temporal axis to some value other than `CRS:1`; |
| 58 | | i. now requests can be done with [[span(`YYYY-MM-DD`, style=color: DodgerBlue; font-size: 90%)]] temporal subsets. |
| 59 | | |
| 60 | | == Ongoing development (towards `rasdaman_9.0`) == |
| 61 | | |
| 62 | | See [attachment:TemporalCRSs.pdf slides] for first concepts and examples. |
| 63 | | |
| 64 | | {{{ |
| 65 | | #!comment |
| 66 | | HTML colors: http://www.w3schools.com/html/html_colornames.asp |
| 67 | | }}} |
| | 78 | See attachments for farther resources on the topic. |
