Apply feedback

docs/geometry.rst

@@ -178,26 +178,33 @@ case of the format type character.
 
 Canonical form
 --------------
-When operations are applied on geometries the result is returned according to some
-conventions.
+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:
+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
+  specifications because the choice was made before this was included in the
+  standard.
+- the starting point of rings can be changed in the output, but the exact order
+  is undefined and should not be relied upon
 - 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:
+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
+- elements in collections are ordered by geometry type: by descending dimension
+  and multi-types first (MultiPolygon, Polygon, MultiLineString, LineString,
+  MultiPoint, Point). Multiple elements from the same type are ordered from
+  right to left and from top to bottom.
 
-It is important to note that input geometries do not have to follow these conventions.
+It is important to note that input geometries do not have to follow these
+conventions.

shapely/_geometry.py

@@ -731,22 +731,25 @@ 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 the precision grid specified 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`` or if a polygon becomes
-    significantly narrower 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.
+    Coordinates will be rounded if the precision grid specified 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`` or if a polygon becomes significantly narrower 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.
+    * 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>`.
+    * the geometry returned will be in
+      :ref:`mild canonical form <canonical-form>`, and the order of vertices can
+      change and should not be relied upon.
     * returns None if geometry is None.
 
     Parameters
@@ -758,22 +761,24 @@ 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 the way a precision reduction is applied on the
-        geometry. 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.
-        2. `'pointwise'`: Precision reduction is performed pointwise. Output geometry
-           may be invalid due to collapse or self-intersection. Duplicate vertices are not
-           removed. In GEOS this option is called NO_TOPO.
+        1. `'valid_output'` (default):  The output is always valid. Collapsed
+           geometry elements (including both polygons and lines) are removed.
+           Duplicate vertices are removed.
+        2. `'pointwise'`: Precision reduction is performed pointwise. Output
+           geometry may be invalid due to collapse or self-intersection.
+           Duplicate vertices are not removed. In GEOS this option is called
+           NO_TOPO.
 
            .. note::
 
-             'pointwise' mode requires at least GEOS 3.10. It is accepted in earlier versions,
-             but the results may be unexpected.
-        3. `'keep_collapsed'`: Like the default mode, except that collapsed linear geometry
-           elements are preserved. Collapsed polygonal input elements are removed. Duplicate
-           vertices are removed.
+             'pointwise' mode requires at least GEOS 3.10. It is accepted in
+             earlier versions, but the results may be unexpected.
+        3. `'keep_collapsed'`: Like the default mode, except that collapsed
+           linear geometry elements are preserved. Collapsed polygonal input
+           elements are removed. Duplicate vertices are removed.
     **kwargs
         See :ref:`NumPy ufunc docs <ufuncs.kwargs>` for other keyword arguments.