Straight Skeleton¶
Overview¶
The straight skeleton of a polygon is what its boundary traces when every edge moves inwards at the same speed.
Each edge sweeps one face, the faces meet along the arcs of the skeleton, and every point of the skeleton lies at a
known distance from the boundary. objectnat.get_straight_skeleton() returns either the arcs or the faces:
the arcs between inner vertices follow the middle of the polygon: they are the centre lines of road, river or corridor polygons, and twice the distance to the boundary is the local width;
the faces are the slopes of a hipped roof over a building outline; with
roof_anglethey are returned in 3D.
Left: roof faces of buildings in the example district, coloured by their height above the eaves at a slope of 30°. Right: centre lines of a street polygon (pedestrian ways of the test district buffered by 6 m), coloured by the street width.¶
Method¶
Polygons and the parts of MultiPolygons are processed independently and in parallel by the compiled extension; a
geographic CRS is projected to its UTM zone for the calculation, so distances are in metres. The algorithm is an
event-driven wavefront: every edge moves inwards at unit speed, and the skeleton records where edges vanish or
the wavefront splits. It handles holes, simultaneous events (squares, regular and rectilinear shapes) and thin
strips with nearly parallel sides. The Rust code is vendored from the geo-straight-skeleton crate (MIT
licence), which is checked against CGAL’s straight skeleton.
output="arcs": one LineString per arc, withdist_startanddist_end, the distance from the boundary at its ends. The arcs that start at polygon corners (bisectors) are included unlessinclude_bisectors=False, which keeps the centre lines only.output="faces": one Polygon per polygon edge, withring(0 for the exterior, then the holes) andedge(the edge number within the ring). The faces cover the polygon exactly. Withroof_anglethe height of every vertex is its distance from the boundary timestan(roof_angle).
Every row keeps the index of its source row and has a part column, the part of a MultiPolygon.
Notes:
A polygon with crossing or touching edges, a ring of zero area or a hole outside the exterior has no straight skeleton; it is skipped with a warning that counts the skipped polygons by reason.
The centre line of a strip stops half its width before the end of the strip, where the corner arcs meet.
Small bends of the boundary produce short side arcs; they can be dropped by length or by distance.
Straight skeleton¶
- objectnat.get_straight_skeleton(gdf, *, output='arcs', include_bisectors=True, roof_angle=None, max_workers=None)[source]¶
Calculate the straight skeleton of polygons: their centre lines or the faces of a hipped roof.
The straight skeleton is what the boundary of a polygon traces when every edge moves inwards at the same speed. Each edge sweeps one face, the faces meet along the arcs of the skeleton, and every skeleton vertex lies at a known distance from the boundary. The arcs between inner vertices follow the middle of the polygon: the centre line of a road, river or corridor polygon, with half its width as the distance. The faces are the slopes of a hipped roof over a building outline. Polygons are processed in parallel by the compiled extension.
- Parameters:
gdf (
gpd.GeoDataFrame | gpd.GeoSeries) – Polygons or MultiPolygons, in any CRS. Every part of a MultiPolygon gets its own skeleton; rows of other geometry types and empty geometries are skipped.output (
Literal['arcs','faces']) –What to return:
"arcs": one LineString per skeleton arc, withdist_startanddist_end, the distance from the polygon boundary at the two ends of the arc;"faces": one Polygon per polygon edge, withring(0 for the exterior, then the holes in their order) andedge(the edge number within the ring, from its first point).
include_bisectors (
bool) – Foroutput="arcs": also return the arcs that start at the polygon corners.Falsekeeps only the arcs between inner vertices, the centre lines.roof_angle (
float, optional) – Foroutput="faces": slope of the roof in degrees (between 0 and 90). The faces are then returned in 3D, with the height of a point equal to its distance from the boundary timestan(roof_angle).max_workers (
int, optional) – Number of threads. Defaults to all cores.
- Returns:
Skeleton arcs or faces with the column
part(the part of a MultiPolygon, 0 for a Polygon) and the columns described inoutput. The index repeats the index of the source row. Returned in the CRS ofgdf; distances are in the units of a projected CRS, and in metres for a geographic CRS, which is projected to its UTM zone for the calculation.- Return type:
gpd.GeoDataFrame
- Raises:
ValueError – If
output,roof_angleormax_workersis invalid.
Notes
Polygons with crossing or touching edges, zero-area rings or holes outside the exterior have no straight skeleton; they are skipped with a warning that counts them by reason.
The centre line of a strip stops half its width before the strip ends, where the corner arcs meet.