Explicit orientation field for polygon winding (#74)

* Explicit orientation field for polygon winding * Remove comment on opposite ring order Co-authored-by: Even Rouault <even.rouault@spatialys.com> * Remove REQUIRED on orientation Co-authored-by: Brendan Ward <bcward@astutespruce.com> * Remove mention of right-hand rule Co-authored-by: Brendan Ward <bcward@astutespruce.com> * Explicit note on lack of consistency Co-authored-by: Brendan Ward <bcward@astutespruce.com> * Wording update on writers Co-authored-by: Brendan Ward <bcward@astutespruce.com> * Reverse crs/orientation order Co-authored-by: Joris Van den Bossche <jorisvandenbossche@gmail.com> * Typo Co-authored-by: Joris Van den Bossche <jorisvandenbossche@gmail.com> * Add quotes Co-authored-by: Joris Van den Bossche <jorisvandenbossche@gmail.com> * updates to talk about spherical more, minor tweaks * Validator update with orientation * Update example file to include orientation * Update example_metadata.json to 0.3.0 * Allow 0.3.0 version * Only allow 0.3.0 * 0.3.0 in spec * Revert change of 0.3.0 to 0.2.0 * Don't use const * Metadata fix * Note on spherical + orientation Co-authored-by: Brendan Ward <bcward@astutespruce.com> * Note on spherical + orientation Co-authored-by: Brendan Ward <bcward@astutespruce.com> Co-authored-by: Even Rouault <even.rouault@spatialys.com> Co-authored-by: Brendan Ward <bcward@astutespruce.com> Co-authored-by: Joris Van den Bossche <jorisvandenbossche@gmail.com> Co-authored-by: Christopher Holmes <cholmes@planet.com>
opengeospatial · Apr 22, 2022 · e3bdb28 · e3bdb28
1 parent f2a01cc
commit e3bdb28
Show file tree

Hide file tree

Showing 5 changed files with 25 additions and 5 deletions.
diff --git a/examples/example.parquet b/examples/example.parquet
diff --git a/examples/example.py b/examples/example.py
@@ -32,6 +32,7 @@
             "geometry_type": ["Polygon", "MultiPolygon"],
             "crs": df.crs.to_wkt(pyproj.enums.WktVersion.WKT2_2019_SIMPLIFIED),
             "edges": "planar",
+            "orientation": "counterclockwise",
             "bbox": [round(x, 4) for x in df.geometry.unary_union.bounds],
         },
     },

diff --git a/examples/example_metadata.json b/examples/example_metadata.json
@@ -14,7 +14,8 @@
         "geometry_type": [
           "Polygon",
           "MultiPolygon"
-        ]
+        ],
+        "orientation": "counterclockwise"
       }
     },
     "primary_column": "geometry",

diff --git a/format-specs/geoparquet.md b/format-specs/geoparquet.md
@@ -54,9 +54,10 @@ Each geometry column in the dataset must be included in the columns field above
 | ---------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
 | encoding | string | **REQUIRED** Name of the geometry encoding format. Currently only 'WKB' is supported. |
 | geometry_type | string or \[string] | **REQUIRED** The geometry type(s) of all geometries, or 'Unknown' if they are not known.  |
-| crs       | string   | **OPTIONAL** [WKT2](https://docs.opengeospatial.org/is/18-010r7/18-010r7.html) string representing the Coordinate Reference System (CRS) of the geometry. If the crs field is not included then the data in this column must be stored in longitude, latitude. In the case where a crs is not provided, CRS-aware implementations should assume a default value of [OGC:CRS84](https://www.opengis.net/def/crs/OGC/1.3/CRS84) (longitude-latitude coordinates) |
+| crs       | string   | **OPTIONAL** [WKT2](https://docs.opengeospatial.org/is/18-010r7/18-010r7.html) string representing the Coordinate Reference System (CRS) of the geometry. If the crs field is not included then the data in this column must be stored in longitude, latitude. In the case where a crs is not provided, CRS-aware implementations should assume a default value of [OGC:CRS84](https://www.opengis.net/def/crs/OGC/1.3/CRS84) (longitude-latitude coordinates). |
+| orientation | string | **OPTIONAL** Winding order of exterior ring of polygons; interior rings are wound in opposite order. If present must be "counterclockwise". If absent, no assertions are made regarding the winding order.
 | edges | string | **OPTIONAL** Name of the coordinate system for the edges. Must be one of 'planar' or 'spherical'. The default value is 'planar'.  |
-| bbox   | \[number] | **OPTIONAL** Bounding Box of the geometries in the file, formatted according to [RFC 7946, section 5](https://tools.ietf.org/html/rfc7946#section-5) |
+| bbox   | \[number] | **OPTIONAL** Bounding Box of the geometries in the file, formatted according to [RFC 7946, section 5](https://tools.ietf.org/html/rfc7946#section-5). |
 | epoch    | double | **OPTIONAL** Coordinate epoch in case of a dynamic CRS, expressed as a decimal year.  |
 
 
@@ -147,9 +148,17 @@ specify "MultiPolygon", but it is expected to specify
 ["Polygon", "MultiPolygon"]. Or if having 3D points, it is not sufficient to
 specify "Point", but it is expected to list "Point Z".
 
-#### Polygon winding
+#### orientation
 
-The winding order of polygons follows the [GeoJSON spec](https://datatracker.ietf.org/doc/html/rfc7946#section-3.1.6). Polygon rings MUST follow the right-hand rule for orientation (counterclockwise external rings, clockwise internal rings).  Traversing vertices of rings in order, the interior of the polygon is on the left.
+This attribute indicates the winding order of polygons. The only available value is:
+
+- "counterclockwise": All vertices of exterior polygon rings MUST be ordered in the counterclockwise direction and all interior rings MUST be ordered in the clockwise direction.
+
+If no value is set, no assertions are made about winding order or consistency of such between exterior and interior rings or between individual geometries within a dataset.  Readers are responsible for verifying and if necessary re-ordering vertices as required for their analytical representation.
+
+Writers are encouraged but not required to set orientation="counterclockwise" for portability of the data within the broader ecosystem.
+
+It is recommended to always set the orientation (to counterclockwise) if `edges` is 'spherical' (see below).
 
 #### edges
 
@@ -159,6 +168,10 @@ This attribute indicates how to interpret the edges of the geometries: whether t
 
 If no value is set, the default value to assume is 'planar'.
 
+Note if `edges` is 'spherical' then it is recommended that `orientation` is always set to 'counterclockwise'. If it is not set, it is not clear how polygons should be interpreted within spherical coordinate systems, which can lead to major analytical errors if interpreted incorrectly. 
+then implementations should choose the smaller polygon for interpretation (but note this can only work with polygons 
+smaller than hemisphere, which is why it is recommended to always set it).
+
 #### bbox
 
 Bounding boxes are used to help define the spatial extent of each geometry column.

diff --git a/validator/python/geoparquet_validator/schema.json b/validator/python/geoparquet_validator/schema.json
@@ -49,6 +49,11 @@
               "enum": ["planar", "spherical"],
               "description": "Name of the coordinate system for the edges. Must be one of 'planar' or 'spherical'. The default value is 'planar'."
             },
+            "orientation": {
+              "type": "string",
+              "enum": ["counterclockwise"],
+              "description": "Winding order of exterior ring of polygons; interior rings are wound in opposite order. If absent, no assertions are made regarding the winding order."
+            },
             "bbox": {
               "type": "array",
               "description": "Bounding Box of the geometries in the file, formatted according to RFC 7946, section 5.",