pyorps.graph.path_finder

PYORPS: An Open-Source Tool for Automated Power Line Routing

Reference: [1] Hofmann, M., Stetz, T., Kammer, F., Repo, S.: ‘PYORPS: An Open-Source Tool for

Automated Power Line Routing’, CIRED 2025 - 28th Conference and Exhibition on Electricity Distribution, 16 - 19 June 2025, Geneva, Switzerland

Functions

get_graph_api_class(graph_api)

Return the graph API class based on the selected graph API using pattern matching.

timed(name, timings_dict)

Simple context manager for timing code blocks.

Classes

PathFinder(dataset_source, source_coords, ...)

A class that encapsulates RasterReader and graph-based routing capabilities.
pyorps.graph.path_finder.timed(name, timings_dict)[source]

Simple context manager for timing code blocks.

Parameters:

  • name (str) – The name of the code block to be timed and used as a key within the timings_dict

  • timings_dict (dict[str, float] | None) – Dictionary to add the timing information to with the specified name as key

Returns:

A context manager that times the code block

Return type:

Generator

pyorps.graph.path_finder.get_graph_api_class(graph_api)[source]

Return the graph API class based on the selected graph API using pattern matching.

Parameters:

  • graph_api (str) – The name of the graph API to use (“networkit”, “igraph”,

  • installed! ("networkx" or "rustworkx). Respective graph library must be)

  • automatically. (Networkit is a dependency of pyorps and will be installed)

Returns:

The corresponding graph API class.

Return type:

class

Raises:

  • ImportError – If the specified graph API module cannot be imported.

  • ValueError – If the specified graph API is not supported.

class pyorps.graph.path_finder.PathFinder(dataset_source, source_coords, target_coords, search_space_buffer_m=None, neighborhood_str='r2', steps=None, ignore_max_cost=True, graph_api='cython', cost_assumptions=None, datasets_to_modify=None, crs=None, bbox=None, mask=None, transform=None, raster_save_path=None, **kwargs)[source]

Bases: object

A class that encapsulates RasterReader and graph-based routing capabilities.

This class provides functionality to: 1. Read raster data using RasterReader or create a raster using GeoRasterizer 2. Create a graph representation of the raster with a defined Graph library 3. Find the shortest paths between coordinates 4. Convert resulting paths of graph node indices back to coordinates 5. Create GeoDataFrames of paths and export to other geo-formats for further analysis

The class supports various graph APIs to create a graph from a raster.

Initialize the RasterGraph with a dataset source and routing parameters.

Parameters:

  • dataset_source (str | dict | GeoDataFrame | GeoSeries | ndarray) – Either: - Path to a file (str) - Tuple of (data_array, crs, transform) - GeoDataset object - Dictionary with url/layer for WFS

  • source_coords (tuple[float, float] | list[float] | list[tuple[float, float] | list[float]] | list[Point] | list[MultiPoint] | ndarray | Point | MultiPoint | GeoSeries | GeoDataFrame | None) – CoordinateInput Can be: tuple, list of tuples, array of arrays, shapely Point, shapely MultiPoint, GeoSeries of points, or GeoDataFrame of points.

  • target_coords (tuple[float, float] | list[float] | list[tuple[float, float] | list[float]] | list[Point] | list[MultiPoint] | ndarray | Point | MultiPoint | GeoSeries | GeoDataFrame | None) – CoordinateInput Can be: tuple, list of tuples, array of arrays, shapely Point, shapely MultiPoint, GeoSeries of points, or GeoDataFrame of points.

  • search_space_buffer_m (float | None) – Buffer around the source and target coordinates in meters. If set to 0, the entire Raster will be considered!

  • neighborhood_str (str | int | None) – Neighborhood type. Defaults to “r2”.

  • steps (ndarray[int] | None) – Steps which define the neighborhood. If None, will be created from neighborhood_str.

  • ignore_max_cost (bool) – Whether to ignore all cells in the raster which have the maximum cost value or not

  • graph_api (str) –

    Graph API to use. Available graph libraries:

    ”networkit” (default), “rustworkx”, “igraph”, “networkx”

  • cost_assumptions (dict | str | CostAssumptions | None) – Cost assumptions to use for rasterization. Required if dataset_source is vector data.

  • datasets_to_modify (list[dict[str, Any]] | None) – List of datasets to use to modify the raster using GeoRasterizer.modify_raster_from_dataset

  • crs (str | None) – The coordinate reference system to be used as project crs (crs of the dataset_source and all other datasets will be converted to this crs)

  • bbox (Polygon | GeoDataFrame | GeoSeries | tuple[float, float, float, float] | None) – The bounding box to be used as project bounding box. Defines the area in which path finding is processed.

  • mask (Polygon | GeoDataFrame | tuple | None) – Defines the area in which path finding is processed similar to the bbox parameter. In this case a more complex Polygon, a Multipolygon or even a GeoSeries/GeoDataFrame with multiple Polygons can be used to define the search space for path finding.

  • transform (Affine | None) – Affine transformation describing the transform of a RasterDataset. Can be used ia a raster dataset is passed directly to dataset_source.

  • raster_save_path (str | None) – Path to save the raster dataset to.

  • **kwargs – Additional keyword arguments to pass to the rasterize function of the RasterHandler (if a VectorDataset or a source to a VectorDataset has been provided with dataset_source) or to the load function of the RasterDataset (if a source to a RasterDataset has been provided with dataset_source).

Minimal example: >>> from pyorps import PathFinder >>> source = (472000, 5593400) >>> target = (472800, 5594000) >>> raster_path = r”./data/raster/sample_raster.tiff” >>> path_finder = PathFinder( >>> dataset_source=raster_path, >>> source_coords=source, >>> target_coords=target, >>> ) >>> path_finder.find_route() Path(path_id=0, source=(472000, 5593400), target=(472800, 5594000),

total_length=1192.43, total_cost=133578.05)

__init__(dataset_source, source_coords, target_coords, search_space_buffer_m=None, neighborhood_str='r2', steps=None, ignore_max_cost=True, graph_api='cython', cost_assumptions=None, datasets_to_modify=None, crs=None, bbox=None, mask=None, transform=None, raster_save_path=None, **kwargs)[source]

Initialize the RasterGraph with a dataset source and routing parameters.

Parameters:

  • dataset_source (str | dict | GeoDataFrame | GeoSeries | ndarray) – Either: - Path to a file (str) - Tuple of (data_array, crs, transform) - GeoDataset object - Dictionary with url/layer for WFS

  • source_coords (tuple[float, float] | list[float] | list[tuple[float, float] | list[float]] | list[Point] | list[MultiPoint] | ndarray | Point | MultiPoint | GeoSeries | GeoDataFrame | None) – CoordinateInput Can be: tuple, list of tuples, array of arrays, shapely Point, shapely MultiPoint, GeoSeries of points, or GeoDataFrame of points.

  • target_coords (tuple[float, float] | list[float] | list[tuple[float, float] | list[float]] | list[Point] | list[MultiPoint] | ndarray | Point | MultiPoint | GeoSeries | GeoDataFrame | None) – CoordinateInput Can be: tuple, list of tuples, array of arrays, shapely Point, shapely MultiPoint, GeoSeries of points, or GeoDataFrame of points.

  • search_space_buffer_m (float | None) – Buffer around the source and target coordinates in meters. If set to 0, the entire Raster will be considered!

  • neighborhood_str (str | int | None) – Neighborhood type. Defaults to “r2”.

  • steps (ndarray[int] | None) – Steps which define the neighborhood. If None, will be created from neighborhood_str.

  • ignore_max_cost (bool) – Whether to ignore all cells in the raster which have the maximum cost value or not

  • graph_api (str) –

    Graph API to use. Available graph libraries:

    ”networkit” (default), “rustworkx”, “igraph”, “networkx”

  • cost_assumptions (dict | str | CostAssumptions | None) – Cost assumptions to use for rasterization. Required if dataset_source is vector data.

  • datasets_to_modify (list[dict[str, Any]] | None) – List of datasets to use to modify the raster using GeoRasterizer.modify_raster_from_dataset

  • crs (str | None) – The coordinate reference system to be used as project crs (crs of the dataset_source and all other datasets will be converted to this crs)

  • bbox (Polygon | GeoDataFrame | GeoSeries | tuple[float, float, float, float] | None) – The bounding box to be used as project bounding box. Defines the area in which path finding is processed.

  • mask (Polygon | GeoDataFrame | tuple | None) – Defines the area in which path finding is processed similar to the bbox parameter. In this case a more complex Polygon, a Multipolygon or even a GeoSeries/GeoDataFrame with multiple Polygons can be used to define the search space for path finding.

  • transform (Affine | None) – Affine transformation describing the transform of a RasterDataset. Can be used ia a raster dataset is passed directly to dataset_source.

  • raster_save_path (str | None) – Path to save the raster dataset to.

  • **kwargs – Additional keyword arguments to pass to the rasterize function of the RasterHandler (if a VectorDataset or a source to a VectorDataset has been provided with dataset_source) or to the load function of the RasterDataset (if a source to a RasterDataset has been provided with dataset_source).

Minimal example: >>> from pyorps import PathFinder >>> source = (472000, 5593400) >>> target = (472800, 5594000) >>> raster_path = r”./data/raster/sample_raster.tiff” >>> path_finder = PathFinder( >>> dataset_source=raster_path, >>> source_coords=source, >>> target_coords=target, >>> ) >>> path_finder.find_route() Path(path_id=0, source=(472000, 5593400), target=(472800, 5594000),

total_length=1192.43, total_cost=133578.05)

static normalize_coordinates(input_data)[source]

Normalize different coordinate formats into tuples or lists of tuples.

Parameters:

input_data (tuple[float, float] | list[float] | list[tuple[float, float] | list[float]] | list[Point] | list[MultiPoint] | ndarray | Point | MultiPoint | GeoSeries | GeoDataFrame | None) – Can be a tuple, a list of tuples, an array of arrays, a shapely Point, a shapely MultiPoint, a GeoSeries of points, or a GeoDataFrame of points.

Returns:

A single coordinate tuple (x, y) or list of coordinate

tuples [(x1, y1), (x2, y2), …]

Return type:

CoordinateOutput

create_raster_handler(cost_assumptions=None, datasets_to_modify=None, raster_save_path=None, **kwargs)[source]

Create a RasterReader object for the specified file and parameters.

Parameters:

  • cost_assumptions (dict | str | CostAssumptions | None) – Cost assumptions to use for rasterization. Required if dataset_source is vector data

  • datasets_to_modify (list[dict[str, Any]] | None) – List of datasets to use to modify the raster using GeoRasterizer.modify_raster_from_dataset

  • raster_save_path (str | None) – Path to save the raster dataset to.

Returns:

The created RasterReader object

Return type:

RasterReader

create_graph(band_index=0)[source]

Create a graph from the raster data.

Parameters:

band_index (int) – Index of the raster band to use. Defaults to 0.

Returns:

The created graph object.

Return type:

Any

property graph_api: GraphAPI
get_node_indices_from_coords(coords)[source]

Convert coordinates to node indices.

Parameters:

coords (tuple[float, float] | list[float] | list[tuple[float, float] | list[float]]) – Either: - A single coordinate pair (x, y) - A list of coordinate pairs [(x1, y1), (x2, y2), …]

Returns:

List of node indices.

Return type:

int | int32 | int64 | uint32 | uint64 | list[int | int32 | int64 | uint32 | uint64] | ndarray[int] | list[list[int | int32 | int64 | uint32 | uint64] | ndarray[int]]

get_coords_from_node_indices(node_indices)[source]

Convert node indices to coordinates.

Parameters:

node_indices (int | int32 | int64 | uint32 | uint64 | list[int | int32 | int64 | uint32 | uint64] | ndarray[int]) – List of node indices.

Returns:

List of coordinates (x, y).

Return type:

list[tuple[float, float] | list[float]]

find_route(source=None, target=None, algorithm='dijkstra', calculate_metrics=True, pairwise=False, raster_parameters=None, **kwargs)[source]

Find the shortest path between source and target coordinates.

Parameter:
source: CoordinateInput - Source coordinates. If None, uses the

source_coords provided at initialization. Can be: tuple, list of tuples, array of arrays, shapely Point, shapely MultiPoint, GeoSeries of points, or GeoDataFrame of points.

target: Target coordinates. If None, uses the target_coords provided at

initialization. Can be a single pair (x, y) or a list of pairs [(x1, y1), (x2, y2), …].

algorithm: Algorithm to use for shortest path. Defaults to “dijkstra”. calculate_metrics: Whether to calculate path metrics. Defaults to True. pairwise: Whether to calculate paths pairwise (requires equal number of

sources and targets). Default is False.

Returns:

Dictionary or list of dictionaries containing path information

Parameters:
Return type:

Path | PathCollection

calculate_path_metrics(path_indices, path)[source]

Calculate metrics about the path and add directly to the Path object.

Parameters:

  • path_indices – List of node indices for the path.

  • path – Path object to update with metrics.

get_path(path_id=None, source=None, target=None)[source]

Retrieve a stored path by ID, or by source AND target.

Parameters:

  • path_id – Numerical ID of the path

  • source – Source coordinates to search for

  • target – Target coordinates to search for

Returns:

Path object or None if not found

create_path_geodataframe()[source]

Create a GeoDataFrame containing all stored paths.

Returns:

GeoDataFrame containing path data, or None if no paths available

save_paths(save_file_path=None)[source]

Save all calculated paths to a file in a GIS-compatible format.

This method creates a GeoDataFrame containing all paths from the PathCollection and saves it to the specified file. The file format is automatically determined from the file extension (e.g., ‘.shp’ for Shapefile, ‘.gpkg’ for GeoPackage).

Parameters:

save_file_path (str | None) – Path to save the paths file. If None, no file is saved. Common formats include: - Shapefile (.shp) - GeoPackage (.gpkg) - GeoJSON (.geojson) - CSV (.csv)

Returns:

None

Return type:

None

Notes

  • The saved file includes all path attributes (ID, length, cost data)

  • The geometries are saved as LineString features with the CRS from the

source dataset - If no paths have been calculated, an empty GeoDataFrame will be created first

save_raster(save_path=None)[source]

Save the raster data used for path calculations to a GeoTIFF file.

This method exports the current raster data to the specified file location. The raster contains the cost values used for path calculations, including any modifications from additional datasets. The exported file includes complete geo referencing information and preserves the original CRS.

Parameters:

save_path (str | None) – Path where the raster file should be saved. If None, uses the default filename “pyorps_raster.tiff” in the current directory.

Returns:

None

Return type:

None

Notes

  • The saved raster includes all cost modifications from additional datasets

  • The file is saved in GeoTIFF format which preserves geo referencing

information - If the PathFinder uses a GeoRasterizer, the complete raster is saved - Otherwise, only the section loaded in the RasterHandler is saved - For large areas, the resulting file size may be substantial

plot_paths(paths=None, plot_all=True, subplots=True, subplot_size=(10, 8), source_color='green', target_color='red', path_colors=None, source_marker='o', target_marker='x', path_line_width=2, show_raster=True, title=None, sup_title=None, path_id=None, reverse_colors=False)[source]

Plot paths with customizable styling and layout options.

This method visualizes the calculated paths, allowing for detailed customization of the plot appearance. It delegates to the PathPlotter class to handle the actual visualization.

Parameters:

  • paths (Path | PathCollection | list[Path] | None) – Specific path(s) to plot. If None, uses all paths in this PathFinder instance. Can be a single Path object, a list of Path objects, or a PathCollection.

  • plot_all (bool) – If True, plots all paths. If False, plots only the path with path_id.

  • subplots (bool) – If True and multiple paths are plotted, creates separate subplots for each path.

  • subplot_size (tuple[int, int]) – Size of each individual subplot in inches (width, height).

  • source_color (str) – Color for source markers.

  • target_color (str) – Color for target markers.

  • path_colors (str | list[str] | None) – Colors for path lines. Can be a single color or a list of colors. If None, default color scheme is used.

  • source_marker (str) – Marker style for source points.

  • target_marker (str) – Marker style for target points.

  • path_line_width (int) – Line width for the paths.

  • show_raster (bool) – Whether to display the raster data as background.

  • title (str | list[str] | None) – Title for the plot or individual subplot titles if a list is provided.

  • sup_title (str | None) – Overall title for the figure (when using multiple subplots).

  • path_id (list[int] | int | None) – ID of specific path to plot when plot_all is False. Can be a single ID or a list of IDs.

  • reverse_colors (bool) – Whether to reverse the color scheme for raster data (dark=low cost, bright=high cost).

Returns:

The matplotlib axes object(s) for the plot. Returns a list of axes if multiple subplots are created, otherwise returns a single axes object.

Return type:

Any | list[Any]

Runtime Notes:

  • The plotting operation itself is generally quick (0.1-0.5 seconds)

  • Most time is spent on data preparation in the initial PathFinder setup

  • When plotting many paths, using subplots=True can improve readability

  • Displaying the raster background (show_raster=True) adds minimal overhead once the PathFinder is initialized