gridify 0.3.1

Generate a grid of box shaped polygons covering an area

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:

• simple_gridify; generate a grid over a single geometry.

• gridify; generate a grid between two geometries, describing an area to include and exclude.

• 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’.

How to use

Import packages

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.

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])

Define an area to exclude

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])

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.

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])

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

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")

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

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")

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.

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])

Define a secondary geometry.

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])

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

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])

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

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")

GridifyProcessor

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

from gridify.processor import GridifyProcessor

Initialize the 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:

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 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 as_centroids back to 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 crs. The GIS file format is specified by parameter file_format.

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

• gridify_primary_geometry(); generate a grid over the primary geometry.

• gridify_secondary_geometry(); generate a grid over the secondary geometry.

• 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.

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

Installation

To install gridify, do:

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

Run tests (including coverage) with:

pip install .[dev]
pytest

Documentation

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

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.