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, max_run_seconds=900, max_optimization_iterations=2000, seed=None)[source]
Variables:

  • 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).

Exclude-members:

original_territory, features2terr_zones, features2terr_zones2blocks

Methods

features2terr_zones

Generate territorial zones for the prepared territory.

features2terr_zones2blocks

Generate territorial zones and subdivide them into blocks.
features2terr_zones(funczone=<genplanner.zones.functional_zones.FunctionalZone object>, relation_matrix='default', terr_zones_fix_points=None)[source]

Generate territorial zones for the prepared territory.

Runs the full zoning pipeline and produces territorial zone polygons without further subdivision into blocks. The method respects existing territorial zones (if provided at initialization), integrates static fix points derived from them, and balances target ratios accordingly.

The pipeline performs:

  • validation and optional adjustment of zone ratios,

  • validation and merging of fixed points,

  • resolution of the relation matrix (adjacency/forbidden rules),

  • task execution (single or multi-feature),

  • merging of generated and existing zones,

  • road-based splitting of final geometries.

Parameters:

  • funczone – Functional zoning definition containing a mapping of TerritoryZone objects to target area ratios. Must be an instance of FunctionalZone.

  • relation_matrix –

    Zone adjacency/preference definition.

    Supported values:

    • ”default”: builds a matrix using predefined forbidden neighborhood rules for the zone kinds in funczone.

    • ”empty”: creates an empty relation matrix with no encoded adjacency constraints.

    • ZoneRelationMatrix instance: validated against the zone kinds of funczone (missing zones raise an error; extra zones produce a warning).

    • None: treated as “default”.

  • terr_zones_fix_points –

    Optional GeoDataFrame of fixed zone anchor points.

    Required schema:

    • geometry: Point (all geometries must be Points)

    • fixed_zone: TerritoryZone (must match keys of funczone.zones_ratio)

    Validation rules:

    • All geometries must be Points.

    • All fixed_zone values must exist in the zone ratio dict.

    • All points must lie within the working territory.

    • If existing zones reduce a zone’s remaining ratio to zero, corresponding fixed points are removed automatically.

Returns:

A pair (zones_gdf, roads_gdf) in the original input CRS:

  • zones_gdf:

    Final territorial zone polygons, including merged existing zones (if provided).

  • roads_gdf:

    Road geometries used/generated during splitting. The column roads_width is always present.

Return type:

tuple[gpd.GeoDataFrame, gpd.GeoDataFrame]

Raises:
features2terr_zones2blocks(funczone=<genplanner.zones.functional_zones.FunctionalZone object>, relation_matrix='default', terr_zones_fix_points=None)[source]

Generate territorial zones and subdivide them into blocks.

Executes the same zoning pipeline as features2terr_zones(), but additionally performs subdivision of territorial zone polygons into smaller block polygons according to zone-specific constraints (e.g., minimum block area).

All preprocessing steps, validation rules, relation matrix handling, fixed point integration, and existing zone balancing are identical to features2terr_zones().

Parameters:

  • funczone – Functional zoning definition containing TerritoryZone objects and their target area ratios. Must be a FunctionalZone.

  • relation_matrix –

    Zone adjacency/preference definition. Supported values:

    • ”default”: builds a relation matrix from predefined forbidden neighborhood rules.

    • ”empty”: creates an empty relation matrix.

    • ZoneRelationMatrix instance: validated against funczone zone kinds.

    • None: treated as “default”.

  • terr_zones_fix_points –

    Optional GeoDataFrame of fixed zone anchor points.

    Required schema:

    • geometry: Point

    • fixed_zone: TerritoryZone (must match keys of funczone.zones_ratio)

    All validation and balancing rules are identical to features2terr_zones().

Returns:

A pair (blocks_gdf, roads_gdf) in the original input CRS:

  • blocks_gdf:

    Subdivided polygons after the additional block-splitting stage (may include both zone-level and block-level outputs, depending on downstream logic).

  • roads_gdf:

    Road geometries used/generated during splitting.

Return type:

tuple[gpd.GeoDataFrame, gpd.GeoDataFrame]

Raises: