gridify 0.3.1
Generate a grid of box shaped polygons covering an area
Requires Python: >=3.10
Keywords: gridify

##########################
Geometry-to-Grid generator
##########################

.. begin-inclusion-intro-marker-do-not-remove

Gridify takes geometries in a geopandas dataframe to describe areas. It then generates a grid of box shaped polygons covering the include area. Gridify has three methods to generate this box shaped polygon grid:

- :code:`simple_gridify`; generate a grid over a single geometry.
- :code:`gridify`; generate a grid between two geometries, describing an area to include and exclude.
- :code:`overlay_gridify`: perform a spatial overlay before generating grid between a primary and secondary geometry, possible spatial overlays are; intersection’, ‘union’, ‘identity’, ‘symmetric_difference’ and ‘difference’.

.. end-inclusion-intro-marker-do-not-remove


.. begin-inclusion-usage-marker-do-not-remove

How to use
----------

.. end-inclusion-usage-marker-do-not-remove

Import packages

.. code:: ipython3

    import geopandas as gpd
    import shapely.geometry
    import matplotlib.pyplot as plt

    from gridify.gridify import gridify

Gridify
^^^^^^^

Define an include area consisting of a polygon and a line part. And put
it in a geodataframe.

.. code:: ipython3

    part1 = shapely.geometry.box(
       minx=0,
       miny=0,
       maxx=0.5,
       maxy=1,
    )
    part2 = shapely.geometry.LineString(
       [
           (0.5, 0),
           (5 / 6, 1.0),
       ]
    )
    include_gdf = gpd.GeoDataFrame({"col1": [1, 2]}, geometry=[part1, part2])
    ax = include_gdf.plot(column="col1")
    ax.set_xlim([-.1, 1.2])
    ax.set_ylim([-.1, 1.2])


.. image:: doc/_static/figs/output_3_1.png


Define an area to exclude

.. code:: ipython3

    exclude = shapely.geometry.box(
        minx=0.5,
        miny=0.5,
        maxx=1.1,
        maxy=1.1,
    )
    exclude_gdf = gpd.GeoDataFrame({"col1": [1]}, geometry=[exclude])
    ax = exclude_gdf.plot(color="red", alpha=0.5)
    ax.set_xlim([-.1, 1.2])
    ax.set_ylim([-.1, 1.2])



.. image:: doc/_static/figs/output_5_1.png


Use include area and exclude area to define a grid with (1/3) as grid
size. Include partial overlap with the exclusion area into the grid.

.. code:: ipython3

    grid = gridify(
        include_area=include_gdf,
        exclude_area=exclude_gdf,
        grid_size=((1/3), (1/3)),
        include_partial=False,
    )

    ax = grid.boundary.plot()
    ax.set_xlim([-.1, 1.2])
    ax.set_ylim([-.1, 1.2])



.. image:: doc/_static/figs/output_7_1.png


Plot the grid overlapping the include area in green, and the exclude
area in red.

.. code:: ipython3

    ax = include_gdf.plot(color="green", alpha=0.5)
    exclude_gdf.plot(ax=ax, color="red", alpha=0.5)
    grid.boundary.plot(ax=ax, color="blue")



.. image:: doc/_static/figs/output_9_1.png


Alternatively, partial overlap may be included into the final grid.

.. code:: ipython3

    grid_include_partial = gridify(
        include_area=include_gdf,
        exclude_area=exclude_gdf,
        grid_size=((1/3), (1/3)),
        include_partial=True,
    )

    ax = include_gdf.plot(color="green", alpha=0.5)
    exclude_gdf.plot(ax=ax, color="red", alpha=0.5)
    grid_include_partial.boundary.plot(ax=ax, color="blue")

.. image:: doc/_static/figs/output_11_1.png


Overlay Gridify
^^^^^^^^^^^^^^^

Define the area of the primary geometry. Both geometries need to be off the same geometry kind. Add the geometries to a dataframe.

.. code:: ipython3

    part1 = shapely.geometry.box(
       minx=0,
       miny=0,
       maxx=0.5,
       maxy=1,
    )
    part2 = shapely.geometry.box(
       minx=0.5,
       miny=0,
       maxx=0.75,
       maxy=0.75,
    )
    primary_gdf = gpd.GeoDataFrame({"col1": [1, 2]}, geometry=[part1, part2])
    ax = primary_gdf.plot(column="col1")
    ax.set_xlim([-.1, 1.2])
    ax.set_ylim([-.1, 1.2])

.. image:: doc/_static/figs/overlay_primary.png


Define a secondary geometry.

.. code:: ipython3

    exclude = shapely.geometry.box(
        minx=0.5,
        miny=0.5,
        maxx=1.1,
        maxy=1.1,
    )
    secondary_gdf = gpd.GeoDataFrame({"col1": [1]}, geometry=[exclude])
    ax = secondary_gdf.plot(color="red", alpha=0.5)
    ax.set_xlim([-.1, 1.2])
    ax.set_ylim([-.1, 1.2])

.. image:: doc/_static/figs/overlay_secondary.png


Perform a `difference` spatial overlay between the primary and secondary geometry before
generating a grid with (1/3) as grid size.

.. code:: ipython3

    grid = overlay_gridify(
        primary_area=primary_gdf,
        secondary_area=secondary_gdf,
        grid_size=((1/3), (1/3)),
        how="difference",
    )

    ax = grid.boundary.plot()
    ax.set_xlim([-.1, 1.2])
    ax.set_ylim([-.1, 1.2])

.. image:: doc/_static/figs/overlay_grid.png


Plot the grid overlapping the primary area in green, and the secondary area in red.

.. code:: ipython3

    ax = primary_gdf.plot(color="green", alpha=0.5)
    secondary_gdf.plot(ax=ax, color="red", alpha=0.5)
    grid.boundary.plot(ax=ax, color="blue")


.. image:: doc/_static/figs/overlay_total.png


GridifyProcessor
^^^^^^^^^^^^^^^^

Other than the basic Gridify functionality, the package also supports raw GeoData handling trough the :code:`GridifyProcessor` class. The class is able to read GIS files and save the grid to a specified GIS file format (`GeoJSON`, `Shapefile` or `GPKG`).


.. code:: ipython3

    from gridify.processor import GridifyProcessor

Initialize the :code:`GridifyProcessor` class by the path to the primary and, optionally, secondary geometry files. For example, to create processor class where the grid is saved as a grid of centroids in GIS format `Shapefile` use:

.. code:: ipython3

    primary_geometry_path = "<dir_to_geometry><primary_geometry_filename>"

    processor = GridifyProcessor(path_to_primary_geometry=primary_geometry_path,
                                 as_centroids=True,
                                 file_format="Shapefile")

Through parameter :code:`as_centroids=True` it is specified to save the grid as points instead of box shaped polygons. The points represents the centroid of each box shaped polygon. To revert back to a grid of box shaped polygons set :code:`as_centroids` back to :code:`False`. It is possible to specify the CRS of the saved grid, this CRS does not need to be the same as the input geometry. This can be done by the parameter :code:`crs`. The GIS file format is specified by parameter :code:`file_format`.

Once the class is initialized, and the output format is specified, a grid may be generated. The :code:`GridifyProcessor` has three methods to generate grid:

- :code:`gridify_primary_geometry()`; generate a grid over the primary geometry.
- :code:`gridify_secondary_geometry()`; generate a grid over the secondary geometry.
- :code:`gridify_overlay()`; generate a grid over a performed spatial overlay between two areas.

For each of the three methods the size of the grid may be set by the user. After successfully calling the function, the path to the saved grid is returned.

.. code:: ipython3

    print(processor.gridify_primary_geometry(grid_size=(300, 300)))
    # <dir_to_geometry><primary_geometry_filename>_300x300_centroids.shp.zip


.. end-inclusion-usage-marker-do-not-remove


.. begin-inclusion-installation-marker-do-not-remove

Installation
------------

To install gridify, do:

.. code-block:: console

  git clone https://gitlab.com/rwsdatalab/public/codebase/image/gridify.git
  cd gridify
  pip install .

Run tests (including coverage) with:

.. code-block:: console

    pip install .[dev]
    pytest

.. end-inclusion-installation-marker-do-not-remove


Documentation
-------------

Include a link to your project's full documentation here.


.. begin-inclusion-license-marker-do-not-remove

License
-------

Copyright (c) 2024, Rijkswaterstaat


Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.



.. end-inclusion-license-marker-do-not-remove