ParcelFlux — Algorithm & Parameter Guide

Version: 0.1.0  |  Author: Yusuf Eminoglu  |  License: GPL-3.0

ParcelFlux subdivides zoning blocks (imar adalar) into individual parcels with tunable geometric variation. It operates on polygon layers and produces a memory layer of parcel polygons with area and optional facade-tracking columns.

1. Algorithm Overview

The engine processes each input block polygon independently through six stages:

1. Geometry Normalization — irregular polygons are replaced by their oriented minimum bounding box (OBB). Regular 4-vertex polygons pass through unchanged.
2. Axis Detection — the two shortest edges define the block "ends." The line connecting their midpoints becomes the centerline (h-line). The perpendicular direction is the division axis along which parcels are laid out.
3. Row Detection — if the short-edge width is less than 1.8 * lot_width, the block is treated as single-row (one strip of parcels). Otherwise it is double-row (two opposing strips on either side of the centerline).
4. Division Line Generation — perpendicular lines are placed along the centerline at intervals equal to lot_width, with optional variation (width, fishbone, asymmetry, h-line shift).
5. Split & Merge — the block is split by the division lines using native:splitwithlines. Residual fragments below the area threshold are merged into the neighbor with the longest shared edge, in up to 3 passes.
6. Filter & Output — parcels exceeding max_area or below 5 m² are excluded. Remaining parcels are written to a memory layer with area and optional ID/facade columns.

2. Parameter Reference

2.1 Lot Width lot_width

Default: 16.0 m  |  Range: 5.0 – 100.0 m

Target frontage width of each parcel. This is the primary control over parcel count. Smaller values produce more parcels per block; larger values produce fewer, wider parcels.

where L_centerline is the length of the line connecting the midpoints of the two shortest edges. In double-row mode, each side independently computes its parcel count.

2.2 Minimum Area min_area

Default: 300.0 m²  |  Range: 0.0 – 999999.0 m²

Parcels smaller than this threshold are merged into the adjacent neighbour with the longest shared boundary. This operates alongside the merge-threshold rule. Set to 0 to disable hard-minimum enforcement.

2.3 Maximum Area max_area

Default: 2000.0 m²  |  Range: 0.0 – 999999.0 m²

Parcels exceeding this area are filtered out of the output. Use a high value (e.g. 999999) to keep all parcels regardless of size.

2.4 Merge Threshold merge_threshold

Default: 35.0 %  |  Range: 0.0 – 100.0 %

Residual (sliver) merging threshold expressed as a percentage of the mean parcel area after the current pass. The threshold is recomputed after each merge pass:

Any parcel with area < T_pass is merged into its neighbor with the longest shared edge. Three passes are attempted; the process stops early if no parcels are merged in a pass. Higher values = more aggressive merging. 0 = only the min_area rule applies.

2.5 Uniform Corners uniform_corners

Default: enabled (True)

Controls how leftover space along the centerline is distributed:

• Enabled: leftover space is split equally on both ends. Corner parcels are similar in width to interior parcels.
• Disabled: parcels stack from one edge. Any remainder collects at the far end, producing one narrower or wider terminal parcel.

2.6 Width Variation width_variation

Default: 0.0 %  |  Range: 0.0 – 25.0 %

Per-parcel random width variation. Each parcel in a row receives an independent random multiplier:

After randomization, all widths are re-normalized so their sum equals the available centerline length. At 0%, all parcels in a row are identical. At 15% with a 20 m target, parcels range from approximately 17 m to 23 m.

2.7 Fishbone Offset fishbone_offset

Default: 0.0 %  |  Range: 0.0 – 15.0 %

Organic zigzag shift applied to division-line endpoints along the centerline direction. Creates a herringbone pattern that mimics traditional settlement morphologies.

At 0%, division lines are straight. At 5-10%, the herringbone effect becomes visually apparent. The two endpoints of each division line are offset independently, so lines can slant rather than remaining parallel.

2.8 Row Width Asymmetry row_width_asymmetry

Default: 0.0 %  |  Range: 0.0 – 25.0 %

Creates different parcel widths on the two rows on opposite sides of the centerline. This models real-world patterns where north-facing parcels may be wider (more desirable solar orientation) than south-facing ones.

This parameter is ignored in single-row mode (when the block's short edge < 1.8 * lot_width).

2.9 H-Line Shift hline_offset

Default: 0.0 %  |  Range: 0.0 – 25.0 %

Shifts the center division line away from the geometric midpoint of the block's short edges, producing asymmetric front/rear depths.

At 0%, the block is split exactly in half. At 10%, the h-line is randomly placed between 40%-60% along each short edge. One row gets deeper parcels, the other gets shallower ones. This is useful for differentiating front-garden and back-garden depths.

3. Single-Row vs Double-Row Detection

The decision rule is:

• Single-row: the block is too narrow for two opposing parcel rows. Division lines cut all the way across the block (no centerline split).
• Double-row: the h-line divides the block into two strips, each subdivided independently.

Rationale for 1.8: each parcel row needs at least lot_width depth. A factor of 1.8 provides a 10% margin (two rows need ~2.0x, thresholding at 1.8 ensures rows are not too shallow). A block with short edge = 30 m and lot_width = 16 m triggers double-row mode because 30 ≥ 1.8 * 16 = 28.8.

4. Residual Merging Algorithm

After the split, sliver polygons (triangular fragments, narrow strips) inevitably form near block edges and division-line intersections. The 3-pass merging algorithm handles these:

1. Pass 1: compute mean parcel area. Any parcel below max(threshold_pct * mean, min_area) is a candidate.
2. For each candidate, find the spatial neighbor with the longest shared boundary (measured via intersection().length() on LineString intersections).
3. Merge the candidate into that neighbor via geometry.combine().
4. Repeat passes 2 and 3 with a recalculated threshold (mean parcel area changes after each pass).
5. Stop early if no parcels are merged in a pass.

This is a greedy algorithm — it processes candidates in feature-ID order and does not revisit already-merged parcels within a single pass. The 3-pass structure allows cascading merges: a merged parcel from pass 1 may itself be below threshold in pass 2 and get merged again.

5. Output Schema

* = optional; controlled by "Add ID columns" and "Add facade columns" checkboxes in the dock UI.

6. QGIS Compatibility

The plugin uses only stable PyQGIS APIs and native Processing algorithms. The QgsWkbTypes.GeometryType enum is resolved at import time with a try/except fallback for QGIS 3.

7. Typical Workflow

1. Load your zoning block polygon layer into QGIS.
2. Open the ParcelFlux dock panel (ParcelFlux menu or toolbar).
3. Select the block layer.
4. Set Lot Width to match your zoning regulations (e.g. 16 m for residential, 25 m for villa plots).
5. Adjust Min/Max Area to filter extreme parcel sizes.
6. Optionally enable Width Variation (5-10%) for natural-looking diversity.
7. For north/south differentiation, enable Row Width Asymmetry (5-12%).
8. For organic-looking boundaries, enable Fishbone Offset (3-8%).
9. Click RUN.
10. The output layer is added to the map. Inspect, then run facade labeling (Step 2 in the PlanX Settlement toolset) to populate facade columns.

ParcelFlux 0.1.0 — part of the PlanX Geospatial Tools suite.