Metadata-Version: 2.4
Name: lczlite
Version: 0.1.0
Summary: Local Climate Zone (Stewart & Oke 2012) classification from urban canopy parameters: fuzzy range scoring with confidence and mixed-class flags, parameters from building footprint grids, WUDAPT codes, colour table and summaries.
Author-email: Yusuf Eminoğlu <geospacephilo@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://gitlab.com/geophilo1/lczlite_sdk
Project-URL: Repository, https://gitlab.com/geophilo1/lczlite_sdk
Project-URL: Issues, https://gitlab.com/geophilo1/lczlite_sdk/-/work_items
Project-URL: Changelog, https://gitlab.com/geophilo1/lczlite_sdk/-/blob/main/CHANGELOG.md
Keywords: local-climate-zones,lcz,urban-climate,urban-heat-island,wudapt,urban-canopy-parameters,sky-view-factor,aspect-ratio,roughness-length,urban-morphology,classification,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: Topic :: Scientific/Engineering :: Atmospheric Science
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

# lczlite

[![PyPI](https://img.shields.io/pypi/v/lczlite.svg)](https://pypi.org/project/lczlite/)
[![Python](https://img.shields.io/pypi/pyversions/lczlite.svg)](https://pypi.org/project/lczlite/)
[![pipeline](https://gitlab.com/geophilo1/lczlite_sdk/badges/main/pipeline.svg)](https://gitlab.com/geophilo1/lczlite_sdk/-/pipelines)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://gitlab.com/geophilo1/lczlite_sdk/-/blob/main/LICENSE)

Local Climate Zone classification from urban canopy parameters.

`lczlite` assigns sites or grid cells to the Local Climate Zones of Stewart & Oke (2012)
by comparing their urban canopy parameters with the property ranges of each zone:

- **Range scoring**: trapezoidal (fuzzy) membership of each parameter in each class's
  range, weighted class scores, best class, confidence, runner-up, margin and mixed-class
  flags; crisp in/out tests with `softness=0`.
- **Parameters from simple inputs**: building, impervious and pervious surface fractions;
  aspect ratio; canyon sky view factor; frontal area index; displacement height and
  roughness length (Macdonald et al. 1998); Davenport terrain roughness class.
- **Building grids**: footprint areas and heights (with x, y) summed into grid cells with
  area-weighted, geometric and maximum heights and frontal areas.
- **Outputs**: WUDAPT integer codes (1-17, 0 = unclassified), LCZ colour table, RGB
  images, QGIS `.qml` palette, class summaries, mixed-pair counts, agreement between two
  maps, majority filter.
- **Published range table bundled**: the property ranges of all 17 classes from Stewart &
  Oke (2012), Tables 3 and 4 (`stewart_oke_table()`); local tables load from CSV or JSON,
  with an empty 17-class template.

It needs only NumPy. A command-line tool is included.

The default range table holds the values of Stewart & Oke (2012), Table 3 (sky view
factor, aspect ratio, building / impervious / pervious surface fraction, height of
roughness elements, terrain roughness class) and Table 4 (surface admittance, albedo,
anthropogenic heat), read from the published article and shipped as
`lczlite/data/stewart_oke_2012.json`. Surface fractions are converted from percent to
0-1. Two cells are blank in the paper and stay blank: the admittance of LCZ A ("unknown")
and the height of roughness elements of LCZ G.

## Installation

```bash
pip install lczlite
```

Requires Python 3.9 or newer.

## Quickstart

```python
import numpy as np
import lczlite as lz

table = lz.stewart_oke_table()     # Stewart & Oke (2012), Tables 3-4
# or a local adaptation: lz.read_range_table("my_ranges.csv", percent=True)

# Parameters per site (any shape; NaN = unknown)
params = {
    "svf": [0.45, 0.75, 0.95],
    "aspect_ratio": [1.2, 0.5, 0.05],
    "bsf": [0.50, 0.30, 0.03],
    "isf": [0.40, 0.30, 0.02],
    "psf": [0.10, 0.40, 0.95],
    "height": [15.0, 6.0, 0.5],
}
res = lz.classify(params, table, mixed_margin=0.1)
res.labels          # best LCZ key per site, '' = unclassified
res.codes           # WUDAPT codes 1-17, 0 = unclassified
res.confidence      # best score (0-1)
res.margin          # gap to the runner-up
res.mixed           # True where the two best classes are close
res.explain(0)      # per-parameter memberships of site 0
lz.class_summary(res)
```

From building footprints to classified cells:

```python
spec = lz.GridSpec(x0=500000, y0=4300000, cell_size=200, shape=(50, 50))
grid = lz.buildings_to_grid(x, y, footprint_area, height, spec)
params = grid.parameters(impervious_area, height="mean",
                         admittance=adm, albedo=alb, anthropogenic_heat=qf)
res = lz.classify(params, table)
rgb = res.to_rgb()                 # (rows, cols, 3) uint8
lz.write_qml("lcz.qml")            # palette for a WUDAPT-coded GeoTIFF in QGIS
```

A complete synthetic run is in [`examples/quickstart.py`](examples/quickstart.py).

## Feature overview

| Area | Functions / classes |
| --- | --- |
| Classes | `LCZ_CLASSES`, `LCZ_KEYS`, `normalize_key`, `wudapt_code`, `key_from_code`, `lcz_class` |
| Colours | `colour_table`, `to_rgb`, `hex_to_rgb`, `write_qml`, `write_colour_csv` |
| Range tables | `RangeTable`, `Range`, `parse_range`, `stewart_oke_table`, `read_range_table`, `write_template`, `PARAMETERS` |
| Parameters | `surface_fractions`, `street_width_regular`, `aspect_ratio`, `svf_canyon`, `frontal_area_index`, `macdonald`, `roughness_class`, `albedo_plan_weighted`, `canopy_parameters`, `DAVENPORT_Z0` |
| Grids | `GridSpec`, `buildings_to_grid -> BuildingGrid` (`parameters()`) |
| Classification | `membership`, `classify -> LCZResult` (`labels`, `codes`, `confidence`, `margin`, `mixed`, `explain`, `records`, `to_rgb`) |
| Summaries | `class_summary`, `mixed_pairs`, `compare_maps`, `majority_filter` |
| I/O | `read_sites_csv`, `result_rows`, `write_results_csv`, `write_csv` |

Parameter names: `svf`, `aspect_ratio`, `bsf` (building surface fraction), `isf`
(impervious), `psf` (pervious), `height` (height of roughness elements), `roughness_class`,
`admittance`, `albedo`, `anthropogenic_heat`; common long names are accepted as aliases.
Surface fractions are 0-1 inside the package; use `percent=True` for tables or site files
in percent.

## Methods and sources

**Local Climate Zones.** Seventeen classes (built types 1-10, land-cover types A-G)
defined by ranges of geometric, surface-cover, thermal, radiative and metabolic properties
(Stewart & Oke 2012). WUDAPT products store them as integers 1-17 with A-G as 11-17
(Demuzere et al. 2021); the default colours follow the palette commonly used for WUDAPT
maps and can be overridden.

**Scoring.** For a range `[lo, hi]` the membership is 1 inside and falls linearly to 0 at
a distance `w` outside; `w = softness · (hi − lo)` for two-sided ranges,
`softness · |bound|` for one-sided ones, or an absolute `tolerance` per parameter. A class
score is the weighted mean membership over the parameters the class constrains and the
site has. The best class gives the confidence; the margin to the second class drives the
mixed flag. The membership shape and the defaults (`softness=0.5`, `mixed_margin=0.1`,
`min_score=0`) are design choices of this package, not values from the paper.

**Parameters.**

| Parameter | Computation | Source |
| --- | --- | --- |
| BSF, ISF, PSF | plan-area shares of the cell; PSF = remainder unless given | definition |
| Street width | `W = L (1/√λp − 1)`, `L = √(mean footprint)` | regular array of square blocks (assumption of this package) |
| Aspect ratio | `H / W` | definition |
| SVF, floor-averaged | `√(1 + (H/W)²) − H/W` | infinite canyon, Hottel's crossed-strings rule |
| SVF, floor centre | `cos(arctan(2H/W))` | Oke (1987) |
| λf | frontal area / cell area; default frontal width `√footprint` | definition |
| zd, z0 | `zd/H = 1 + A^(−λp)(λp − 1)`, `z0/H = (1 − zd/H) exp(−(0.5 β C_D/κ² (1 − zd/H) λf)^(−1/2))`, `A = 4.43`, `β = 1.0`, `C_D = 1.2`, `κ = 0.4` (staggered arrays) | Macdonald, Griffiths & Hall (1998) |
| Roughness class | Davenport class whose nominal z0 (0.0002, 0.005, 0.03, 0.10, 0.25, 0.5, 1.0, ≥2 m) is nearest on a log scale | Davenport et al. (2000); nearest-class rule is this package's convention. Stewart & Oke (2012, Table 5) print 0.0005 m for class 2; 0.005 m is the Davenport-Wieringa value |
| Albedo (optional) | plan-area-weighted component albedos | approximation, ignores canyon trapping |
| Admittance, anthropogenic heat | passed through | user data |

Buildings are assigned whole to the cell containing their reference point.

## Values left to the user

- Local adaptations of the LCZ property ranges (the published ranges are bundled).
- Impervious and pervious areas, surface admittance, albedo and anthropogenic heat.
- Membership softness, tolerances, weights, `min_score` and `mixed_margin`.

## Command line

```bash
lczlite ranges -o so2012.csv                       # bundled Stewart & Oke ranges as CSV
lczlite template lcz_ranges.csv                    # empty 17-class table for local ranges
lczlite grid buildings.csv --cell-size 200 -o cells.csv      # x,y,area,height -> cells
# add impervious_area (and optional albedo, admittance, ...) to cells.csv, then:
lczlite params cells.csv --height-col height_geometric -o params.csv
lczlite classify params.csv \
    --weights svf=2 --mixed-margin 0.1 --scores -o lcz.csv --summary summary.json
lczlite colours --qml lcz.qml --csv lcz_colours.csv
```

`params` expects `cell_area`, `building_area`, `impervious_area` and a height column, and
uses `mean_footprint`, `street_width`, `frontal_area`, `svf`, `pervious_area`,
`admittance`, `albedo`, `anthropogenic_heat` when present.

## Limitations

- Range scoring is a rule-based approach on known parameters, not the WUDAPT
  remote-sensing workflow; it does not use training areas or satellite imagery.
- Canyon formulas assume long symmetric canyons and regular arrays; real urban fabric
  differs, so measured SVF and street widths are preferable where available.
- The result depends on the range table, which should be cited with the classification.
  Stewart & Oke present their ranges as generic values; local fabric may need adapted
  ranges (`--ranges my_ranges.csv --table-percent`).

## References

- Davenport, A. G., Grimmond, C. S. B., Oke, T. R. & Wieringa, J. (2000). Estimating the
  roughness of cities and sheltered country. *12th Conference on Applied Climatology*,
  American Meteorological Society, 96-99.
- Demuzere, M., Kittner, J. & Bechtel, B. (2021). LCZ Generator: a web application to
  create Local Climate Zone maps. *Frontiers in Environmental Science* 9, 637455.
- Macdonald, R. W., Griffiths, R. F. & Hall, D. J. (1998). An improved method for the
  estimation of surface roughness of obstacle arrays. *Atmospheric Environment* 32(11),
  1857-1864.
- Oke, T. R. (1987). *Boundary Layer Climates*, 2nd ed. Routledge, London.
- Stewart, I. D. & Oke, T. R. (2012). Local Climate Zones for urban temperature studies.
  *Bulletin of the American Meteorological Society* 93(12), 1879-1900.
  https://doi.org/10.1175/BAMS-D-11-00019.1

## Academic citation

```bibtex
@software{eminoglu_lczlite,
  author  = {Eminoğlu, Yusuf},
  title   = {lczlite},
  year    = {2026},
  version = {0.1.0},
  url     = {https://gitlab.com/geophilo1/lczlite_sdk}
}
```

## License

MIT, see [LICENSE](LICENSE).
