[Geoserver-devel] Elevation Units in WMS Capabilities

GeoServer GeoServer Developer
1

Hello all,

I created a custom coverage store for forecasted METOC data and use the TIME and ELEVATION dimensions pretty heavily. The problem I have is that not all of the data has elevation in meters. Some data has elevation in mbar, C, etc. The units and unitSymbol in the WMS (1.3.0) capabilities document is hard coded to meters in DimensionHelper.java. I am planning on imlemeting a solution to this and submitting a patch but, since it touches various component, I thought I’d run it by the GeoServer developers first.

To be a complete capability it requires adding functionality to the admin web UI, the REST interface, and capabilities document(s) transformer. Since the WMS Specification requires the units for TIME be ISO8601 without a unitSymbol I plan on only adding these fields to the ELEVATION web UI.

The units/unitSymbol will need to be stored in the DimensionInfoImpl class so it can be retrieved the capabilities transformer. Adding these attributes to the capabilities document is relatively simple.

<Dimension name="elevation" default="2.0" units="unit_name" unitSymbol="unit_symbol">2.0,4.0,6.0</Dimension>

As far as adding the functionality to the REST interface it would look like this:

<metadata>
<entry key="elevation">
<dimensionInfo>
<enabled>true</enabled>
<attribute>elev_attribute</attribute>
<presentation>LIST</presentation>
<units>unit_name</units>
<unitSymbol>unit_symbol</unitSymbol>
</dimensionInfo
</entry>
</metadata>

The examples in the documentation of adding a coverage via the REST API do not include the TIME/ELEVATION dimensions so I was panning on adding this including the units/unitSymbol.

I have already read Annex C of the WMS 1.3.0 Specification about handling multi-dimensional data. I will also take into account WMS 1.1.1. Are there any potential pitfalls to adding this unit support?

What is the best process for submitting a patch? Create a ticket now and attach the patch when I’m done or wait to create the ticket until the patch is finished? The reason I ask is because I am under the impression that JIRA tickets with patches (and unit tests) attached have a higher priority. As far as I can tell there is no way to check the “patch/unit test attached” check box after the ticket is created. Also is the preferred method of patching to use github and fork/pull request or attach an svn diff to the JIRA ticket.

Thanks in advance,

Michael Romero
Forward Slope Inc.

2

On Tue, Jun 26, 2012 at 10:26 PM, Michael Romero <mromero@anonymised.com> wrote:

I created a custom coverage store for forecasted METOC data and use the TIME and ELEVATION dimensions pretty heavily.

Nice. Is this store something that could be of general use? What kind of data source does it use? (just curious)

The problem I have is that not all of the data has elevation in meters. Some data has elevation in mbar, C, etc. The units and unitSymbol in the WMS (1.3.0) capabilities document is hard coded to meters in DimensionHelper.java. I am planning on imlemeting a solution to this and submitting a patch but, since it touches various component, I thought I’d run it by the GeoServer developers first.

Good call :slight_smile:

To be a complete capability it requires adding functionality to the admin web UI, the REST interface, and capabilities document(s) transformer. Since the WMS Specification requires the units for TIME be ISO8601 without a unitSymbol I plan on only adding these fields to the ELEVATION web UI.

Makes sense, but wondering if it would not be better to have a single drop down with the list of the ISO units.
Isn’t the unit symbol implied by the chosen unit?

The units/unitSymbol will need to be stored in the DimensionInfoImpl class so it can be retrieved the capabilities transformer. Adding these attributes to the capabilities document is relatively simple.

<Dimension name="elevation" default="2.0" units="unit_name" unitSymbol="unit_symbol">2.0,4.0,6.0</Dimension>

As far as adding the functionality to the REST interface it would look like this:

<metadata>
<entry key="elevation">
<dimensionInfo>
<enabled>true</enabled>
<attribute>elev_attribute</attribute>
<presentation>LIST</presentation>
<units>unit_name</units>
<unitSymbol>unit_symbol</unitSymbol>
</dimensionInfo
</entry>
</metadata>

The examples in the documentation of adding a coverage via the REST API do not include the TIME/ELEVATION dimensions so I was panning on adding this including the units/unitSymbol.

I have already read Annex C of the WMS 1.3.0 Specification about handling multi-dimensional data. I will also take into account WMS 1.1.1. Are there any potential pitfalls to adding this unit support?

Sigh… yes, there are, it is a combination of bad design on my part and bad timing vs the 2.2.0 release.
The above would be API changes, since you’d need new fields,
which are not allowed anymore now since we are releasing a RC this week,
tomorrow if all goes well, which means trunk is becoming the new stable series and its API is cast in stone.
In particular we have to ensure that it’s possible to move forwards and backwards within the stable
series using the same data dir, so no new explicit configuration fields can be added

Normally we handle that by using the open ended MetadataMap that is available in most CatalogInfo
objects, sticking the new values in it on the stable series, and add the new fields on the unstable one
so that the XML persistence format does not change along a stable series
… unfortunately I forgot to add that into DimensionInfo, and doing that now is yet another API change…

The only clean way to handle this now is to make it happen on the new trunk, which is going to become
2.3.0 in six months, once we branch off the current one to a new 2.2.x branch
(see also GSIP 77, time boxed releases, on how we are going to handle API
changes from now on).

What is the best process for submitting a patch? Create a ticket now and attach the patch when I’m done or wait to create the ticket until the patch is finished? The reason I ask is because I am under the impression that JIRA tickets with patches (and unit tests) attached have a higher priority. As far as I can tell there is no way to check the “patch/unit test attached” check box after the ticket is created. Also is the preferred method of patching to use github and fork/pull request or attach an svn diff to the JIRA ticket.

There is not official policy but yes, during the weekend I try to review jiras that have patches attached.
There was a way to locate jiras with attachments, and I was looking at that to find the tickets to review,
now it’s gone due to a Jira upgrade but I’ve found that looking for recently created/modified tickets that
have the word “patch” in the works well enough

Cheers
Andrea

–
Ing. Andrea Aime
GeoSolutions S.A.S.
Tech lead

Via Poggio alle Viti 1187
55054 Massarosa (LU)
Italy

phone: +39 0584 962313
fax: +39 0584 962313
mob: +39 339 8844549

http://www.geo-solutions.it
http://geo-solutions.blogspot.com/
http://www.youtube.com/user/GeoSolutionsIT
http://www.linkedin.com/in/andreaaime
http://twitter.com/geowolf

3

The data is in the form of GeoTiffs so there’s nothing new in terms of data processing. The reason we needed a custom store is because we are dealing with 300,000+ files that change every 6 hours. These files are stored at a METOC data center and we download the files on demand when the user requests a layer. We added time and elevation modeled after the Image Mosaic store but using a DB instead of shape file and that got the number of layers down to about 1,500. I don’t think it would be much use to the community because of how specific the data source is. However, I’ll put some more thought into how to generalize the concept. I thought about doing that at first but there is no finite list because the WMS specification is pretty flexible: The specification actually allows anything but suggests using units from the UCUM. No worries, I wasn’t planning on getting this into the 2.2.0 release. I’ve been following the emails on the devel list :slight_smile: I can go ahead and add this to the DimensionInfo while I’m at it. That’s the plan. Thanks for the input, Michael Romero Forward Slope Inc.

···

On 06/27/2012 01:59 PM, Andrea Aime wrote:On Tue, Jun 26, 2012 at 10:26 PM, Michael Romero

Nice. Is this store something that could be of general use? What kind of data source does it use? (just curious)

Makes sense, but wondering if it would not be better to have a single drop down with the list of the ISO units.
Isn’t the unit symbol implied by the chosen unit?

If the dimensional quantity has units, unit names should be taken from the Unified Code for Units of Measure
(UCUM) if UCUM has an appropriate entry. When UCUM is used, the mandatory units attribute shall be an
appropriate entry from the UCUM “name” column.

If present, the unitSymbol shall be a 7-bit ASCII character string. When UCUM is used, the unitSymbol shall
be the entry from the UCUM “c/s” column (case-sensitive abbreviation) corresponding to the UCUM name.
UCUM prefix names and symbols may be present as well.

Sigh… yes, there are, it is a combination of bad design on my part and bad timing vs the 2.2.0 release.
The above would be API changes, since you’d need new fields,
which are not allowed anymore now since we are releasing a RC this week,
tomorrow if all goes well, which means trunk is becoming the new stable series and its API is cast in stone.
In particular we have to ensure that it’s possible to move forwards and backwards within the stable
series using the same data dir, so no new explicit configuration fields can be added

Normally we handle that by using the open ended MetadataMap that is available in most CatalogInfo
objects, sticking the new values in it on the stable series, and add the new fields on the unstable one
so that the XML persistence format does not change along a stable series
… unfortunately I forgot to add that into DimensionInfo, and doing that now is yet another API change…

The only clean way to handle this now is to make it happen on the new trunk, which is going to become
2.3.0 in six months, once we branch off the current one to a new 2.2.x branch
(see also GSIP 77, time boxed releases, on how we are going to handle API
changes from now on).

4

On Fri, Jun 29, 2012 at 1:30 AM, Michael Romero <mromero@anonymised.com> wrote:

On 06/27/2012 01:59 PM, Andrea Aime wrote:On Tue, Jun 26, 2012 at 10:26 PM, Michael Romero

Nice. Is this store something that could be of general use? What kind of data source does it use? (just curious)

The data is in the form of GeoTiffs so there’s nothing new in terms of data processing. The reason we needed a custom store is because we are dealing with 300,000+ files that change every 6 hours. These files are stored at a METOC data center and we download the files on demand when the user requests a layer. We added time and elevation modeled after the Image Mosaic store but using a DB instead of shape file and that got the number of layers down to about 1,500. I don’t think it would be much use to the community because of how specific the data source is. However, I’ll put some more thought into how to generalize the concept.

I see. Btw, the image mosaic store can also keep the tile index in a database, actually, against any data store supported by Geotools, though it’s mostly tested against PostGIS and Oracle

Makes sense, but wondering if it would not be better to have a single drop down with the list of the ISO units.
Isn’t the unit symbol implied by the chosen unit?

I thought about doing that at first but there is no finite list because the WMS specification is pretty flexible:

If the dimensional quantity has units, unit names should be taken from the Unified Code for Units of Measure
(UCUM) if UCUM has an appropriate entry. When UCUM is used, the mandatory units attribute shall be an
appropriate entry from the UCUM “name” column.

If present, the unitSymbol shall be a 7-bit ASCII character string. When UCUM is used, the unitSymbol shall
be the entry from the UCUM “c/s” column (case-sensitive abbreviation) corresponding to the UCUM name.
UCUM prefix names and symbols may be present as well.

The specification actually allows anything but suggests using units from the UCUM.

I see, make sense, thanks for the explanation

Sigh… yes, there are, it is a combination of bad design on my part and bad timing vs the 2.2.0 release.
The above would be API changes, since you’d need new fields,
which are not allowed anymore now since we are releasing a RC this week,
tomorrow if all goes well, which means trunk is becoming the new stable series and its API is cast in stone.
In particular we have to ensure that it’s possible to move forwards and backwards within the stable
series using the same data dir, so no new explicit configuration fields can be added

No worries, I wasn’t planning on getting this into the 2.2.0 release. I’ve been following the emails on the devel list :slight_smile:

Ha ha, I guess it has been entertaining :wink:

Normally we handle that by using the open ended MetadataMap that is available in most CatalogInfo
objects, sticking the new values in it on the stable series, and add the new fields on the unstable one
so that the XML persistence format does not change along a stable series
… unfortunately I forgot to add that into DimensionInfo, and doing that now is yet another API change…

I can go ahead and add this to the DimensionInfo while I’m at it.

That would be great

The only clean way to handle this now is to make it happen on the new trunk, which is going to become
2.3.0 in six months, once we branch off the current one to a new 2.2.x branch
(see also GSIP 77, time boxed releases, on how we are going to handle API
changes from now on).

That’s the plan.

+1 on the plan then!

Cheers
Andrea

–
Ing. Andrea Aime
GeoSolutions S.A.S.
Tech lead

Via Poggio alle Viti 1187
55054 Massarosa (LU)
Italy

phone: +39 0584 962313
fax: +39 0584 962313
mob: +39 339 8844549

http://www.geo-solutions.it
http://geo-solutions.blogspot.com/
http://www.youtube.com/user/GeoSolutionsIT
http://www.linkedin.com/in/andreaaime
http://twitter.com/geowolf