Centerline Python Library

You can install centerline via PyPI using pip.

To simplify the process, you can use the [gdal] extra dependency, which attempts to install GDAL for you.

Warning: Using pip install centerline[gdal] can be error-prone because pip may attempt to install a version of GDAL that conflicts with the version you have installed system-wide. It is often safer to install the system GDAL and python-GDAL manually first, then install centerline normally.

# Standard installation
$ pip install centerline

# Installation with GDAL extra (use with caution)
$ pip install centerline[gdal]

Once the system-wide GDAL binary and environment variables are configured, install python-GDAL into your virtual environment.

Important: The version of python-GDAL should match your system-wide GDAL version as closely as possible. If an exact match is unavailable, use the closest minor version.

Example workflow:

1. Check system version: gdalinfo --version
2. Install matching version: pip install GDAL==<version>

# Check system version
$ gdalinfo --version
# Output: GDAL 2.1.4, released 2017/06/23

# Install matching version in virtual environment
$ pip install GDAL==2.1.3

Before installing the Python bindings (python-GDAL), you must locate the GDAL headers and set the CPLUS_INCLUDE_PATH and C_INCLUDE_PATH environment variables to point to the GDAL include directory. This ensures the Python installation can find the necessary headers.

# Locate GDAL headers
$ whereis gdal
# Example output: gdal: /usr/include/gdal /usr/share/gdal

# Set include paths
$ export CPLUS_INCLUDE_PATH=/usr/include/gdal/
$ export C_INCLUDE_PATH=/usr/include/gdal/

To use the create_centerline command-line tool, you must first install the GDAL library system-wide. On Fedora, you can install the GDAL library and necessary dependencies using dnf.

$ sudo dnf install gdal gdal-devel gcc-c++ redhat-rpm-config

To contribute to centerline, follow these steps:

1. Fork and clone the repository.
2. Install the library in editable (develop) mode with all necessary extras (dev, gdal, lint, test, docs).
3. Run the test suite using tox to verify the environment.

# 1. Clone the repository
$ git clone git@github.com:user/centerline.git

# 2. Install in develop mode with extras
$ pip install -e .[dev,gdal,lint,test,docs]

# 3. Run tests
$ tox

If the create_centerline script produces very few ridges (e.g., a single line or a single point), it is likely due to the polygon's structure or the chosen border density. In these cases, the Voronoi algorithm may fail to produce enough vertices that lie entirely within the polygon boundaries.

When this occurs, the script raises a TooFewRidgesError. The script is designed to handle this by skipping the problematic geometry and continuing to process the remaining geometries in your input.

If the generated centerline geometry is too complex or has too much detail, adjust the border density parameter in the create_centerline script.

Note that because the centerline is calculated using a Voronoi diagram, certain border density settings may cause occasional small branches to stick out from the main centerline. These branches can be manually removed using GIS software like QGIS.

This error is caused by a unit mismatch between your input data and the create_centerline script's default border density. For example, if your input data uses geographic coordinates (like EPSG:4326 in degrees) but the script expects metric units (meters), the calculation will fail.

To resolve this, you can either:

1. Specify the border density in degrees to match your input data.
2. Transform your input data into a metric coordinate reference system (e.g., EPSG:3857) before running the script.

# Example: Specifying border density in degrees for EPSG:4326 input
$ create_centerlines input.shp output.geojson 0.00001

You can use the Centerline class directly in your Python code. To instantiate it, provide a geometric object of type shapely.geometry.Polygon or shapely.geometry.MultiPolygon. You can also pass optional attributes as keyword arguments which will be stored as attributes on the Centerline instance.

from shapely.geometry import Polygon
from centerline.geometry import Centerline

# Define a polygon
polygon = Polygon([[0, 0], [0, 4], [4, 4], [4, 0]])

# Define optional attributes
attributes = {"id": 1, "name": "polygon", "valid": True}

# Instantiate the Centerline object
centerline = Centerline(polygon, **attributes)

# Access attributes and geometry
print(centerline.id)          # Output: 1
print(centerline.name)        # Output: 'polygon'
print(centerline.geometry)   # Accesses the resulting centerline geometry

For programmatic access, use the Centerline class from centerline.geometry. You can pass a shapely.geometry.Polygon and arbitrary keyword arguments which will be stored as attributes on the resulting Centerline instance. The centerline geometry is accessible via the .geometry attribute.

from shapely.geometry import Polygon
from centerline.geometry import Centerline

polygon = Polygon([[0, 0], [0, 4], [4, 4], [4, 0]])
attributes = {"id": 1, "name": "polygon", "valid": True}

centerline = Centerline(polygon, **attributes)

# Accessing attributes
print(centerline.id)      # 1
print(centerline.name)    # 'polygon'

# Accessing the generated geometry
print(centerline.geometry)