┌──────────────────────────────────────────────────────┐
│                    Docker Network                     │
│                                                       │
│  ┌──────────────────┐     ┌────────────────────────┐ │
│  │   Nginx + Front  │────▶│  FastAPI Backend v3    │ │
│  │   (port 3000)    │     │  (port 8000)           │ │
│  │   OpenLayers UI  │     │  Shapely / GEOS engine │ │
│  └──────────────────┘     └────────────────────────┘ │
└──────────────────────────────────────────────────────┘
          ▲
          │ Browser
     http://localhost:3000

Quick Start

Prerequisites

Docker and Docker Compose

Run

cd parcel-tool
docker compose up --build

Open http://localhost:3000 in your browser.

Stop

docker compose down

Feature Overview

Drawing Tools

Tool	Description
◇ Boundary	Draw the site boundary polygon. Double-click to finish. Only one boundary is kept at a time.
⟋ Road	Draw road centrelines. Each line is buffered to the configured road width. Draw multiple; all are used.
▦ Building	Draw existing building footprints. Carved out before subdivision; containing parcel flagged as "built".
📏 Measure	Click to place measure points, double-click to finish. Shows live distance in the active unit system (m/km or ft/mi).
✕ Stop	Exit any active draw or measure mode.

Map Interaction

Action	Result
Hover over a parcel	Floating tooltip: area (dual units), frontage, depth, status, road access
Click a parcel	Pins a detail panel bottom-left; highlights parcel in gold
Click empty map	Clears selection
Scroll / drag	Standard map pan and zoom

Sidebar Tabs

Draw — Drawing tools and Run Subdivision / Export buttons
Config — Subdivision parameters with live unit conversion
Layers — Visibility, opacity, basemap switcher, and legend
Results — Stats dashboard and scrollable parcel list

UI Controls

Theme Toggle (sun/moon button)

Click the ☀️ / 🌙 button in the top-left of the sidebar header to switch between dark and light themes. The preference is saved in localStorage and restored on next visit. Switching theme also switches the default basemap automatically.

Unit System (m / ft)

Click the m or ft pill to toggle metric/imperial. All config inputs convert in-place. Results display both units. The backend always receives and returns SI (metres, m²).

Basemap Switcher

12 basemaps in 5 categories, accessible from the Layers tab or the floating Basemap panel (bottom-right):

Category	Options
Style	Dark (CARTO), Light (CARTO), Night Lights
Street	OpenStreetMap
Terrain	OpenTopoMap, ESRI Topo, ESRI Shaded Relief, Ocean
Imagery	ESRI Satellite, ESRI Satellite + Labels
Artistic	Stamen Terrain, Stamen Watercolor

Layer Switcher

Both the floating Layers panel and the Layers tab expose per-layer controls:

Visibility checkbox
Opacity slider (0–100%, live update)
Colour swatch

Layers: Boundary · Buildings (drawn) · Roads (drawn) · Road surfaces · Cul-de-sacs · Blocks · Parcels

Subdivision Engine

Algorithm

1.  Parse boundary polygon (WGS84 / EPSG:4326)
2.  Parse user-drawn road centrelines + existing building footprints
3.  Build road network:
    a. Buffer user roads → road polygons
    b. Auto-generate grid roads to fill blocks > max_block_length
       (combined with user roads, never either/or)
    c. Add perimeter access ring inside the boundary edge
4.  Carve: buildable = boundary − roads − buildings
5.  Extract contiguous buildable blocks
6.  Generate cul-de-sacs for oversized blocks (if enabled)
7.  Subdivide each block into rectangular parcels:
    a. Detect dominant orientation via oriented bounding box
    b. Double-bank parcels back-to-back where depth allows
    c. Clip each cell to the actual block polygon
8.  Quality passes:
    a. Absorb undersized / badly-shaped parcels into neighbours
    b. Enforce road access — merge landlocked parcels into accessed neighbour
9.  Apply existing buildings → merge spanning parcels, mark status="built"
10. Re-number sequentially, assign addresses
11. Return GeoJSON + stats

Parcel Access Guarantee

Every parcel is checked for road adjacency. Landlocked parcels are merged into their nearest same-block neighbour that has road access. This loop runs until stable. Any remaining inaccessible parcels are flagged in red on the map and counted in the stats panel.

Metric Scaling

All internal geometry is in WGS84 degrees. A scale factor (metres-per-degree) is computed at the site centroid so that metre-based config values work correctly at any latitude:

m_per_deg = (111 320 + 111 320 × cos(lat)) / 2

Default Configuration

Parameter	Default	Description
`min_frontage`	12 m	Minimum parcel road frontage
`min_depth`	25 m	Minimum parcel depth
`road_width`	9 m	Road right-of-way width
`max_block_length`	120 m	Max block length before road/cul-de-sac insertion
`allow_culdesac`	true	Generate cul-de-sacs for oversized blocks
`corner_radius`	3 m	Road corner rounding radius

Parcel Properties (GeoJSON)

{
  "parcel_id":        "P0042",
  "parcel_num":       42,
  "block_id":         3,
  "area_m2":          340.5,
  "area_ha":          0.034,
  "frontage_m":       12.3,
  "depth_m":          27.7,
  "address":          "Block 3, Plot 42",
  "zone":             "Residential",
  "status":           "vacant",
  "has_access":       true,
  "frontage_ok":      true,
  "area_ok":          true,
  "building_area_m2": 0
}

status is "built" when an existing building footprint overlaps the parcel.

API Reference

`POST /subdivide`

{
  "boundary": { "type": "Polygon", "coordinates": [[...]] },
  "roads": [
    { "type": "Feature", "geometry": { "type": "LineString", "coordinates": [[...]] }, "properties": {} }
  ],
  "existing_features": [
    { "type": "Feature", "geometry": { "type": "Polygon", "coordinates": [[...]] }, "properties": {} }
  ],
  "config": {
    "min_frontage": 12,
    "min_depth": 25,
    "road_width": 9,
    "max_block_length": 120,
    "allow_culdesac": true,
    "corner_radius": 3
  }
}

Both bare geometry dicts and GeoJSON Feature wrappers are accepted.

Response:

{
  "parcels":   [ ],
  "roads":     [ ],
  "blocks":    [ ],
  "culdesacs": [ ],
  "stats": {
    "total_parcels": 42,
    "total_blocks": 4,
    "total_roads": 3,
    "culdesacs": 1,
    "parcels_no_access": 0,
    "parcels_built": 2,
    "parcels_vacant": 40,
    "boundary_area_m2": 18400.0,
    "road_area_m2": 2100.0,
    "buildable_area_m2": 14200.0,
    "avg_parcel_area_m2": 338.1,
    "existing_buildings": 2,
    "user_roads_drawn": 1
  }
}

`GET /health`

Returns {"status": "ok", "version": "3.0.0"}

`GET /config/defaults`

Returns the default SubdivisionConfig as JSON.

Map Colour Legend

Colour	Meaning
Blue outline	Vacant parcel
Orange outline	Built parcel (existing building)
Red dashed outline	No road access ⚠
Gold outline	Currently selected parcel
Yellow fill	Road surface
Purple fill	Cul-de-sac
Green dashed	Site boundary
Purple dashed	Drawn building footprint

Export

Export GeoJSON in the Draw tab downloads a .geojson file with all parcels, roads, and cul-de-sacs plus a metadata block (timestamp, display units). All attribute values are always in SI units regardless of the unit switcher.

Development

Backend

cd backend
pip install -r requirements.txt
uvicorn main:app --reload --port 8000

Frontend

Open frontend/index.html directly in a browser. API_URL auto-detects: port 3000 proxies to port 8000, otherwise uses same origin.

File Structure

parcel-tool/
├── docker-compose.yml
├── README.md
├── backend/
│   ├── Dockerfile
│   ├── requirements.txt
│   └── main.py              ← Subdivision engine (v3)
└── frontend/
    ├── Dockerfile
    ├── nginx.conf
    └── index.html           ← OpenLayers UI

Technical Notes

Coordinate system: EPSG:4326 for API I/O; EPSG:3857 for map display
Geometry engine: Shapely 2.x + GEOS
Basemaps: CARTO, OSM, Esri, Stamen — no API key needed
Theme: Persisted in localStorage under key parcelgen-theme
Imperial mode: Display only — backend always receives metres
Performance: Sites up to ~50 ha typically process in under 2 s

README.md Unescape Escape

⬡ ParcelGen — Land Subdivision Tool

Architecture