Merge b4eb283 into 72a440d

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,20 +731,23 @@ def set_precision(geometry, grid_size, mode="valid_output", **kwargs):
 
     By default, geometries use double precision coordinates (grid_size = 0).
 
-    Coordinates will be rounded if a precision grid is less precise than the
-    input geometry. Duplicated vertices will be dropped from lines and
-    polygons for grid sizes greater than 0. Line and polygon geometries may
-    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.
+    Coordinates will be rounded if a precision grid is less precise than the input
+    geometry. Duplicated vertices will be dropped from lines and polygons for grid sizes
+    greater than 0. Line and polygon geometries may collapse to empty geometries if all
+    vertices are closer together than ``grid_size``. Spikes or sections in Polygons
+    narrower than ``grid_size`` after rounding the vertices will be removed, which can
+    lead to MultiPolygons or empty geometries. Z values, if present, will not be
+    modified.
+
+    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
     ----------
@@ -755,7 +758,8 @@ def set_precision(geometry, grid_size, mode="valid_output", **kwargs):
         value is more precise than input geometry, the input geometry will
         not be modified.
     mode :  {'valid_output', 'pointwise', 'keep_collapsed'}, default 'valid_output'
-        This parameter determines how to handle invalid output geometries. There are three modes:
+        This parameter determines the way a precision reduction is applied on the
+        geometry. There are three modes:
 
         1. `'valid_output'` (default):  The output is always valid. Collapsed geometry elements
            (including both polygons and lines) are removed. Duplicate vertices are removed.

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
     ----------