---

name: "urban-morphology" description: "Build projected-CRS urban morphology graphs from building footprints and movement segments, including barrier-aware tessellation, place/movement composition, network-distance filters, fallbacks, and multi-distance outputs." metadata: disco-role: operating disable-model-invocation: true license: BSD 3-Clause

Urban morphology

Use this skill when the task is to turn building footprints and street-like LineString segments into a place/movement urban morphology graph, or when the task needs one of its three typed relation layers independently. The runtime API is GeoDataFrame-first and can return NetworkX only as a compatibility output. It does not require a notebook, Overture download, live service, or source checkout at execution time.

Read the bundled reference that matches the next decision:

• references/input-contracts.md — required geometry, ID, CRS, barrier, and output contracts.
• references/workflows.md — end-to-end, pairwise, and multi-distance recipes.
• references/troubleshooting.md — validation failures, empty/degraded tessellations, distance surprises, and barrier diagnostics.

Operating surface

Need	Entry point	What it returns
Complete morphology	city2graph.morphology.morphological_graph	(nodes, edges) dictionaries, or a deprecated-compatible NetworkX graph
Several network budgets	morphological_graphs	{float_distance: (nodes, edges)} or {float_distance: nx.Graph}
Place adjacency	place_to_place_graph	place nodes and touched_to edges
Place/street interface	place_to_movement_graph	combined nodes and faced_to edges
Street-segment connectivity	movement_to_movement_graph	movement nodes and connected_to edges
Explicit segment topology	segments_to_graph	endpoint nodes and segment edges
Standalone tessellation	city2graph.utils.create_tessellation	polygon cells with tess_id; enclosed cells also have enclosure_index

Prefer GeoDataFrame output. For downstream graph conversion, pass the returned nodes/edges to the package's graph-conversion API rather than relying on the deprecated as_nx argument.

Fast routing rules

1. Have buildings and segments, and need all three relation types? Call morphological_graph(buildings_gdf, segments_gdf, ...).
2. Need multiple radii from one center? Call morphological_graphs with a non-empty list/tuple of distances. It computes the movement graph and one reachability field once and reuses the largest-distance tessellation context.
3. Already have tessellation cells? Use the pairwise functions. Ensure cells have place_id and movement rows have movement_id before calling place_to_movement_graph or place_to_place_graph.
4. Need a movement topology only? Use segments_to_graph for endpoint topology, or movement_to_movement_graph for the dual graph whose nodes are segments.
5. Need barriers that are not traversable movement? Supply a boolean non_movement_barrier_col; supply primary_barrier_col separately when a row's alternative geometry should be used as the tessellation/facing geometry. These switches are orthogonal.
6. Need NetworkX? Prefer the package conversion function after inspecting GeoDataFrame output. as_nx=True remains available but is deprecated; any duplicate_edges=True, as_nx=True combination is invalid.

End-to-end procedure

1. Normalize spatial inputs

• Load building Polygon/MultiPolygon footprints and movement LineString segments into GeoDataFrames.
• Reproject every layer and the center point to one suitable projected CRS before any metric distance, centroid, buffer, or tessellation operation. Coordinates in EPSG:4326 are degrees, not meters. The morphology pipeline harmonizes the active segment CRS to the building CRS, but do not rely on that implicit conversion for the center or for an auxiliary barrier column.
• Ensure segment endpoints that are intended to connect are coordinate-equal; segments_to_graph deduplicates exact endpoint coordinate tuples, not fuzzy near-matches.
• If segments were reprojected after an auxiliary barrier_geometry column was made, keep that column geometry-aware or rebuild it. The implementation reprojects a CRS-tagged alternative barrier column to the active segment CRS; a CRS-less geometry column adopts the segment CRS.

2. Build the morphology graph

from city2graph.morphology import morphological_graph

nodes, edges = morphological_graph(
    buildings_gdf=buildings,
    segments_gdf=segments,
    center_point=center,       # optional Point/one-row GeoSeries/GeoDataFrame
    distance=500.0,            # optional network budget in projected units
    clipping_buffer=300.0,     # tessellation context beyond the budget
    extent_buffer=100.0,       # independent street-access cap
    primary_barrier_col="barrier_geometry",
    contiguity="queen",
    keep_buildings=True,
    keep_segments=True,
    tolerance=1e-6,
    include_unenclosed_buildings=False,
    tessellation_fallback=False,
    tessellation_n_jobs=1,
)

The pipeline validates and CRS-aligns inputs, assigns movement_id from the segment index on an owned copy, optionally splits barrier-only rows, builds a segment topology and (when requested) one shared reachability field, creates an enclosed tessellation, filters cells/buildings/segments, then composes the three relation layers. Caller-owned frames are not mutated.

center_point without distance does not activate network-distance filtering. distance without a center also does not activate it. A distance-filtered run uses the center snapped to its nearest usable network edge; a center far away is still snapped to that edge, so it is not a reason to expect an empty result unless the budget is too small or the network is unusable.

3. Inspect the typed result

With GeoDataFrame output, nodes has exactly the keys "place" and "movement". In the complete morphology path:

• nodes["place"] is indexed by place_id; geometry is the cell centroid, and tessellation_geometry preserves the original polygon. With keep_buildings=True, building_geometry and available building attributes are attached.
• nodes["movement"] is indexed by movement_id; geometry is the segment centroid. With keep_segments=True, segment_geometry preserves the original LineString and original segment attributes remain available.
• edges[("place", "touched_to", "place")] has a MultiIndex of from_place_id, to_place_id; it represents same-enclosure contiguity by default and includes a weight/edge geometry when non-empty.
• edges[("movement", "connected_to", "movement")] has from_movement_id, to_movement_id and is the segment dual/topological relation.
• edges[("place", "faced_to", "movement")] has place_id, movement_id and LineString edges between place and movement centroids.

Node geometries are centroids for graph conversion, not the original spatial objects. Always use tessellation_geometry, building_geometry, or segment_geometry when computing polygon/line features.

Composition semantics

Place-to-place (touched_to)

place_to_place_graph(place_gdf, group_col=None, contiguity="queen") requires place_id for non-empty input. queen joins cells sharing a boundary or vertex; rook requires shared edge contact. If group_col is set, only cells with the same group value connect. The complete morphology pipeline uses group_col="enclosure_index" when that column exists, preventing adjacency across enclosed street barriers. Duplicate place_id rows are deduplicated for graph construction. Empty/single-cell input returns nodes and empty edges.

Place-to-movement (faced_to)

place_to_movement_graph(place_gdf, movement_gdf, ...) requires place_id and movement_id for non-empty frames. It first uses a spatial-index dwithin query from movement geometry to place geometry with tolerance (map units). If a place cell has no match, it receives one nearest-movement fallback edge unless the nearest distance exceeds max_connection_distance. In a complete morphology graph this cap is extent_buffer; direct pairwise calls default to infinite. Regular tolerance matches are not removed by the fallback cap. A missing/empty movement layer produces empty interface edges.

If primary_barrier_col exists, it replaces the active movement geometry for this proximity query only. It does not remove the row from movement nodes. Null/empty alternative geometries do not become barrier/facing query geometries, although the segment remains a movement node.

Movement-to-movement (connected_to)

movement_to_movement_graph uses movement_id when present. Otherwise it creates a temporary _edge_id on a copy. It converts segment endpoint connections to a dual graph: each LineString is a movement node, and connected segments are linked. segments_to_graph is the lower-level endpoint graph: its node GDF contains unique endpoint Points indexed by node_id; its edge GDF preserves input segment rows and uses (from_node_id, to_node_id[, edge_key]). The default is multigraph=True, directed=True; set directed=False to canonicalize reverse-drawn endpoint pairs, and keep multigraph support when parallel segments are valid.

Barriers, clipping, and fallback policy

Alternative and barrier-only segment geometries

• primary_barrier_col selects an alternative geometry for tessellation barriers and place/movement proximity. It substitutes geometry only; those rows still become movement nodes and participate in movement-distance computation using their active LineString geometry.
• non_movement_barrier_col is a boolean flag. Truthy rows are removed from movement nodes, dual connectivity, and reachability, but appended to the tessellation context as barrier-only rows. False/missing values remain normal movement rows. When a center and distance are supplied, barrier-only rows are clipped by Euclidean radius distance + clipping_buffer (or distance when clipping_buffer is infinite) before being added to context. They are not granted reachability by being barriers.
• A null or empty alternative barrier geometry means “no barrier geometry for this row”; it does not mean “remove the movement row.”

Clipping and access budgets

clipping_buffer is context, not walking distance. It must be non-negative and at least extent_buffer. With a center and distance, movement segments within the network budget are the final movement layer; a wider buffered network out to distance + clipping_buffer supplies tessellation context and barriers. Without a center/distance, no network filtering is applied and clipping does not prune the movement layer.

extent_buffer is an independent perpendicular access cap. A building/cell is retained only when the network cost to a projected street foot is within distance and the straight-line access from that foot is within extent_buffer; access is never added to the walking-network budget. This prevents a disconnected or barrier-crossing straight-line leg from making a place reachable. The same two-cap rule is used for buildings and cells. A segment straddling the distance boundary is retained whole when its nearer reachable endpoint is within budget.

Tessellation fallbacks

create_tessellation(buildings) makes an un-enclosed morphological tessellation. create_tessellation(buildings, primary_barriers=barriers) makes an enclosed one. The enclosed default limit is a 100-unit buffered union of buildings and barriers and is clipped; an explicit limit is forwarded and uses the explicit-limit semantics described in input-contracts.md.

The tessellation utility handles known momepy/GEOS degeneracies with a retry ladder (coarser grid_size=1e-3, then deterministic vertex jitter), validates overlap/coverage, salvages polygon parts of GeometryCollections, and may return a uniform empty enclosed schema. Unknown exceptions propagate.

morphological_graph(..., tessellation_fallback=True) additionally uses one building footprint per eligible/reachable building when enclosed tessellation cannot be made or produces no retained cells. Fallback IDs look like fallback_<source-index>. With include_unenclosed_buildings=True, only buildings missed by an otherwise usable enclosed tessellation are appended as footprint cells; they are filtered using the same reachability/access caps first. Both fallback paths log warnings. Default False preserves the empty or error behavior instead of silently changing the place layer.

When center_point and distance are active, place cells with no faced_to edge are removed along with affected touched_to edges. Without a distance budget, isolated place cells are not pruned.

Multi-distance execution

from city2graph.morphology import morphological_graphs

layers = morphological_graphs(
    buildings, segments, distances=[250.0, 500.0, 1000.0],
    center_point=center, clipping_buffer=200.0,
    extent_buffer=75.0, tessellation_n_jobs=1,
)
for radius, (radius_nodes, radius_edges) in layers.items():
    ...

distances must be non-empty; values are normalized to floats and dictionary keys are those float values. A shared segment graph and single-source reachability field are prepared once. Enclosed tessellation context is built once from the largest requested distance and reused, so smaller-radius output can differ slightly near the clipping boundary from separate morphological_graph calls. Each distance still redoes the cheap segment, cell, relation, and retention filters. The return is a dict even for one requested distance. as_nx=True returns one NetworkX graph per key.

Verification checklist

Before treating a morphology result as usable, check:

1. all input and center CRS values are projected and aligned;
2. building geometry types are Polygon/MultiPolygon and segment types are LineString;
3. clipping_buffer >= extent_buffer >= 0;
4. nodes and edges contain the documented keys and index names;
5. every non-empty place and movement node ID is unique;
6. every edge endpoint exists in its corresponding node layer;
7. faced_to fallback edges do not exceed the configured access cap;
8. in a distance-filtered run, every retained place has a faced_to edge;
9. fallback warnings, empty schemas, and tessellation retry messages are recorded rather than hidden;
10. caller input frames remain unchanged.

Native repository tests are verification evidence for maintainers, not a runtime dependency of this skill. Do not require notebook execution or live Overture/OSM access to run a synthetic morphology workflow.