genplanner.GenPlanner

class genplanner.GenPlanner(features_gdf, roads_gdf=None, roads_extend_distance=5, exclude_gdf=None, exclude_buffer=5, existing_terr_zones=None, existing_tz_fill_ratio=0.7, existing_tz_merge_radius=50, simplify_geometry_value=0.01, parallel=True, parallel_max_workers=None, rust_write_logs=False, run_name=None)[source]
Parameters:
original_territory

Copy of the input features_gdf.

original_crs

CRS of the input territory.

local_crs

Estimated local projected CRS (UTM).

territory_to_work_with

Prepared working territory polygons in local_crs.

existing_terr_zones

Prepared existing zones in local_crs.

static_fix_points

Fixed points derived from existing zones (column fixed_zone).

user_roads

Prepared roads in local_crs (column roads_width always present).

source_multipolygon

True if the working territory contains multiple polygons.

run_name

Run identifier (and log directory prefix).

__init__(features_gdf, roads_gdf=None, roads_extend_distance=5, exclude_gdf=None, exclude_buffer=5, existing_terr_zones=None, existing_tz_fill_ratio=0.7, existing_tz_merge_radius=50, simplify_geometry_value=0.01, parallel=True, parallel_max_workers=None, rust_write_logs=False, run_name=None)[source]

Initialize a territory zoning pipeline.

The planner prepares the input territory geometry into a working GeoDataFrame in a local projected CRS, optionally applies exclusions, cuts the territory by roads, integrates existing territorial zones, and configures runtime settings such as parallel execution and optimizer logging.

High-level preprocessing steps:

  1. Keep only Polygon/MultiPolygon features from features_gdf.

  2. Reproject to a local CRS (estimated UTM) and explode multipart geometries.

  3. If exclude_gdf is provided: clip, buffer by exclude_buffer, subtract.

  4. If roads_gdf is provided: normalize/deduplicate, extend by roads_extend_distance, split the territory, and keep roads that intersect produced splitters; fill missing roads_width with a default and warn.

  5. If existing_terr_zones is provided: validate schema, clip to territory, merge territory fragments into existing zones when coverage ratio exceeds existing_tz_fill_ratio, then cut the remaining territory by those zones.

  6. If existing zones exist: build static fixed points from existing zones using existing_tz_merge_radius and snap them to the territory boundary.

Parameters:

  • features_gdf (GeoDataFrame) – Input territory geometry as a GeoDataFrame. Only Polygon and MultiPolygon geometries are used. If the final working set has more than one polygon, the planner will run a “multi feature” task variant.

  • roads_gdf (GeoDataFrame | None) – Optional roads GeoDataFrame used to split the territory. Any geometry type is accepted, but it is expected to contain line-like geometries after normalization. The roads_width column is optional; if missing, it will be filled with a default width and a warning will be logged.

  • roads_extend_distance (float) – Distance (in local CRS units, typically meters) used to extend road linestrings before splitting.

  • exclude_gdf (GeoDataFrame | None) – Optional exclusion geometries (e.g., water, protected areas). If provided, they are buffered and subtracted from the territory.

  • exclude_buffer (float) – Buffer distance (local CRS units) applied to exclude_gdf before subtraction.

  • existing_terr_zones (GeoDataFrame | None) – Optional existing territorial zones to preserve and merge into the output. If provided, it must contain a territory_zone column.

  • existing_tz_fill_ratio (float) – Minimum ratio of a territory polygon area that must be covered by an existing zone for that polygon to be merged into the existing zone instead of being split further. Must be in [0, 1].

  • existing_tz_merge_radius – Radius (local CRS units) used to merge nearby fragments of the same existing zone when deriving static fix points, and to stabilize representative point selection.

  • simplify_geometry_value – Internal simplification factor in normalized 0..1 space used for speed/robustness trade-offs. It does not directly change the final output geometry, but can influence processing.

  • parallel – Whether to use multiprocessing for downstream tasks. If disabled or if the machine has fewer than 2 CPUs, execution is forced to single-worker mode.

  • parallel_max_workers – Maximum worker count for parallel execution. If None and parallel is enabled, defaults to max(1, cpu_count - 1).

  • rust_write_logs – If True, enables Rust optimizer logs and creates a directory for run_name.

  • run_name – Optional run identifier used as a log/artifact prefix. If None, an auto name like gp_DDMMYY_HH_MM is generated.

Raises:

GenPlannerInitError – If features_gdf has no valid Polygon/MultiPolygon geometries, or CRS checks fail, or existing_terr_zones is provided without the required territory_zone column.

Methods

__init__(features_gdf[, roads_gdf, ...])

Initialize a territory zoning pipeline.

features2terr_zones([funczone, ...])

Generate territorial zones for the prepared territory.

features2terr_zones2blocks([funczone, ...])

Generate territorial zones and subdivide them into blocks.

Attributes

RelationMatrixArg