pyorps.raster

Raster data processing functionality for geospatial analysis.

This module provides: 1. Classes for handling and manipulating raster datasets 2. Rasterization tools for converting vector data to rasters 3. Cost surface generation capabilities 4. Utility functions for creating test data and processing rasters

class pyorps.raster.RasterHandler(raster_source, source_coords, target_coords, search_space_buffer_m=None, input_crs=None, apply_mask=True, outside_value=None, bands=None)[source]

Bases: object

Class for efficiently working with raster data while preserving geographic transformation information. Can be initialized with either a file path or directly with raster data, CRS, and transform.

Initialize a RasterHandler for working with raster data and coordinate transformations.

Creates a window and buffer geometry based on source and target coordinates: - If source and target are single coordinates: creates a line buffer - If source and/or target are lists of coordinates: creates a polygon buffer

Parameters:

  • raster_source (RasterDataset) – Either: - Path to the raster file (str), or - Tuple of (data_array, crs, transform)

  • source_coords (Tuple[float, float] | List[Tuple[float, float]]) – Source point(s) as (x, y) tuple or list of tuples

  • target_coords (Tuple[float, float] | List[Tuple[float, float]]) – Target point(s) as (x, y) tuple or list of tuples

  • search_space_buffer_m (float) – Buffer distance in map units (typically meters)

  • input_crs (str | None) – CRS of the input coordinates (e.g., ‘EPSG:4326’). If None, assumes same as raster

  • apply_mask (bool) – If True, apply the buffer mask after loading data

  • outside_value (Any | None) – Value to set for pixels outside the buffer (defaults to max value of the data type)

  • bands (List[int] | None) – List of bands to modify if apply_mask is True (1-based). If None, all bands are modified

__init__(raster_source, source_coords, target_coords, search_space_buffer_m=None, input_crs=None, apply_mask=True, outside_value=None, bands=None)[source]

Initialize a RasterHandler for working with raster data and coordinate transformations.

Creates a window and buffer geometry based on source and target coordinates: - If source and target are single coordinates: creates a line buffer - If source and/or target are lists of coordinates: creates a polygon buffer

Parameters:

  • raster_source (RasterDataset) – Either: - Path to the raster file (str), or - Tuple of (data_array, crs, transform)

  • source_coords (Tuple[float, float] | List[Tuple[float, float]]) – Source point(s) as (x, y) tuple or list of tuples

  • target_coords (Tuple[float, float] | List[Tuple[float, float]]) – Target point(s) as (x, y) tuple or list of tuples

  • search_space_buffer_m (float | None) – Buffer distance in map units (typically meters)

  • input_crs (str | None) – CRS of the input coordinates (e.g., ‘EPSG:4326’). If None, assumes same as raster

  • apply_mask (bool) – If True, apply the buffer mask after loading data

  • outside_value (Any | None) – Value to set for pixels outside the buffer (defaults to max value of the data type)

  • bands (List[int] | None) – List of bands to modify if apply_mask is True (1-based). If None, all bands are modified

apply_geometry_mask(geometry, outside_value=None, bands=None)[source]

Set pixel values outside the given geometry to the specified value.

Parameters:

  • geometry (Polygon) – A shapely geometry object (Polygon)

  • outside_value (int | None) – Value to set for pixels outside the geometry

  • bands (list[int] | int | None) – List of bands to modify (1-based). If None, all bands are modified.

coords_to_indices(coords)[source]

Convert geographic coordinates to pixel row/column indices within this raster section.

Parameters:

coords (tuple[float, float] | list[float] | list[tuple[float, float] | list[float]]) – List of (x, y) coordinate tuples or a single coordinate tuple

Returns:

Array of (row, col) pixel indices

Return type:

numpy.ndarray

estimate_buffer_width(source_coords, target_coords, min_buffer=200, max_buffer=4000, sample_radius=50)[source]

Estimate an appropriate buffer width for path finding based on terrain characteristics.

Parameters:
Returns:

Estimated optimal buffer width in meters

indices_to_coords(indices)[source]

Convert pixel indices to geographic coordinates.

Parameters:

indices (List[Tuple[int, int]]) – List of (row, col) pixel indices

Returns:

Array of (x, y) coordinates

Return type:

numpy.ndarray

static max_distance_pair(coords1, coords2)[source]

Find the pair of coordinates (one from coords1, one from coords2) with the highest Euclidean distance.

Parameters:
Returns:

A tuple containing the two points with the maximum distance (point1, point2)

save_section_as_raster(output_path)[source]

Save the section as a new raster file with proper geo referencing.

Parameters:

output_path (str) – Path for the output raster file

raster_dataset: RasterDataset
search_space_buffer_m: float
buffer_geometry: Polygon
window: Window
window_transform: Affine
data: ndarray
class pyorps.raster.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

Initialize the GeoRasterizer with a base dataset and optional parameters.

Parameters:

  • input_data (GeoDataset) – The base dataset to rasterize (file path, GeoDataFrame, dict with web params, or GeoDataset)

  • mask (Polygon | GeoDataFrame | tuple | None) – Window or polygon mask to limit data reading

  • cost_assumptions (dict | str | CostAssumptions) – Cost values for rasterization (dict, file path, or CostAssumptions object)

  • default_crs (str | None) – Default coordinate reference system to use

  • **kwargs – Additional parameters passed to load function of the GeoDataset if base_dataset is not a GeoDataset

  • bbox (Polygon | GeoDataFrame | GeoSeries | tuple[float, float, float, float] | None)

__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:

  • input_data (GeoDataset) – The base dataset to rasterize (file path, GeoDataFrame, dict with web params, or GeoDataset)

  • mask (Polygon | GeoDataFrame | tuple | None) – Window or polygon mask to limit data reading

  • cost_assumptions (dict | str | CostAssumptions) – Cost values for rasterization (dict, file path, or CostAssumptions object)

  • default_crs (str | None) – Default coordinate reference system to use

  • **kwargs – Additional parameters passed to load function of the GeoDataset if base_dataset is not a GeoDataset

  • bbox (Polygon | GeoDataFrame | GeoSeries | tuple[float, float, float, float] | None)

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 (GeoDataFrame | Polygon) – The geometry to clip by

Returns:

The clipped base dataset

Return type:

GeoDataset

create_bounds_geodataframe(target_crs=None)[source]

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

Parameters:

target_crs (str | None) – The desired CRS for the new GeoDataFrame

Returns:

A new GeoDataFrame containing the bounds of the base data

Return type:

GeoDataFrame

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

Add a buffer to geometries in a dataset.

Parameters:

  • dataset (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

Returns:

The buffered dataset

Return type:

VectorDataset | GeoDataFrame

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:

  • input_data (str | dict | GeoDataFrame | GeoSeries | ndarray) – Path to the additional dataset file

  • cost_assumptions (dict | str | CostAssumptions | int | float | None) – The CostAssumptionsType or numeric to apply as cost values to the base_dataset

  • bbox (Polygon | GeoDataFrame | GeoSeries | tuple[float, float, float, float] | None) – The bounding box to apply to the input data

  • mask (Polygon | GeoDataFrame | tuple | None) – The geometry mask to apply to the input data

  • transform (Affine | None) – The transform describing the input data

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

  • ignore_value (float | None) – Value in the raster to ignore

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

  • zone_field (str | None) – Field name for zones in the dataset

  • forbidden_zone (str | None) – Zone value that should be treated as forbidden

  • forbidden_value (int) – Value to use for forbidden areas

  • **kwargs – Additional keyword arguments, passed to the loading function of the GeoDataset

Returns:

The modified raster

Return type:

ndarray

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 (float | None) – Value in the raster to ignore during modification

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

Returns:

The modified raster

Return type:

ndarray

rasterize(field_name='cost', resolution_in_m=1.0, fill_value=65535, save_path=None, dtype='uint16', geometry_buffer_m=0, bounding_box=None, preprocessing_function=None, preprocessing_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 (str | None) – 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 (Polygon | None) – Bounding box to define the rasterization extent

  • preprocessing_function (Callable | None) – A function that takes the base dataset as a first

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

  • rasterization (be called before)

  • preprocessing_kwargs (dict[str, Any] | None) – The keyword arguments passed to preprocessing_function

Returns:

tuple of (raster_data, transform)

Return type:

RasterDataset

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

Returns:

The shrunk raster

Return type:

ndarray

Modules

handler

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

rasterizer

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