Merge 0ef9455 into 6c9f301

docs/geometry.rst

@@ -173,3 +173,31 @@ specified, rounding precision will be disabled showing full precision.
 Format types ``'x'`` and ``'X'`` show a hex-encoded string representation of
 WKB or Well-Known Binary, with the case of the output matched the
 case of the format type character.
+
+.. _canonical-form:
+
+Canonical form
+--------------
+When operations are applied on geometries the result is returned according to some
+conventions.
+
+In most cases, geometries will be returned in "mild" canonical form. There is no goal
+to keep this form stable, so it is expected to change in future versions of GEOS:
+
+- the coordinates of exterior rings follow a clockwise orientation and interior
+  rings have a counter-clockwise orientation. This is the opposite of the OGC
+  specifications because the choice was made before this was included in the standard.
+- the starting point of rings can be changed, but it is undefined
+- the order of geometry types in a collection can be changed, but the order is
+  undefined
+
+When :func:`~shapely.normalize` is used, the "strict" canonical form is applied. This
+type of normalization is meant to be stable, so changes to it will be avoided if
+possible:
+
+- the coordinates of exterior rings follow a clockwise orientation and interior
+  rings have a counter-clockwise orientation
+- the starting point of rings is lower left
+- elements in collections are ordered by geometry type
+
+It is important to note that input geometries do not have to follow these conventions.

shapely/_geometry.py

@@ -731,14 +731,15 @@ def set_precision(geometry, grid_size, mode="valid_output", **kwargs):
     collapse to empty geometries if all vertices are closer together than
     grid_size. Z values, if present, will not be modified.
 
-    Note: subsequent operations will always be performed in the precision of
-    the geometry with higher precision (smaller "grid_size"). That same
-    precision will be attached to the operation outputs.
-
-    Also note: input geometries should be geometrically valid; unexpected
-    results may occur if input geometries are not.
-
-    Returns None if geometry is None.
+    Notes:
+
+    * subsequent operations will always be performed in the precision of
+      the geometry with higher precision (smaller "grid_size"). That same
+      precision will be attached to the operation outputs.
+    * input geometries should be geometrically valid; unexpected results may
+      occur if input geometries are not.
+    * the geometry returned will be in :ref:`mild canonical form <canonical-form>`.
+    * returns None if geometry is None.
 
     Parameters
     ----------

shapely/constructive.py

@@ -592,11 +592,11 @@ def make_valid(geometry, method="linework", keep_collapsed=True, **kwargs):
 
 @multithreading_enabled
 def normalize(geometry, **kwargs):
-    """Converts Geometry to normal form (or canonical form).
+    """Converts Geometry to strict normal form (or canonical form).
 
-    This method orders the coordinates, rings of a polygon and parts of
-    multi geometries consistently. Typically useful for testing purposes
-    (for example in combination with ``equals_exact``).
+    In :ref:`strict canonical form <canonical-form>`, the coordinates, rings of a polygon and
+    parts of multi geometries are ordered consistently. Typically useful for testing
+    purposes (for example in combination with ``equals_exact``).
 
     Parameters
     ----------