parcelform 0.1.0__tar.gz

parcelform-0.1.0/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [Unreleased]
+
+## [0.1.0] - 2026-11-15
+### Added
+- Planar geometry: area, perimeter (with holes), centroid, convex hull (monotone chain),
+  minimum-area rectangle by rotating calipers, minimum enclosing circle (Welzl),
+  point-in-polygon, half-plane clipping.
+- Shape indices: Polsby-Popper, Schwartzberg (and its original ratio), Reock,
+  rectangularity, elongation, aspect ratio, area and perimeter convexity, FRAGSTATS
+  fractal dimension; MBR orientation as angle and azimuth.
+- Frontage against street centrelines or block outlines (exact capsule intervals with an
+  angle filter), per-street lengths, corner / through / interior / landlocked lot types.
+- Lot depth, width, mean depth and width-to-depth ratio relative to the primary front.
+- Buildable envelope by uniform, per-edge or role-based setbacks (exact for convex
+  parcels; verified mitred offset with edge-collapse handling for non-convex parcels).
+- Lot rules (minimum area, frontage, depth, width) and subdivision feasibility by
+  equal-frontage or equal-area perpendicular cuts.
+- FeatureCollection batch analysis, envelope and subdivision layers; GeoJSON and CSV I/O.
+- Command line: `parcelform metrics | envelope | subdivide`.
+
+### Fixed (pre-release review)
+- Frontage capsule intervals: an edge that passes a street segment's end inside the end
+  disc, but crosses the perpendicular band only beyond the end, no longer gets an
+  over-long frontage interval; checked against dense sampling in the tests.
+- Shape-index docs: the two convexity ratios are labelled as the classical measures
+  discussed by Zunic & Rosin (2004); reference details completed.

parcelform-0.1.0/CITATION.cff

@@ -0,0 +1,23 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite it as below."
+authors:
+  - family-names: "Eminoğlu"
+    given-names: "Yusuf"
+    email: "geospacephilo@gmail.com"
+    orcid: "https://orcid.org/0009-0005-6000-2934"
+title: "parcelform"
+version: "0.1.0"
+date-released: "2026-11-15"
+license: "MIT"
+repository-code: "https://gitlab.com/geophilo1/parcelform_sdk"
+url: "https://pypi.org/project/parcelform/"
+abstract: "Parcel and lot geometry metrics from GeoJSON polygons in projected coordinates: area, perimeter, convex hull, minimum-area rectangle and orientation; Polsby-Popper, Schwartzberg, Reock, rectangularity, elongation, convexity and fractal dimension; frontage against street centrelines or blocks with corner, through and interior lot classification; lot depth and width; buildable envelopes by setback; lot-rule checks and subdivision feasibility."
+keywords:
+  - parcel
+  - lot
+  - cadastre
+  - frontage
+  - setback
+  - shape index
+  - urban planning
+  - gis

parcelform-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yusuf Eminoğlu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

parcelform-0.1.0/MANIFEST.in

@@ -0,0 +1,9 @@
+include LICENSE
+include README.md
+include CHANGELOG.md
+include CITATION.cff
+include pyproject.toml
+include src/parcelform/py.typed
+recursive-include src/parcelform *.py
+recursive-include tests *.py
+recursive-include examples *.py

parcelform-0.1.0/PKG-INFO

@@ -0,0 +1,273 @@
+Metadata-Version: 2.4
+Name: parcelform
+Version: 0.1.0
+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: Issues, https://gitlab.com/geophilo1/parcelform_sdk/-/work_items
+Project-URL: Changelog, https://gitlab.com/geophilo1/parcelform_sdk/-/blob/main/CHANGELOG.md
+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: 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
+
+# parcelform
+
+[![PyPI](https://img.shields.io/pypi/v/parcelform.svg)](https://pypi.org/project/parcelform/)
+[![Python](https://img.shields.io/pypi/pyversions/parcelform.svg)](https://pypi.org/project/parcelform/)
+[![pipeline](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-blue.svg)](https://gitlab.com/geophilo1/parcelform_sdk/-/blob/main/LICENSE)
+
+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.0},
+  url     = {https://gitlab.com/geophilo1/parcelform_sdk}
+}
+```
+
+See also [CITATION.cff](CITATION.cff).
+
+## License
+
+MIT, see [LICENSE](LICENSE).

parcelform-0.1.0/README.md

@@ -0,0 +1,238 @@
+# parcelform
+
+[![PyPI](https://img.shields.io/pypi/v/parcelform.svg)](https://pypi.org/project/parcelform/)
+[![Python](https://img.shields.io/pypi/pyversions/parcelform.svg)](https://pypi.org/project/parcelform/)
+[![pipeline](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-blue.svg)](https://gitlab.com/geophilo1/parcelform_sdk/-/blob/main/LICENSE)
+
+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.0},
+  url     = {https://gitlab.com/geophilo1/parcelform_sdk}
+}
+```
+
+See also [CITATION.cff](CITATION.cff).
+
+## License
+
+MIT, see [LICENSE](LICENSE).

parcelform-0.1.0/examples/quickstart.py

@@ -0,0 +1,65 @@
+"""parcelform quickstart on a small synthetic block (no input files needed).
+
+Run:  python examples/quickstart.py
+"""
+
+from __future__ import annotations
+
+import json
+
+import parcelform as pf
+
+
+def square(x0: float, y0: float, w: float, d: float) -> dict:
+    ring = [[x0, y0], [x0 + w, y0], [x0 + w, y0 + d], [x0, y0 + d], [x0, y0]]
+    return {"type": "Polygon", "coordinates": [ring]}
+
+
+def main() -> None:
+    # Three lots along a street whose centreline runs 6 m south of the lots; the
+    # westernmost lot also faces a side street.
+    parcels = {
+        "type": "FeatureCollection",
+        "features": [
+            {"type": "Feature", "id": "A", "properties": {}, "geometry": square(0, 0, 18, 35)},
+            {"type": "Feature", "id": "B", "properties": {}, "geometry": square(18, 0, 60, 35)},
+            {"type": "Feature", "id": "C", "properties": {}, "geometry": square(78, 10, 15, 25)},
+        ],
+    }
+    streets = [
+        {"type": "LineString", "coordinates": [[-50, -6], [150, -6]]},
+        {"type": "LineString", "coordinates": [[-6, -50], [-6, 100]]},
+    ]
+
+    rep = pf.analyze_parcel(parcels["features"][0]["geometry"], streets=streets, tolerance=7)
+    print("lot A:", rep.frontage.lot_type, "frontage", rep.frontage.total)
+    print("shape:", {k: round(v, 3) for k, v in rep.shape.to_dict().items()})
+
+    # Zoning values below are placeholders; take them from the code that applies.
+    rules = pf.LotRules(min_area=400, min_frontage=12, min_depth=25)
+    out = pf.analyze(
+        parcels,
+        streets=streets,
+        tolerance=7,
+        setbacks={"front": 5, "side": 3, "rear": 3},
+        rules=rules,
+        subdivide=True,
+        primary_rule="shortest",  # corner lots front on their narrower street side
+    )
+    for f in out["features"]:
+        p = f["properties"]
+        print(
+            f["id"],
+            p.get("lot_type"),
+            "frontage",
+            round(p.get("frontage", 0), 2),
+            "envelope",
+            round(p.get("envelope_area") or 0, 1),
+            "max lots",
+            p.get("max_lots"),
+        )
+    print(json.dumps(out["features"][1]["properties"], indent=1)[:400])
+
+
+if __name__ == "__main__":
+    main()