ENH: Add export to GeoArrow

ci/envs/39-minimal.yaml

@@ -20,7 +20,7 @@ dependencies:
   - geopy
   - SQLalchemy
   - libspatialite
-  - pyarrow=8.0.0
+  - pyarrow=10.0
   - geodatasets
   - pip
   - pip:

geopandas/_compat.py

@@ -23,6 +23,7 @@
 # Shapely / GEOS compat
 # -----------------------------------------------------------------------------
 
+SHAPELY_GE_204 = Version(shapely.__version__) >= Version("2.0.4")
 
 GEOS_GE_390 = shapely.geos.geos_version >= (3, 9, 0)
 GEOS_GE_310 = shapely.geos.geos_version >= (3, 10, 0)

geopandas/geodataframe.py

@@ -1149,6 +1149,80 @@ def to_wkt(self, **kwargs):
 
         return df
 
+    def to_arrow(self, index=None, geometry_encoding="WKB", interleaved=True):
+        """Encode a GeoDataFrame to GeoArrow format.
+
+        See https://geoarrow.org/ for details on the GeoArrow specification.
+
+        This functions returns a generic Arrow data object implementing
+        the `Arrow PyCapsule Protocol`_ (i.e. having an ``__arrow_c_stream__``
+        method). This object can then be consumed by your Arrow implementation
+        of choice that supports this protocol.
+
+        .. _Arrow PyCapsule Protocol: https://arrow.apache.org/docs/format/CDataInterface/PyCapsuleInterface.html
+
+        Parameters
+        ----------
+        index : bool, default None
+            If ``True``, always include the dataframe's index(es) as columns
+            in the file output.
+            If ``False``, the index(es) will not be written to the file.
+            If ``None``, the index(ex) will be included as columns in the file
+            output except `RangeIndex` which is stored as metadata only.
+        geometry_encoding : {'WKB', 'geoarrow' }, default 'WKB'
+            The GeoArrow encoding to use for the data conversion.
+        interleaved : bool, default True
+            Only relevant for 'geoarrow' encoding. If True, the geometries
+            coordinates are interleaved in a single fixed size list array.
+            If False, the coordinates are stored as separate arrays in a
+            struct type.
+
+        Returns
+        -------
+        ArrowTable
+            A generic Arrow table object with geometry columns encoded to
+            GeoArrow.
+
+        Examples
+        --------
+        >>> from shapely.geometry import Point
+        >>> data = {'col1': ['name1', 'name2'], 'geometry': [Point(1, 2), Point(2, 1)]}
+        >>> gdf = geopandas.GeoDataFrame(data)
+        >>> gdf
+            col1     geometry
+        0  name1  POINT (1 2)
+        1  name2  POINT (2 1)
+
+        >>> arrow_table = gdf.to_arrow()
+        >>> arrow_table
+        <geopandas.io.geoarrow.ArrowTable object at ...>
+
+        The returned data object needs to be consumed by a library implementing
+        the Arrow PyCapsule Protocol. For example, wrapping the data as a
+        pyarrow.Table (requires pyarrow >= 14.0):
+
+        >>> import pyarrow as pa
+        >>> table = pa.table(arrow_table)
+        >>> table
+        pyarrow.Table
+        col1: string
+        geometry: binary
+        ----
+        col1: [["name1","name2"]]
+        geometry: [[0101000000000000000000F03F0000000000000040,\
+01010000000000000000000040000000000000F03F]]
+
+        """
+        from geopandas.io.geoarrow import ArrowTable, geopandas_to_arrow
+
+        table = geopandas_to_arrow(
+            self,
+            index=index,
+            geometry_encoding=geometry_encoding,
+            interleaved=interleaved,
+        )
+        return ArrowTable(table)
+
     def to_parquet(
         self, path, index=None, compression="snappy", schema_version=None, **kwargs
     ):

geopandas/io/arrow.py

@@ -5,8 +5,6 @@
 import numpy as np
 from pandas import DataFrame, Series
 
-import shapely
-
 import geopandas
 from geopandas import GeoDataFrame
 from geopandas._compat import import_optional_dependency
@@ -272,24 +270,16 @@ def _geopandas_to_arrow(df, index=None, schema_version=None):
     """
     Helper function with main, shared logic for to_parquet/to_feather.
     """
-    from pyarrow import Table
+    from geopandas.io.geoarrow import geopandas_to_arrow
 
     _validate_dataframe(df)
 
     # create geo metadata before altering incoming data frame
     geo_metadata = _create_metadata(df, schema_version=schema_version)
 
-    if shapely.geos_version > (3, 10, 0):
-        kwargs = {"flavor": "iso"}
-    else:
-        if any(
-            df[col].array.has_z.any() for col in df.columns[df.dtypes == "geometry"]
-        ):
-            raise ValueError("Cannot write 3D geometries with GEOS<3.10")
-        kwargs = {}
-    df = df.to_wkb(**kwargs)
-
-    table = Table.from_pandas(df, preserve_index=index)
+    table = geopandas_to_arrow(
+        df, geometry_encoding="WKB", index=index, interleaved=True
+    )
 
     # Store geopandas specific file-level metadata
     # This must be done AFTER creating the table or it is not persisted