momepy.enclosed_tessellation

momepy.enclosed_tessellation(geometry, enclosures, shrink=0.4, segment=0.5, threshold=0.05, simplify=None, n_jobs=-1, inner_barriers=None, cell_size=1, neighbor_mode='moore', **kwargs)[source]

Generate enclosed tessellation

Enclosed tessellation is an enhanced morphological_tessellation(), based on predefined enclosures and building footprints. We can see enclosed tessellation as two-step partitioning of space based on building footprints and boundaries (e.g. street network, railway). Original morphological tessellation is used under the hood to partition each enclosure.

When inner_barriers are provided, the tessellation is derived using a Cellular Automata implementation that recognizes dangling barriers (such as dead-end streets) as valid limits of cell growth. This is more computationally intensive but handles complex barrier configurations more accurately.

Tessellation requires data of relatively high level of precision and there are three particular patterns causing issues:

  1. Features will collapse into empty polygon - these do not have tessellation cell in the end.

  2. Features will split into MultiPolygons - in some cases, features with narrow links between parts split into two during ‘shrinking’. In most cases that is not an issue and the resulting tessellation is correct anyway, but sometimes this results in a cell being a MultiPolygon, which is not correct.

  3. Overlapping features - features which overlap even after ‘shrinking’ cause invalid tessellation geometry.

All three types can be tested using momepy.CheckTessellationInput.

The index of the resulting GeoDataFrame links the input buildings with the output geometry. Enclosures with no buildings are also included in the output with negative index. Ensure that the input geometry has unique non-negative index for this to work correctly.

Parameters:
geometry : GeoSeries | GeoDataFrame

A GeoDataFrame or GeoSeries containing buildings to tessellate the space around.

enclosures : GeoSeries | GeoDataFrame

The enclosures geometry, which can be generated using momepy.enclosures().

shrink : float, optional

The distance for negative buffer to generate space between adjacent polygons. Shall be changed in sync with segment. By default 0.4

segment : float, optional

The maximum distance between points after discretization. A right value is a sweet spot between computational inefficiency (when the value is too low) and suboptimal resulting geometry (when the value is too large). The default is empirically derived for the use case on building footprints represented in map units. By default 0.5

threshold : float, optional

The minimum threshold for a building to be considered within an enclosure. Threshold is a ratio of building area which needs to be within an enclosure to inlude it in the tessellation of that enclosure. Resolves sliver geometry issues. If None, the check is skipped and all intersecting buildings are considered. By default 0.05

simplify : None

Deprecated keyword with no effect. It will be removed in a future release.

n_jobs : int, optional

The number of jobs to run in parallel. -1 means using all available cores. By default -1

inner_barriers : GeoSeries | GeoDataFrame, optional

Barriers that should be included in the tessellation process. When provided, tessellation will be derived using a Cellular Automata implementation that recognizes dangling barriers (such as dead-end streets or cul-de-sacs) as valid limits of cell growth. This is more computationally intensive than the default Voronoi-based approach but can handle inner barriers. By default None.

cell_size : float, optional

Grid cell size for the Cellular Automata implementation when inner_barriers is not None. Smaller values provide higher resolution but increase computational cost. This parameter controls the spatial granularity of the tessellation grid. When inner_barriers is None, this parameter is ignored. By default 1.0

neighbor_mode : str, optional

Choice of neighbor connectivity for the Cellular Automata implementation when inner_barriers is not None. Options are ‘moore’ (8-connected, including diagonal neighbors) or ‘neumann’ (4-connected, only orthogonal neighbors). When inner_barriers is None, this parameter is ignored. By default ‘moore’.

**kwargs

Additional keyword arguments passed to libpysal.cg.voronoi_frames() when inner_barriers is None, such as grid_size. These arguments are ignored when inner_barriers is provided and the Cellular Automata implementation is used.

Warning

Due to the floating point precision issues in clipping the tessellation cells to the extent of their parental enclosures, the result does not form a precise polygonal coverage. To build a contiguity graph, use fuzzy contiguity builder with a small buffer, e.g.:

from libpysal import graph

graph.Graph.build_fuzzy_contiguity(tessellation, buffer=1e-6)
Returns:

GeoDataFrame with an index matching the index of input geometry and a column matching the index of input enclosures.

Return type:

GeoDataFrame

See also

momepy.enclosures, momepy.morphological_tessellation, momepy.CheckTessellationInput, momepy.verify_tessellation

Examples

>>> path = momepy.datasets.get_path("bubenec")
>>> buildings = geopandas.read_file(path, layer="buildings")
>>> streets = geopandas.read_file(path, layer="streets")

Generate enclosures:

>>> enclosures = momepy.enclosures(streets)

Generate tessellation:

>>> momepy.enclosed_tessellation(buildings, enclosures).head()
                                              geometry  enclosure_index
0    POLYGON ((1603546.697 6464383.596, 1603585.64 ...                0
113  POLYGON ((1603517.131 6464349.296, 1603546.697...                0
114  POLYGON ((1603517.87 6464285.864, 1603515.152 ...                0
125  POLYGON ((1603586.269 6464256.691, 1603581.813...                0
126  POLYGON ((1603499.92 6464243.917, 1603493.299 ...                0