Validate config vs collection description refinement/depth levels

[fmigneault]

@tik65536
I'm testing out the latest updates (very nice 👍)

I noticed in the following response that some values are null.

      "geometryDimension": null,
      "minScaleDenominator": null,
      "maxScaleDenominator": null,
      "minCellSize": null,
      "maxCellSize": null

Are they expected to be filled manually or calculated from the config? I set the following it the collection's definition:

        "min_refinement_level": 0,
        "max_refinement_level": 10,

Full content for context:

https://hirondelle.crim.ca/dggs-api/collections/manitoba-rcm-ard

{
  "id": "manitoba-rcm-ard",
  "title": "Manitoba RCM ARD",
  "description": "Analysis-Ready Data from Radarsat Constellation Mission over Manitoba",
  "attribution": null,
  "links": [
    {
      "href": "https://hirondelle.crim.ca/dggs-api/collections/manitoba-rcm-ard",
      "rel": "self",
      "type": "application/json",
      "hreflang": null,
      "title": "this document",
      "length": null
    },
    {
      "href": "https://hirondelle.crim.ca/dggs-api/collections/manitoba-rcm-ard/dggs",
      "rel": "[ogc-rel:dggrs-list]",
      "type": "application/json",
      "hreflang": null,
      "title": "DGGS list",
      "length": null
    }
  ],
  "extent": {
    "spatial": {
      "bbox": [
        [
          -98.0,
          49.0,
          -96.5,
          50.25
        ]
      ],
      "storageCrsBbox": null,
      "crs": "http://www.opengis.net/def/crs/OGC/1.3/CRS84",
      "grid": ""
    },
    "temporal": {
      "interval": [
        [
          "2025-09-01T00:00:00Z",
          "2025-10-05T00:00:00Z"
        ]
      ],
      "trs": "http://www.opengis.net/def/uom/ISO-8601/0/Gregorian",
      "grid": ""
    }
  },
  "itemType": "",
  "crs": [
    "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
  ],
  "storageCrs": "http://www.opengis.net/def/crs/OGC/1.3/CRS84",
  "dataType": null,
  "geometryDimension": null,
  "minScaleDenominator": null,
  "maxScaleDenominator": null,
  "minCellSize": null,
  "maxCellSize": null
}

[tik65536]

@fmigneault, Yes, those fields need to be set manually at the moment.

I have checked the Table B.8 — Elements of “OGC API — Common::CollectionDescription” for the geometryDimension field. I think we can hard-code it to 2 (surfaces) for a DGGS dataset? Since DGGS data is working on zones.

And for the minCellSize and maxCellSize, I don't know what we should return, since the unit is missing, and both values are real, which range from 0 to 1. That's not applicable to the DGGS dataset. Do you have any ideas?

I have no idea what minScaleDenominator and maxScaleDenominator are. Could you help give me some input on them?

[fmigneault]

I think it makes sense to have geometryDimension: 2 since the quantized zone values applies over the entire zone (similar to a pixel discretization).

My guess would be that minCellSize/maxCellSize would represent in this case the min/max "width" of the zones against available min/max refinement levels in that collection. DGGRID produces characteristic length scale (CLS) in grid statistics. Maybe those could be reported?

Note that the [0..1] indicates "omitted or 1" value for that field. It is not the value range. Any real number (eg: the CLS) can be used.

The ScaleDenominator represents the 1:<ScaleDenominator> zoom level to map real-world dimensions to pixels, assuming a standard pixel dimension of 0.28mm. Normally, we use it with width/height of the raster/pixels, but I guess it would be also use CLS in DGGS world. Something like: CLS = ScaleDenominator * 0.00028. Min/Max would be based on available zone levels refinements.

@jerstlouis I'd like for validation on these points. Since it is not "classical 2D lat/lon width/height", I am not 100% sure how it maps to the "1D DGGS zone-id" case.

[jerstlouis]

@fmigneault Regarding minCellSize / maxCellSize and minScaleDenominator / maxDenominator, the mapping of the DGGRS levels to these should be fixed, as returned by the DGGAL APIs:

getScaleDenominatorFromLevel

and

getMetersPerSubZoneFromLevel

with the latter converted to CRS units.

When invoking these methods you can either use the level of the sub-zones with depth 0, or specify the depth and the base refinement level. You can also use the DGGAL command-line dgg tool to check this: dgg isea7h_z7 level 14 -depth 0 or dgg isea7h_z7 level -depth 0 to see the table of all levels.
For the scale denominator, you can pass 0.28 mm/pixels or you can pass a different actual resolution of the display device / paper map. However, the min/maxScaleDenominator of the collection description implies 0.28 mm/pixel.

The unit of minCellSize / maxCellSize are the storageCrs (defaults to WGS84) unit.
So they are in degrees / pixel if you don't set storageCrs which defaults to WGS84, or meters / pixsel if you set it to most projected CRS using meters.

You could potentially use the CLS instead of the meters per sub-zone metric that DGGAL returns.
The DGGAL calculation is based on the width of square pixels rather than the diameter of a circle I think, so they should be relatively close e.g., mpp = sqrt(Pi) (CLS/2) = 0.8862269 CLS.

I'm not really sure whether the CLS should be used instead, considering that you could offer the same collection via OGC API - Coverages and OGC API - Maps as well, so these cells here were more in the context of traditional pixels, but especially if the collection is only available via DGGS, it should be fine to use the CLS (and since the values are so close anyways).

Regarding geometryDimensions, this is normally intended for vector data , but setting it to 2 for a 2D coverage considering it's the dimension of the individual cells with Value-Represents-Area should be fine.

@tik65536
Regarding the null values, in general I think it's better to not output the values at all if they are set to null. A simple != null check should do it. There are a lot more properties than these anyways in the latest collection description model.

Note that everything except the id and links in the collection description is optional, and the only additional requirement for OGC API - DGGS is to link to the /collections/{collectionId}/dggs if you offer the DGGS API for a particular collection.

DGGS clients generally would use the maxRefinementLevel in /collections/{collectionId}/dggs/{dggrsId} rather than the maxScaleDenominator / minScaleDenominator, minCellSize / maxCellSize, but it's good to include these for general discovery of the collection resolution (especially if you serve the collection through other OGC API data access mechanisms).

[fmigneault]

Thanks for the references for the parameters.

Regarding the null values, in general I think it's better to not output the values at all if they are set to null.

I disagree with this part. This is not what Requirement 10-B indicates as filter result.
The DGGS-JSON response should include them explicitly. That makes sense, otherwise we just cannot figure out which value is which when combining zone-depth yielding many sub-zones.

[jerstlouis]

@fmigneault I was not talking about the DGGS-JSON encoding, I was talking about the collection description JSON response properties.

Of course things get out of sync in the values array if you simply skip null values in DGGS-JSON.

Although Requirement 24 F should probably be taken with a grain of salt, in that if you need to distinguish between different types of null values, then it should be fine to use integers with x-ogc-nullValues indicating the meaning of null values in the schema.

[fmigneault]

@jerstlouis
I see. My bad for misunderstanding.

@tik65536
If you want to auto-remove null entries for fields that were omitted during instantiation of pydantic models, this is an example of the solution I found: https://github.com/stac-extensions/mlm/blob/93b54e9d7a7d658d5a7f7b725be569659f3f0a87/stac_model/base.py#L15-L58
Just make sure NOT to use the OmitIfNone annotation for cases that we want to keep the explicit null, such as the mentioned DGGS-JSON response model.

[jerstlouis]

@fmigneault

for cases that we want to keep the explicit null, such as the mentioned DGGS-JSON response model.

Would this also apply for values of an array though?

Isn't this OmitIfNone only for properties of an object?

[fmigneault]

@jerstlouis Indeed, only the properties directly under each model's definition. Nested array values would need another kind of check.

[tik65536]

@fmigneault, @jerstlouis, thanks for the input.

I have made the changes according to @fmigneault suggestion in #44 (comment).
Currently, I have applied it to the CollectionDesc only and will make the necessary changes for other schemas if needed.

Thanks,
Tik