momepy.Tessellation#

class momepy.Tessellation(gdf, unique_id, limit=None, shrink=0.4, segment=0.5, verbose=True, enclosures=None, enclosure_id='eID', threshold=0.05, use_dask=True, n_chunks=None)[source]#

Generates tessellation. Three versions of tessellation can be created:

  1. Morphological tessellation around given buildings

    gdf within set limit.

  2. Proximity bands around given street network gdf

    within set limit.

  3. Enclosed tessellation based on given buildings

    gdf within enclosures.

Pass either limit to create morphological tessellation or proximity bands or enclosures to create enclosed tessellation.

See [Fleischmann et al., 2020] for details of implementation of morphological tessellation and [Araldi and Fusco, 2019] for proximity bands.

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 prior momepy.Tessellation using momepy.CheckTessellationInput.

Parameters:
gdfGeoDataFrame

A GeoDataFrame containing building footprints or street network.

unique_idstr

The name of the column with the unique ID.

limitMultiPolygon or Polygon (default None)

MultiPolygon or Polygon defining the study area limiting morphological tessellation or proximity bands (otherwise it could go to infinity).

shrinkfloat (default 0.4)

The distance for negative buffer to generate space between adjacent polygons (if geometry type of gdf is (Multi)Polygon).

segmentfloat (default 0.5)

The maximum distance between points after discretization.

verbosebool (default True)

If True, shows progress bars in loops and indication of steps.

enclosuresGeoDataFrame (default None)

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

enclosure_idstr (default ‘eID’)

The name of the enclosure_id containing unique identifer for each row in enclosures. Applies only if enclosures are passed.

thresholdfloat (default 0.05)

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. Applies only if enclosures are passed.

use_daskbool (default True)

Use parallelised algorithm based on dask.dataframe. Requires dask. Applies only if enclosures are passed.

n_chunksNone

The number of chunks to be used in parallelization. Ideal is one chunk per thread. Applies only if enclosures are passed. Default automatically uses n == dask.system.cpu_count.

Attributes:
tessellationGeoDataFrame

A GeoDataFrame containing resulting tessellation. For enclosed tessellation, gdf contains three columns:

  • geometry,

  • unique_id matching with parental building,

  • enclosure_id matching with enclosure integer index

gdfGeoDataFrame

The original GeoDataFrame.

idSeries

A Series containing used unique ID.

limitMultiPolygon or Polygon

MultiPolygon or Polygon defining the study area limiting morphological tessellation or proximity bands.

shrinkfloat

The distance for negative buffer to generate space between adjacent polygons.

segmentfloat

The maximum distance between points after discretization.

collapsedlist

A list of unique_id``s of collapsed features (if there are any). Applies only if ``limit is passed.

multipolygonslist

A list of unique_id``s of features causing MultiPolygons (if there are any). Applies only if ``limit is passed.

Examples

>>> tess = mm.Tessellation(
... buildings_df, 'uID', limit=mm.buffered_limit(buildings_df)
... )
Inward offset...
Generating input point array...
Generating Voronoi diagram...
Generating GeoDataFrame...
Dissolving Voronoi polygons...
>>> tess.tessellation.head()
    uID     geometry
0   1       POLYGON ((1603586.677274485 6464344.667944215,...
1   2       POLYGON ((1603048.399497852 6464176.180701573,...
2   3       POLYGON ((1603071.342637536 6464158.863329805,...
3   4       POLYGON ((1603055.834005827 6464093.614718676,...
4   5       POLYGON ((1603106.417554705 6464130.215958447,...

>>> enclosures = mm.enclosures(streets, admin_boundary, [railway, rivers])
>>> encl_tess = mm.Tessellation(
... buildings_df, 'uID', enclosures=enclosures
... )
>>> encl_tess.tessellation.head()
     uID                                           geometry  eID
0  109.0  POLYGON ((1603369.789 6464340.661, 1603368.754...    0
1  110.0  POLYGON ((1603368.754 6464340.097, 1603369.789...    0
2  111.0  POLYGON ((1603458.666 6464332.614, 1603458.332...    0
3  112.0  POLYGON ((1603462.235 6464285.609, 1603454.795...    0
4  113.0  POLYGON ((1603524.561 6464388.609, 1603532.241...    0
__init__(gdf, unique_id, limit=None, shrink=0.4, segment=0.5, verbose=True, enclosures=None, enclosure_id='eID', threshold=0.05, use_dask=True, n_chunks=None)[source]#

Methods

__init__(gdf, unique_id[, limit, shrink, ...])