API Reference

PYORPS - Python for Optimal Routes in Power Systems.

class pyorps.CostAssumptions(source=None)[source]

Bases: object

A class for handling cost assumptions for rasterization.

This class handles: - Loading cost assumptions from files (CSV, Excel, JSON) or generating of cost assumptions from a dictionary or a GeoDataFrame. - Mapping costs to features in a GeoDataFrame - Managing hierarchical cost structures

Parameters:

source (str | dict | None)

__init__(source=None)[source]

Initialize the CostAssumptions object.

Parameters:

source (Union[str, dict, None]) –

  1. Path to a cost assumptions file

  2. A dictionary of cost values

apply_to_geodataframe(gdf, main_feature=None, side_features=None)[source]

Apply cost assumptions to a GeoDataFrame.

Parameters:

  • gdf (GeoDataFrame) – GeoDataFrame to apply costs to

  • main_feature (Optional[str]) – Main feature column name

  • side_features (Optional[list[str]]) – list of side feature column names or single side feature name

Returns:

GeoDataFrame with ‘cost’ column added

convert_df_to_cost_dict(df)[source]

Convert a DataFrame to a nested dictionary for cost assumptions.

Parameters:

df (DataFrame) – DataFrame containing cost assumptions with hierarchical structure

Return type:

dict

Returns:

dictionary of cost assumptions with nested structure based on DataFrame columns

Uses one numeric column for costs, and all other columns as a hierarchical index: - The first column is the ‘main_feature’ - All additional columns are ‘side_features’

cost_dict_to_df(cost_dict)[source]

Convert cost assumptions dictionary to DataFrame.

Parameters:

cost_dict (dict) – Dictionary of cost assumptions

Return type:

DataFrame

Returns:

DataFrame representation of cost assumptions

load(source)[source]

Load cost assumptions from a file or dictionary.

Parameters:

source (Union[str, dict]) – Path to a file or a dictionary containing cost assumptions

Return type:

dict

Returns:

dictionary of cost assumptions

to_csv(filepath, separator=';', decimal='.', encoding='ISO-8859-1')[source]

Save the cost assumptions to a CSV file.

Parameters:

  • filepath (str) – Path where to save the CSV file

  • separator (str) – Column separator character (default is ‘;’)

  • decimal (str) – Decimal separator character (default is ‘.’)

  • encoding (str) – The encoding of the file (default is ‘ISO-8859-1’)

Return type:

None

to_excel(filepath, sheet_name='CostAssumptions', index=False)[source]

Save the cost assumptions to an Excel file.

Parameters:

  • filepath (str) – Path where to save the Excel file

  • sheet_name (str) – Name of the worksheet (default is ‘CostAssumptions’)

  • index (bool) – Whether to write row indices (default is False)

Return type:

None

to_json(filepath, indent=2, encoding='ISO-8859-1')[source]

Save the cost assumptions to a JSON file.

Parameters:

  • filepath (str) – Path where to save the JSON file

  • indent (int) – Number of spaces for indentation (default is 2)

  • encoding (str) – The encoding of the file (default is ‘ISO-8859-1’)

Return type:

None

class pyorps.GeoDataset(file_source, crs=None)[source]

Bases: ABC

Parameters:

  • file_source (Any)

  • crs (str | None)

__init__(file_source, crs=None)[source]
Parameters:

  • file_source (Any)

  • crs (str | None)

crs: Optional[str] = None
data: Union[GeoDataFrame, ndarray, None] = None
file_source: Any
abstractmethod load_data(**kwargs)[source]
class pyorps.GeoRasterizer(input_data, cost_assumptions, bbox=None, mask=None, default_crs=None, **kwargs)[source]

Bases: object

A class for preparing and rasterizing geospatial data with cost assumptions.

This class integrates:

  • GeoDataset for representing datasets with metadata

  • CostAssumptions for handling cost mappings

  • Rasterization functionality for converting vector data to rasters

Parameters:
__init__(input_data, cost_assumptions, bbox=None, mask=None, default_crs=None, **kwargs)[source]

Initialize the GeoRasterizer with a base dataset and optional parameters.

Parameters:
property base_data: GeoDataFrame

Property to directly access the data attribute of the base_dataset.

Returns:

The base dataset (GeoDataFrame

clip_to_area(clip_geometry)[source]

Clip the base dataset to a specific area.

Parameters:

clip_geometry (Union[GeoDataFrame, Polygon]) – The geometry to clip by

Return type:

GeoDataset

Returns:

The clipped base dataset

create_bounds_geodataframe(target_crs=None)[source]

Creates a GeoDataFrame from the bounds of the base data in a specified CRS.

Parameters:

target_crs (Optional[str]) – The desired CRS for the new GeoDataFrame

Return type:

GeoDataFrame

Returns:

A new GeoDataFrame containing the bounds of the base data

static create_buffer(dataset, geometry_buffer_m, inplace=True)[source]

Add a buffer to geometries in a dataset.

Parameters:

  • dataset (Union[VectorDataset, GeoDataFrame]) – The dataset to buffer (GeoDataset or GeoDataFrame)

  • geometry_buffer_m (float) – Distance to buffer in dataset’s CRS units

  • inplace (bool) – If True, modify the dataset in place

Return type:

Union[VectorDataset, GeoDataFrame]

Returns:

The buffered dataset

property crs

Passing crs property of base_dataset.

Returns:

The desired CRS of the base dataset

modify_raster_from_dataset(input_data, cost_assumptions=None, bbox=None, mask=None, transform=None, geometry_buffer_m=0, ignore_value=65535, multiply=False, zone_field=None, forbidden_zone=None, forbidden_value=65535, **kwargs)[source]

Modify the raster with an additional dataset.

Parameters:
Return type:

ndarray

Returns:

The modified raster

modify_raster_with_geodataframe(gdf, value, ignore_value=65535, multiply=False)[source]

Modifies the raster cells inside the polygons of a GeoDataFrame.

Parameters:

  • gdf (GeoDataFrame) – The GeoDataFrame containing polygons to use for masking

  • value (float) – The value to set for the raster cells inside the polygons

  • ignore_value (Optional[float]) – Value in the raster to ignore during modification

  • multiply (bool) – If True, multiply the raster values by the given value

Return type:

ndarray

Returns:

The modified raster

rasterize(field_name='cost', resolution_in_m=1.0, fill_value=65535, save_path=None, dtype='uint16', geometry_buffer_m=0, bounding_box=None, fancy_function=None, fancy_function_kwargs=None)[source]

Rasterize the base dataset based on a specified field.

Parameters:

  • field_name (str) – The field to use for rasterization values

  • resolution_in_m (float) – The resolution of the output raster in meters

  • fill_value (int) – Value to use for areas with no data

  • save_path (Optional[str]) – Path to save the rasterized output

  • dtype (str) – Data type for the output raster

  • geometry_buffer_m (float) – Buffer to apply to the dataset geometries

  • bounding_box (Optional[Polygon]) – Bounding box to define the rasterization extent

  • fancy_function (Optional[Callable]) – A function that takes the base dataset as a first

  • will (argument and other arguments defined in fancy_function_kwargs which)

  • rasterization (be called before)

  • fancy_function_kwargs (Optional[dict[str, Any]]) – The keyword arguments passed to fancy_function

Return type:

RasterDataset

Returns:

tuple of (raster_data, transform)

save_raster(save_path)[source]

Save the rasterized data to a file.

Parameters:

save_path (str) – Path to save the raster file

Return type:

None

shrink_raster(exclude_value)[source]

Shrink the raster by removing outer bounds with a specific value.

Parameters:

exclude_value (int) – Value to exclude from the outer bounds

Return type:

ndarray

Returns:

The shrunk raster

class pyorps.InMemoryRasterDataset(file_source, crs, transform)[source]

Bases: RasterDataset

Parameters:
__init__(file_source, crs, transform)[source]
Parameters:
count: int
crs: str = None
data: Union[GeoDataFrame, ndarray, None] = None
dtype: dtype
file_source: Any
load_data(**kwargs)[source]
shape: tuple[int, int]
transform: Affine
class pyorps.InMemoryVectorDataset(file_source, crs=None, bbox=None, mask=None)[source]

Bases: VectorDataset

Parameters:
__init__(file_source, crs=None, bbox=None, mask=None)
Parameters:
apply_bbox()[source]
apply_mask()[source]
bbox: Union[Polygon, GeoDataFrame, GeoSeries, tuple[float, float, float, float], None] = (None,)
correct_crs()[source]
crs: Optional[str] = None
data: Union[GeoDataFrame, ndarray, None] = None
file_source: Any
load_data(**kwargs)[source]
mask: Union[Polygon, GeoDataFrame, tuple, None] = (None,)
post_loading()[source]
class pyorps.LocalRasterDataset(file_source, crs=None)[source]

Bases: RasterDataset

Parameters:
__init__(file_source, crs=None)
Parameters:

  • file_source (Any)

  • crs (str | None)

count: int
crs: str = None
data: Union[GeoDataFrame, ndarray, None] = None
dtype: dtype
file_source: Any
load_data(**kwargs)[source]
shape: tuple[int, int]
transform: Affine
class pyorps.LocalVectorDataset(file_source, crs=None, bbox=None, mask=None)[source]

Bases: InMemoryVectorDataset

Parameters:
__init__(file_source, crs=None, bbox=None, mask=None)
Parameters:
apply_bbox()[source]
apply_mask()[source]
bbox: Union[Polygon, GeoDataFrame, GeoSeries, tuple[float, float, float, float], None] = (None,)
correct_crs()
crs: Optional[str] = None
data: Union[GeoDataFrame, ndarray, None] = None
file_source: Any
load_data(**kwargs)[source]
mask: Union[Polygon, GeoDataFrame, tuple, None] = (None,)
post_loading()
class pyorps.Path(source, target, algorithm, graph_api, path_indices, path_coords, path_geometry, euclidean_distance, runtimes, path_id, search_space_buffer_m, neighborhood, total_length=None, total_cost=None, length_by_category=None, length_by_category_percent=None)[source]

Bases: object

Dataclass representing a path in a raster graph. Used as container for all path metrics and information.

Parameters:
__eq__(other)[source]

Check for equality between two paths.

Return type:

bool

Parameters:

other (Any)

__init__(source, target, algorithm, graph_api, path_indices, path_coords, path_geometry, euclidean_distance, runtimes, path_id, search_space_buffer_m, neighborhood, total_length=None, total_cost=None, length_by_category=None, length_by_category_percent=None)
Parameters:
Return type:

None

__repr__()[source]

Return a detailed string representation of the path.

Return type:

str

__str__()[source]

Return a string representation of the path including the path_id, source and target, as well as the path’s total length and total cost.

Return type:

str

Returns:

A string representation of the path.

algorithm: str
euclidean_distance: float
graph_api: str
length_by_category: Optional[dict[float, float]] = None
length_by_category_percent: Optional[dict[float, float]] = None
neighborhood: str
path_coords: list[Union[tuple[float, float], list[float]]]
path_geometry: LineString
path_id: int
path_indices: Union[list[Union[int, int32, int64, uint32, uint64]], ndarray[int]]
runtimes: dict[str, float]
search_space_buffer_m: float
source: Union[tuple[float, float], list[float]]
target: Union[tuple[float, float], list[float]]
to_geodataframe_dict()[source]

Convert Path object to a dictionary suitable for GeoDataFrame creation.

Return type:

dict

Returns:

dictionary with path data formatted for GeoDataFrame

total_cost: Optional[float] = None
total_length: Optional[float] = None
class pyorps.PathCollection[source]

Bases: object

Container for Path objects with O(1) retrieval by path ID and O(n) lookup for source and target information. Paths can be added with new id by replacing a Path object with the same ID already existing in th PathCollection.

__eq__(other)[source]

Check if PathCollections are equal. They do not have to be in the same order to be equal!

Return type:

bool

__getitem__(path_id)[source]

Get path by path_id of the Path object from the PathCollection.

__init__()[source]

Create an empty PathCollection for collecting Paths with their IDs in a dictionary.

__iter__()[source]

Iterate through all paths in the PathCollection.

__len__()[source]

Return the number of paths in the PathCollection.

__repr__()[source]

Return a detailed string representation of the path collection.

Return type:

str

__str__()[source]

Return a string representation of the path collection.

Return type:

str

add(path, replace=False)[source]

Add a path to the PathCollection. If the Path’s path_id is None or if replace is False, the path_id of the Path object will set to self._next_id and self._next_id will be incremented. If the Path’s path_id is not None and replace is True, a Path with the same path_id (if present) will be replaced with the new Path object.

Parameters:

  • path (Path) – A Path object which should be added to the PathCollection.

  • replace (bool) – Whether to replace an existing Path object with the same path_id (if present) or not.

Return type:

None

property all

Return all Path objects from the values of the PathCollection’s _paths dictionary as a list.

Returns:

A list of all Path objects in the PathCollection.

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

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

Parameters:

  • path_id (int) – The ID of the Path object to retrieve (must be None if path should be found by source and target)

  • source (Any) – The source Path object to retrieve (only used if path_id is None and target os set too; neglected otherwise)

  • target (Any) – The target Path object to retrieve (only used if path_id is None and target os set too; neglected otherwise)

Return type:

Optional[Path]

Returns:

The Path object with the specified ID or source/target pair. None if no such path exists.

to_geodataframe_records()[source]

Convert all paths to a list of dictionaries suitable for a GeoDataFrame.

Return type:

list

Returns:

List of dictionaries with path data formatted for a GeoDataFrame

class pyorps.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.

Parameters:
__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 (Union[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 (Union[tuple[float, float], list[float], list[Union[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 (Union[tuple[float, float], list[float], list[Union[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 (Optional[float]) – Buffer around the source and target

  • meters. (coordinates in)

  • neighborhood_str (Union[str, int, None]) – Neighborhood type. Defaults to “r2”.

  • steps (Optional[ndarray[int]]) – 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 (Union[dict, str, CostAssumptions, None]) – Cost assumptions to use for rasterization. Required if dataset_source is vector data.

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

  • crs (Optional[str]) – 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 (Union[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 (Union[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 (Optional[Affine]) – Affine transformation describing the transform of a RasterDataset. Can be used ia a raster dataset is passed directly to dataset_source.

  • raster_save_path (Optional[str]) – 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)

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.

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.

Return type:

Any

Returns:

The created graph object.

create_path_geodataframe()[source]

Create a GeoDataFrame containing all stored paths.

Returns:

GeoDataFrame containing path data, or None if no paths available

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 (Union[dict, str, CostAssumptions, None]) – Cost assumptions to use for rasterization. Required if dataset_source is vector data

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

  • raster_save_path (Optional[str]) – Path to save the raster dataset to.

Returns:

The created RasterReader object

Return type:

RasterReader

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.

Return type:

Union[Path, PathCollection]

Returns:

Dictionary or list of dictionaries containing path information

Parameters:
get_coords_from_node_indices(node_indices)[source]

Convert node indices to coordinates.

Parameters:

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

Return type:

list[Union[tuple[float, float], list[float]]]

Returns:

List of coordinates (x, y).

get_node_indices_from_coords(coords)[source]

Convert coordinates to node indices.

Parameters:

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

Return type:

Union[int, int32, int64, uint32, uint64, list[Union[int, int32, int64, uint32, uint64]], ndarray[int], list[Union[list[Union[int, int32, int64, uint32, uint64]], ndarray[int]]]]

Returns:

List of node indices.

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

property graph_api: GraphAPI
static normalize_coordinates(input_data)[source]

Normalize different coordinate formats into tuples or lists of tuples.

Parameters:

input_data (Union[tuple[float, float], list[float], list[Union[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

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 (Union[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 (Union[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 (Union[str, list[str], None]) – Title for the plot or individual subplot titles if a list is provided.

  • sup_title (Optional[str]) – Overall title for the figure (when using multiple subplots).

  • path_id (Union[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).

Return type:

Union[Any, list[Any]]

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.

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

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 (Optional[str]) – Path to save the paths file. If None, no file is saved. Common formats include: - Shapefile (.shp) - GeoPackage (.gpkg) - GeoJSON (.geojson) - CSV (.csv)

Return type:

None

Returns:

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 (Optional[str]) – Path where the raster file should be saved. If None, uses the default filename “pyorps_raster.tiff” in the current directory.

Return type:

None

Returns:

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

class pyorps.RasterDataset(file_source, crs=None)[source]

Bases: GeoDataset, ABC

Parameters:
__init__(file_source, crs=None)
Parameters:

  • file_source (Any)

  • crs (str | None)

count: int
crs: str = None
data: Union[GeoDataFrame, ndarray, None] = None
dtype: dtype
file_source: Any
abstractmethod load_data(**kwargs)
shape: tuple[int, int]
transform: Affine
class pyorps.VectorDataset(file_source, crs=None, bbox=None, mask=None)[source]

Bases: GeoDataset, ABC

Parameters:
__init__(file_source, crs=None, bbox=None, mask=None)[source]
Parameters:
abstractmethod apply_bbox()[source]
abstractmethod apply_mask()[source]
bbox: Union[Polygon, GeoDataFrame, GeoSeries, tuple[float, float, float, float], None] = (None,)
abstractmethod correct_crs()[source]
crs: Optional[str] = None
data: Union[GeoDataFrame, ndarray, None] = None
file_source: Any
abstractmethod load_data(**kwargs)
mask: Union[Polygon, GeoDataFrame, tuple, None] = (None,)
abstractmethod post_loading()[source]
class pyorps.WFSVectorDataset(file_source, crs=None, bbox=None, mask=None)[source]

Bases: LocalVectorDataset

Parameters:
__init__(file_source, crs=None, bbox=None, mask=None)
Parameters:
apply_bbox()
apply_mask()[source]
bbox: Union[Polygon, GeoDataFrame, GeoSeries, tuple[float, float, float, float], None] = (None,)
correct_crs()
crs: Optional[str] = None
data: Union[GeoDataFrame, ndarray, None] = None
file_source: Any
load_data(**kwargs)[source]
mask: Union[Polygon, GeoDataFrame, tuple, None] = (None,)
post_loading()
pyorps.detect_feature_columns(gdf, max_features_per_column=50)[source]

Analyze columns in a geodataframe to identify the best candidates for main_feature and side_features based on statistical metrics.

Parameters:

  • gdf (GeoDataFrame) – GeoDataFrame to analyze

  • max_features_per_column (int) – Maximum number of unique values allowed in a

  • column (categorical)

Return type:

tuple[str, list[str]]

Returns:

tuple of (main_feature, side_features)

Raises:

NoSuitableColumnsError – When no suitable columns are found for feature selection

pyorps.get_zero_cost_assumptions(gdf, main_feature, side_features)[source]

Generate cost assumptions with zero values for all feature combinations.

Creates structures matching format for CostAssumptions: - Without side features: {main_feature: {val1: 0, val2: 0, …}} - With side features: {(main_feature, side_feature1, …): {(val1, val2, …): 0, …}}

Parameters:

  • gdf (GeoDataFrame) – GeoDataFrame with feature columns

  • main_feature (str) – Primary feature column name

  • side_features (list[str]) – List of secondary feature column names

Returns:

Instacne of zero-cost assumptions

Return type:

CostAssumptions

pyorps.initialize_geo_dataset(file_source, crs=None, bbox=None, mask=None, transform=None)[source]

Factory function to create the appropriate GeoDataset instance based on the provided input.

Parameters:
Return type:

GeoDataset

Returns:

An appropriate GeoDataset subclass instance

Examples

# From local vector file vector_dataset = create_geo_dataset(“path/to/shapefile.shp”, crs=”EPSG:4326”)

# From GeoDataFrame vector_dataset = create_geo_dataset(gdf, bbox=(x1, y1, x2, y2))

# From WFS source wfs_dataset = create_geo_dataset({“url”: “https://example.com/wfs”,

“layer”: “layer1”})

# From local raster file raster_dataset = create_geo_dataset(“path/to/dem.tif”)

# From numpy array raster_dataset = create_geo_dataset(array_data, transform=transform,

crs=”EPSG:4326”)

pyorps.save_empty_cost_assumptions(geo_dataset, save_path, main_feature=None, side_features=None, file_type='csv', **kwargs)[source]

Generate and save empty cost assumptions with zero values for a geo dataset.

This function analyzes the given dataset to detect appropriate feature columns, creates a CostAssumptions object with zero costs for all feature combinations, and saves it to the specified path in the requested format.

Parameters:

  • geo_dataset (Any) – GeoDataset object with a ‘data’ attribute containing a GeoDataFrame

  • save_path (Union[str, Path]) – File path where the cost assumptions should be saved

  • main_feature (Optional[str]) – Column name for the primary feature

  • side_features (Optional[list[str]]) – List containing a single column name for the secondary feature

  • file_type (str) – Output file format - one of ‘json’, ‘csv’, or ‘excel’ (default is ‘json’)

Raises:
Returns:

This function saves to a file and doesn’t return a value

Return type:

None