Update clause_specification_text.adoc

[chris-little]

Added example of a polygon with holes
Added text clarifying use of MultiPolygon and improved examples
Minor text edits

[awarde96]

I think this looks good and clarifies the multiPolygon, maybe to be more explicit we could add the range for the Polygon example with holes that there is only a single value in the range? Not fully needed but maybe helps people understand it is a single polygon.

{
  "type" : "Coverage",
  "domain" : {
    "type": "Domain",
    "domainType": "Polygon",
    "axes": {
      "composite": {
        "dataType": "polygon",
        "coordinates": ["x","y"],
        "values": [
          [ [ [100.0, 0.0], [101.0, 0.0], [101.0, 1.0], [100.0, 1.0], [100.0, 0.0] ]
            [ [100.3, 0.2], [100.3, 0.4], [100.5, 0.4], [100.5, 0.2], [100.3, 0.2] ]
            [ [100.7, 0.6], [100.8, 0.8], [100.9, 0.6], [100.7, 0.6] ] ]
        ]
      },
      "z": { "values": [2] },
      "t": { "values": ["2008-01-01T04:00:00Z"] }
    },
    "referencing": [...]
  },
  "parameters" : {
    "temperature": {...}
  },
  "ranges" : {
    "temperature" : {
      "type" : "NdArray",
      "dataType": "float",
      "values" : [273.15]
    }
  }
}

I would also add an explicit example of MultiPolygon where one of the Polygons has a hole.

{
  "type": "Coverage",
  "domain": {
    "type": "Domain",
    "domainType": "MultiPolygon",
    "axes": {
      "composite": {
        "dataType": "polygon",
        "coordinates": ["x", "y"],
        "values": [
          [
            [
              [40, 40],
              [20, 45],
              [45, 30],
              [40, 40]
            ]
          ],
          [
            [
              [20, 35],
              [10, 30],
              [10, 10],
              [30, 5],
              [45, 20],
              [20, 35]
            ],
            [
              [30, 20],
              [20, 15],
              [20, 25],
              [30, 20]
            ]
          ]
        ]
      },
      "z": {
        "values": [2]
      },
      "t": {
        "values": ["2008-01-01T04:00:00Z"]
      }
    },
    "referencing": [...]
  },
  "parameters": {
  },
  "ranges": {
    "temperature": {
      "type": "NdArray",
      "dataType": "float",
      "axisNames": ["composite"],
      "shape": [2],
      "values": [23.1, 24.7]
    }
  }
}

[jonblower]

In the above MultiPolygon example, why are there two temperature values in the range? There is only one z value and one t value, and I thought the agreement was that a MultiPolygon describes a single domain element, defined by a set of polygons.

[jonblower]

I wonder if we should clarify the text around MultiPolygons. Instead of:

A MultiPolygon is intended to represent several polygons, possibly with holes, that define non-contiguous regions of one underlying coverage range. It is not intended to represent several polygons that are separate coverages, each with their own separate ranges. The latter case is a collection of coverages.

how about:

A MultiPolygon uses multiple polygons to represent non-contiguous regions, which are collectively treated as a single coverage domain, with a single associated range value. For example the MultiPolygon could represent the individual islands within a country, associated with the total population of that country.

(Note I've proposed that we could consider a new domain type for the use case of encoding the population of the individual islands - see #218.)

[awarde96]

Hi @jonblower, for the MultiPolygon I am trying to represent two Polygons, one with a hole and one without, hence the two values in the range.

This is the first polygon.

          [
            [
              [40, 40],
              [20, 45],
              [45, 30],
              [40, 40]
            ]
          ],

And this is the second

          [
            [
              [20, 35],
              [10, 30],
              [10, 10],
              [30, 5],
              [45, 20],
              [20, 35]
            ],
            [
              [30, 20],
              [20, 15],
              [20, 25],
              [30, 20]
            ]
          ]

I am trying to represent the example found here https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry under Multipart geometries (2D), the MultiPolygon example specifically.

Maybe I have a few parentheses off somewhere?

In the group meeting we agreed that a MultiPolygon could have multiple domain elements. Maybe @chris-little can elaborate further.

[jonblower]

@awarde96 I was just suggesting a change to the explanatory text - I didn't see a problem with the example (although I didn't check it in detail, it looks fine to me)

[chris-little]

See my understnading of the use of MultiPolygons at Issue #218