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_angle they are returned in 3D.

Roof faces of buildings and centre lines of a street polygon

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, with dist_start and dist_end, the distance from the boundary at its ends. The arcs that start at polygon corners (bisectors) are included unless include_bisectors=False, which keeps the centre lines only.

  • output="faces": one Polygon per polygon edge, with ring (0 for the exterior, then the holes) and edge (the edge number within the ring). The faces cover the polygon exactly. With roof_angle the height of every vertex is its distance from the boundary times tan(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, with dist_start and dist_end, the distance from the polygon boundary at the two ends of the arc;

    • "faces": one Polygon per polygon edge, with ring (0 for the exterior, then the holes in their order) and edge (the edge number within the ring, from its first point).

  • include_bisectors (bool) – For output="arcs": also return the arcs that start at the polygon corners. False keeps only the arcs between inner vertices, the centre lines.

  • roof_angle (float, optional) – For output="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 times tan(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 in output. The index repeats the index of the source row. Returned in the CRS of gdf; 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_angle or max_workers is 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.