Support for requesting specific resolution in /cube endpoint

[lukas-phaf]

Use case

There is currently no way to indicate a specific resolution of the data to be returned by the /cube endpoint. We would like to indicate this with the resolution-x and resolution-y parameters, similar to the /corridor endpoint.

resolution-x=10 would request to return 10 points in the x direction, while resolution-x=0 would request the number of points in the original grid (which is probably what the API was intended to return if the parameter is not provided at all).

[m-burgoyne]

I think it will be essential allow a service to advertise that it supports this capability and inform end users of the range of valid query values. This could be achived by extending the Cube (and Corridor) data query sections in the Collections response. For instance:

"cube": {
  "link": {
    "href": "https://www.example.edr/collections/nwp-model/cube",
    "hreflang": "en",
    "rel": "data",
    "variables": {
      "title": "Cube query",
      "query_type": "cube",
      "output_formats": [
        "NetCDF",
        "GeoTiff"
      ],
      "x-resolutions": [0,5,10],
      "y-resolutions": [0,4,8],
      "default_output_format": "NetCDF",
      "crs_details": [
        {
          "crs": "EPSG:4326",
          "wkt": "GEOGCS[\"WGS 84\",DATUM[\"WGS_1984\",SPHEROID[\"WGS 84\",6378137,298.257223563,AUTHORITY[\"EPSG\",\"7030\"]],AUTHORITY[\"EPSG\",\"6326\"]],PRIMEM[\"Greenwich\",0,AUTHORITY[\"EPSG\",\"8901\"]],UNIT[\"degree\",0.0174532925199433,AUTHORITY[\"EPSG\",\"9122\"]],AUTHORITY[\"EPSG\",\"4326\"]]"
        }
      ]
    }
  }
}

If the a x-resolutions or y-resolutions attributes are not specifed then the functionality is not supported. If the query parameter is not specifed in the request the default response will be the native resolution of the data, this would also have the advatange of not breaking existing implementations.

[chris-little]

@lukas-phaf The approach that @m-burgoyne has suggested allows the collections to advertise that resolution is supported, so tht service implementers can choose to offer the option or not. This seems a better, more loosely coupled, approach than making resolution a hard wired parameter of the queries. What do you think?

[lukas-phaf]

I see the value of advertising this functionality as part of the collections response (data_queries section). But unless I am misunderstanding, the parameters still need to be added to the query for this to work. They should of course be optional, for backward compatibility.

As the resolution parameter in a /corridor query specifies the number of points to return in that dimension, I gave it the same meaning in the /cube endpoint (so 10 means I want 10 points back, and not that I want a point every 10 meters). But this means giving a list of supported resolution does not seem meaningful, as the difference in coordinate is also affected by the bbox size.

I do think it should also be possible to specify all resolutions are supported, if the collections is capable of providing interpolated values.

The use case we are looking for is to provide/limit the resolution of the returned data, and just trying to find what fits best in OGC EDR.

[m-burgoyne]

@lukas-phaf you are correct the query parameters would have be added to the /cube query. @chris-little the changes to data_queries section have two aims

• Allow a collection to advertise that it supports alternate data resolutions
• Allow a collection to provide a list of valid resolutions

I don't think it would be a good idea to allow a user of the API to enter any number for the resolution query parameters (and with hindsight this is also true for the /corridor query)

[lukas-phaf]

But this would mean redefining the resolution parameter to a "step size" (where providing supported resolutions would be natural), correct?

Although the supported "step size" would be different for each CRS (if multiple are supported).

[m-burgoyne]

We could specify that the step size units are defined by the CRS, this is the approach for the units of the values in the coords query parameter.

[lukas-phaf]

Yes, that makes sense. But wouldn't the supported step size be dependent on the CRS? 1 degree in latitude in WGS84 is very different from 1 meter in some projected CRS.

[m-burgoyne]

Good point, there would need to be an entry for every CRS supported for the collection, for instance:

"cube": {
  "link": {
    "href": "https://www.example.edr/collections/nwp-model/cube",
    "hreflang": "en",
    "rel": "data",
    "variables": {
      "title": "Cube query",
      "query_type": "cube",
      "output_formats": [
        "NetCDF",
        "GeoTiff"
      ],
      "resolution_intervals": {
        "EPSG:4326": {
            "x": [0,5,10],    
            "y": [0,4,8]
        },
        "EPSG:3857": {
            "x": [0,5000,10000],    
            "y": [0,4000,80000]
        }
      }
      "default_output_format": "NetCDF",
      "crs_details": [
        {
          "crs": "EPSG:4326",
          "wkt": "GEOGCS[\"WGS 84\",DATUM[\"WGS_1984\",SPHEROID[\"WGS 84\",6378137,298.257223563,AUTHORITY[\"EPSG\",\"7030\"]],AUTHORITY[\"EPSG\",\"6326\"]],PRIMEM[\"Greenwich\",0,AUTHORITY[\"EPSG\",\"8901\"]],UNIT[\"degree\",0.0174532925199433,AUTHORITY[\"EPSG\",\"9122\"]],AUTHORITY[\"EPSG\",\"4326\"]]"
        },
        {
          "crs": "EPSG:3857",
          "wkt": "PROJCS[\"WGS 84 / Pseudo-Mercator\",GEOGCS[\"WGS 84\",DATUM[\"WGS_1984\",SPHEROID[\"WGS 84\",6378137,298.257223563,AUTHORITY[\"EPSG\",\"7030\"]],AUTHORITY[\"EPSG\",\"6326\"]],PRIMEM[\"Greenwich\",0,AUTHORITY[\"EPSG\",\"8901\"]],UNIT[\"degree\",0.0174532925199433,AUTHORITY[\"EPSG\",\"9122\"]],AUTHORITY[\"EPSG\",\"4326\"]],PROJECTION[\"Mercator_1SP\"],PARAMETER[\"central_meridian\",0],PARAMETER[\"scale_factor\",1],PARAMETER[\"false_easting\",0],PARAMETER[\"false_northing\",0],UNIT[\"metre\",1,AUTHORITY[\"EPSG\",\"9001\"]],AXIS[\"Easting\",EAST],AXIS[\"Northing\",NORTH],EXTENSION[\"PROJ4\",\"+proj=merc +a=6378137 +b=6378137 +lat_ts=0 +lon_0=0 +x_0=0 +y_0=0 +k=1 +units=m +nadgrids=@null +wktext +no_defs\"],AUTHORITY[\"EPSG\",\"3857\"]]"
        }
      ]
    }
  }
}

This would have the added advantage of having the option to limit support for alternate resolutions to a subset of the CRS supported by the collection.

[chris-little]

@iandruska-ibl @ShaneMill1, @lukas-phaf , @tomkralidis @dblodgett-usgs and others, what do you think about these proposals?

[dblodgett-usgs]

At first glance, as long as it's the similar enough to the corridor approach to not add complexity to the spec, I'm fine with it.

[tomkralidis]

Echo @dblodgett-usgs, focusing on consistency with .../corridor.

[chris-little]

I suspect we may have missed an opportunity by not specifying the corridor in terms of half-width rather than the full width that we did. :-(

[iandruska-ibl]

I agree on adding resolution-x and resolution-y parameters to the /cube query. It would be a very useful feature. In fact, we already implemented the parameters long time ago in our server as an extension.

However, I am not sure what is the conclusion of the discussion above. If I read correctly, two different meanings of resolution-x and resolution-y parameters have been considered:

1. the parameters represent number of grid points in X,Y dimensions. This is consistent with the resolution-* parameters in the current /corridor implementation
2. the parameters represent step size. In this case the actual number of grid points on the output is the function of the crs, resolution-x and resolution-y parameters. This is inconsistent with the /corridor query, of course.

Which approach has been selected?

[lukas-phaf]

For me, the meaning of "resolution" seems to imply number of points (compare with "resolution of a screen"), but I am not a native English speaker.

I originally proposed "resolution" because of the consistency with corridor. Specifying step size is also an option, but I would not call that parameter "resolution", to avoid confusion with the /corridor endpoint.

[m-burgoyne]

I did confuse the issue by proposing different functionality and it would make sense to use different names for the query parameters if that approach was implemented. My concern with replicating the functionality defined for corridor is that it provides no constraints on the values a user could enter.

One approach would be to support the Stepping size option on both Cube and Corridor (whilst keeping the resolution-* on corridor for backward compatibility).

Or as originally requested add support for the resolution query parameters on Cube

[chris-little]

At EDR API SWG 92, 2023-01-26 agreed to add V1.2 label

[chris-little]

Pending more discussion and experimentation and use case to clarify the requirement(s) and consistency.

Currently there is a presumption that consistency with corridor is the strongest requirement.

[chris-little]

Close when PR #473 merged