Metadata-Version: 2.4
Name: tr-donati
Version: 0.1.1
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.1},
  url     = {https://github.com/YusufEminoglu/tr_donati_sdk}
}
```

Ayrıca bkz. `CITATION.cff`.

## Lisans

MIT © 2026 Yusuf Eminoğlu. Bkz. [LICENSE](LICENSE).
