Merge pull request #23 from caspervdw/setops

Documentation for set operations

docs/index.rst

@@ -59,6 +59,7 @@ API Reference
 
    constructive
    predicates
+   set_operations
 
 
 Indices and tables

docs/set_operations.rst

@@ -0,0 +1,9 @@
+:mod:`pygeos.set_operations`
+=============================
+
+.. automodule:: pygeos.set_operations
+   :members:
+   :exclude-members:
+   :special-members:
+   :inherited-members:
+   :show-inheritance:

pygeos/set_operations.py

@@ -1,32 +1,207 @@
-from . import ufuncs
+import numpy as np
+from . import ufuncs, Empty, Geometry, GeometryType
 
-__all__ = ["difference", "intersection", "symmetric_difference", "union"]
+__all__ = [
+    "difference",
+    "intersection",
+    "intersection_all",
+    "symmetric_difference",
+    "symmetric_difference_all",
+    "union",
+    "union_all",
+]
 
 
-def difference(a, b=None, axis=0):
-    if b is None:
-        return ufuncs.difference.reduce(a, axis=axis)
-    else:
-        return ufuncs.difference(a, b)
+def difference(a, b, **kwargs):
+    """Returns the part of geometry A that does not intersect with geometry B.
 
+    Parameters
+    ----------
+    a : Geometry or array_like
+    b : Geometry or array_like
 
-def intersection(a, b=None, axis=0):
-    if b is None:
-        return ufuncs.intersection.reduce(a, axis=axis)
-    else:
-        return ufuncs.intersection(a, b)
+    Examples
+    --------
+    >>> line = Geometry("LINESTRING (0 0, 2 2)")
+    >>> difference(line, Geometry("LINESTRING (1 1, 3 3)"))
+    <pygeos.Geometry LINESTRING (0 0, 1 1)>
+    >>> difference(Empty, line)
+    <pygeos.Empty>
+    >>> difference(line, Empty)
+    <pygeos.Geometry LINESTRING (0 0, 2 2)>
+    """
+    return ufuncs.difference(a, b, **kwargs)
 
 
-def symmetric_difference(a, b=None, axis=0):
-    if b is None:
-        return ufuncs.symmetric_difference.reduce(a, axis=axis)
-    else:
-        return ufuncs.symmetric_difference(a, b)
+def intersection(a, b, **kwargs):
+    """Returns the geometry that is shared between input geometries.
+
+    Parameters
+    ----------
+    a : Geometry or array_like
+    b : Geometry or array_like
+
+    See also
+    --------
+    intersection_all
+
+    Examples
+    --------
+    >>> line = Geometry("LINESTRING(0 0, 2 2)")
+    >>> intersection(line, Geometry("LINESTRING(1 1, 3 3)"))
+    <pygeos.Geometry LINESTRING (1 1, 2 2)>
+    >>> intersection(Empty, line)
+    <pygeos.Empty>
+    """
+    return ufuncs.intersection(a, b, **kwargs)
+
+
+def intersection_all(geometries, axis=0, **kwargs):
+    """Returns the intersection of multiple geometries.
+
+    Parameters
+    ----------
+    geometries : array_like
+    axis : int, tuple or None
+        Axis or axes along which the operation is performed. The default
+        performs the operation over the first dimension of the input array.
+        axis may be negative, in which case it counts from the last to the
+        first axis. If axis is None, the operation is performed over all the
+        axes. If it is a tuple of ints, a reduction is performed on multiple
+        axes.
+
+    See also
+    --------
+    intersection
+
+    Examples
+    --------
+    >>> line_1 = Geometry("LINESTRING(0 0, 2 2)")
+    >>> line_2 = Geometry("LINESTRING(1 1, 3 3)")
+    >>> intersection_all([line_1, line_2])
+    <pygeos.Geometry LINESTRING (1 1, 2 2)>
+    >>> intersection_all([[line_1, line_2, Empty]], axis=1).tolist()
+    [<pygeos.Empty>]
+    """
+    return ufuncs.intersection.reduce(geometries, axis=axis, **kwargs)
+
+
+def symmetric_difference(a, b, **kwargs):
+    """Returns the geometry that represents the portions of input geometries
+    that do not intersect.
+
+    Parameters
+    ----------
+    a : Geometry or array_like
+    b : Geometry or array_like
+
+    See also
+    --------
+    symmetric_difference_all
+
+    Examples
+    --------
+    >>> line = Geometry("LINESTRING(0 0, 2 2)")
+    >>> symmetric_difference(line, Geometry("LINESTRING(1 1, 3 3)"))
+    <pygeos.Geometry MULTILINESTRING ((0 0, 1 1), (2 2, 3 3))>
+    >>> symmetric_difference(line, Empty)
+    <pygeos.Geometry LINESTRING (0 0, 2 2)>
+    """
+    return ufuncs.symmetric_difference(a, b, **kwargs)
+
+
+def symmetric_difference_all(geometries, axis=0, **kwargs):
+    """Returns the symmetric difference of multiple geometries.
+
+    Parameters
+    ----------
+    geometries : array_like
+    axis : int, tuple or None
+        Axis or axes along which the operation is performed. The default
+        performs the operation over the first dimension of the input array.
+        axis may be negative, in which case it counts from the last to the
+        first axis. If axis is None, the operation is performed over all the
+        axes. If it is a tuple of ints, a reduction is performed on multiple
+        axes.
+
+    See also
+    --------
+    symmetric_difference
+
+    Examples
+    --------
+    >>> line_1 = Geometry("LINESTRING(0 0, 2 2)")
+    >>> line_2 = Geometry("LINESTRING(1 1, 3 3)")
+    >>> intersection_all([line_1, line_2])
+    <pygeos.Geometry LINESTRING (1 1, 2 2)>
+    >>> intersection_all([[line_1, line_2, Empty]], axis=1).tolist()
+    [<pygeos.Empty>]
+    """
+    return ufuncs.symmetric_difference.reduce(geometries, axis=axis, **kwargs)
+
+
+def union(a, b, **kwargs):
+    """Merges geometries into one.
+
+    Parameters
+    ----------
+    a : Geometry or array_like
+    b : Geometry or array_like
+
+    See also
+    --------
+    union_all
+
+    Examples
+    --------
+    >>> line = Geometry("LINESTRING(0 0, 2 2)")
+    >>> union(line, Geometry("LINESTRING(2 2, 3 3)"))
+    <pygeos.Geometry MULTILINESTRING ((0 0, 2 2), (2 2, 3 3))>
+    >>> union(line, Empty)
+    <pygeos.Geometry LINESTRING (0 0, 2 2)>
+    """
+    return ufuncs.union(a, b, **kwargs)
+
+
+def union_all(geometries, axis=0, **kwargs):
+    """Returns the union of multiple geometries.
+
+    Parameters
+    ----------
+    geometries : array_like
+    axis : int, tuple or None
+        Axis or axes along which the operation is performed. The default
+        performs the operation over the first dimension of the input array.
+        axis may be negative, in which case it counts from the last to the
+        first axis. If axis is None, the operation is performed over all the
+        axes. If it is a tuple of ints, a reduction is performed on multiple
+        axes.
 
+    See also
+    --------
+    union
 
-def union(a, b=None, axis=0):
-    if b is None:
-        a = ufuncs.create_collection(a, axis=axis)
-        return ufuncs.unary_union(a)
+    Examples
+    --------
+    >>> line_1 = Geometry("LINESTRING(0 0, 2 2)")
+    >>> line_2 = Geometry("LINESTRING(2 2, 3 3)")
+    >>> union_all([line_1, line_2])
+    <pygeos.Geometry MULTILINESTRING ((0 0, 2 2), (2 2, 3 3))>
+    >>> union_all([[line_1, line_2, Empty]], axis=1).tolist()
+    [<pygeos.Geometry MULTILINESTRING ((0 0, 2 2), (2 2, 3 3))>]
+    """
+    # for union_all, GEOS provides an efficient route through first creating
+    # GeometryCollections
+    # first roll the aggregation axis backwards
+    geometries = np.asarray(geometries)
+    if axis is None:
+        geometries = geometries.ravel()
     else:
-        return ufuncs.union(a, b)
+        geometries = np.rollaxis(
+            np.asarray(geometries), axis=axis, start=geometries.ndim
+        )
+    # create_collection acts on the inner axis
+    collections = ufuncs.create_collection(
+        geometries, GeometryType.GEOMETRYCOLLECTION
+    )
+    return ufuncs.unary_union(collections, **kwargs)