tesspy package

tesspy

.. py:module:: tesspy

tesspy — geographic tessellation for urban spatial analysis.

tesspy discretises a geographic area into non-overlapping, gap-free subregions using five tessellation methods driven by OpenStreetMap data:

   * squares         — regular quadkey-based square grid
   * hexagons        — regular H3 hexagon grid (Uber)
   * adaptive_squares — POI-density-driven recursive square subdivision
   * voronoi         — Voronoi polygons seeded by POI cluster centroids
   * city_blocks     — urban blocks formed by the OSM road network

Public API

Tessellation : main class; instantiate with a city name or GeoDataFrame count_poi_per_tile : count OSM POI categories per tessellation tile configure_logging : configure package logger output/level

Subpackages

tesspy.methods : individual tessellation algorithm implementations tesspy.data : OSM data retrieval (POI via Overpass API, roads via osmnx)

.. rubric:: Example

from tesspy import Tessellation t = Tessellation(“Frankfurt am Main”) squares = t.squares(resolution=12) hexagons = t.hexagons(resolution=8)

.. py:class:: Tessellation(area: ~geopandas.geodataframe.GeoDataFrame | str) :module: tesspy :canonical: tesspy.tessellation.Tessellation

Bases: :py:class:object

Create a Tessellation object for a geographic area, enabling multiple tessellation methods (squares, hexagons, adaptive squares, Voronoi, and city blocks).

:param area: GeoDataFrame must have a single Polygon or MultiPolygon in its geometry column with a defined CRS. str must be a city name or address of a region. :type area: geopandas.GeoDataFrame or str

.. rubric:: Examples

ffm = Tessellation(‘Frankfurt am Main’) squares_gdf = ffm.squares(resolution=12)

.. py:method:: Tessellation.adaptive_squares(start_resolution: int, poi_categories: list[str] | ~typing.Literal[‘all’] | None = None, threshold: int | None = None, timeout: int = 300, verbose: bool = True) -> ~geopandas.geodataframe.GeoDataFrame :module: tesspy

  Generate adaptive squares based on POI density.

  Squares are created at start_resolution and recursively subdivided
  into four smaller squares whenever the POI count exceeds the threshold.

  :param start_resolution: Initial zoom level for the square grid
  :type start_resolution: int
  :param poi_categories: OSM primary map feature categories used to guide subdivision
  :type poi_categories: list of str or 'all', default=["amenity", "building"]
  :param threshold: POI count threshold for subdivision. If None, uses the median
                    count across all initial squares.
  :type threshold: int or None, default=None
  :param timeout: Overpass API timeout in seconds
  :type timeout: int, default=300
  :param verbose: Log progress information via the ``tesspy`` logger
  :type verbose: bool, default=True

  :returns: GeoDataFrame with adaptive square tiles
  :rtype: gpd.GeoDataFrame

.. py:method:: Tessellation.city_blocks(n_polygons: int | None = None, detail_deg: int | None = None, verbose: bool = True) -> ~geopandas.geodataframe.GeoDataFrame :module: tesspy

  Create city block tiles using OSM road network data.

  The study area boundary is included in the road line network before
  polygonization, producing gap-free blocks that fully tile the area.
  When *n_polygons* is set, adjacent blocks are merged using
  connectivity-constrained agglomerative clustering.

  :param n_polygons: Target number of city blocks (approximate).  Uses adjacency-
                     constrained hierarchical clustering to merge small blocks.
                     If None, all raw blocks are returned.
  :type n_polygons: int or None, default=None
  :param detail_deg: Number of top OSM highway types to include. None means all 19 types.
  :type detail_deg: int or None, default=None
  :param verbose: Log progress information via the ``tesspy`` logger
  :type verbose: bool, default=True

  :returns: GeoDataFrame with city block tiles and a 'cityblock_id' column
  :rtype: gpd.GeoDataFrame

.. py:method:: Tessellation.get_poi_data() -> ~pandas.DataFrame :module: tesspy

  Return the cached POI DataFrame (empty if no POI methods called yet).

.. py:method:: Tessellation.get_polygon() -> ~geopandas.geodataframe.GeoDataFrame :module: tesspy

  Return the study area polygon as a GeoDataFrame.

.. py:method:: Tessellation.get_road_network() -> ~pandas.DataFrame :module: tesspy

  Return the cached road network GeoDataFrame.

.. py:method:: Tessellation.hexagons(resolution: int) -> ~geopandas.geodataframe.GeoDataFrame :module: tesspy

  Generate a regular hexagon grid over the area (Uber H3).

  :param resolution: H3 resolution controlling hexagon size (0–15)
  :type resolution: int

  :returns: GeoDataFrame containing the hexagon tiles with a 'hex_id' column
  :rtype: gpd.GeoDataFrame

.. py:method:: Tessellation.osm_highway_types() -> list[str] :module: tesspy :staticmethod:

  Return the list of OSM highway type categories.
  See https://wiki.openstreetmap.org/wiki/Key:highway

.. py:method:: Tessellation.osm_primary_features() -> list[str] :module: tesspy :staticmethod:

  Return the list of primary OSM map feature categories.
  See https://wiki.openstreetmap.org/wiki/Map_features

.. py:method:: Tessellation.squares(resolution: int) -> ~geopandas.geodataframe.GeoDataFrame :module: tesspy

  Generate a regular square grid over the area.

  :param resolution: Zoom level controlling square size (higher = smaller squares)
  :type resolution: int

  :returns: GeoDataFrame containing the square tiles
  :rtype: gpd.GeoDataFrame

.. py:method:: Tessellation.voronoi(cluster_algo: ~typing.Literal[‘k-means’, ‘hdbscan’] | None = ‘k-means’, poi_categories: list[str] | ~typing.Literal[‘all’] | None = None, timeout: int = 300, n_polygons: int = 100, min_cluster_size: int = 15, verbose: bool = True) -> ~geopandas.geodataframe.GeoDataFrame :module: tesspy

  Generate Voronoi polygon tessellation driven by POI density.

  :param cluster_algo: Clustering algorithm used to derive Voronoi generators.
                       If None, POI locations are used directly (max 5000).
  :type cluster_algo: {'k-means', 'hdbscan', None}, default='k-means'
  :param poi_categories: OSM primary map feature categories used as input data
  :type poi_categories: list of str or 'all', default=["amenity", "building"]
  :param timeout: Overpass API timeout in seconds
  :type timeout: int, default=300
  :param n_polygons: Target number of polygons (k-means only)
  :type n_polygons: int, default=100
  :param min_cluster_size: Minimum cluster size (hdbscan only)
  :type min_cluster_size: int, default=15
  :param verbose: Log progress information via the ``tesspy`` logger
  :type verbose: bool, default=True

  :returns: GeoDataFrame with Voronoi polygon tiles and a 'voronoi_id' column
  :rtype: gpd.GeoDataFrame

.. py:function:: configure_logging(level: int | str = ‘INFO’, *, stream: ~typing.TextIO | None = None, fmt: str = ‘%(asctime)s | %(levelname)s | %(name)s | %(message)s’, datefmt: str = ‘%Y-%m-%d %H:%M:%S’) -> ~logging.Logger :module: tesspy

Configure the package logger for tesspy and return it.

This function is idempotent: repeated calls do not stack duplicate package- owned handlers.

.. py:function:: count_poi_per_tile(city: ~geopandas.geodataframe.GeoDataFrame | str, gdf: ~geopandas.geodataframe.GeoDataFrame, poi_categories: list[str] | str | None = None, timeout: int = 300, verbose: bool = True) -> ~geopandas.geodataframe.GeoDataFrame :module: tesspy

Count POI categories per tessellation tile.

For each POI category an additional count column is added to the tessellation GeoDataFrame.

:param city: Study area as a GeoDataFrame (single Polygon/MultiPolygon, EPSG:4326) or a city name string to geocode via OSM. If you have a Tessellation object, pass t.get_polygon() here. :type city: geopandas.GeoDataFrame or str :param gdf: Tessellation GeoDataFrame (output of any Tessellation method) :type gdf: geopandas.GeoDataFrame :param poi_categories: OSM primary map feature categories to count per tile. :type poi_categories: list of str or str, default=[“amenity”, “building”] :param timeout: TCP timeout in seconds for the OSM Overpass request :type timeout: int, default=300 :param verbose: Log progress information via the tesspy logger. :type verbose: bool, default=True

:returns: gdf – Tessellation GeoDataFrame with additional count columns per POI category :rtype: geopandas.GeoDataFrame

tesspy.poi_data

.. py:module:: tesspy.poi_data

Backward-compatibility shim for tesspy.poi_data.

.. deprecated:: This module is deprecated and will be removed in v0.3.0. Import from tesspy.data directly:

   from tesspy.data.poi import POIdata
   from tesspy.data.roads import RoadData

.. py:class:: POIdata(area, poi_categories: list[str], timeout: int, verbose: bool) :module: tesspy.poi_data :canonical: tesspy.data.poi.POIdata

Bases: :py:class:object

Query OSM for Points of Interest within a study area using osmnx.

osmnx provides automatic retry on 429/504 errors, proactive rate-limit checking, file-based response caching, and polygon-based spatial filtering.

:param area: GeoDataFrame with a single Polygon or MultiPolygon and a defined CRS. :type area: geopandas.GeoDataFrame :param poi_categories: OSM primary map feature categories to query. :type poi_categories: list of str :param timeout: Request timeout in seconds for the Overpass query. :type timeout: int :param verbose: If True, log progress information via the tesspy logger. :type verbose: bool

.. py:method:: POIdata.get_poi_data() -> ~pandas.DataFrame :module: tesspy.poi_data

  Query OSM POI data and return it as a DataFrame.

  :returns: **poi_df** -- DataFrame with center coordinates and boolean columns for each
            queried POI category.
  :rtype: pandas.DataFrame

.. py:method:: POIdata.osm_primary_features() -> list[str] :module: tesspy.poi_data :staticmethod:

  Return the list of primary OSM map feature categories.
  See https://wiki.openstreetmap.org/wiki/Map_features

  :rtype: list of str

.. py:class:: RoadData(area: ~geopandas.geodataframe.GeoDataFrame, detail_deg: int | None = None, split_roads: bool = True, verbose: bool = False) :module: tesspy.poi_data :canonical: tesspy.data.roads.RoadData

Bases: :py:class:object

Retrieve and process OSM road network data using osmnx.

:param area: GeoDataFrame with a single Polygon or MultiPolygon and a defined CRS. :type area: geopandas.GeoDataFrame :param detail_deg: Number of top highway types to include. None means all 19 types. :type detail_deg: int or None :param split_roads: If True, LineStrings are split so each has exactly 2 points. :type split_roads: bool :param verbose: If True, log progress information via the tesspy logger. :type verbose: bool

.. py:method:: RoadData.create_custom_filter() -> str :module: tesspy.poi_data

  Build the osmnx custom filter string for the selected highway types.

  :returns: **custom_filter** -- Filter string in osmnx format, e.g. "['highway'~'motorway|trunk|...']"
  :rtype: str

.. py:method:: RoadData.get_road_network() -> ~geopandas.geodataframe.GeoDataFrame :module: tesspy.poi_data

  Download the road network for the study area and return it as a GeoDataFrame.

  :returns: **graph_edges_as_gdf** -- GeoDataFrame containing road network edges
  :rtype: geopandas.GeoDataFrame

.. py:method:: RoadData.osm_highway_types() -> list[str] :module: tesspy.poi_data :staticmethod:

  Return the list of OSM highway type categories.
  See https://wiki.openstreetmap.org/wiki/Key:highway

  :rtype: list of str

.. py:function:: geom_ceil(coordinate: float, precision: int = 4) -> float :module: tesspy.poi_data

Round coordinate up to specified decimal precision.

.. py:function:: geom_floor(coordinate: float, precision: int = 4) -> float :module: tesspy.poi_data

Round coordinate down to specified decimal precision.

tesspy.tessellation

.. py:module:: tesspy.tessellation

Core Tessellation class — the primary public interface of tesspy.

.. py:class:: Tessellation(area: ~geopandas.geodataframe.GeoDataFrame | str) :module: tesspy.tessellation

Bases: :py:class:object

Create a Tessellation object for a geographic area, enabling multiple tessellation methods (squares, hexagons, adaptive squares, Voronoi, and city blocks).

:param area: GeoDataFrame must have a single Polygon or MultiPolygon in its geometry column with a defined CRS. str must be a city name or address of a region. :type area: geopandas.GeoDataFrame or str

.. rubric:: Examples

ffm = Tessellation(‘Frankfurt am Main’) squares_gdf = ffm.squares(resolution=12)

.. py:method:: Tessellation.adaptive_squares(start_resolution: int, poi_categories: list[str] | ~typing.Literal[‘all’] | None = None, threshold: int | None = None, timeout: int = 300, verbose: bool = True) -> ~geopandas.geodataframe.GeoDataFrame :module: tesspy.tessellation

  Generate adaptive squares based on POI density.

  Squares are created at start_resolution and recursively subdivided
  into four smaller squares whenever the POI count exceeds the threshold.

  :param start_resolution: Initial zoom level for the square grid
  :type start_resolution: int
  :param poi_categories: OSM primary map feature categories used to guide subdivision
  :type poi_categories: list of str or 'all', default=["amenity", "building"]
  :param threshold: POI count threshold for subdivision. If None, uses the median
                    count across all initial squares.
  :type threshold: int or None, default=None
  :param timeout: Overpass API timeout in seconds
  :type timeout: int, default=300
  :param verbose: Log progress information via the ``tesspy`` logger
  :type verbose: bool, default=True

  :returns: GeoDataFrame with adaptive square tiles
  :rtype: gpd.GeoDataFrame

.. py:method:: Tessellation.city_blocks(n_polygons: int | None = None, detail_deg: int | None = None, verbose: bool = True) -> ~geopandas.geodataframe.GeoDataFrame :module: tesspy.tessellation

  Create city block tiles using OSM road network data.

  The study area boundary is included in the road line network before
  polygonization, producing gap-free blocks that fully tile the area.
  When *n_polygons* is set, adjacent blocks are merged using
  connectivity-constrained agglomerative clustering.

  :param n_polygons: Target number of city blocks (approximate).  Uses adjacency-
                     constrained hierarchical clustering to merge small blocks.
                     If None, all raw blocks are returned.
  :type n_polygons: int or None, default=None
  :param detail_deg: Number of top OSM highway types to include. None means all 19 types.
  :type detail_deg: int or None, default=None
  :param verbose: Log progress information via the ``tesspy`` logger
  :type verbose: bool, default=True

  :returns: GeoDataFrame with city block tiles and a 'cityblock_id' column
  :rtype: gpd.GeoDataFrame

.. py:method:: Tessellation.get_poi_data() -> ~pandas.DataFrame :module: tesspy.tessellation

  Return the cached POI DataFrame (empty if no POI methods called yet).

.. py:method:: Tessellation.get_polygon() -> ~geopandas.geodataframe.GeoDataFrame :module: tesspy.tessellation

  Return the study area polygon as a GeoDataFrame.

.. py:method:: Tessellation.get_road_network() -> ~pandas.DataFrame :module: tesspy.tessellation

  Return the cached road network GeoDataFrame.

.. py:method:: Tessellation.hexagons(resolution: int) -> ~geopandas.geodataframe.GeoDataFrame :module: tesspy.tessellation

  Generate a regular hexagon grid over the area (Uber H3).

  :param resolution: H3 resolution controlling hexagon size (0–15)
  :type resolution: int

  :returns: GeoDataFrame containing the hexagon tiles with a 'hex_id' column
  :rtype: gpd.GeoDataFrame

.. py:method:: Tessellation.osm_highway_types() -> list[str] :module: tesspy.tessellation :staticmethod:

  Return the list of OSM highway type categories.
  See https://wiki.openstreetmap.org/wiki/Key:highway

.. py:method:: Tessellation.osm_primary_features() -> list[str] :module: tesspy.tessellation :staticmethod:

  Return the list of primary OSM map feature categories.
  See https://wiki.openstreetmap.org/wiki/Map_features

.. py:method:: Tessellation.squares(resolution: int) -> ~geopandas.geodataframe.GeoDataFrame :module: tesspy.tessellation

  Generate a regular square grid over the area.

  :param resolution: Zoom level controlling square size (higher = smaller squares)
  :type resolution: int

  :returns: GeoDataFrame containing the square tiles
  :rtype: gpd.GeoDataFrame

.. py:method:: Tessellation.voronoi(cluster_algo: ~typing.Literal[‘k-means’, ‘hdbscan’] | None = ‘k-means’, poi_categories: list[str] | ~typing.Literal[‘all’] | None = None, timeout: int = 300, n_polygons: int = 100, min_cluster_size: int = 15, verbose: bool = True) -> ~geopandas.geodataframe.GeoDataFrame :module: tesspy.tessellation

  Generate Voronoi polygon tessellation driven by POI density.

  :param cluster_algo: Clustering algorithm used to derive Voronoi generators.
                       If None, POI locations are used directly (max 5000).
  :type cluster_algo: {'k-means', 'hdbscan', None}, default='k-means'
  :param poi_categories: OSM primary map feature categories used as input data
  :type poi_categories: list of str or 'all', default=["amenity", "building"]
  :param timeout: Overpass API timeout in seconds
  :type timeout: int, default=300
  :param n_polygons: Target number of polygons (k-means only)
  :type n_polygons: int, default=100
  :param min_cluster_size: Minimum cluster size (hdbscan only)
  :type min_cluster_size: int, default=15
  :param verbose: Log progress information via the ``tesspy`` logger
  :type verbose: bool, default=True

  :returns: GeoDataFrame with Voronoi polygon tiles and a 'voronoi_id' column
  :rtype: gpd.GeoDataFrame

.. py:function:: count_poi_per_tile(city: ~geopandas.geodataframe.GeoDataFrame | str, gdf: ~geopandas.geodataframe.GeoDataFrame, poi_categories: list[str] | str | None = None, timeout: int = 300, verbose: bool = True) -> ~geopandas.geodataframe.GeoDataFrame :module: tesspy.tessellation

Count POI categories per tessellation tile.

For each POI category an additional count column is added to the tessellation GeoDataFrame.

:param city: Study area as a GeoDataFrame (single Polygon/MultiPolygon, EPSG:4326) or a city name string to geocode via OSM. If you have a Tessellation object, pass t.get_polygon() here. :type city: geopandas.GeoDataFrame or str :param gdf: Tessellation GeoDataFrame (output of any Tessellation method) :type gdf: geopandas.GeoDataFrame :param poi_categories: OSM primary map feature categories to count per tile. :type poi_categories: list of str or str, default=[“amenity”, “building”] :param timeout: TCP timeout in seconds for the OSM Overpass request :type timeout: int, default=300 :param verbose: Log progress information via the tesspy logger. :type verbose: bool, default=True

:returns: gdf – Tessellation GeoDataFrame with additional count columns per POI category :rtype: geopandas.GeoDataFrame

.. py:function:: get_city_polygon(city: str) -> ~geopandas.geodataframe.GeoDataFrame :module: tesspy.tessellation

Retrieve the boundary polygon of a city or region from OSM.

:param city: Name of a city or address of a region :type city: str

:returns: df_city – GeoDataFrame containing the boundary polygon :rtype: geopandas.GeoDataFrame

tesspy.tessellation_functions

.. py:module:: tesspy.tessellation_functions

Backward-compatibility shim for tesspy.tessellation_functions.

.. deprecated:: This module is deprecated and will be removed in v0.3.0. Import from tesspy.methods directly:

   from tesspy.methods.squares import (
       count_poi, get_squares_polyfill, get_adaptive_squares,
   )
   from tesspy.methods.hexagons import get_h3_hexagons
   from tesspy.methods.voronoi import voronoi_polygons
   from tesspy.methods.city_blocks import (
       split_linestring, explode, create_blocks, get_rest_polygon,
   )
   from tesspy.methods._clustering import get_hierarchical_clustering_parameter

.. py:function:: count_poi(df: ~geopandas.geodataframe.GeoDataFrame, points: ~geopandas.geodataframe.GeoDataFrame) -> ~geopandas.geodataframe.GeoDataFrame :module: tesspy.tessellation_functions

Counts the number of POI in each tile.

:param df: GeoDataFrame containing the tiles (polygons) :type df: geopandas.GeoDataFrame :param points: GeoDataFrame containing the POI points :type points: geopandas.GeoDataFrame

:returns: final_gdf – GeoDataFrame containing the tiles with an added ‘count’ column :rtype: geopandas.GeoDataFrame

.. py:function:: create_blocks(road_network: ~geopandas.geodataframe.GeoDataFrame) -> ~geopandas.geodataframe.GeoDataFrame :module: tesspy.tessellation_functions

Use shapely polygonize to create city block polygons from road LineStrings.

.. deprecated:: Use :func:create_city_blocks instead, which includes boundary handling and proper noding. Will be removed in v0.3.0.

:param road_network: GeoDataFrame containing street segment geometries :type road_network: geopandas.GeoDataFrame

:returns: blocks – GeoDataFrame of block polygons formed by the road network :rtype: geopandas.GeoDataFrame

.. py:function:: create_city_blocks(road_network: ~geopandas.geodataframe.GeoDataFrame, area: ~geopandas.geodataframe.GeoDataFrame) -> ~geopandas.geodataframe.GeoDataFrame :module: tesspy.tessellation_functions

Create city block polygons from a road network and study area boundary.

The study area boundary is included as lines before polygonizing, so polygonize naturally produces closed blocks at the perimeter without requiring a separate gap-filling step. All lines are noded via unary_union to split them at every intersection point.

:param road_network: GeoDataFrame containing road LineString geometries. :type road_network: geopandas.GeoDataFrame :param area: GeoDataFrame with a single Polygon or MultiPolygon defining the study area boundary. Must have a defined CRS. :type area: geopandas.GeoDataFrame

:returns: GeoDataFrame of city block Polygons (CRS EPSG:4326). Only blocks whose representative point falls within the study area are included. :rtype: geopandas.GeoDataFrame

.. py:function:: explode(gdf: ~geopandas.geodataframe.GeoDataFrame) -> ~geopandas.geodataframe.GeoDataFrame :module: tesspy.tessellation_functions

Explode MultiPolygon geometries into individual Polygon rows.

.. deprecated:: Use gdf.explode(index_parts=True) directly. Will be removed in v0.3.0.

:param gdf: GeoDataFrame that may contain MultiPolygon geometries :type gdf: geopandas.GeoDataFrame

:returns: gdf_out – GeoDataFrame with only single Polygon geometries :rtype: geopandas.GeoDataFrame

.. py:function:: get_adaptive_squares(input_gdf: ~geopandas.geodataframe.GeoDataFrame, threshold: int) -> ~geopandas.geodataframe.GeoDataFrame :module: tesspy.tessellation_functions

Adaptive tessellation.

Subdivides all squares where the POI count threshold is exceeded.

:param input_gdf: GeoDataFrame containing the tiles (polygons) with a ‘count’ column :type input_gdf: geopandas.GeoDataFrame :param threshold: Threshold, which controls the division of squares :type threshold: int

:returns: gdf – GeoDataFrame containing the updated squares :rtype: geopandas.GeoDataFrame

.. py:function:: get_h3_hexagons(gdf: ~geopandas.geodataframe.GeoDataFrame, resolution: int) -> ~geopandas.geodataframe.GeoDataFrame :module: tesspy.tessellation_functions

Hexagon tessellation based on the H3 implementation by Uber.

:param gdf: GeoDataFrame containing the area polygon(s) :type gdf: geopandas.GeoDataFrame :param resolution: Resolution, which controls the hexagon sizes :type resolution: int

:returns: gdf – GeoDataFrame containing the hexagons :rtype: geopandas.GeoDataFrame

.. py:function:: get_hierarchical_clustering_parameter(coordinates: ~numpy.ndarray, threshold: int) -> int | None :module: tesspy.tessellation_functions

Find a distance_threshold for AgglomerativeClustering that yields fewer clusters than the given threshold.

Uses binary search over [200, 1200] to minimize the number of model fits.

:param coordinates: Array of (x, y) centroid coordinates :type coordinates: numpy.ndarray :param threshold: Maximum acceptable number of clusters :type threshold: int

:returns: th – The distance_threshold value, or None if no suitable value was found in the search range (200–1200) :rtype: int or None

.. py:function:: get_rest_polygon(blocks: ~geopandas.geodataframe.GeoDataFrame, area: ~geopandas.geodataframe.GeoDataFrame) -> ~geopandas.geodataframe.GeoDataFrame :module: tesspy.tessellation_functions

Create “rest polygons” to fill gaps not covered by road-based blocks.

.. deprecated:: Use :func:create_city_blocks instead, which includes the study area boundary in the polygonization so no gap-filling is needed. Will be removed in v0.3.0.

:param blocks: GeoDataFrame containing city block polygons :type blocks: geopandas.GeoDataFrame :param area: GeoDataFrame containing the study area boundary polygon :type area: geopandas.GeoDataFrame

:returns: rest_polygons – GeoDataFrame containing the gap-filling polygons :rtype: geopandas.GeoDataFrame

.. py:function:: get_squares_polyfill(gdf: ~geopandas.geodataframe.GeoDataFrame, zoom_level: int) -> ~geopandas.geodataframe.GeoDataFrame :module: tesspy.tessellation_functions

Square tessellation based on the quadKeys concept.

:param gdf: GeoDataFrame containing the area polygon(s) :type gdf: geopandas.GeoDataFrame :param zoom_level: Resolution, which controls the square sizes :type zoom_level: int

:returns: gdf – GeoDataFrame containing the squares :rtype: geopandas.GeoDataFrame

.. py:function:: merge_city_blocks(blocks: ~geopandas.geodataframe.GeoDataFrame, n_polygons: int) -> ~geopandas.geodataframe.GeoDataFrame :module: tesspy.tessellation_functions

Merge city block polygons into n_polygons groups using adjacency-constrained agglomerative clustering.

Only spatially adjacent blocks (those sharing a boundary segment) can be merged together, preventing disconnected MultiPolygon results.

:param blocks: GeoDataFrame of city block Polygons. :type blocks: geopandas.GeoDataFrame :param n_polygons: Target number of merged blocks. :type n_polygons: int

:returns: GeoDataFrame of merged block Polygons (CRS EPSG:4326). :rtype: geopandas.GeoDataFrame

.. py:function:: split_linestring(df: ~geopandas.geodataframe.GeoDataFrame) -> ~geopandas.geodataframe.GeoDataFrame :module: tesspy.tessellation_functions

Split LineStrings with more than 2 points into 2-point segments. Each resulting segment retains the osmid of the original road.

.. deprecated:: Use :func:create_city_blocks instead, which handles noding automatically. Will be removed in v0.3.0.

:param df: GeoDataFrame containing shapely LineStrings :type df: geopandas.GeoDataFrame

:returns: dataset – GeoDataFrame with 2-point LineStrings :rtype: geopandas.GeoDataFrame

.. py:function:: voronoi_polygons(sp_voronoi_obj: ~scipy.spatial._qhull.Voronoi, diameter: float) -> ~collections.abc.Generator[~shapely.geometry.polygon.Polygon, None, None] :module: tesspy.tessellation_functions

Convert a scipy Voronoi object into shapely Polygons.

:param sp_voronoi_obj: Voronoi object created from point coordinates :type sp_voronoi_obj: scipy.spatial.Voronoi :param diameter: Controls the extent of infinite Voronoi regions. Should be large enough to cover the bounding box of the input points. :type diameter: float

:Yields: shapely.geometry.Polygon – Voronoi polygons (finite and infinite regions)