Skip to main content

parcelform

PyPI Python pipeline License: MIT

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

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

@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)

Source distribution for parcelform 0.1.0
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)

Table of built distributions (wheels) for parcelform 0.1.0
File Interpreter ABI Platform Actions
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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page