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
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
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:
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.
lengthis the long side,widththe short side,anglethe long axis counter-clockwise from +x in[0, 180),azimuththe 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 atcorner_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
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_pieceorcorner_angleto 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
@software{eminoglu_parcelform,
author = {Eminoğlu, Yusuf},
title = {parcelform},
year = {2026},
version = {0.1.0},
url = {https://gitlab.com/geophilo1/parcelform_sdk}
}
See also CITATION.cff.
License
MIT, see LICENSE.
Metadata
Release files for parcelform 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| parcelform-0.1.0.tar.gz | 50.4 kB | Without provenance | Details for parcelform-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| parcelform-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for parcelform-0.1.0-py3-none-any.whl |
Total release size: 91.6 kB
Release files / parcelform-0.1.0.tar.gz
| Download URL | parcelform-0.1.0.tar.gz |
|---|---|
| Size | 50.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
6b54df79cbf7b586c12ca07b5fa2fd52493c8b05372407209ddfdfd0e04929b2
|
|
BLAKE2b-256 checksum How to use checksums |
0724f12e80f3627caa148aea3d1e9121f5b1299f2c0527e2ad465d059d245633
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.18
|
Release files / parcelform-0.1.0-py3-none-any.whl
| Download URL | parcelform-0.1.0-py3-none-any.whl |
|---|---|
| Size | 41.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
5ea0ee45bb24ce3326fa9831c184db4a587ab90d372f10240afc03d8f75faa41
|
|
BLAKE2b-256 checksum How to use checksums |
8f9680211e571bddc61e18fe1339084bf0c0f0f1270a8843fe06f3bf1a691d5a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.18
|
Security for parcelform 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.