tr-donati 0.1.0__tar.gz

tr_donati-0.1.0/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [Unreleased]
+
+## [0.1.0] - 2026-11-09
+### Added
+- Bundled, data-driven EK-2 standards table of the Mekânsal Planlar Yapım Yönetmeliği
+  (RG 14/6/2014-29030; EK-2 as amended by RG 17/5/2017-30069), transcribed from the official
+  annex file on mevzuat.gov.tr, with regulation version/date metadata and the 13 explanations.
+- `StandardsTable` with population-band lookup, per-capita standards, minimum unit areas,
+  deep-merge overrides and JSON loading.
+- `required_areas` / `total_per_capita` by planned population, settlement (ilçe projection)
+  population and il/ilçe scope.
+- `check_compliance`: provided vs required areas, deficits, per-capita indicators, minimum
+  parcel size checks (`check_parcel`) and the open/green-area rules of explanations 9 and 10.
+- GeoJSON/CSV plan input with planar or spherical polygon areas and a configurable land-use
+  code -> donatı type mapping (JSON/CSV, share splits).
+- Service-radius coverage analysis (Euclidean, haversine or user distance matrix).
+- Turkish Markdown/CSV reports and the `tr-donati` CLI (`standartlar`, `ihtiyac`, `denetle`,
+  `erisim`).

tr_donati-0.1.0/CITATION.cff

@@ -0,0 +1,21 @@
+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: "tr-donati"
+version: "0.1.0"
+date-released: "2026-11-09"
+license: "MIT"
+repository-code: "https://github.com/YusufEminoglu/tr_donati_sdk"
+url: "https://pypi.org/project/tr-donati/"
+abstract: "Donatı (social and technical infrastructure) area standards for Turkish spatial plans based on EK-2 of the Mekânsal Planlar Yapım Yönetmeliği: required areas by population, plan compliance checks with deficits and per-capita indicators, minimum parcel sizes, service-radius analysis and Turkish Markdown/CSV reports."
+keywords:
+  - urban planning
+  - spatial planning
+  - Turkey
+  - social infrastructure
+  - planning standards
+  - gis

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

tr_donati-0.1.0/MANIFEST.in

@@ -0,0 +1,10 @@
+include LICENSE
+include README.md
+include CHANGELOG.md
+include CITATION.cff
+include pyproject.toml
+include src/tr_donati/py.typed
+recursive-include src/tr_donati *.py
+recursive-include src/tr_donati/data *.json
+recursive-include tests *.py
+recursive-include examples *.py *.geojson

tr_donati-0.1.0/PKG-INFO

@@ -0,0 +1,262 @@
+Metadata-Version: 2.4
+Name: tr-donati
+Version: 0.1.0
+Summary: Donatı (social and technical infrastructure) area standards for Turkish spatial plans: EK-2 of the Mekânsal Planlar Yapım Yönetmeliği, required areas, plan compliance checks, per-capita indicators and service-radius analysis.
+Author-email: Yusuf Eminoğlu <geospacephilo@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/YusufEminoglu/tr_donati_sdk
+Project-URL: Repository, https://github.com/YusufEminoglu/tr_donati_sdk
+Project-URL: Issues, https://github.com/YusufEminoglu/tr_donati_sdk/issues
+Project-URL: Changelog, https://github.com/YusufEminoglu/tr_donati_sdk/blob/main/CHANGELOG.md
+Keywords: turkish,turkey,turkiye,urban-planning,spatial-planning,imar-plani,donati,donati-alani,mekansal-planlar-yapim-yonetmeligi,social-infrastructure,green-space,planning-standards,accessibility,geojson,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: Natural Language :: Turkish
+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
+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
+
+# tr-donati
+
+[![PyPI](https://img.shields.io/pypi/v/tr-donati.svg)](https://pypi.org/project/tr-donati/)
+[![Python](https://img.shields.io/pypi/pyversions/tr-donati.svg)](https://pypi.org/project/tr-donati/)
+[![CI](https://github.com/YusufEminoglu/tr_donati_sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/YusufEminoglu/tr_donati_sdk/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+**English summary.** `tr-donati` implements the minimum social and technical infrastructure
+("donatı") area standards that Turkish spatial plans must meet: Annex 2 (EK-2) of the
+*Mekânsal Planlar Yapım Yönetmeliği* (Official Gazette 14 June 2014, no. 29030; annex as
+amended on 17 May 2017). It computes required areas for a planned population, checks a plan's
+land-use polygons (GeoJSON/CSV) against those standards with deficits, per-capita indicators
+and minimum parcel sizes, runs service-radius checks, and writes Turkish Markdown/CSV reports.
+Pure Python, no dependencies.
+
+---
+
+**Türk imar planları için donatı alanı standartları.** `tr-donati`, Mekânsal Planlar Yapım
+Yönetmeliği'nin **EK-2** tablosundaki ("Farklı nüfus gruplarında asgari sosyal ve teknik
+altyapı alanlarına ilişkin standartlar ve asgari alan büyüklükleri tablosu") kişi başı
+standartları ve asgari birim alanları veri olarak içerir ve bunlarla:
+
+- planlanan nüfus için **gerekli donatı alanlarını** hesaplar (nüfus grubuna ve il/ilçe
+  kapsamına göre),
+- plan arazi kullanım poligonlarını (GeoJSON/CSV) okuyup **sunulan ve gerekli alanları
+  karşılaştırır**, açıkları ve kişi başı göstergeleri verir,
+- tesis parsellerini **asgari birim alana** göre denetler (ör. ilkokul ≥ 5.000 m², devlet
+  hastanesi yatak başına 130 m²),
+- EK-2 açıklama 9 ve 10'daki **açık-yeşil alan kurallarını** denetler,
+- okul/park gibi tesisler için **hizmet yarıçapı (etki alanı)** analizi yapar (kuş uçuşu ya da
+  kullanıcının verdiği ağ mesafeleri),
+- Türkçe **Markdown/CSV rapor** üretir.
+
+Standart tablosu veri tabanlıdır (JSON); yönetmelik sürümü ve tarihi tabloda kayıtlıdır ve
+tüm değerler kullanıcı tarafından değiştirilebilir. Saf Python, bağımlılık yok, Python 3.9+.
+
+## Kurulum
+
+```bash
+pip install tr-donati
+```
+
+## Hızlı başlangıç (Python)
+
+```python
+>>> import tr_donati as td
+>>> {r.category: r.required_area for r in td.required_areas(120_000)}["acik_yesil_ilce"]
+1200000.0
+>>> td.population_group(120_000).label
+'75.001 - 150.000'
+>>> rep = td.check_compliance(
+...     {"park": 80_000, "cocuk_bahcesi": 15_000, "ilkokul": 16_500},
+...     population=10_000,
+...     settlement_population=200_000,   # ilçe projeksiyon nüfusu -> nüfus grubu
+... )
+>>> green = rep.result("acik_yesil_ilce")
+>>> green.required_area, green.provided_area, green.deficit
+(100000.0, 95000.0, 5000.0)
+>>> rep.result("ilkokul").deficit
+3500.0
+>>> td.check_parcel("ilkokul", 4_500, 200_000).status
+'asgari alanın altında'
+
+```
+
+Plan dosyasından rapor:
+
+```python
+import tr_donati as td
+
+feats = td.read_plan("plan.geojson", code_field="KULLANIM")      # alan geometriden hesaplanır
+summary = td.summarize(feats)                                     # varsayılan eşleştirme
+rep = td.check_compliance(summary.provided, population=10_000, settlement_population=200_000,
+                          parcels=summary.parcels, unmapped=summary.unmapped,
+                          plan_area=summary.plan_area)
+open("rapor.md", "w", encoding="utf-8").write(rep.to_markdown())
+```
+
+Daha fazlası için `examples/quickstart.py` ve `examples/ornek_plan.geojson` dosyalarına bakın.
+
+## Komut satırı
+
+```bash
+# EK-2 tablosu
+tr-donati standartlar
+
+# 120 000 kişi için gerekli alanlar
+tr-donati ihtiyac --nufus 120000
+
+# 10 000 kişilik plan, 200 000 nüfuslu ilçede; il bütünü kapsamında; CSV çıktı
+tr-donati ihtiyac --nufus 10000 --yerlesme-nufusu 200000 --kapsam il --bicim csv
+
+# Plan uygunluk denetimi (GeoJSON veya CSV)
+tr-donati denetle examples/ornek_plan.geojson --nufus 10000 --yerlesme-nufusu 200000 \
+    --kod-alani KULLANIM --kimlik-alani ADA_PARSEL --birim-alani YATAK -o rapor.md
+
+# Kendi kodlarınız ve standartlarınızla
+tr-donati denetle plan.csv --nufus 25000 --kod-alani KOD --alan-alani ALAN_M2 \
+    --eslestirme eslestirme.json --standartlar cdp_standartlari.json --siki
+
+# İlkokul etki alanı: konut adalarından 800 m
+tr-donati erisim --tesisler plan.geojson --tesis-filtre-alani KULLANIM --tesis-filtre-degeri İlkokul \
+    --talep plan.geojson --talep-filtre-alani KULLANIM --talep-filtre-degeri Konut \
+    --agirlik-alani NUFUS --yaricap 800
+```
+
+`--siki` verildiğinde standart sağlanmazsa çıkış kodu 1 olur (CI/otomasyon için).
+`--cografi` / `--projeksiyonlu` koordinat türünü zorlar; verilmezse otomatik algılanır.
+
+## API özeti
+
+| İşlev / sınıf | Açıklama |
+| --- | --- |
+| `StandardsTable.default()` | Gömülü EK-2 tablosu; `with_overrides()`, `from_json()`, `group_for()`, `per_capita()`, `min_area()` |
+| `required_areas(pop, settlement_population=None, scope="ilce")` | Kategori bazında gerekli alanlar (`Requirement`) |
+| `total_per_capita(pop, scope)` | Toplam kişi başı standart (m²/kişi) |
+| `check_compliance(provided, pop, ...)` | `ComplianceReport`: açıklar, kurallar, parsel kontrolleri, `indicators()`, `to_markdown()`, `to_csv()` |
+| `check_parcel(facility, area, pop, units=None)` | Tek parselin asgari birim alan kontrolü |
+| `LandUseMapping` | Kullanım kodu → tesis türü (paylı bölme destekli), JSON/CSV'den yükleme |
+| `read_plan`, `read_geojson`, `read_csv`, `summarize` | Plan girdisi okuma ve alan toplama |
+| `service_coverage(demand, facilities, radius, metric, distances)` | Etki alanı / en yakın tesis analizi |
+| `read_points`, `read_distance_matrix` | Nokta ve mesafe matrisi okuma |
+
+### Kategoriler ve tesis türleri
+
+Kişi başı standart taşıyan kategoriler: `anaokulu`, `ilkokul`, `ortaokul`, `ortaogretim`
+(lise + diğer eğitim tesisleri, tabloda tek birleşik hücre), `acik_yesil_ilce` (10 m²/kişi),
+`acik_yesil_il` (il bütününde +5 m²/kişi), `saglik`, `sosyal_kulturel`, `ibadet`,
+`teknik_altyapi` (yol ve otopark hariç). `otopark` ve `resmi_kurum` EK-2'de standart
+içermez; yalnızca sunulan alan raporlanır (isterseniz `with_overrides` ile standart ekleyin).
+
+Tesis türleri (örnek): `anaokulu`, `ilkokul`, `ortaokul`, `gunduzlu_lise`, `yatili_lise`,
+`meslek_lisesi`, `ozel_egitim`, `halk_egitim`, `cocuk_bahcesi`, `oyun_alani`, `park`,
+`meydan`, `semt_spor_alani`, `botanik_parki`, `mesire_yeri`, `rekreasyon`, `kent_ormani`,
+`aile_sagligi_merkezi`, `devlet_hastanesi`, `saglik_kampusu`, `kulturel_tesis`,
+`sosyal_tesis`, `kucuk_ibadet_yeri`, `orta_ibadet_yeri`, `buyuk_ibadet_yeri`,
+`teknik_altyapi`, `otopark`, `resmi_kurum`. Tam liste: `tr-donati standartlar --json`.
+
+### Eşleştirme dosyası
+
+Kullanım adları normalize edilir (`"Çocuk Bahçesi"` → `cocuk_bahcesi`). Varsayılan eşleştirme
+tesis kimliklerini, etiketlerini ve yaygın eş anlamlıları (Kreş, ASM, Cami, Hastane, Trafo...)
+tanır. Kendi kodlarınız için:
+
+```json
+{"mapping": {"1101": "park", "1204": {"ilkokul": 0.5, "ortaokul": 0.5}}}
+```
+
+veya CSV (`kod;tesis;pay`). Varsayılan olarak "İlköğretim alanı" ilkokul/ortaokul arasında
+%50-%50 bölünür; bu bir varsayımdır, gerekirse değiştirin.
+
+### Standartları değiştirme
+
+Yönetmelik Md. 11/2 kentsel asgari standartların çevre düzeni planıyla belirlenebileceğini,
+EK-2 açıklama 13 ise asgari alan büyüklüklerinin ilgili bakanlık düzenlemelerine göre
+belirlenebileceğini söyler. Bu yüzden tüm değerler değiştirilebilir:
+
+```python
+t = td.StandardsTable.default().with_overrides({
+    "meta": {"annex_version": "X Çevre Düzeni Planı hükümleri"},
+    "categories": {"acik_yesil_ilce": {"per_capita": [12, 12, 12, 12]}},
+    "facilities": {"ilkokul": {"min_area": [[6000, 9000]] * 4}},
+})
+```
+
+Değiştirilmiş tablo raporlarda "kullanıcı tarafından değiştirilmiştir" uyarısıyla belirtilir.
+
+## Yöntem ve kaynaklar
+
+- **Birincil kaynak:** Mekânsal Planlar Yapım Yönetmeliği, RG 14/6/2014 sayı 29030, Md. 11 ve
+  EK-2 (Değişik: RG 17/5/2017-30069). Değerler mevzuat.gov.tr'de yayımlanan resmi ek dosyasından
+  (`7.5.19788-ek.zip` → `EK-2.xlsx`) aktarılmış, RG 22/1/2026-33145 değişikliği işlenmiş
+  konsolide metinle karşılaştırılmıştır (EK-2 2017'den bu yana değişmemiştir). Kaynak bilgisi
+  `src/tr_donati/data/ek2_2017.json` içindeki `meta` alanındadır; EK-2'nin 13 açıklaması
+  aynen `notes` alanında yer alır.
+- **Nüfus grubu:** EK-2 açıklama 1'e göre ilçe projeksiyon nüfusuyla seçilir
+  (`settlement_population`). Gerekli alan = kişi başı standart × planlanan nüfus.
+- **Açık-yeşil alan kuralı (açıklama 9):** çocuk bahçesi, oyun alanı, park, meydan ve semt spor
+  alanı toplamı %75'in altına düşemez. Paydanın metinde açıkça belirtilmemesi nedeniyle paket
+  bunu standardın %75'i (0,75 × 10 m²/kişi × nüfus) olarak denetler ve sunulan yeşil alan
+  içindeki payı ayrıca raporlar.
+- **İl bütünü (açıklama 10):** `scope="il"` ile hayvanat bahçesi, kent ormanı, ağaçlandırılacak
+  alan, fuar ve hipodrom için +5 m²/kişi; toplam 15 m²/kişi kuralı denetlenir.
+- **Asgari birim alan:** tablodaki aralığın alt sınırı asgari değer olarak kullanılır; yatak/ünit
+  bazlı tesislerde alan = birim alan × yatak/ünit sayısı. Md. 11/3 ve açıklama 13 istisnaları
+  nedeniyle bu kontroller uyarı niteliğindedir.
+- **Alan hesabı:** projeksiyonlu koordinatlarda shoelace formülü; boylam/enlem koordinatlarında
+  küre üzerinde Chamberlain & Duquette (2007, *Some algorithms for polygons on a sphere*, JPL
+  07-03) çizgi integrali (R = 6.371.008,8 m; elipsoide göre hata < ~%0,5). Kesin alan için verinizi
+  TUREF/TM gibi metrik bir projeksiyona dönüştürün.
+- **Mesafe:** düzlemde Öklid, coğrafi koordinatta haversine veya kullanıcı mesafe matrisi.
+
+## Sınırlamalar
+
+- **Hizmet yarıçapları yönetmelikte yoktur.** `DEFAULT_SERVICE_RADII` (çocuk bahçesi 300 m,
+  park 500 m, anaokulu 500 m, ilkokul 800 m, ortaokul 1.000 m, lise 1.500 m, ASM 1.000 m,
+  ibadet yeri 500 m, semt spor alanı 1.000 m) planlama eğitiminde kullanılan **gösterge**
+  değerlerdir; birincil kaynakla doğrulanmamıştır. Resmi değerlendirmelerde `--yaricap` ile
+  kendi değerinizi verin.
+- Kuş uçuşu mesafe gerçek yürüme mesafesini olduğundan kısa gösterir; ağ analizi sonuçlarını
+  `--mesafeler` ile verebilirsiniz.
+- Otopark ihtiyacı Otopark Yönetmeliği'ne tabidir ve bu pakette hesaplanmaz.
+- Kaynak tabloda son nüfus grubu "501.000 +" olarak yazılmıştır; 500.001-500.999 aralığı bu
+  gruba atanmıştır.
+- Varsayılan eşleştirmedeki eş anlamlılar (ör. "Hastane" → devlet hastanesi, "İlköğretim" →
+  %50 ilkokul + %50 ortaokul) varsayımdır.
+- Koruma amaçlı imar planları (Md. 11/4), turizm alanları (Md. 11/5) ve 6306 sayılı Kanun
+  planları (açıklama 11) için özel hükümler otomatik uygulanmaz.
+- Bu araç karar desteği içindir; resmi plan onay ve denetim süreçlerinin yerine geçmez.
+
+## Akademik atıf
+
+```bibtex
+@software{eminoglu_tr_donati,
+  author  = {Eminoğlu, Yusuf},
+  title   = {tr-donati},
+  year    = {2026},
+  version = {0.1.0},
+  url     = {https://github.com/YusufEminoglu/tr_donati_sdk}
+}
+```
+
+Ayrıca bkz. `CITATION.cff`.
+
+## Lisans
+
+MIT © 2026 Yusuf Eminoğlu. Bkz. [LICENSE](LICENSE).

tr_donati-0.1.0/README.md

@@ -0,0 +1,227 @@
+# tr-donati
+
+[![PyPI](https://img.shields.io/pypi/v/tr-donati.svg)](https://pypi.org/project/tr-donati/)
+[![Python](https://img.shields.io/pypi/pyversions/tr-donati.svg)](https://pypi.org/project/tr-donati/)
+[![CI](https://github.com/YusufEminoglu/tr_donati_sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/YusufEminoglu/tr_donati_sdk/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+**English summary.** `tr-donati` implements the minimum social and technical infrastructure
+("donatı") area standards that Turkish spatial plans must meet: Annex 2 (EK-2) of the
+*Mekânsal Planlar Yapım Yönetmeliği* (Official Gazette 14 June 2014, no. 29030; annex as
+amended on 17 May 2017). It computes required areas for a planned population, checks a plan's
+land-use polygons (GeoJSON/CSV) against those standards with deficits, per-capita indicators
+and minimum parcel sizes, runs service-radius checks, and writes Turkish Markdown/CSV reports.
+Pure Python, no dependencies.
+
+---
+
+**Türk imar planları için donatı alanı standartları.** `tr-donati`, Mekânsal Planlar Yapım
+Yönetmeliği'nin **EK-2** tablosundaki ("Farklı nüfus gruplarında asgari sosyal ve teknik
+altyapı alanlarına ilişkin standartlar ve asgari alan büyüklükleri tablosu") kişi başı
+standartları ve asgari birim alanları veri olarak içerir ve bunlarla:
+
+- planlanan nüfus için **gerekli donatı alanlarını** hesaplar (nüfus grubuna ve il/ilçe
+  kapsamına göre),
+- plan arazi kullanım poligonlarını (GeoJSON/CSV) okuyup **sunulan ve gerekli alanları
+  karşılaştırır**, açıkları ve kişi başı göstergeleri verir,
+- tesis parsellerini **asgari birim alana** göre denetler (ör. ilkokul ≥ 5.000 m², devlet
+  hastanesi yatak başına 130 m²),
+- EK-2 açıklama 9 ve 10'daki **açık-yeşil alan kurallarını** denetler,
+- okul/park gibi tesisler için **hizmet yarıçapı (etki alanı)** analizi yapar (kuş uçuşu ya da
+  kullanıcının verdiği ağ mesafeleri),
+- Türkçe **Markdown/CSV rapor** üretir.
+
+Standart tablosu veri tabanlıdır (JSON); yönetmelik sürümü ve tarihi tabloda kayıtlıdır ve
+tüm değerler kullanıcı tarafından değiştirilebilir. Saf Python, bağımlılık yok, Python 3.9+.
+
+## Kurulum
+
+```bash
+pip install tr-donati
+```
+
+## Hızlı başlangıç (Python)
+
+```python
+>>> import tr_donati as td
+>>> {r.category: r.required_area for r in td.required_areas(120_000)}["acik_yesil_ilce"]
+1200000.0
+>>> td.population_group(120_000).label
+'75.001 - 150.000'
+>>> rep = td.check_compliance(
+...     {"park": 80_000, "cocuk_bahcesi": 15_000, "ilkokul": 16_500},
+...     population=10_000,
+...     settlement_population=200_000,   # ilçe projeksiyon nüfusu -> nüfus grubu
+... )
+>>> green = rep.result("acik_yesil_ilce")
+>>> green.required_area, green.provided_area, green.deficit
+(100000.0, 95000.0, 5000.0)
+>>> rep.result("ilkokul").deficit
+3500.0
+>>> td.check_parcel("ilkokul", 4_500, 200_000).status
+'asgari alanın altında'
+
+```
+
+Plan dosyasından rapor:
+
+```python
+import tr_donati as td
+
+feats = td.read_plan("plan.geojson", code_field="KULLANIM")      # alan geometriden hesaplanır
+summary = td.summarize(feats)                                     # varsayılan eşleştirme
+rep = td.check_compliance(summary.provided, population=10_000, settlement_population=200_000,
+                          parcels=summary.parcels, unmapped=summary.unmapped,
+                          plan_area=summary.plan_area)
+open("rapor.md", "w", encoding="utf-8").write(rep.to_markdown())
+```
+
+Daha fazlası için `examples/quickstart.py` ve `examples/ornek_plan.geojson` dosyalarına bakın.
+
+## Komut satırı
+
+```bash
+# EK-2 tablosu
+tr-donati standartlar
+
+# 120 000 kişi için gerekli alanlar
+tr-donati ihtiyac --nufus 120000
+
+# 10 000 kişilik plan, 200 000 nüfuslu ilçede; il bütünü kapsamında; CSV çıktı
+tr-donati ihtiyac --nufus 10000 --yerlesme-nufusu 200000 --kapsam il --bicim csv
+
+# Plan uygunluk denetimi (GeoJSON veya CSV)
+tr-donati denetle examples/ornek_plan.geojson --nufus 10000 --yerlesme-nufusu 200000 \
+    --kod-alani KULLANIM --kimlik-alani ADA_PARSEL --birim-alani YATAK -o rapor.md
+
+# Kendi kodlarınız ve standartlarınızla
+tr-donati denetle plan.csv --nufus 25000 --kod-alani KOD --alan-alani ALAN_M2 \
+    --eslestirme eslestirme.json --standartlar cdp_standartlari.json --siki
+
+# İlkokul etki alanı: konut adalarından 800 m
+tr-donati erisim --tesisler plan.geojson --tesis-filtre-alani KULLANIM --tesis-filtre-degeri İlkokul \
+    --talep plan.geojson --talep-filtre-alani KULLANIM --talep-filtre-degeri Konut \
+    --agirlik-alani NUFUS --yaricap 800
+```
+
+`--siki` verildiğinde standart sağlanmazsa çıkış kodu 1 olur (CI/otomasyon için).
+`--cografi` / `--projeksiyonlu` koordinat türünü zorlar; verilmezse otomatik algılanır.
+
+## API özeti
+
+| İşlev / sınıf | Açıklama |
+| --- | --- |
+| `StandardsTable.default()` | Gömülü EK-2 tablosu; `with_overrides()`, `from_json()`, `group_for()`, `per_capita()`, `min_area()` |
+| `required_areas(pop, settlement_population=None, scope="ilce")` | Kategori bazında gerekli alanlar (`Requirement`) |
+| `total_per_capita(pop, scope)` | Toplam kişi başı standart (m²/kişi) |
+| `check_compliance(provided, pop, ...)` | `ComplianceReport`: açıklar, kurallar, parsel kontrolleri, `indicators()`, `to_markdown()`, `to_csv()` |
+| `check_parcel(facility, area, pop, units=None)` | Tek parselin asgari birim alan kontrolü |
+| `LandUseMapping` | Kullanım kodu → tesis türü (paylı bölme destekli), JSON/CSV'den yükleme |
+| `read_plan`, `read_geojson`, `read_csv`, `summarize` | Plan girdisi okuma ve alan toplama |
+| `service_coverage(demand, facilities, radius, metric, distances)` | Etki alanı / en yakın tesis analizi |
+| `read_points`, `read_distance_matrix` | Nokta ve mesafe matrisi okuma |
+
+### Kategoriler ve tesis türleri
+
+Kişi başı standart taşıyan kategoriler: `anaokulu`, `ilkokul`, `ortaokul`, `ortaogretim`
+(lise + diğer eğitim tesisleri, tabloda tek birleşik hücre), `acik_yesil_ilce` (10 m²/kişi),
+`acik_yesil_il` (il bütününde +5 m²/kişi), `saglik`, `sosyal_kulturel`, `ibadet`,
+`teknik_altyapi` (yol ve otopark hariç). `otopark` ve `resmi_kurum` EK-2'de standart
+içermez; yalnızca sunulan alan raporlanır (isterseniz `with_overrides` ile standart ekleyin).
+
+Tesis türleri (örnek): `anaokulu`, `ilkokul`, `ortaokul`, `gunduzlu_lise`, `yatili_lise`,
+`meslek_lisesi`, `ozel_egitim`, `halk_egitim`, `cocuk_bahcesi`, `oyun_alani`, `park`,
+`meydan`, `semt_spor_alani`, `botanik_parki`, `mesire_yeri`, `rekreasyon`, `kent_ormani`,
+`aile_sagligi_merkezi`, `devlet_hastanesi`, `saglik_kampusu`, `kulturel_tesis`,
+`sosyal_tesis`, `kucuk_ibadet_yeri`, `orta_ibadet_yeri`, `buyuk_ibadet_yeri`,
+`teknik_altyapi`, `otopark`, `resmi_kurum`. Tam liste: `tr-donati standartlar --json`.
+
+### Eşleştirme dosyası
+
+Kullanım adları normalize edilir (`"Çocuk Bahçesi"` → `cocuk_bahcesi`). Varsayılan eşleştirme
+tesis kimliklerini, etiketlerini ve yaygın eş anlamlıları (Kreş, ASM, Cami, Hastane, Trafo...)
+tanır. Kendi kodlarınız için:
+
+```json
+{"mapping": {"1101": "park", "1204": {"ilkokul": 0.5, "ortaokul": 0.5}}}
+```
+
+veya CSV (`kod;tesis;pay`). Varsayılan olarak "İlköğretim alanı" ilkokul/ortaokul arasında
+%50-%50 bölünür; bu bir varsayımdır, gerekirse değiştirin.
+
+### Standartları değiştirme
+
+Yönetmelik Md. 11/2 kentsel asgari standartların çevre düzeni planıyla belirlenebileceğini,
+EK-2 açıklama 13 ise asgari alan büyüklüklerinin ilgili bakanlık düzenlemelerine göre
+belirlenebileceğini söyler. Bu yüzden tüm değerler değiştirilebilir:
+
+```python
+t = td.StandardsTable.default().with_overrides({
+    "meta": {"annex_version": "X Çevre Düzeni Planı hükümleri"},
+    "categories": {"acik_yesil_ilce": {"per_capita": [12, 12, 12, 12]}},
+    "facilities": {"ilkokul": {"min_area": [[6000, 9000]] * 4}},
+})
+```
+
+Değiştirilmiş tablo raporlarda "kullanıcı tarafından değiştirilmiştir" uyarısıyla belirtilir.
+
+## Yöntem ve kaynaklar
+
+- **Birincil kaynak:** Mekânsal Planlar Yapım Yönetmeliği, RG 14/6/2014 sayı 29030, Md. 11 ve
+  EK-2 (Değişik: RG 17/5/2017-30069). Değerler mevzuat.gov.tr'de yayımlanan resmi ek dosyasından
+  (`7.5.19788-ek.zip` → `EK-2.xlsx`) aktarılmış, RG 22/1/2026-33145 değişikliği işlenmiş
+  konsolide metinle karşılaştırılmıştır (EK-2 2017'den bu yana değişmemiştir). Kaynak bilgisi
+  `src/tr_donati/data/ek2_2017.json` içindeki `meta` alanındadır; EK-2'nin 13 açıklaması
+  aynen `notes` alanında yer alır.
+- **Nüfus grubu:** EK-2 açıklama 1'e göre ilçe projeksiyon nüfusuyla seçilir
+  (`settlement_population`). Gerekli alan = kişi başı standart × planlanan nüfus.
+- **Açık-yeşil alan kuralı (açıklama 9):** çocuk bahçesi, oyun alanı, park, meydan ve semt spor
+  alanı toplamı %75'in altına düşemez. Paydanın metinde açıkça belirtilmemesi nedeniyle paket
+  bunu standardın %75'i (0,75 × 10 m²/kişi × nüfus) olarak denetler ve sunulan yeşil alan
+  içindeki payı ayrıca raporlar.
+- **İl bütünü (açıklama 10):** `scope="il"` ile hayvanat bahçesi, kent ormanı, ağaçlandırılacak
+  alan, fuar ve hipodrom için +5 m²/kişi; toplam 15 m²/kişi kuralı denetlenir.
+- **Asgari birim alan:** tablodaki aralığın alt sınırı asgari değer olarak kullanılır; yatak/ünit
+  bazlı tesislerde alan = birim alan × yatak/ünit sayısı. Md. 11/3 ve açıklama 13 istisnaları
+  nedeniyle bu kontroller uyarı niteliğindedir.
+- **Alan hesabı:** projeksiyonlu koordinatlarda shoelace formülü; boylam/enlem koordinatlarında
+  küre üzerinde Chamberlain & Duquette (2007, *Some algorithms for polygons on a sphere*, JPL
+  07-03) çizgi integrali (R = 6.371.008,8 m; elipsoide göre hata < ~%0,5). Kesin alan için verinizi
+  TUREF/TM gibi metrik bir projeksiyona dönüştürün.
+- **Mesafe:** düzlemde Öklid, coğrafi koordinatta haversine veya kullanıcı mesafe matrisi.
+
+## Sınırlamalar
+
+- **Hizmet yarıçapları yönetmelikte yoktur.** `DEFAULT_SERVICE_RADII` (çocuk bahçesi 300 m,
+  park 500 m, anaokulu 500 m, ilkokul 800 m, ortaokul 1.000 m, lise 1.500 m, ASM 1.000 m,
+  ibadet yeri 500 m, semt spor alanı 1.000 m) planlama eğitiminde kullanılan **gösterge**
+  değerlerdir; birincil kaynakla doğrulanmamıştır. Resmi değerlendirmelerde `--yaricap` ile
+  kendi değerinizi verin.
+- Kuş uçuşu mesafe gerçek yürüme mesafesini olduğundan kısa gösterir; ağ analizi sonuçlarını
+  `--mesafeler` ile verebilirsiniz.
+- Otopark ihtiyacı Otopark Yönetmeliği'ne tabidir ve bu pakette hesaplanmaz.
+- Kaynak tabloda son nüfus grubu "501.000 +" olarak yazılmıştır; 500.001-500.999 aralığı bu
+  gruba atanmıştır.
+- Varsayılan eşleştirmedeki eş anlamlılar (ör. "Hastane" → devlet hastanesi, "İlköğretim" →
+  %50 ilkokul + %50 ortaokul) varsayımdır.
+- Koruma amaçlı imar planları (Md. 11/4), turizm alanları (Md. 11/5) ve 6306 sayılı Kanun
+  planları (açıklama 11) için özel hükümler otomatik uygulanmaz.
+- Bu araç karar desteği içindir; resmi plan onay ve denetim süreçlerinin yerine geçmez.
+
+## Akademik atıf
+
+```bibtex
+@software{eminoglu_tr_donati,
+  author  = {Eminoğlu, Yusuf},
+  title   = {tr-donati},
+  year    = {2026},
+  version = {0.1.0},
+  url     = {https://github.com/YusufEminoglu/tr_donati_sdk}
+}
+```
+
+Ayrıca bkz. `CITATION.cff`.
+
+## Lisans
+
+MIT © 2026 Yusuf Eminoğlu. Bkz. [LICENSE](LICENSE).