Metadata-Version: 2.4
Name: parcelform
Version: 0.1.2
Summary: Parcel and lot geometry metrics from GeoJSON polygons: shape indices, minimum-area rectangle, frontage and lot type, depth and width, setback envelopes and subdivision feasibility checks.
Author-email: Yusuf Eminoğlu <geospacephilo@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://gitlab.com/geophilo1/parcelform_sdk
Project-URL: Repository, https://gitlab.com/geophilo1/parcelform_sdk
Project-URL: Documentation, https://gitlab.com/geophilo1/parcelform_sdk#readme
Project-URL: Issues, https://gitlab.com/geophilo1/parcelform_sdk/-/work_items
Project-URL: Changelog, https://gitlab.com/geophilo1/parcelform_sdk/-/blob/main/CHANGELOG.md
Project-URL: SDK dashboard, https://geophilo.com/sdk-dashboard/
Project-URL: DOI, https://doi.org/10.5281/zenodo.24235570
Keywords: parcel,lot,cadastre,land-subdivision,frontage,setback,zoning,shape-index,polsby-popper,minimum-bounding-rectangle,geojson,urban-planning,gis
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: OS Independent
Classifier: Environment :: Console
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Other Audience
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.21
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Dynamic: license-file

<p align="center">
  <a href="https://geophilo.com/sdk-dashboard/"><img src="https://geophilo.com/assets/sdk_icons/parcelform_sdk.svg" width="120" height="120" alt="parcelform icon"></a>
</p>

# parcelform

[![PyPI version](https://img.shields.io/pypi/v/parcelform.svg)](https://pypi.org/project/parcelform/)
[![Python versions](https://img.shields.io/pypi/pyversions/parcelform.svg)](https://pypi.org/project/parcelform/)
[![pipeline status](https://gitlab.com/geophilo1/parcelform_sdk/badges/main/pipeline.svg)](https://gitlab.com/geophilo1/parcelform_sdk/-/pipelines)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://gitlab.com/geophilo1/parcelform_sdk/-/blob/main/LICENSE)
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.24235570.svg)](https://doi.org/10.5281/zenodo.24235570)
[![Downloads](https://static.pepy.tech/badge/parcelform/month)](https://pepy.tech/project/parcelform)

Parcel and lot geometry metrics from GeoJSON polygons in projected coordinates.

`parcelform` measures cadastral parcels and building lots the way planners and land-use
analysts usually need them: size and shape, how much of the lot faces a street, whether it
is a corner, through or interior lot, how deep and wide it is, what is left after
setbacks, and whether it can be split into lots that meet minimum standards. It needs only
NumPy and reads and writes plain GeoJSON.

## Installation

```bash
pip install parcelform
```

Requires Python 3.9 or newer and NumPy. Coordinates must be projected (metres or feet);
the package does not reproject and refuses data that looks like longitude/latitude.

## Quickstart

```python
import parcelform as pf

lot = {"type": "Polygon",
       "coordinates": [[[0, 0], [20, 0], [20, 40], [0, 40], [0, 0]]]}
streets = [{"type": "LineString", "coordinates": [[-50, -4], [200, -4]]},   # main street
           {"type": "LineString", "coordinates": [[-4, -50], [-4, 100]]}]   # side street

pf.shape_indices(lot).polsby_popper          # 0.698
pf.min_area_rectangle(lot).to_dict()         # length 40, width 20, angle 90

fr = pf.frontage(lot, streets, tolerance=5, primary_rule="shortest")
fr.total, fr.lot_type                        # 60.0, 'corner'
pf.lot_dimensions(lot, fr)                   # depth 40, width 20, width/depth 0.5

env = pf.buildable_envelope(lot, {"front": 5, "side": 3, "rear": 4,
                                  "secondary_front": 3}, fr)
env.area, env.share                          # 434.0, 0.5425

rules = pf.LotRules(min_area=300, min_frontage=12, min_depth=20)   # from your zoning code
pf.check_lot(lot, rules, streets, tolerance=5).passed

wide = {"type": "Polygon",
        "coordinates": [[[0, 0], [60, 0], [60, 30], [0, 30], [0, 0]]]}
res = pf.subdivision_feasibility(wide, rules, streets[:1], tolerance=4)
res.n_lots                                   # 5 lots of 12 m x 30 m
```

Whole layers in one call:

```python
fc = pf.analyze("parcels.geojson", streets="streets.geojson", tolerance=8,
                setbacks={"front": 5, "side": 3, "rear": 3},
                rules=pf.LotRules(min_area=400, min_frontage=12), subdivide=True,
                on_error="record")
pf.write_geojson(fc, "parcels_measured.geojson")
```

## Features

| Area | Functions | Notes |
| --- | --- | --- |
| Geometry | `area`, `perimeter`, `centroid`, `convex_hull`, `min_area_rectangle`, `min_enclosing_circle`, `points_in_polygon` | holes and MultiPolygons supported |
| Orientation | `Rectangle.angle`, `Rectangle.azimuth`, `orientation_difference` | long axis of the minimum-area rectangle |
| Shape indices | `shape_indices`, `polsby_popper`, `schwartzberg`, `fractal_dimension` | Polsby-Popper, Schwartzberg, Reock, rectangularity, elongation, aspect ratio, area and perimeter convexity, fractal dimension |
| Frontage | `frontage -> Frontage`, `StreetSegments`, `as_streets` | street centrelines or block outlines; per-street lengths; corner / through / interior / landlocked |
| Lot dimensions | `lot_dimensions -> LotDimensions` | depth, width, mean depth, width-to-depth ratio |
| Setbacks | `buildable_envelope -> Envelope`, `edge_roles`, `resolve_setbacks` | uniform, per edge, or by role (front, side, rear, secondary front) |
| Lot rules | `LotRules`, `check_lot`, `evaluate_rules` | minimum area, frontage, depth, width (all user-supplied) |
| Subdivision | `subdivision_feasibility`, `split_parcel`, `lot_count_bound` | equal-frontage or equal-area perpendicular cuts |
| Layers | `analyze`, `envelopes`, `subdivide_collection` | FeatureCollection in, FeatureCollection out |
| I/O | `read_geojson`, `write_geojson`, `write_csv`, `read_rules` | standard library only |

## Methods

### Geometry

- Areas by the shoelace formula; perimeters include holes unless `include_holes=False`.
- Convex hull by Andrew's (1979) monotone chain.
- **Minimum-area rectangle** by rotating calipers: one side of the optimal rectangle is
  collinear with a convex-hull edge (Freeman & Shapira 1975; Toussaint 1983), so every
  hull-edge direction is tried, vectorised. `length` is the long side, `width` the short
  side, `angle` the long axis counter-clockwise from +x in `[0, 180)`, `azimuth` the same
  axis as a bearing from grid north.
- Minimum enclosing circle by Welzl's (1991) algorithm with a fixed shuffle seed.

### Shape indices

`A` area, `P` perimeter, `A_h`/`P_h` convex hull area and perimeter, `L`/`W` long and short
side of the minimum-area rectangle (MBR).

| Index | Formula | Range | Source |
| --- | --- | --- | --- |
| Polsby-Popper | `4 pi A / P^2` | (0, 1], circle = 1 | Polsby & Popper (1991) |
| Schwartzberg | `2 sqrt(pi A) / P` | (0, 1], circle = 1 | Schwartzberg (1966) |
| Reock | `A / A_circle` (minimum enclosing circle) | (0, 1] | Reock (1961) |
| Rectangularity | `A / (L W)` | (0, 1] | Rosin (1999) |
| Elongation | `1 - W / L` | [0, 1), square MBR = 0 | MBR (Freeman & Shapira 1975) |
| Aspect ratio | `L / W` | >= 1 | MBR (Freeman & Shapira 1975) |
| Convexity (area, "solidity") | `A / A_h` | (0, 1] | classical measure, see Zunic & Rosin (2004) |
| Convexity (perimeter) | `P_h / P` | (0, 1] | classical measure, see Zunic & Rosin (2004) |
| Fractal dimension | `2 ln(0.25 P) / ln A` | about 1-2 | McGarigal & Marks (1995), FRAGSTATS FRAC |

Schwartzberg (1966) defined `P / (2 sqrt(pi A))` (>= 1); `schwartzberg` reports its
reciprocal so that all compactness indices point the same way, and `schwartzberg_ratio`
gives the original. The fractal dimension uses the FRAGSTATS correction (a square scores
1); it depends on the length unit and is NaN for `A <= 1`.

### Frontage and lot type

For every parcel edge and street segment, the part of the edge within `tolerance` of the
segment is the intersection of the edge with the segment's capsule (a convex set, so the
answer is one interval, computed in closed form). Only parts where the edge runs within
`max_angle` (default 20 degrees) of the street direction count, so side lot lines that end
at the street do not. Intervals are merged per edge, so overlapping street lines are not
double-counted; `by_street` gives the length per street id.

With street **centrelines**, set `tolerance` to about half the right-of-way width plus a
digitising allowance. With **block outlines** (or lines on the street side of the lots),
use a small tolerance.

- `corner`: two frontage pieces at `corner_angle` (default 45 degrees) or more to each
  other;
- `through`: two roughly parallel frontage pieces facing away from each other;
- `interior`: frontage on one side; `landlocked`: none.

The **primary front** is the longest frontage piece by default; `primary_rule="shortest"`
uses the shortest piece, which matches codes that put the front of a corner lot on the
narrower street side. `depth` is the extent of the lot perpendicular to the primary front,
`width` the extent along it, `mean_depth = area / width`. Without frontage the MBR is used
(`basis = "mbr"`). Zoning codes define lot depth and width in several ways; check that
these definitions fit the code you apply.

### Buildable envelope

Each lot line is moved inward, parallel to itself, by its setback, and the envelope is the
area inside all setback lines. Setbacks are uniform, per edge, or by role: an edge is a
`front` edge when at least half of it is frontage, `secondary_front` when it is a front
edge turned 45 degrees or more from the primary front, `rear` when it faces away from the
primary front, otherwise `side`.

- Convex parcels: exact half-plane intersection by Sutherland-Hodgman clipping
  (Sutherland & Hodgman 1974).
- Non-convex parcels: mitred offset with removal of collapsing edges, as in the edge
  events of a straight skeleton (Aichholzer et al. 1995), then verified (simple ring, every
  vertex and edge midpoint keeps every setback). An envelope that would split into pieces
  raises `ParcelError`; one with no buildable point is returned empty.

### Subdivision feasibility

`subdivision_feasibility` first checks the parcel against the rules, bounds the lot count
by `floor(min(area / min_area, frontage / min_frontage))`, then tries that count and fewer,
splitting the parcel by straight cuts perpendicular to the primary front (equal frontage or
equal area) and re-measuring every new lot's frontage, depth and width against the
streets. It returns the largest conforming count (`0` if the parcel itself fails, `1` if it
cannot be split). It is a screening tool: flag lots, curved streets, easements and access
rules are out of scope.

No lot standards or setback distances are built in. They are parameters, because they come
from the zoning or subdivision code that applies.

## Command line

```bash
parcelform metrics parcels.geojson --streets streets.geojson --tolerance 8 \
    --front 5 --side 3 --rear 3 --min-area 400 --min-frontage 12 --subdivide \
    -o parcels_measured.geojson --csv parcels.csv

parcelform envelope parcels.geojson --setback 3 -o envelopes.geojson
parcelform envelope parcels.geojson --streets streets.geojson --tolerance 8 \
    --front 5 --side 3 --rear 4 --secondary-front 3 -o envelopes.geojson

parcelform subdivide parcels.geojson --streets streets.geojson --tolerance 8 \
    --rules rules.json --by area -o lots.geojson --csv lots.csv
```

`--rules` takes a JSON object or a two-column `key,value` CSV with `min_area`,
`min_frontage`, `min_depth`, `min_width`. Without `-o` and `--csv`, GeoJSON goes to stdout.

## Limitations

- Planar geometry only; no reprojection, no curved segments.
- Non-convex envelopes that would split into several pieces are not computed; split the
  parcel first.
- Lot classification uses straight frontage pieces; along strongly curved streets
  (cul-de-sac bulbs) set `min_piece` or `corner_angle` to avoid false corner lots.
- Subdivision uses parallel straight cuts only.

## References

- Aichholzer, O., Aurenhammer, F., Alberts, D. & Gärtner, B. (1995). A novel type of
  skeleton for polygons. *Journal of Universal Computer Science* 1(12), 752-761.
- Andrew, A. M. (1979). Another efficient algorithm for convex hulls in two dimensions.
  *Information Processing Letters* 9(5), 216-219.
- Freeman, H. & Shapira, R. (1975). Determining the minimum-area encasing rectangle for an
  arbitrary closed curve. *Communications of the ACM* 18(7), 409-413.
- McGarigal, K. & Marks, B. J. (1995). FRAGSTATS: spatial pattern analysis program for
  quantifying landscape structure. USDA Forest Service, Gen. Tech. Rep. PNW-GTR-351.
- Polsby, D. D. & Popper, R. D. (1991). The third criterion: compactness as a procedural
  safeguard against partisan gerrymandering. *Yale Law & Policy Review* 9(2), 301-353.
- Reock, E. C. (1961). A note: measuring compactness as a requirement of legislative
  apportionment. *Midwest Journal of Political Science* 5(1), 70-74.
- Rosin, P. L. (1999). Measuring rectangularity. *Machine Vision and Applications* 11(4),
  191-196.
- Schwartzberg, J. E. (1966). Reapportionment, gerrymanders, and the notion of
  compactness. *Minnesota Law Review* 50, 443-452.
- Sutherland, I. E. & Hodgman, G. W. (1974). Reentrant polygon clipping. *Communications
  of the ACM* 17(1), 32-42.
- Toussaint, G. T. (1983). Solving geometric problems with the rotating calipers.
  *Proceedings of IEEE MELECON '83*, Athens.
- Welzl, E. (1991). Smallest enclosing disks (balls and ellipsoids). In *New Results and
  New Trends in Computer Science*, LNCS 555, 359-370.
- Zunic, J. & Rosin, P. L. (2004). A new convexity measure for polygons. *IEEE
  Transactions on Pattern Analysis and Machine Intelligence* 26(7), 923-934.

## Citation

```bibtex
@software{eminoglu_parcelform,
  author  = {Eminoğlu, Yusuf},
  title   = {parcelform},
  year    = {2026},
  version = {0.1.2},
  doi     = {10.5281/zenodo.24235570},
  url     = {https://gitlab.com/geophilo1/parcelform_sdk}
}
```

See also [CITATION.cff](https://gitlab.com/geophilo1/parcelform_sdk/-/blob/main/CITATION.cff).

## Related Geophilo SDKs

- [spacematrix](https://pypi.org/project/spacematrix/): Spacematrix urban density indicators (FSI, GSI, OSR, L) at lot, island, fabric and district level.
- [streetform](https://pypi.org/project/streetform/): street-network form and connectivity metrics from GeoJSON lines.
- [tr-imar](https://pypi.org/project/tr-imar/): Turkish zoning (imar) calculations under the Planlı Alanlar İmar Yönetmeliği.
- [tr-dop](https://pypi.org/project/tr-dop/): Turkish land readjustment (arazi ve arsa düzenlemesi, İmar Kanunu m.18) calculations.

## License

MIT, see [LICENSE](https://gitlab.com/geophilo1/parcelform_sdk/-/blob/main/LICENSE).
