wassname/geopandas
1
0
Fork 0
mirror of https://github.com/wassname/geopandas.git synced 2026-09-10 12:00:21 +08:00
Code Issues Packages Projects Releases Wiki Activity

Docs for geometric manipulations and overlay (#308)

Browse Source
This commit is contained in:
Nick Eubank
2016-05-17 23:16:27 +02:00
committed by Joris Van den Bossche
parent 943624edc1
commit 5c2257a080
6 changed files with 115 additions and 56 deletions
Download Patch File Download Diff File Expand all files Collapse all files
doc/source/_static/overlay_operations.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 19 KiB

doc/source/data_structures.rst
+1 -1
View File
@@ -70,7 +70,7 @@ Basic Methods
Relationship Tests
^^^^^^^^^^^^^^^^^^^
* ``almost_equals(other)``: is shape almost the same as ``other`` (good when floating point precision issues make shapes slightly different)
* ``geom_almost_equals(other)``: is shape almost the same as ``other`` (good when floating point precision issues make shapes slightly different)
* ``contains(other)``: is shape contained within ``other``
* ``intersects(other)``: does shape intersect ``other``
doc/source/geometric_manipulations.rst
+28 -46
View File
@@ -1,92 +1,74 @@
Geometric Manipulations
========================
*geopandas* makes available all the tools for geometric manipulations in the `*shapely* library <http://toblerity.org/shapely/manual.html>`_.
Set-theoretic Methods
~~~~~~~~~~~~~~~~~~~~~
.. attribute:: GeoSeries.boundary
Returns a ``GeoSeries`` of lower dimensional objects representing
each geometries's set-theoretic `boundary`.
.. method:: GeoSeries.difference(other)
Returns a ``GeoSeries`` of the points in each geometry that
are not in the *other* object.
.. method:: GeoSeries.intersection(other)
Returns a ``GeoSeries`` of the intersection of each object with the `other`
geometric object.
.. method:: GeoSeries.symmetric_difference(other)
Returns a ``GeoSeries`` of the points in each object not in the `other`
geometric object, and the points in the `other` not in this object.
.. method:: GeoSeries.union(other)
Returns a ``GeoSeries`` of the union of points from each object and the
`other` geometric object.
.. attribute:: GeoSeries.unary_union
Return a geometry containing the union of all geometries in the ``GeoSeries``.
Note that documentation for all set-theoretic tools for creating new shapes using the relationship between two different spatial datasets -- like creating intersections, or differences -- can be found on the :doc:`set operations <set_operations>` page.
Constructive Methods
~~~~~~~~~~~~~~~~~~~~~
~~~~~~~~~~~~~~~~~~~~
.. method:: GeoSeries.buffer(distance, resolution=16)
.. method:: GeoSeries.buffer(distance, resolution=16)
Returns a ``GeoSeries`` of geometries representing all points within a given `distance`
of each geometric object.
.. attribute:: GeoSeries.convex_hull
.. attribute:: GeoSeries.boundary
Returns a ``GeoSeries`` of lower dimensional objects representing
each geometries's set-theoretic `boundary`.
.. attribute:: GeoSeries.centroid
Returns a ``GeoSeries`` of points for each geometric centroid.
.. attribute:: GeoSeries.convex_hull
Returns a ``GeoSeries`` of geometries representing the smallest
convex `Polygon` containing all the points in each object unless the
number of points in the object is less than three. For two points,
the convex hull collapses to a `LineString`; for 1, a `Point`.
.. attribute:: GeoSeries.envelope
.. attribute:: GeoSeries.envelope
Returns a ``GeoSeries`` of geometries representing the point or
smallest rectangular polygon (with sides parallel to the coordinate
axes) that contains each object.
.. method:: GeoSeries.simplify(tolerance, preserve_topology=True)
.. method:: GeoSeries.simplify(tolerance, preserve_topology=True)
Returns a ``GeoSeries`` containing a simplified representation of
each object.
Affine transformations
~~~~~~~~~~~~~~~~~~~~~~~
~~~~~~~~~~~~~~~~~~~~~~~~
.. method:: GeoSeries.rotate(self, angle, origin='center', use_radians=False)
.. method:: GeoSeries.rotate(self, angle, origin='center', use_radians=False)
Rotate the coordinates of the GeoSeries.
.. method:: GeoSeries.scale(self, xfact=1.0, yfact=1.0, zfact=1.0, origin='center')
.. method:: GeoSeries.scale(self, xfact=1.0, yfact=1.0, zfact=1.0, origin='center')
Scale the geometries of the GeoSeries along each (x, y, z) dimensio.
.. method:: GeoSeries.skew(self, angle, origin='center', use_radians=False)
.. method:: GeoSeries.skew(self, angle, origin='center', use_radians=False)
Shear/Skew the geometries of the GeoSeries by angles along x and y dimensions.
.. method:: GeoSeries.translate(self, angle, origin='center', use_radians=False)
.. method:: GeoSeries.translate(self, angle, origin='center', use_radians=False)
Shift the coordinates of the GeoSeries.
`Aggregating methods`
Aggregation Methods
~~~~~~~~~~~~~~~~~~~~
.. attribute:: GeoSeries.unary_union
Return a geometry containing the union of all geometries in the ``GeoSeries``.
Examples of Geometric Manipulations
------------------------------------
.. sourcecode:: python
doc/source/index.rst
+1
View File
@@ -32,6 +32,7 @@ such as PostGIS.
Making Maps <mapping>
Managing Projections <projections>
Geometric Manipulations <geometric_manipulations>
Set Operations with overlay <set_operations>
Merging Data <mergingdata>
Geocoding <geocoding>
Reference to All Attributes and Methods <reference>
doc/source/reference.rst
+9 -9
View File
@@ -124,15 +124,6 @@ The following Shapely methods and attributes are available on
`Set-theoretic Methods`
.. attribute:: GeoSeries.boundary
Returns a ``GeoSeries`` of lower dimensional objects representing
each geometries's set-theoretic `boundary`.
.. attribute:: GeoSeries.centroid
Returns a ``GeoSeries`` of points for each geometric centroid.
.. method:: GeoSeries.difference(other)
Returns a ``GeoSeries`` of the points in each geometry that
@@ -160,6 +151,15 @@ The following Shapely methods and attributes are available on
Returns a ``GeoSeries`` of geometries representing all points within a given `distance`
of each geometric object.
.. attribute:: GeoSeries.boundary
Returns a ``GeoSeries`` of lower dimensional objects representing
each geometries's set-theoretic `boundary`.
.. attribute:: GeoSeries.centroid
Returns a ``GeoSeries`` of points for each geometric centroid.
.. attribute:: GeoSeries.convex_hull
Returns a ``GeoSeries`` of geometries representing the smallest
doc/source/set_operations.rst
+76
View File
@@ -0,0 +1,76 @@
.. ipython:: python
:suppress:
import geopandas as gpd
world = gpd.GeoDataFrame().from_file('_example_data/naturalearth_lowres.shp')
capitals = gpd.GeoDataFrame().from_file('_example_data/naturalearth_cities.shp')
# For spatial join
countries = world[['geometry', 'name']]
# Project
countries = countries.to_crs('+init=epsg:3395')[countries.name!="Antarctica"]
capitals = capitals.to_crs('+init=epsg:3395')
Set-Operations with Overlay
============================
When working with multiple spatial datasets -- especially multiple *polygon* or *line* datasets -- users often wish to create new shapes based on places where those datasets overlap (or don't overlap). These manipulations are often referred using the language of sets -- intersections, unions, and differences. These types of operations are made available in the *geopandas* library through the ``overlay`` function.
The basic idea is demonstrated by the graphic below but keep in mind that overlays operate at the DataFrame level, not on individual geometries, and the properties from both are retained. In effect, for every shape in the first GeoDataFrame, this operation is executed against every other shape in the other GeoDataFrame:
.. image:: _static/overlay_operations.png
**Source: QGIS Documentation**
(Note to users familiar with the *shapely* library: ``overlay`` can be thought of as offering versions of the standard *shapely* set-operations that deal with the complexities of applying set operations to two *GeoSeries*. The standard *shapely* set-operations are also available as ``GeoSeries`` methods.)
Overlay Example
-----------------
To illustrate the ``overlay`` function, consider the following case in which one wishes to identify the "core" portion of each country -- defined as areas within 500km of a capital -- using a ``GeoDataFrame`` of countries and a ``GeoDataFrame`` of capitals.
.. ipython:: python
# Look at countries:
@savefig world_basic.png width=5in
countries.plot();
# Now buffer cities to find area within 500km.
# Check CRS -- World Mercator, units of meters.
capitals.crs
# make 500km buffer
capitals['geometry']= capitals.buffer(500000)
@savefig capital_buffers.png width=5in
capitals.plot();
To select only the portion of countries within 500km of a capital, we specify the ``how`` option to be "intersect", which creates a new set of polygons where these two layers overlap:
.. ipython:: python
from geopandas.tools import overlay
country_cores = overlay(countries, capitals, how='intersection')
@savefig country_cores.png width=5in
country_cores.plot();
Changing the "how" option allows for different types of overlay operations. For example, if we were interested in the portions of countries *far* from capitals (the peripheries), we would compute the difference of the two.
.. ipython:: python
country_peripheries = overlay(countries, capitals, how='difference')
@savefig country_peripheries.png width=5in
country_peripheries.plot();
More Examples
-----------------
A larger set of examples of the use of ``overlay`` can be found `here <http://nbviewer.jupyter.org/github/geopandas/geopandas/blob/master/examples/overlays.ipynb>`_
.. toctree::
:maxdepth: 2