ENH: Standardize 2.5D => Z in geometry type labels (#234)

Author: brendan-ward

CHANGES.md

@@ -8,6 +8,8 @@
 -   Add "driver" property to `read_info` result (#224)
 -   Add support for dataset open options to `read`, `read_dataframe`, and
     `read_info` (#233)
+-   Standardized 3-dimensional geometry type labels from "2.5D <type>" to
+    "<type> Z" for consistency with well-known text (WKT) formats (#234)
 
 ## 0.5.1 (2023-01-26)
 

docs/source/known_issues.md

@@ -23,7 +23,7 @@ Measured geometry types are not supported for reading or writing. These are not
 supported by the GEOS library and cannot be converted to geometry objects in
 GeoDataFrames.
 
-These are automatically downgraded to their 2.5D (x,y, single z) equivalent and
+These are automatically downgraded to their 3D (x,y,z) equivalent and
 a warning is raised.
 
 To ignore this warning:
@@ -59,7 +59,7 @@ give at most millisecond resolution (`datetime64[ms]` data type), even though
 the data is cast `datetime64[ns]` data type when reading into a data frame
 using `pyogrio.read_dataframe()`. When writing, only precision up to ms is retained.
 
-Not all file formats have dedicated support to store datetime data, like ESRI 
+Not all file formats have dedicated support to store datetime data, like ESRI
 Shapefile. For such formats, or if you require precision > ms, a workaround is to
 convert the datetimes to string.
 

pyogrio/_geometry.pyx

@@ -34,37 +34,37 @@ GEOMETRY_TYPES = {
     wkbMultiLineStringZM: 'Measured 3D MultiLineString',
     wkbMultiPolygonZM: 'Measured 3D MultiPolygon',
     wkbGeometryCollectionZM: 'Measured 3D GeometryCollection',
-    wkbPoint25D: '2.5D Point',
-    wkbLineString25D: '2.5D LineString',
-    wkbPolygon25D: '2.5D Polygon',
-    wkbMultiPoint25D: '2.5D MultiPoint',
-    wkbMultiLineString25D: '2.5D MultiLineString',
-    wkbMultiPolygon25D: '2.5D MultiPolygon',
-    wkbGeometryCollection25D: '2.5D GeometryCollection',
+    wkbPoint25D: 'Point Z',
+    wkbLineString25D: 'LineString Z',
+    wkbPolygon25D: 'Polygon Z',
+    wkbMultiPoint25D: 'MultiPoint Z',
+    wkbMultiLineString25D: 'MultiLineString Z',
+    wkbMultiPolygon25D: 'MultiPolygon Z',
+    wkbGeometryCollection25D: 'GeometryCollection Z',
 }
 
 GEOMETRY_TYPE_CODES = {v:k for k, v in GEOMETRY_TYPES.items()}
 
-# add additional aliases from Simple Features WKT types with Z
+# add additional aliases from 2.5D format
 GEOMETRY_TYPE_CODES.update({
-    'Point Z': wkbPoint25D,
-    'LineString Z': wkbLineString25D,
-    'Polygon Z': wkbPolygon25D,
-    'MultiPoint Z': wkbMultiPoint25D,
-    'MultiLineString Z': wkbMultiLineString25D,
-    'MultiPolygon Z': wkbMultiPolygon25D,
-    'GeometryCollection Z': wkbGeometryCollection25D
+    '2.5D Point': wkbPoint25D,
+    '2.5D LineString': wkbLineString25D,
+    '2.5D Polygon': wkbPolygon25D,
+    '2.5D MultiPoint': wkbMultiPoint25D,
+    '2.5D MultiLineString': wkbMultiLineString25D,
+    '2.5D MultiPolygon': wkbMultiPolygon25D,
+    '2.5D GeometryCollection': wkbGeometryCollection25D
 })
 
 # 2.5D also represented using negative numbers not enumerated above
 GEOMETRY_TYPES.update({
-    -2147483647: '2.5D Point',
-    -2147483646: '2.5D LineString',
-    -2147483645: '2.5D Polygon',
-    -2147483644: '2.5D MultiPoint',
-    -2147483643: '2.5D MultiLineString',
-    -2147483642: '2.5D MultiPolygon',
-    -2147483641: '2.5D GeometryCollection',
+    -2147483647: 'Point Z',
+    -2147483646: 'LineString Z',
+    -2147483645: 'Polygon Z',
+    -2147483644: 'MultiPoint Z',
+    -2147483643: 'MultiLineString Z',
+    -2147483642: 'MultiPolygon Z',
+    -2147483641: 'GeometryCollection Z',
 })
 
 

pyogrio/geopandas.py

@@ -368,7 +368,7 @@ def write_dataframe(
         if geometry_type is None:
             geometry_type = tmp_geometry_type
             if has_z and geometry_type != "Unknown":
-                geometry_type = f"2.5D {geometry_type}"
+                geometry_type = f"{geometry_type} Z"
 
     crs = None
     if geometry.crs:

pyogrio/tests/test_core.py

@@ -99,7 +99,7 @@ def test_list_layers(naturalearth_lowres, naturalearth_lowres_vsi, test_fgdb_vsi
         list_layers(naturalearth_lowres_vsi[1]), [["naturalearth_lowres", "Polygon"]]
     )
 
-    # Measured 3D is downgraded to 2.5D during read
+    # Measured 3D is downgraded to plain 3D during read
     # Make sure this warning is raised
     with pytest.warns(
         UserWarning, match=r"Measured \(M\) geometry types are not supported"
@@ -111,9 +111,9 @@ def test_list_layers(naturalearth_lowres, naturalearth_lowres_vsi, test_fgdb_vsi
         # Make sure that nonspatial layer has None for geometry
         assert array_equal(fgdb_layers[0], ["basetable_2", None])
 
-        # Confirm that measured 3D is downgraded to 2.5D during read
-        assert array_equal(fgdb_layers[3], ["test_lines", "2.5D MultiLineString"])
-        assert array_equal(fgdb_layers[6], ["test_areas", "2.5D MultiPolygon"])
+        # Confirm that measured 3D is downgraded to plain 3D during read
+        assert array_equal(fgdb_layers[3], ["test_lines", "MultiLineString Z"])
+        assert array_equal(fgdb_layers[6], ["test_areas", "MultiPolygon Z"])
 
 
 def test_read_bounds(naturalearth_lowres):

pyogrio/tests/test_geopandas_io.py

@@ -868,37 +868,37 @@ def test_write_geometry_z_types(tmp_path, wkt, geom_types):
 @pytest.mark.parametrize(
     "test_descr, exp_geometry_type, mixed_dimensions, wkt",
     [
-        ("1 Point Z", "2.5D Point", False, ["Point Z (0 0 0)"]),
-        ("1 LineString Z", "2.5D LineString", False, ["LineString Z (0 0 0, 1 1 0)"]),
+        ("1 Point Z", "Point Z", False, ["Point Z (0 0 0)"]),
+        ("1 LineString Z", "LineString Z", False, ["LineString Z (0 0 0, 1 1 0)"]),
         (
             "1 Polygon Z",
-            "2.5D Polygon",
+            "Polygon Z",
             False,
             ["Polygon Z ((0 0 0, 0 1 0, 1 1 0, 0 0 0))"],
         ),
-        ("1 MultiPoint Z", "2.5D MultiPoint", False, ["MultiPoint Z (0 0 0, 1 1 0)"]),
+        ("1 MultiPoint Z", "MultiPoint Z", False, ["MultiPoint Z (0 0 0, 1 1 0)"]),
         (
             "1 MultiLineString Z",
-            "2.5D MultiLineString",
+            "MultiLineString Z",
             False,
             ["MultiLineString Z ((0 0 0, 1 1 0), (2 2 2, 3 3 2))"],
         ),
         (
             "1 MultiLinePolygon Z",
-            "2.5D MultiPolygon",
+            "MultiPolygon Z",
             False,
             [
                 "MultiPolygon Z (((0 0 0, 0 1 0, 1 1 0, 0 0 0)), ((1 1 1, 1 2 1, 2 2 1, 1 1 1)))"  # noqa: E501
             ],
         ),
         (
             "1 GeometryCollection Z",
-            "2.5D GeometryCollection",
+            "GeometryCollection Z",
             False,
             ["GeometryCollection Z (Point Z (0 0 0))"],
         ),
-        ("Point Z + Point", "2.5D Point", True, ["Point Z (0 0 0)", "Point (0 0)"]),
-        ("Point Z + None", "2.5D Point", False, ["Point Z (0 0 0)", None]),
+        ("Point Z + Point", "Point Z", True, ["Point Z (0 0 0)", "Point (0 0)"]),
+        ("Point Z + None", "Point Z", False, ["Point Z (0 0 0)", None]),
         (
             "Point Z + LineString Z",
             "Unknown",
@@ -918,12 +918,12 @@ def test_write_geometry_z_types_auto(
 ):
     # Shapefile has some different behaviour that other file types
     if ext == ".shp":
-        if exp_geometry_type in ("2.5D GeometryCollection", "Unknown"):
+        if exp_geometry_type in ("GeometryCollection Z", "Unknown"):
             pytest.skip(f"ext {ext} doesn't support {exp_geometry_type}")
-        elif exp_geometry_type == "2.5D MultiLineString":
-            exp_geometry_type = "2.5D LineString"
-        elif exp_geometry_type == "2.5D MultiPolygon":
-            exp_geometry_type = "2.5D Polygon"
+        elif exp_geometry_type == "MultiLineString Z":
+            exp_geometry_type = "LineString Z"
+        elif exp_geometry_type == "MultiPolygon Z":
+            exp_geometry_type = "Polygon Z"
 
     column_data = {}
     column_data["test_descr"] = [test_descr] * len(wkt)