The definition of maxRelativeDepth of Dggrs #80
Comments
tik65536
changed the title
There is a distinction between the DGGRS definition (as per the examples in Annex B linked with So these properties (of the DGGRS description) serve two completely different purposes: maxRelativeDepth is the greatest relative depths that the server accepts to return for zone data query, independently of the level of the zone for which data is being requested, and independently of the native resolution of the data. For example, if requesting data from a level 0 zone, for data that goes down to level 20, if maxRelativeDepth is 10, the server will reject requests for maxRefinementLevel on the other hand would normally be specific to a particular dataset or collection, and indicates the native resolution of the data. It does not necessarily mean that the server will reject requests beyond this level (it could upsample the data), but it is allowed to do so -- see Permission 1. So in the example above, maxRefinementLevel would be 20, and for a GET request on |
|
@jerstlouis Thx. If I understand correctly, it restricts the maximum zone level we can include in the response from the current zone level. |
For Zone Data Retrieval, the level of the responses should always be well-defined. If the client did not specify a If the server does not conform to the "Custom Depths" requirement class, that is the only valid option. If the client did specify a If the client specified a valid
We could add some examples just below the recommendation if that would be useful. |
Sorry, it causes confusion for me right now. Let's, for example dggrid with z7string. It determines the zone level by the number of strings (omit the first 2 from left) Example: /dggrs/IGEO7/0023262345/data, so the zone level will be 8 (8 chars: 23262345)
Carry from the above assumption (zone level is determined from zone ID); the zone-depth parameter will be the relative zone level based on the base zone level. For example : Example: /dggrs/IGEO7/0023262345/data?zone-depth=2 It will return data with zone level 10 (8 + 2), and if the maxRelativeLevel is set with 11, then it should be a valid request. That's the logic from your first reply.
|
8 from the The data has to be returned at 8 + defaultDepth -- whatever defaultDepth is set to in Depending on the refinement ratio of your DGGRS, different defaultDepth values might be more appropriate. We try to return ~64k values by default, similar to typical 256x256 tiles. That's a defaultDepth of 10 for ISEA3H, 5 for ISEA9R and 8 for GNOSISGlobalGrid. For ISEA7H / H3, you could pick 5 (7^5 = 16,807) or 6 (7^6 = 117,649). The level of the parent clipping zone (to which the relative depth is added to obtain the absolute depth of the sub-zones for which individual values are being returned) is always inferred from the |
That is not correct. The relative depth here is the 2 specified in If you meant maxRefinementLevel, then the server would be allowed to either reject it or upsample if that's set to 9 per Permission 1. |
|
Hey ~ Thx. I misunderstood the spec at the very beginning. So, in terms of the flow on how to retrieve data:
However, the point you mentioned above on returning one value per API is not the main reason. For example, multiple data can still be associated with zone ID at level 8; it depends on whether the data provider will aggregate the data before return. In general, it will benefit development if the API are more intuitive ( like what you sent, what you will get). For the above logic, I suggest aligning the other's API endpoint with {zoneID} supported to have the same logic. Otherwise, it confuses people a lot. Thx , Tik |
I'm not clear on where the confusion lies, or what you mean by the first sentence. I do not believe significant API changes are justified or necessary at this stage. First we should discuss to clarify how the API is intended to be used, then you could help us facilitate readers' understanding by pointing out where we need additional clarifications.
The Zone Data Retrieval is intended to retrieve multiple data values in a single request. So necessarily, there is a parent level for the zone of interest -- the
For a DGGS API client with a built-in understanding of a DGGRS supported by the server, for a pure data visualization scenario, there would be no need to first perform a Zone Query. The client would instead use its own library to figure out which zones at which level it wishes to visualize. If the client is 3D, the region of interest would likely not be a bounding box or at the same refinement level either. When doing this, the client would again pick zones of a coarser level compared to the number of pixels it wishes to represent distinctly on the screen. If we take the example of ISEA3H hexagons with a depth of 10 containing about 64k sub-zones, it could compute hexagons at refinement levels where each hexagon that is displayed on the screen occupies roughly about 64k pixels, before retrieving data at level 10 for each of these larger zones. Requesting zones individually would mean 64,000 times more HTTP requests (!). Conceptually, the Zone Data retrieval is very similar to OGC API - Tiles and WMTS, with the exception that DGGRS are much more flexible than 2D Tile Matrix Sets e.g., zones do not need to be rectangular. If we take the WorldCRS84Quad 2DTMS for example, which covers the whole world in OGC:CRS84, and a corresponding hypothetical DGGRS (the GNOSISGlobalGrid is actually very similar to this, except for starting at level 1 of WorldCRS84Quad and handling the polar regions better). WorldCRS84Quad, like many 2DTMS, defines tiles as being 256x256. This would correspond to a defaultDepth or The sub-zones of DGGS Zone Data corresponds to the individual pixels or cells inside the tile, whereas the There is a very similar analogy between the internal grid of Mapbox Vector Tiles and the sub-zones used to quantize coordinates of vector geometry with DGGS-FG-JSON. There is also no concept of default or relative zone depth with
The client could potentially perform aggregation as a use case, but I don't understand why you bring up aggregation here?
The assumption for Zone Data Retrieval is that the data is quantized to the sub-zone level -- sub-zone level = parent level from For the DGGS-JSON (raster) encoding (and I would expect the same for Zarr), this means one value (or set of properties/variables/fields) per sub-zone. The value for coarser refinement level would normally be some aggregation of the corresponding values for finer refinement levels. For the DGGS-FG-JSON (vector) encoding, this means that geometry points are precise to the sub-zone. The properties associated with vector features would usually be the same at all refinement levels (with potential exceptions for special generalization strategies), but the geometry naturally gets generalized by the coarser precision of the sub-zones. Representations of Zone Data in other formats are for facilitating interoperability with non-DGGS clients, and the API implementations do their best to return an equivalent representation of the data constrained by the limitations of the particular format. |
The DGGRS definition included both "maxRefinementLevel" and "maxRelativeDepth", which from the description of the yaml file, they are similar. Both define the max refinement level in an absolute or relative sense. But we can always check if the request zone_level + relative_level >= maxRefinementLevel, without the use maxRelativeDepth. So, what's the actual usage of maxRelativeDepth ?
Another interpretation from the API implementation perspective is to limit the number of level returns in one API call. But that is not Dggrs definition related.
Thx,
Tik
The text was updated successfully, but these errors were encountered: